How to package a Dashboard created using WSO2 BAM Gadget Generation Tool in a BAM Toolbox

WSO2 BAM comes with a gadget generation tool which has a step by step wizard that allows you to generate gadgets for your dashboard in a few simple steps. Read here for more information.

In this post, I am going to discuss how to package a dashboard created using Gadget Gen Tool in a BAM Toolbox. It is important to do that because otherwise it will be very difficult to add the created dashboard to a different BAM server instance. If you have Toolbox created, it is just a matter of installing the Toolbox. 

Let's assume you have created a dashboard which consists of two gadgets named brand_vs_qty and sales_summary. In my previous post I have discussed on how to create such dashboard which looks like below.



Follow below steps to package above dashboard in a toolbox.

1. First, create a empty folders and files in following structure. 

BAM_Toolbox<folder>

└── dashboard<folder>

         ├── dashboard.properties<file>

         ├── gadgets<folder>

         └── jaggery<folder>

                  └── gadgetgen<folder>

Note : Refer the structure of sample  HTTPD_Logs.tbox and KPI_Phone_Retail_Store.tbox that are packed with BAM by default. (Can be found at <BAM_HOME/samples/toolboxes>)

2. Copy two jaggery files(brand_vs_qty.jag, sales_summary.jag) which was generated above from <BAM_HOME>/repository/deployment/server/jaggeryapps/gadgetgen to BAM_Toolbox/dashboard/jaggery/gadgetgen

3. Modify the above jaggery files(brand_vs_qty.jag, sales_summary.jag) to use the datasource name of BAM summary DB. By default Gadget Gen Tool add DB credentials provided in Gadget Gen Wizard, so it is important to change it to use the datasource name, because otherwise we will have to change DB credentials manually. 

        try {

           db = new Database("WSO2BAM_DATASOURCE");

        result = db.query(" select * from brandSummary");

        } finally {

           if (db != null) {

               db.close();

           }

        }

3. Download Gadget XMLs brand_vs_qty.xml and sales_summary.xml from WSO2 BAM Configuration Registry.

Path - /_system/config/repository/components/org.wso2.carbon.bam.gadgetgen/gadgetgen 

To download the .xml files click on each of them and click 'Download' Link

4. Copy above downloaded files(brand_vs_qty.xml and sales_summary.xml) to BAM_Toolbox/dashboard/gadgets/ folder

5. Open brand_vs_qty.xml file using a text editor. Modify the 'url' value in update() function as follows. By default Gadget Gen Tool add localhost ip and port to URL, so that needs to be modified in order to use relative path to support both super tenant and tenant modes.

            function update() {

                var respJson = null;

                var finalURL = "";

                if (window.location.pathname.search("/t/") == 0) {

                    finalURL = "./jaggeryapps/gadgetgen/brand_vs_qty.jag";

                } else {

                    finalURL = "../../gadgetgen/brand_vs_qty.jag";

                }

                $.ajax({

                    url: finalURL,

                    

                    dataType: 'json',

6. Open sales_summary.xml file using a text editor and modify the 'url' value in update() function as similar to the above.

            function update() {

                var respJson = null;

                var finalURL = "";

                if (window.location.pathname.search("/t/") == 0) {

                    finalURL = "./jaggeryapps/gadgetgen/sales_summary.jag";

                } else {

                    finalURL = "../../gadgetgen/sales_summary.jag";

                }

                $.ajax({

                    url: finalURL,

                    dataType: 'json',

7. We need to add required gadget related files (css, js, images, etc.) to our Toolbox. Extract existing KPI_Phone_Retail_Store.tbox (or HTTPD_Logs.tbox) and copy all three css, images, js folders found at KPI_Phone_Retail_Store/dashboard/gadgets to BAM_Toolbox/dashboard/gadgets/

7. Open dashboard.properties file and add following properties.

    dashboard.tabs=tab1

    dashboard.tabs.tab1.name=Phone Brands

    dashboard.tabs.tab1.gadgets=brand_vs_qty.xml,sales_summary.xml

8. Zip the BAM_Toolbox folder and rename extension to .tbox. So our toolbox name will be BAM_Toolbox.tbox. 

9. Now we have successfully package the created dashboard in a Toolbox. To make sure it works properly, install the toolbox in a fresh BAM pack and check the dashboard.