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
- Analytics
- Dashboard components
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 include 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 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.
Note: The steps below show how to install/uninstall a toolbox using the management console. Alternatively, you can copy the .tbox file to <BAM_HOME>/repository/deployment/server/bam-toolbox folder to install it via BAM hot deployment. Create the bam-toolbox directory if it doesn't exist by default.
Similarly, deleting the .tbox file uninstalls the toolbox.
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 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 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" 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.