Introduction to BAM Toolbox

A toolbox in BAM is an installable archive, with a .tbox extension. It contains all or some of the following artifacts that model a complete usecase. When you install a toolbox, all artifacts inside it get deployed.

• Stream definitions: Contain descriptions of streams of data sent to BAM in order to perform analytics. You can place any number of stream definitions under one toolbox and deploy all of them together. But, each stream definition needs to be in a separate file. For more details on creating stream definition artifacts, see Stream Definition Artifacts.
• Analytics: Contain the hive scripts. 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 creating analytic scripts and cron expressions, see  Analytic Artifacts.
• Dashboard components: Contain the gadget xmls, jaggery files, etc. You can specify the number of tabs, title of tabs, gadgets that are displayed in a tab in a properties file according to which the dashboard is organized. For information on creating the dashboard components, see Dashboard Components.

For example, sample stream definitions, analyzers and dashboard components required to monitor the service statistics of service-hosting WSO2 products are available in the Service Stats toolbox. Therefore, installing the Service Stats toolbox simply installs all artifacts to the necessary locations in the server. When data from a service stats data agent reaches BAM, you will see the Service Stats dashboard populated with statistics. For more information on setting up service statistics to BAM from other service-hosting products, see 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. You can remove it using the instructions in  Feature Management.  

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

• Installing Default Toolbox
• Installing Custom Toolbox
• Uninstalling a Toolbox

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 using the management console.

1. Log on to the product's management console and selectBAM ToolBox -> Add in the Main menu.
2. Select an option listed under theBasic Toolbox. E.g., Phone Retail Store Toolbox, HTTPD Logs Analysis Toolbox and Install.
3. Toolbox installs and th Available BAM Tool Boxes page opens. If the toolbox status is still Installing, wait a few seconds and refresh the page to see the toolbox status changed to Installed.

Installing Custom Toolbox

You can install toolboxes that 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 as in the previous section.
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 example,
   For information on creating your own custom toolbox, see Creating a Custom Toolbox.
3. Click Install.
   
   The Available BAM Tool Boxes page opens with the status of the toolbox as installing. Wait a few seconds 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.