Use the instructions in the following sections to monitor a business process with WSO2 Data Analytics Server (DAS).
Business process data can be monitored with WSO2 DAS. In order to specify which configuration and data is to be monitored, BPS uses a configuration file called AnalyticsProfile. This file is included within the BPEL package.
Configure the DAS publishing extension
Add the following extensionActivity to the bps.xml file, which is located in the <BPS_HOME>/repository/conf/ directory.
<tns:ExtensionBundles>
<tns:runtimes>
<tns:runtime class="org.wso2.carbon.bpel.analytics.publisher.AnalyticsPublisherExtensionBundle"/>
</tns:runtimes>
</tns:ExtensionBundles>
Create the BPEL process to publish data to DAS
To create the BPEL process, do the following.
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 must specify the BPEL process in the deploy.xml file (deployment descriptor file for a BPEL package). The analytics server profile is specified as follows:
<analyticsServerProfiles>
<profile name="AnalyticsServerProfile" location="file:AnalyticsServerProfile.xml"/>
</analyticsServerProfiles>
The analyticsServerProfiles element must come under the process element in deployment descriptor (deploy.xml). The following is an example of a deployment descriptor configuration.
<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>
<analyticsServerProfiles>
<profile name="AnalyticsServerProfile" location="file:AnalyticsServerProfile.xml"/>
</analyticsServerProfiles>
</process>
</deploy>
The ‘file:‘ value in location is used to specify a file path. Similarly, the analytics server profile can be kept in the WSO2 registry as well. If the Analytics server profile file is stored in configuration registry, it can be referred to as conf:<resource path>. Similarly, if the Analytics server profile is stored in the Governance Registry, it can be referred to as gov:<resource path>.
Create the Analytics server profile
Analytics server profile is an XML file with the following structure.
<ServerProfile name=””>
<Connection/>
<Credential/>
<Streams>
<Stream/>
...
...
<Stream/>
</Streams>
</ServerProfile>
The Connection element is used to describe the analytics server information. The Credential element describes the authentication info to authenticate to the analytics server. Under the Streams element, many analytics streams can be defined. The following is the structure for an analytics 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 DAS Stream definition must have the properties: ‘name’, ‘version’, ‘nickName’ and ‘description’. Under the Stream element, each of the data items published to the analytics server 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 analytics server to identify the given data item and the type attribute describes the type of data item. Analytics server 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 DAS, 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 an AnalyticsServer Profile.
<ServerProfile xmlns="http://wso2.org/analytics/3.0" name="AnalyticsServerProfile">
<Connection secure="false" ip="127.0.0.1" authPort="7711" receiverPort="7611"/>
<Credential userName="admin" password="kuv2MubUUveMyv6GeHrXr9il59ajJIqUI4eoYHcgGKf/BBFOWn96NTjJQI+wYbWjKW6r79S7L7ZzgYeWx7DlGbff5X3pBN2Gh9yV0BHP1E93QtFqR7uTWi141Tr7V7ZwScwNqJbiNoV+vyLbsqKJE7T3nP8Ih9Y6omygbcLcHzg="/>
<!-- KeyStore
location="<DAS_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>
Run the BPEL Process and publish data to Analytics server
When developing the BPEL process, the following information must be included in the BPEL process for DAS publishing to work. Under the process element in the BPEL script, define the DAS 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 analyticsServerProfile="AnalyticsServerProfile" 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 Analytics 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 Analytics server.
Monitoring information via DAS
The KPI Monitoring Sample with BPS submits event information to the Analytics server.
The following are the required products.
- WSO2 BPS
- WSO2 DAS
To setup the sample, do the following.
- Start DAS without a port offset.
- Download and unzip BPS.
- Configure the
bps.xmlfile in the<BPS_HOME>/repository/confdirectory by adding the DAS publishing extension mentioned in Configure the DAS publishing extension. - Configure a port offset of 5 in the
<BPS_HOME>/repository/conf/carbon.xmlfile. - Upload the KPISample.zip BPEL process to BPS.
Click on the services list and send a KPISampleProcess request as mentioned below using tryit editor.
<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 to DAS and deploy a new stream definition with id ‘org.wso2.bam.phone.retail.store.kpi:1.0.0’.
Commence KPI Monitoring. To do this, do the following.
- Log into DAS.
- Click on Streams under the Manage tab to check the created stream definition.
Click Edit under the Actions column. This will show all the information of the event stream. Do not change anything here for this sample. It will change the stream.
You need to persist the data received from the BPEL process in order to analyse it. Click on the ‘Next[Persist Event]’ button at the bottom.
Select whatever data you need to persist from here and click Save Event Stream.
You must add an event receiver to populate the table you created with data received from the BPEL process. To do this, do the following.
Click on Receivers under the Manage tab.
Click on Add Event Receiver. The following form appears.
Fill the form with following information.
Event Receiver Name: <proper name>
Adapter type: wso2event
Event stream: org.wso2.bam.phone.retail.store.kpi:1.0.0
Message format: wso2event
Submit the form to create new event receiver from BPS.
Now you have setup the infrastructure to receive and analyse event information from BPS. Create a dashboard to visualize the KPI data.
Create a new Dashboard in DAS as instructed in Adding a Dashboard.
Follow the instructions in the ‘Adding a gadget using the gadget generation wizard’ section in the Adding Gadgets to a Dashboard topic. Select ‘ORG_WSO2_BAM_PHONE_STORE_KPI’ as the datasource here. You can create different types of charts and use different data combinations here.
Add the new gadget to your dashboard.
Now you can visualise the event information using the Analytics Dashboard. Try sending more requests to the BPEL process and note the changes in charts.