Introduction

You can use CEI in IBM® WebSphere® Business Integration Server Foundation V5.1.1 (Business Integration Server) to create and distribute events in a uniform fashion, as well as to retrieve and query these events. Events are typically used to emit the business-process-related information, which you can use to calculate business process metrics or KPIs. In Part 1 of this series, we introduced an on demand business process scenario for an Order to Manufacturing Processing System (OTMPS), with the following KPIs:

• Average order throughput. Total number of orders processed/Total time taken
• Success ratio. Number of process instances that ended successfully/Total number of process instances
• Number of invalid orders. Total number of orders that failed validation
• Average problem resolution time. Average time, in seconds, taken to correct a system's failure

In this paper, we show you how to document the KPIs for the business processes in WebSphere Business Integration Modeler V5.1 (Business Integration Modeler) and create the corresponding events in Business Integration Server. In Business Integration Server, you can create events using any of the following:

1. CEI APIs
2. Event Correlation Spheres (ECS) APIs
3. State Observer Plugin (SOP)
4. Deployment descriptor (DD) extensions for Enterprise JavaBeans (EJB)

We also highlight the pros and cons of these four options.

Back to top

Document KPIs in the process model

As illustrated in Part 3 of this series, an analyst documents the business process KPIs using Business Integration Modeler.

For example, Figure 1 shows a KPI "Number of orders received each hour" and the corresponding observation points (for example, in the figure we selected Input Criteria and Output Criteria as observation points). Observation points are the points in a process (tasks, subprocesses, variables, and loops) where measurements are needed to validate the KPI. This specific KPI is associated with the "Order Process Subsystem" task in the process model. This KPI documentation assists you in generating the correct artifacts in the development environment. Table 1 illustrates the KPIs that the analyst specifies for the OTMPS scenario, their descriptions, and the corresponding observation points in the process model.

In a later section we will show you how these observations points are transferred into executable workflow code using event creation facilities available with the Business Integration Server. These KPIs specified in Business Integration Modeler are later used to monitor the business performance from the events generated from the workflow code. Part 8 of this series will describe how we use these KPI specifications to create an object model to capture the required metrics.

Back to top

Create events

Business Integration Modeler can export a business process model in the BPEL form, which can then be imported into Business Integration Server to create an executable workflow (see Part 4 of this series). For the KPIs and observation points documented in Business Integration Modeler, you have to add some code or configure the generated workflow to create the required events at the required places. In this section, we briefly describe the Common Base Event (CBE) model and Common Event Infrastructure (CEI). We also discuss the different approaches that you can use to create events and show you how we created events corresponding to OTMPS KPIs.

Common Base Event Model

The Common Base Event (CBE) model is a standard, developed by the IBM Autonomic Computing Architecture Board, that defines a common representation of events in an XML format. For a detailed discussion on the CBE model V1.0.1 refer to "Standardize messages with the Common Base Event model" in the Resources section.

Common Event Infrastructure

Common Event Infrastructure (CEI) is a set of modular components that provides support for generation, propagation, persistence, and consumption of events. These events are represented using the CBE model. CEI currently supports V1.0.1 of the CBE model described above.

CEI is available in Business Integration Server. Within Business Integration Server Foundation, CEI provides the following facilities (refer to the Business Integration Server Foundation Information Center -- "Using the Common Event Infrastructure" in the Resources section for more details):

• Run-time environment. CEI provides the run-time environment for propagation, persistence, query and distribution of events. The run-time environment consists of two J2EE applications -- event-application.ear and event-message.ear. These applications need to be successfully deployed before other applications can use CEI.
• Administration environment. An administrator can configure the CEI run-time environment. Using the Admin Console, an administrator can start and stop the CEI Service, start and stop the Application Events Service, create and update Emitter Factory Profiles, and create and update Event Groups.
• An Event Browser. CEI includes an event browser application -- a CBEViewer.ear file that can be used to view the events that the CEI stores.

Use CEI to emit events

CEI provides the standard interfaces and services for WebSphere applications to create and emit event objects.

Steps for this task (for more details on each step, refer to "Using the Common Base Event in the Common Event Infrastructure" and "Emitting events using the WebSphere Event Programming Model" in the Resources section):

1. Create event -- create a CBE using an events factory.
2. Add data (optional) -- add ExtendedDataElement to the event.
3. Add context (optional) -- add ContextDataElement to the event.
4. Get emitter -- get an emitter from an emitter factory.
5. Send the event -- send the event using the emitter.
6. Free the emitter resources -- close the emitter.

CBE has some mandatory properties, for example, version (a string attribute), creationTime (a dateTime attribute), sourceComponentId (ComponentIdentification element), and Situation (Situation element). Business Integration Server provides a content handler that automatically fills in these event properties. This content handler is associated with the default events factory provided by Business Integration Server. In other words, Business Integration Server automatically adds the system-specific information to the events created using the default events factory. An application can also define an application-specific content handler and associate it with an events factory. However, only one content handler can be associated with an events factory. One workaround is to use a utility class that acts as a facade on top of the CEI and adds the application-specific information, for example, application name, to the events prior to invoking sendEvent(), which invokes the content handler. The Business Integration Server content handler does not overwrite the information that the application adds.

Listing 1 shows the sample code for such a utility class, and Listing 2 shows its usage from a Java snippet in a BPEL workflow. Complete code is available in the Download section (click the code icon at the top or bottom of this paper to download the code sample).

public class EventHandler {
	private static String emitterFactoryLookup = 
"com/ibm/events/configuration/emitter/Default";
	private static String eventFactoryLookup = 
"com/ibm/websphere/events/factory";
	private static String property1 = "NumberOfOrders";

	
	public static EventHandler eINSTANCE = new EventHandler();
	
	private EventHandler() {

			// Get an EmitterFactory
			// Get an emitter from the EmitterFactory
			// Get an EventFactory

	}

	public void sendEvent (String eventName, String msg, Object data, 
String context) {
		try {
			// create CBE using event factory
			CommonBaseEvent event = 
eventFactory.createCommonBaseEvent(eventName);

			// add application specific information to event
			if (data != null) {
				Order [] orders = (Order [])data;
				event.addExtendedDataElement(property1, 
String.valueOf(orders.length));
			}

			if (context !=null) {
				event.addContextDataElementWithValue("string", 
"OTMPS Process", context);
			}

			event.setMsg(msg);
			
			ComponentIdentification sourceComponentId = 
eventFactory.createComponentIdentification();
	sourceComponentId.setComponentIdType(ComponentIdentification.COMP
ONENT_ID_TYPE_APPLICATION);
			sourceComponentId.setApplication("OTMPS");
			event.setSourceComponentId(sourceComponentId);

			// send event using emitter
			emitter.sendEvent(event, SynchronizationMode.DEFAULT, 
TransactionMode.NEW);
		} catch(Exception ex) {
			ex.printStackTrace();
		}
	}
}

EventHandler.eINSTANCE.sendEvent("OTMPSStartEvent", "OTMPS started by "+userName, 
orders, this.activityInstance().getProcessInstanceID().toString());   

Use ECS to emit events

Business Integration Server has extended CEI by adding an Event Correlation Sphere (ECS) facade to it, which provides access to CEI through an ECSEmitter class. Compared to CEI APIs, the advantage of using ECSEmitter is that it preserves the event context. ECSEmitter automatically adds two context elements -- the current and parent context -- to the events that are sent using this emitter. For example, if a sub-process emits an event, then the current context refers to the sub-process instance, and the parent context refers to the instance of the main process (for more details refer to "Information Center -- Creating and populating an event using the ECSEmitter class" in the Resources section). ECSEmitter also provides an API to create data events. Data events are used to emit additional data information. For example, an OTMPSStartEvent represents a start situation, but an OrderDataEvent does not indicate any situation and is only used to emit order data handled by OTMPS.

Steps for emitting events using ECSEmitter (for more details on each step, see "Information Center -- Creating and populating an event using the ECSEmitter class" in the Resources section):

1. Create ECSEmitter -- create an instance of ECSEmitter by specifying the events factory to use and, optionally, the new context id.
2. Create event -- create a CBE using ECSEmitter.
3. Add data (optional) -- add ExtendedDataElement to the event.
4. Create data event (optional)-- Create a data event using ECSEmitter.
5. Send the event -- send the event using the ECS emitter.
6. Free emitter resources -- close the emitter.

ECSEmitter makes it easier to emit and correlate events, but it does not address the single content handler limitation of CEI that we discussed earlier. Therefore, you still need a utility class if you want to add application-specific information to the events. Listing 3 shows the utility class for ECS. In this case, we are not specifying a new context id for the ECSEmitter because Business Integration Server automatically sets the current and parent context ids for the business process when a process starts.

public class EventHandler {
	private static String emitterFactoryLookup = 
"com/ibm/events/configuration/emitter/Default";
	private static String eventFactoryLookup = 
"com/ibm/websphere/events/factory";
	private static String property1 = "NumberOfOrders";
	
	public static EventHandler eINSTANCE = new EventHandler();
	
	public void sendEvent (ECSEmitter emitter, String eventName, 
String msg, Object data) {
		CommonBaseEvent event = null;
		try {
			// create a new ECS emitter
			ECSEmitter emitter = new 
ECSEmitter(emitterFactoryLookup, null);

			// create a CBE using ECS emitter
			event = emitter.createCommonBaseEvent(eventName);

			// add application specific information to event

			// send event using ECS emitter
			emitter.sendEvent(event, SynchronizationMode.DEFAULT, 
TransactionMode.NEW);
		} catch(Exception ex) {
			ex.printStackTrace();
		}
	}
	
	public void sendDataEvent (Object contextData) {
		try {
			// create a new ECS emitter
			ECSEmitter emitter = new 
ECSEmitter(emitterFactoryLookup, null);

			// create and send data event using ECS emitter
			if (contextData != null) {
				Order [] orders = (Order [])contextData;
				Properties properties = new Properties();
				properties.setProperty(property1, 
String.valueOf(orders.length));
				emitter.addUserDataEvent(properties);
			}
		} catch(Exception ex) {
			ex.printStackTrace();
		}
	}
}

Use SOP to emit events

State Observer Plugin (SOP), provided by Business Integration Server, automatically emits the appropriate events corresponding to the processes, activities, variables, and so on, that are marked as "BusinessRelevant" in BPEL. For example, if a process is marked as "BusinessRelevant," as shown in Figure 2, SOP generates two ProcessInstance events, one for StartSituation and another for StopSituation (see "Information Center -- Monitoring business processes using common base events" in the Resources section).

This approach is easiest to use and is expected to integrate seamlessly with the busines performance monitoring tools. However, it does not allow the applications to directly add data to the events. It generates separate events for variables. An event correlation is required to find the data corresponding to an activity or process.

Figure 3 shows all of the events that can be generated from a BPEL flow. Table 2 shows the details of some of these events. The events that SOP generates are of different types, for example, WPC:ProcessinstanceEvent, WPC:ActivityinstanceEvent, and WPC:VariableEvent. These events are further categorized by the situations, for example, WPC:ProcessinstanceEvent can be used in case of Start, Stop, Destroy, or Fail situations. Same situations can also be used to represent different conditions, for example, Stop situation can be used to represent successful or unsuccessful completion.

An event data represents a unique combination of type, situation, and condition. Events that SOP generates are generic in nature. It is difficult to query and correlate these events. You have to look at the extendDataElements or contextDataElements to differentiate one event from another. For example, in order to find which process created a particular event, you have to look at the ExtendedDataElement "processTemplateName." To add to the complexity, some of the extendedDataElements are only available with the first event emitted for a process/activity. For example, ExtendedDataElement "processTemplateName" is only available for the start event, and you have to use the contextDataElements to find the corresponding stop event. Another limitation of SOP is that it uses the toString() function to serialize the variables and therefore cannot be used for complex variables by default.

Use DD extensions to emit events

Business Integration Server also provides a way to create events corresponding to the start and end of EJB methods by using the Deployment Descriptor (DD) extensions. For example, as shown in Figure 4, OrderProcessSystemBean's sendOrderProcessSystem_InputCriteria method is configured to generate an event before that method call. For details on how to set the common base event deployment attributes for an enterprise bean, refer to "Information Center -- Setting EJB module common base event deployment attributes" in the Resources section.

This approach is very useful for capturing EJB-related events. However, for business processes with generated EJB code, it is difficult to identify the appropriate methods. Also these deployment descriptors are overwritten every time the deployment code is generated for the BPEL.

Table 3 summarizes the advantages and disadvantages of each approach.

Emit events for OTMPS

We decided to use SOP for emitting events. Our primary reason was that events that SOP generates are expected to seamlessly integrate with the future monitoring tools. In addition, we don't need to create the data events for complex variables, and, in our opinion, the advantages of using SOP outweigh the need to correlate the variable events with the process and activity events. For details on how to correlate the events that SOP generates, watch for Part 8 of this series.

As shown in Figure 2, we marked the following BPEL processes and variables as "BusinessRelevant."

• OrderProcessSystem
  • OrderProcessSystem process
  • numberOfOrders variable
  • numberOfInvalidOrders variable
• ExceptionHandler
  • ExceptionHandler process

(See

of this series for details about different processes.)

Back to top

Acknowledgements

The authors would like to thank Eric D. Wayne, Dr. German Goldszmidt, Wilfred C. Jamison, and Tai W. Nam for reviewing this paper.

Back to top

Conclusion

In this paper, the authors showed you different options for emitting events and concluded that, though it is difficult to correlate the events that the State Observer Plugin (SOP) generates, it is still the best approach to use for business processes that are modeled using WebSphere Business Integration Modeler V5.1. However, the variables that are marked as "BusinessRelevant" must be simple data types. In the next paper, the authors will demonstrate how to receive the events and correlate them. They will illustrate how they use the KPI specifications documented in this paper to create an object model to capture the required metrics.

Back to top

Download

Information about download methods

Resources

• Read all parts of the On demand business process life cycle, and keep track as we add new installments.
  
  
• Learn more from the following InfoCenters and Redbooks, which provide excellent resources on the Common Base Event model and using the Common Event Infrastructure:
  1. Information Center for WebSphere Business Integration Server Foundation -- Using the Common Event Infrastructure.
  2. Standardize messages with the Common Base Event model, David Bridgewater, IBM developerWorks, 17 Feb 2004
  3. Using the Common Base Event in the Common Event Infrastructure, Amanda Watkinson, IBM devleoperWorks, 04 Aug 2004
  4. Emitting events using the WebSphere Event Programming Model Technical Preview, Andy Brodie, IBM developerWorks, 11 Aug 2004
  5. Information Center for WebSphere Business Integration Server Foundation -- Creating and populating an event using the ECSEmitter class
  6. Information Center for WebSphere Business Integration Server Foundation -- Monitoring business processes using common base events
  7. Information Center for WebSphere Studio Application Developer Integration Edition -- Setting EJB module common base event deployment attributes
  
  
  
• Get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®. You can download evaluation versions of the products at no charge, or select the Linux® or Windows® version of developerWorks' Software Evaluation Kit.
  
  
• Browse for books on these and other technical topics.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• The IBM developerWorks team hosts hundreds of technical briefings around the world which you can attend at no charge.
  
  
• Want more? The developerWorks SOA and Web services zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Document KPIs in the process model
• Create events
• Acknowledgements
• Conclusion
• Download
• Resources
• About the authors
• Comments

Dig deeper into SOA and Web services on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers