[Tutorial] Capturing Events Received via HTTP Requests with WSO2 Business Activity Monitor 2.5.0

Introduction

This sample demonstrates how to configure the WSO2 BAM to capture incoming events via HTTP requests, store those events within the Cassandra and publish them to the message console to view the results.

Prerequisites

To try out the example discussed in this tutorial we will need to meet the following prerequisites;

1. WSO2 Business Activity Monitor 2.5.0 with embedded Cassandra needs to be downloaded. You can download it here.
2. The commands used in this tutorial assumes that the operating system used is a Linux based operating system.

Setting Up the Sample

Configuring and running WSO2 BAM 2.5.0

First we need to start the BAM server. Navigate to BAM_HOME/bin and type the following command: sh wso2server.sh.

Next, we need to prepare the WSO2 BAM 2.5.0 to capture events. Upload the toolbox which will generate an event stream as shown below.

Note: Once created, the stream will be saved within the path /_system/governance/StreamDefinitions.

  
{
  "name": "http_stream",
  "version": "1.0.0",
  "nickName": "Filedata",
  "description": "Event Stream",
  "metaData": [
	{
  	"name": "tenant_id",
  	"type": "INT"
	},
	{
  	"name": "http_method",
  	"type": "STRING"
	},
	{
  	"name": "character_set_encoding",
  	"type": "STRING"
	},
	{
  	"name": "remote_address",
  	"type": "STRING"
	},
	{
  	"name": "transport_in_url",
  	"type": "STRING"
	},
	{
  	"name": "message_type",
  	"type": "STRING"
	},
	{
  	"name": "remote_host",
  	"type": "STRING"
	},
	{
  	"name": "service_prefix",
  	"type": "STRING"
	},
	{
  	"name": "host",
  	"type": "STRING"
	}
  ],
  "correlationData": [
	{
  	"name": "activity_id",
  	"type": "STRING"
	}
  ],
  "payloadData": [
	{
  	"name": "message_direction",
  	"type": "STRING"
	},
	{
  	"name": "service_name",
  	"type": "STRING"
	},
	{
  	"name": "operation_name",
  	"type": "STRING"
	},
	{
  	"name": "message_id",
  	"type": "STRING"
	},
	{
  	"name": "timestamp",
  	"type": "LONG"
	}
  ]
}

Next, create an HTTP Input Adaptor by specifying what type of input the adaptor is to capture.

Figure 01

• Adaptor Name: a unique name to identify the input adaptor
• Event Adaptor Type: http

The creation of the input adaptor will result in the generation of an xml file with the details below;

Figure 02

Note: The xml file is available within wso2bam-2.5.0/repository/deployment/server/inputeventadaptors

Then we need to create an event builder. An event builder converts different input event formats into a uniform format that is supported by the event consumer. To create an event builder, under the InFlow option of the created stream, click on the option “Receive from External Event Stream (via Event Builder)”.

As shown below, within the event builder we specify a topic which will be used when the requests are generated as HTTP requests.

Figure 03

• Event Builder Name: a unique name to identify the event builder
• Input Event Adaptor Name: select the input adaptor created for HTTP from the drop-down list
• Topic: a topic to which the HTTP events are sent

The creation of the input adaptor will result in the generation of an xml file with the details below;



Figure 04

Note: The xml file is available within :/wso2bam-2.5.0/repository/deployment/server/eventbuilders

Running the Sample

We have now explained the basic steps needed to setup the initial configurations for the business activity monitor. Next, we will see how we can perform an easy test to determine whether the configured flow works.

Our aim is to create a request using the curl command and to pass the payload data along with the request. First create an xml file called events.xml and save the file in any location.

  
<events>
	<event>
    	<metaData>
        	<tenant_id>45</tenant_id>
        	<http_method>data1</http_method>
        	<character_set_encoding>data1</character_set_encoding>
        	<remote_address>data1</remote_address>
        	<transport_in_url>data2</transport_in_url>
        	<message_type>data2</message_type>
        	<remote_host>data2</remote_host>
        	<service_prefix>data4</service_prefix>
        	<host>data3</host>
    	</metaData>
    	<correlationData>
        	<activity_id>data5</activity_id>
    	</correlationData>
    	<payloadData>
        	<message_direction>data4</message_direction>
        	<service_name>data2</service_name>
        	<operation_name>data5</operation_name>
        	<message_id>data4</message_id>
        	<timestamp>56783</timestamp>
    	</payloadData>
	</event>
</events>

Next, from the location of the xml file, run the below curl command to generate the required HTTP events.

curl -v -X POST -H "Content-Type:application/xml" [email protected] "https://localhost:9763/endpoints/http_input/http_topic"

Once the events are generated, we need to determine whether BAM has successfully captured and stored those events. To determine this, access the Cassandra data store and check under EVENT_KS to see whether a record with the stream name exists.

As shown below in the diagram, when we generate events via curl, an event keystore is created with the name http_stream within Cassandra;

Figure 05

Once we click on the event_ks named http_stream, the number of events captured will be listed as shown below.

Figure 06

Optionally, to view the messages (events) stored on the Cassandra data store, click on the Message Console option under dashboards to view the events as shown below. This view can be useful if the users do not have access to the Cassandra data store.

Figure 07

How does it work?

In the previous section we have discussed how to configure and test the WSO2 Business Activity Monitor 2.5.0 with HTTP events. In this section lets see what happens when the test is conducted.

As explained above, upon the execution of the curl command with an xml payload, the message is passed via the input adaptor and is processed by the event builder based on the topic of the message. If the messages are generated in xml format and if the messages match the stream definition and the topic name, they are accepted and stored in the Cassandra data store.

Conclusion

This tutorial explained how to configure the WSO2 Business Activity Monitor version 2.5.0 to capture and process HTTP events. The tutorial initially focused on configuration that is needed to get the system ready and then looked at how the flow can be tested to understand how WSO2 BAM supportsHTTP event processing.

All artefacts for this tutorial are available for download here.

References

[1] https://wso2.com/products/business-activity-monitor/