This documentation is for WSO2 Business Activity Monitor 2.0.0. View documentation for the latest release.

Introduction to BAM Toolbox

Owned by Former user (Deleted)
Last updated: Sept 18, 2012Version comment
5 min read

A toolbox in BAM is an installable archive, with a .tbox extension. It contains necessary artifacts that models a complete usecase. These artifacts are optional and only the ones available in the toolbox will be deployed. The artifacts are as follows:

  • Stream definitions
  • Analytics
  • Dashboard components

Stream definitions are descriptions of streams of data to be sent to WSO2 BAM in order to perform analytics. You can place any number of stream definitions under one toolbox and all of them will be deployed. But, each stream definition needs to be in a separate file. For more details on how to create the stream definition artifacts, refer to section, Stream Definition Artifacts described when creating a custom toolbox.

Analytics include the hive scripts to be deployed in WSO2 BAM. Similar to the 'stream definitions' artifact, any number of analytic scripts can be deployed under one toolbox. You can provide the cron expression to schedule the analytic script for each script in a separate properties file. Find more information on how to create the analytic scripts and cron expressions, refer to section, Analytics Artifacts described when creating a custom toolbox.

Dashboard components contain the gadget xmls, jaggery files, etc. You can specify the number of tabs, title of tabs, gadgets that should be shown in a tab, etc in a properties file according to which the dashboard will be organized. Find more information on how to create the dashboard components in section, Dashboard Components described when creating a custom toolbox.

For example, to monitor the service statistics of service-hosting WSO2 products, the required stream definitions, analyzers and dashboard components are available in the "Service Stats" toolbox. Therefore, by installing the "Service Stats" toolbox, all artifacts can be deployed to the necessary locations in the server. Afterwords, when data from a "Service Stats Data Agent" reaches BAM, you will see the Service Stats dashboard populated with service statistics. For more information on setting up service statistics to BAM from other service-hosting products, refer to section Data Agents.

The WSO2 BAM Toolbox functionality is provided by the following feature in the WSO2 feature repository:

Name: WSO2 Carbon - BAM Tool Box Deployer
Identifier: org.wso2.carbon.bam.toolbox.deployer.feature.group

The above feature is bundled by default in WSO2 BAM. To uninstall it if required or to install it to a different product distribution, refer to instructions given in section Feature Management. 

Shown below is how to install default or custom toolboxes using the BAM management console.

Installing a Toolbox

There are toolboxes shipped with WSO2 BAM by default. In addition, you can also create your own toolboxes with specific requirements.

Installing Default Toolbox

Follow the instructions below to install a default tookbox to WSO2 BAM.

1. Log on to the product's management console and select "BAM ToolBox -> Add" in the "Main" menu.

2. Select an option listed under the "Basic Toolbox". Eg: Phone Retail Store Toolbox, HTTPD Logs Analysis Toolbox and select the "Install" button.



3. Toolbox installs and the "Available BAM Tool Boxes" page opens. The selected toolbox will have status as 'installing'.

Wait a few seconds and refresh the page to see the toolbox status changed to 'Installed'.

Installing Custom Toolbox

You can install toolboxes which are not listed in the "Basic Toolbox" list by providing the system file path or URL pointing to the toolbox.

1. Log on to the product's management console and select "BAM ToolBox -> Add" in the "Main" menu.

2. Select the option "Toolbox From File System" if the toolbox is in your system. For example,


OR Select "ToolBox From URL" if the toolbox is hosted in a location separate from your system.

For information on creating your own custom toolbox, refer to section Creating a Custom Toolbox.

3. Click on "Install" button once the URL or path is given.

4. The "Available BAM Tool Boxes" page opens with the status of the toolbox as 'installing'.

5. Wait about a minute and refresh the page to see the status changed to 'Installed'.

Uninstalling a Toolbox

Uninstalling a toolbox removes deployed artifacts associated with it from the system. For example, if you have installed some analytic hive script via toolbox, it will be removed when unistalling the toolbox.

1. Log on to the product's management console and select "BAM ToolBox -> List" in the "Main" menu.

2. Select the toolboxes to be uninstall and click the "Uninstall button". For example,

3. Click 'yes' to confirm the removal. Notice that the status of the selected toolbox(s) will be 'uninstalling'.

4. Wait for approximately 1mintue and refresh the page to see the toolbox(s) removed.