Creating a Custom Toolbox

A toolbox can contain three main artifacts as follows:

All three artifacts are optional. You can have all three types or either one of them in one toolbox, and only the available artifacts will be deployed.

Toolbox Structure

Toolbox artifacts should be placed in the structure shown below:

Analytic Artifacts

The analytics scripts (Eg: Hive script) should be placed in the analytics folder under toolbox. All the scripts which are placed under the analytics folder will be deployed. The analyzers.properties file should be included as follows in case the script needs to be scheduled.

The following are the properties to be included in the analyzers.properties file, if there ar two scripts by the names 'my_script' and 'my_another_script' that need to be included to the toolbox.

analyzers.scripts=script1, script2

analyzers.scripts.script1.filename=my_script
analyzers.scripts.script1.description=Description about my script
analyzers.scripts.script1.cron=1 * * * * ? *

analyzers.scripts.script2.filename=my_another_script
analyzers.scripts.script2.description=Description about my another script
analyzers.scripts.script2.cron=1 * * * * ? *

As shown above, linking the analyzer script to the toolbox occurs through 'analyzers.scripts.script1.filename' property.

The cron property is optional. It should be mentioned in this property file if you want to schedule the script. Both scripts shown above are scheduled with cron expression '1 * * * * ? *'. If a script doesn't need to be schedules to run, avoid this cron property in the analyzers.properties file.

Stream Definition Artifacts

As shown in the structure of the toolbox, the stream definitions should be placed under streamDefn folder. The stream definitions are the definitions of your data stream published to BAM. You can have any number of stream definitions within one toolbox, but they should be defined in different files and the user name, password, etc properties of the stream definitions should be mentioned in the streams.properties file in the streamDefn folder.

For example, if your data is published with the stream definition shown below, it should be copied to a file and placed under the streamDefn folder. (The file name is not important but the content of the files is).

{
                   'name':'org.wso2.bam.mystream',
                   'version':'1.0.0',
                   'nickName': 'My_Stream',
                   'description': 'This is the stream definition used to send data to bam',
                   'metaData':[
                           {'name':'clientType','type':'STRING'}
                   ],
                   'payloadData':[
                           {'name':'my_field_1','type':'STRING'},
                           {'name':'my_field_2','type':'INT'},
                           {'name':'my_field_3','type':'INT'},
                           {'name':'my_field_4','type':'STRING'}
                   ]
}

Assume you have saves this stream definition as MyTestStreamDefinition.js, then the streams.properties file should be as follows,

streams.definitions=defn1
streams.definitions.defn1.filename= MyTestStreamDefinition.js
streams.definitions.defn1.username=admin
streams.definitions.defn1.password=admin
streams.definitions.defn1.description=This is my test stream definition

And the user name and password which is mentioned in the streams.properties file is the BAM receiver's user name and password.

Dashboard Artifacts

As shown in the toolbox structure, the dashboard artifacts should be placed under the dashboard directory. Dashboard artifacts can be for Gadget Dashboard or Jasper Dashboard or both. You need to have the respective artifacts for the dashboard in which your data is visualized. The following section describes how to include artifacts in the toolbox.

Gadget Dashboard Artifacts

Gadget Dashboard related artifacts are given below.

As shown above, all gadget xmls to be included in the dashboard should be placed under the 'gadgets' folder, including any .css/.js files, if any. If jaggery files are used in the gadget xmls, they should be placed in the 'jaggery' folder in the 'dashboard' folder. Finally, the dashboard tabs and gadgets for the tabs should be mentioned in the 'dashboard.properties' file. According to what is mentioned in the dashboard.properties file, the gadgets and tabs will be organized in the gadget dashboard.

Note

Jaggery is a 100% open source framework to write Web applications and HTTP-focused Web services purely in Java Script, for all aspects of the application: front-end, server-side logic, communication and persistence. For more information on Jaggery, refer to: http://jaggeryjs.org

Assume you have gadget xmls as My_Gadget_1.xml, My_Gadget_2.xml, My_Gadget_3.xml, My_Gadget_4.xml under the gadgets folder. You are want to add My_Gadget_1.xml, My_Gadget_2.xml to the first tab, and My_Gadget_3.xml, My_Gadget_4.xml to the second. Then the dashboard.properties should be as follows.

dashboard.tabs=tab1, tab2
dashboard.tabs.tab1.name=Tab-1 Title
dashboard.tabs.tab1.gadgets=My_Gadget_1.xml, My_Gadget_2.xml
dashboard.tabs.tab2.name=Tab-2 Title
dashboard.tabs.tab2.gadgets=My_Gadget_3.xml, My_Gadget_4.xml

Similar to anayzers.properties file, tab1, tab2 are reference in the properties. 'dashboard.tabs.tab1.name' denotes the title of the tab denoted by reference tab1. tab1, will have the gadgets My_Gadget_1.xml, My_Gadget_2.xml in the that order. Similarly. for the tab2, the title is 'Tab-2 Title' and the gadgets will be My_Gadget_3.xml, My_Gadget_4.xml in that order.

If you need to add the jaggery application to the BAM dashboard, then you need to have the dashboard.properties shown as below. This enables to get the toolboxes installed dynamically and show in the navigation pane of the BAM Dashboard.Then the dashboard.properties should be as follows.

dashboard.jaggery.apps=app1
dashboard.jaggery.apps.app1.main.displayName= Toolbox Name which you like to display

dashboard.jaggery.apps.app1.tabs=tab1, tab2, tab3
dashboard.jaggery.apps.app1.tab1.displayName=Sub Item - tab1 of the toolbox
dashboard.jaggery.apps.app1.tab1.url=URL redirection for the sub item - tab1

dashboard.jaggery.apps.app1.tab2.displayName=Sub Item - tab2 of the toolbox
dashboard.jaggery.apps.app1.tab2.url=URL redirection for the sub item - tab2

dashboard.jaggery.apps.app1.tab3.displayName=Sub Item - tab3 of the toolbox
dashboard.jaggery.apps.app1.tab3.url=URL redirection for the sub item - tab3

Packing the Toolbox

After including all required artifacts as described above in a directory, zip archive it and change the file extension to .tbox. The name of the .tbox is taken as the name of the toolbox. You are now ready to install your toolbox. For information, refer to section Installing custom toolbox.