Business Process Monitoring with BAM2

To monitor a business process with BAM2:

Configure BAM publishing extension.
Implement a business process with the configurations to publish the data to BAM2.
Run the BPEL process and publish data to BAM.
Monitor information via BAM.

Business process data can be monitored with BAM2. In order to specify which configuration and data is to be monitored, BPS uses a configuration file called BAMProfile. This file is included within the BPEL package.

Step 1: Configure the BAM publishing extension

Add the following extensionActivity to bps.xml, which is located in <BPS_HOME>/repository/conf/directory.

<tns:ExtensionBundles>
	<tns:runtimes>
		<tns:runtime class="org.wso2.carbon.bpel.bam.publisher.BAMPublisherExtensionBundle"/>
	</tns:runtimes>
</tns:ExtensionBundles>

Step 2: Create the BPEL process to publish data to BAM2

To create the BPEL process:

Configure the deployment descriptor.
In order to specify the server configuration details, and monitoring data (Payload, Correlation and Meta), BPS uses an XML configuration file. This configuration file should specify the BPEL process in the deploy.xml file (deployment descriptor file for a BPEL package). The BAM server profile is specified as follows:
```
<bamServerProfiles>
	<profile name="BAMServerProfile" location="file:BAMServerProfile.xml"/>
</bamServerProfiles>
```
The <bamServerProfiles> element should come under the process element in deployment descriptor (deploy.xml). The following is an example of a deployment descriptor.
```
<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03" xmlns:SalesData="http://www.samples.wso2.org/bps/SalesData/" xmlns:samples.bps.wso2.org="http://samples.bps.wso2.org">
	<process name="samples.bps.wso2.org:KPISampleProcess">
		<active>true</active>
		<retired>false</retired>
		<process-events generate="all"/>
		<provide partnerLink="client">
			<service name="samples.bps.wso2.org:KPISampleProcess" port="KPISampleProcessPort"/>
		</provide>
		<bamServerProfiles>
			<profile name="BAMServerProfile" location="file:BAMServerProfile.xml"/>
		</bamServerProfiles>
	</process>
</deploy>
```
The ‘file:‘ in location is used to specify a file path. Similarly, the BAM server profile can be kept in the WSO2 registry as well. If the BAM server profile file is stored in configuration registry, it can be referred to as conf:<resource path>. Similarly, if the BAM server profile is stored in the Governance Registry, it can be referred to as gov:<resource path>.

Create the BAM server profile.
BAM server profile is an XML file with the following structure:

<ServerProfile name=””>
	<Connection/>
	<Credential/>
	<Streams>
		<Stream/>
		...
		...
		<Stream/>
	</Streams>
</ServerProfile>

BAM Server Profile Elements
The connection element is used to describe the BAM2 server information. Credential element describes the authentication info to authenticate to the BAM2 server. Under the <Streams> element, many BAM streams can be defined. The following is the structure for a BAM stream definition:

<Stream name="org.wso2.bam.phone.retail.store.kpi" version="1.0.0" nickName="Phone_Retail_Shop" description="Phone Sales">
	<Data>
		<Key name="brand" type="payload">
			<From variable="brand"/>
		</Key>
		<Key name="quantity" type="payload">
			<From variable="quantity"/>
		</Key>
		<Key name="user" type="payload">
			<From variable="user"/>
		</Key>
		<Key name="total" type="payload">
			<From variable="total"/>
		</Key>
	</Data>
</Stream>

A BAM2 <Stream> definition should have the properties, ‘name’, ‘version’, ‘nickName’ and ‘description’. Under the <Stream> element, each of the data items published to BAM is specified using the <Data> element.

<Data>
	<key name=”” type=”payload | meta | correlation”>
		<From variable=”quantity”/>
	</key>
<Data>

The name attribute of the <key> element describes the key used by BAM to identify the given data item and the type attribute describes the type of data item. BAM2 has three types of data. They are meta data, payload data and correlation data. This can be specified using the type attribute. The standard From syntax from BPEL is used to select the value of each key. When selecting a variable to be published to BAM, it can be specified as <From variable=”quantity”/>. The variable name should be the same name used in the BPEL process. The following is a complete example of a BAMServer Profile:

<ServerProfile xmlns="http://wso2.org/bam/2.0" name="BAMServerProfile">
	<Connection enableLoadBalancing="false" url="tcp://127.0.0.1:7611"/>
	<Credential userName="admin" password="kuv2MubUUveMyv6GeHrXr9il59ajJIqUI4eoYHcgGKf/BBFOWn96NTjJQI+wYbWjKW6r79S7L7ZzgYeWx7DlGbff5X3pBN2Gh9yV0BHP1E93QtFqR7uTWi141Tr7V7ZwScwNqJbiNoV+vyLbsqKJE7T3nP8Ih9Y6omygbcLcHzg="/>
	<!-- KeyStore
		location="<BAM_HOME>/repository/resources/security/client-truststore.jks"
		password="CpIZ4fbSj03GQyiNSVUJCbX/6UMJJbaTNOzPKtFlkC0="/-->
	<Streams>
		<Stream name="org.wso2.bam.phone.retail.store.kpi" version="1.0.0" nickName="Phone_Retail_Shop" description="Phone Sales">
			<Data>
				<Key name="brand" type="payload">
					<From variable="brand"/>
				</Key>
				<Key name="quantity" type="payload">
					<From variable="quantity"/>
				</Key>
				<Key name="user" type="payload">
					<From variable="user"/>
				</Key>
				<Key name="total" type="payload">
					<From variable="total"/>
				</Key>
			</Data>
		</Stream>
	</Streams>
</ServerProfile>

Set enableLoadBalancing to "true" with a comma separated urls to publish in multiple BAM receiver nodes.

Receiver URL= tcp://<BAM Receiver -1>:<port>,tcp://<BAM Receiver -2>:<port>,tcp://<BAM Receiver -3>:<port>

eg: <Connection enableLoadBalancing="true" url="tcp://127.0.0.1:7611,tcp://127.0.0.1:7613"/>

Step 3: Run the BPEL Process and publish data to BAM

When developing the BPEL process, the following information should be included in the BPEL process in order for BAM publishing to work. Under the process element in the BPEL script, define the BAM publishing extension.

<bpel:extensions>
	<bpel:extension namespace="http://wso2.org/bps/monitoring/publisher" mustUnderstand="yes"/> 
</bpel:extensions>

Also include the namespace found in http://wso2.org/bps/monitoring/publisher in the process declaration. Now, in the location where you want information published, include the following extension activity section.

<bpel:extensionActivity xmlns:bpel="http://docs.oasis-open.org/wsbpel/2.0/process/executable" xmlns:bam="http://wso2.org/bps/monitoring/publisher">
	<bam:publish bamServerProfile="BAMServerProfile" streamName="org.wso2.bam.phone.retail.store.kpi" version="1.0.0" nickName="kpistore"/>
</bpel:extensionActivity>

The publish element describes the name given to the BAM server profile and the corresponding stream definition to get the configuration data. If all configurations are done correctly, when you run the BPEL process, the data is published to BAM2.

Step 4: Monitoring information via BAM

KPI Monitoring Sample with BPS

The KPI Monitoring Sample with BPS uses the same KPI monitoring toolbox available from BAM. In addition to this, the KPISampleProcess sends out a request to a Service Hosted in App Server. This request may fail sometimes. The BPEL process publishes the received data from the initial invoke and the receive fault information to BAM.

Required products:

BPS
BAM
AS

To setup the sample:

Start BAM without a port offset.
Download and unzip BPS.
Configure the bam publisher extension in the bps.xml file.
Configure a port offset of 5 in carbon.xml for BPS.
Upload KPIProcess.zip BPEL process to BPS.

Now click on the services list and try the KPISampleProcess request.

<p:KPISampleProcessRequest xmlns:p="http://samples.bps.wso2.org">
	<brand xmlns="http://samples.bps.wso2.org">samsung</brand>
	<quantity xmlns="http://samples.bps.wso2.org">1</quantity>
	<total xmlns="http://samples.bps.wso2.org">500</total>
	<user xmlns="http://samples.bps.wso2.org">test</user>
</p:KPISampleProcessRequest>

Send a few request to the BPS process. It would publish this data and the fault data received from salesdata service to BAM.
Configuring KPI Monitoring.
1. Log into BAM,
2. Install KPI_Phone_Retail_Store toolbox.
3. The hive script will be executed in three minute intervals. Hence after some time, you can visit the dashboard to see the visualizations generated based on data sent to the BPEL process.
Conduct Fault Monitoring. In order to monitor the fault information, do the following:
1. An additional hive script should be added to BAM in the analytics section and select Add.
2. Copy and paste the hive script from phone_retail_sale_post_error_script to the text area and save the script.
3. Execute the script. It generates the fault Summary table which contains the processed fault information.
Generate the visualizer gadget.
1. Go to the Tools menu and select Gadget Gen Tool and configure the data source.
  The URL to be used is jdbc:h2:<BAM_HOME>/repository/database/samples/WSO2CARBON_DB;
  configure <BAM_HOME> according the directory where your bam is located.
2. Specify the path according to your setup.
3. The driver class name is org.h2.Driver.
4. The username and password is wso2carbon.
5. Click Next.
6. Specify the SQL statement.
7. Select faultCode and faultCount from faultSummary. You can view the result set from preview SQL results section.
Now the gadget generator shows the UI elements. Select your options and configure the gadget. Fault Against is the fault code that can be configured with this gadget. Once the gadget is configured, copy the gadget URL.
Click the Add Gadget tab and add the gadget to the portal by pasting the gadget URL obtained from the Gadget Gen Tool.
Now it should show the graph that was constructed with the Gadget Gen Tool.
The constructed sample gadget processfault.xml is also uploaded.