In this episode of our WSO2 tutorial: It sounds like the name of a rapper; TBOX. But the TBOX we mean does not rap, it is a bundling of aggregation, analysis and presentation settings for WSO2 Business Activity Monitor (BAM).
In a toolbox, which is in essence a zip file with the .tbox extension, you can find the three main type of artifacts needed:
- Stream Definition
- Analytics
- Dashboard
This is of course logical because these are the main elements of the WSO2 Business Activity Monitor, or now called WSO2 Data Analytic Server part of the open source integration platform WSO2. The stream definition defines the data within the events that will come from the input streams. The analytics part describes the hive script for the analysis and the dashboard offer the output to the user,
It is good to know that a toolbox does not necessarily has to have all three artifacts in it. Only the available artifacts will be deployed.
A fixed structure
The structure of a toolbox is always the same. Unlike the structure of a connector (a collection of APIs to connect to a external systems like Twitter) that we use within the WSO2 Enterprise Service Bus (ESB), this structure is less complex and can be simply created by hand. We will now explain each of the directories in the structure.
Stream Definition Artifacts
The incoming datastreams are defined in the streamDefn directory. You can define multiple streams but remember that each should be defined in its own file and that you reference the stream in the streams properties file in the streamDefn directory together with the user name, password, etc.
Figure 1: The Activity Monitor Toolbox Stream Definition file
In the streams.properties file the relevant other data is recorded,like the bam receiver username and password.
As you can see the link to the streams is made in the streams.properties file.
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.
Looking at the Activity Monitoring toolbox we also uses as a sample for the Steams definitions, we see the following scripts and definitions.
With, again, the associated analyzers.properties file. This links the actual script to the file in the Analytics directory. There is however a bug, as you can see the activity_monitoring_script in the properties files defines a longer filename than in the directory can be found. This is a small bug that will corrected in upcoming versions.
The cron property is optional. Cron is a Linux Time Based job scheduling tool that allows you to indicate when a job needs to run. For more information on cron, see the Wikipedia Page on it. If you do not need cron, just omit it from the analyzers.properties file.
Dashboard Artifacts
Lastly we find the dashboard artifacts in the dashboard directory. In the Activity Monitoring toolbox there is of course dashboard.properties file which describes and links to the dashboard(s), gtadgets and jaggery files (an open source javascript based web application language).
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 structure looks like this:
You place all gadget xml files that should be part of the dashboard in the ‘gadgets’ directory, including any .css/.js files. If jaggery files are used in the gadget xmls, place them in the ‘jaggery’ directory.
Why Toolboxes?
Toolboxes are a good way to bundle often used routines to share them across instances of WSO2. For often used use cases there are toolboxes available for download. In other cases you need to create them yourself.
Available toolboxes
There are a number of toolboxes available for BAM. You can download them from the WSO2 website. Please note that these boxes are linked to versions of the product and / or databases. Select the right toolbox for your needs.
Packing the Toolbox
When all files are in the directory structure you simply create a zip file and change the extention for .zip to .tbox. There are two ways of installing the custom toolbox you created or editied. The first way is to simply drop it in the <BAM_HOME>/repository/deployment/server/bam-toolbox/ folder for it to be hot deployed. Alternatively, log on to BAM management console and select BAM ToolBox -> Add in the Main menu where you have the possibility to upload a toolbox.
| WSO2TORIALS help you to change, update or improve WSO2 products and are based on our experiences with the products. WSO2TORIALS will guide you step by step with minimal knowledge required. | |
