Introduction

This article, the fifth in our series, focuses on the event infrastructure in IBM WebSphere Business Integration Server Foundation 5.1.1. The event infrastructure enables business processes to emit business events that can later be observed by consumers who want to analyze the behavior of the business. The application supplies business data, providing information such as who did what and when. For example, in a purchase order application, the business data could contain the order id, the order and the ship date. WebSphere Business Integration Server Foundation fills in the runtime environment with information such as the server name, middleware component details, the process and thread IDs, and so on. The event infrastructure in WebSphere Business Integration Server Foundation for business events is based on the Common Event Infrastructure (CEI). CEI is a common component currently in the process of being adopted by all IBM systems and middleware. Information about an event is stored in an event object. The event object uses a standard format called the Common Base Event (CBE), which has been submitted to Organization for the Advancement of Structured Information Standards (OASIS) (see Resources).

This article shows you how a Business Process Execution Language (BPEL) process can create events that can be consumed by other entities using the event infrastructure in WebSphere Business Integration Server Foundation. As in the previous articles in this series, we use the odFinance personal loan scenario as an example.

Back to top

Enable the personal loan application to generate business events

The simplest way to emit events from your BPEL process is to use the BPEL editor in WebSphere Studio Application Developer Integration Edition (Application Developer). Without writing any Java™ code, you can check the Business Relevant flag on any activity, which causes predefined events to be emitted. For example, a start event is emitted when the activity starts, and a completed event is emitted when the activity finishes. Figure 1 shows the Business Relevant flag for the createApplication activity of the odFinance personal loan BPEL process.

Back to top

Set up the unit test server configuration

To view or consume the events emitted by your BPEL process in the unit test environment (UTE) of Application Developer, after installing the product, you must select the Install embedded messaging client and server option from the installation Launchpad window.

To create a server instance enabled for CEI, you need to do several additional steps:

1. Enable CEI in the server instance. When creating a new server instance, check Enable the Common Event Infrastructure, as shown in Figure 2.
   Figure 2. Enable CEI using UTE
   
   
2. To configure the Java Messaging Service (JMS) Provider, go to the JMS page. Select Embedded Messaging, as shown in Figure 3.
   Figure 3. Selecting embedded messaging
   
   
3. To set the variables, go to the Variables page and update the following variables:
   • MQ_INSTALL_ROOT to point where WebSphere MQ is installed.

     (For example, MQ_INSTALL_ROOT = C:\Program Files\IBM\WebSphere MQ)

   • WAS_PUBSUB_ROOT to point where the WebSphere-embedded Publish and Subscribe are installed.

     (For example, WAS_PUBSUB_ROOT = C:\Program Files\IBM\WebSphere MQ\WEMPS)

4. Enable security (Optional). If you're using staff activity, make sure you go to the Security page, check the Enable security box, and set up the server ID to a valid user ID on your system. You also need to make sure all the user IDs in the Java Authentication and Authorization Service (JAAS) authentication entries have the correct password.

   For example, you may want to modify the user ID for the Business Process Engine (BPE) and CEI authentication entries, as shown in Figure 4. If you are using an ID that is different from admin, make sure you choose Edit BPEContainer Deployment Descriptor on the server instance, and update the default user settings for BPESystemAdministrator, WebClientUser, and JMSAPIUser.

   
   Figure 4. Enabling security
   
   

Back to top

Use the built-in event browser

After running your personal loan business process, you can use the built-in event browser to review the generated events. To launch the built-in event browser, select Launch CBE Event Browser from the server configuration. Enter a valid date range, and click Get data to retrieve all the CBE events that are generated over the range you specified.

As shown in Figure 5, the event browser shows an event for the CreateApplication activity. WebSphere Business Integration Server Foundation populates the CBE fields with important information about each activity when Business Relevant is selected. Some of the fields are common to all activities. For example, creationTime is always set to the UTC timestamp when the event is created. Other fields, such as ContextDataElement and ExtendedDataElement, are context sensitive. They can contain process instance or activity information depending on what object it is emitted from.

Back to top

Develop your own event consumers

Now that your BPEL process can send events where you specified (in this case, in the CreateApplication activity of the PersonalLoan) and you're able to view the events that are being emitted, you can develop your own event consumers to retrieve these events. Events that are generated are stored in the event data store. In the UTE, the event data store is defaulted to the embedded IBM Cloudscape™ database. You can retrieve these events in two different ways.

• Retrieving events directly from the event data store

  Query the event data store directly using an EventAccess bean instance. Use this approach only when you need to access historical events. No additional configuration is required. The code snippet in Listing 1 shows how to do this programmatically.

  Listing 1. Simple Java™ snippet to query events from the CEI data store
  

  (1) // Create an EventAccess bean (2) InitialContext context = new InitialContext(); (3) eventAccessHomeObj = context.lookup("ejb/com/ibm/events/access/ EventAccess"); (4) EventAccessHome eventAccessHome = (5) (EventAccessHome) PortableRemoteObject.narrow( (6) eventAccessHomeObj,EventAccessHome.class); (7) eventAccess = (EventAccess) eventAccessHome.create(); (8) (9) // Query the event data store. The default event group is "All events" and the (10)// xpath defines the event selector in xpath format (11) CommonBaseEvent results[] = eventAccess.queryEventsByEventGroup ("All events", xpath, true);

  
  

  Lines 2 to 7 show the traditional way of creating an instance of a remote bean. In this case, CEI requires that we create an instance of the EventAccess bean, which comes with the infrastructure. You can use several methods from EventAccess to actually retrieve events (see Resources).

  In line 11, we used the queryEventsByEventGroup using the default event group All events. (See Create event groups for more information.) The path parameter is used to filter out specific events from the event group we're interested in. As implied, the filter is expressed using the XPATH syntax. The third parameter specifies whether we want the results to be in ascending order or not (based on creation time of the events). The method returns an array of CommonBaseEvent objects.

• Retrieving events from topics and queues

  Develop a message-driven bean (MDB) to retrieve events from topics and queues using a NotificationHelper bean. Use this approach if you want to retrieve events as they arrive. You must add a Listener Port, as shown in Figure 6, for the queues or topics, and associate the MDB with the Listener Port.

  
  Figure 6. Add a Listener Port for the MDB
  
  

  Listing 2. Implementation of onMessage method for an MDB that listens to CEI events
  

  (1) public void onMessage(javax.jms.Message msg) { (2) InitialContext context; (3) try { (4) // Create a NotificationHelper bean (5) context = new InitialContext(); (6) Object notificationHelperFactoryObject = context.lookup ("com/ibm/events/NotificationHelperFactory"); (7) NotificationHelperFactory nhFactory = (NotificationHelperFactory) (8) PortableRemoteObject.narrow(notificationHelperFactoryObject, NotificationHelperFactory.class); (9) NotificationHelper nh = nhFactory.getNotificationHelper(); (10) int msgType = nh.getNotificationType(msg); (11) if(msgType == NotificationHelper.CREATE_EVENT_NOTIFICATION_TYPE) { (12) CommonBaseEvent event = nh.getCreatedEvent(msg); (13) } (14) } catch (NamingException e) { (15) e.printStackTrace(); (16) } catch (EventsException e) { (17) e.printStackTrace(); (18) } (19) }

  
  

  Again, lines 5 to 8 show the traditional way of creating a remote instance of the NotificationHelperFactory. Because it is just a factory object, line 9 is needed to actually get an instance of the NotificationHelper bean. The best practice is to put lines 5 to 9 outside of this method, since they only need to be executed once and make the reference to the NotificationHelper global in the class.

  First, we need to test which type of message has been received by the method. Currently, there are only 2 types of events by CEI for event distribution: CREATE_EVENT_NOTIFICATION_TYPE and UNKNOWN_NOTIFICATION_TYPE. However, there will be more types in the future, so it's good practice to perform the test if the message is of type CREATE_EVENT_NOTIFICATION_TYPE. Remember, all events that go through a distribution queue or topic are of this type. Line 12 essentially converts the received message into a CommonBaseEvent object.

Both Listing 1 and Listing 2 are bare code for retrieving the events. In reality, some additional code has to be written to process the events retrieved, but they definitely depend on what the consumer program would like to achieve. Click the top-right code icon to download a complete example on how to develop your own event consumers.

Back to top

Use event groups

An event group defines a logical collection of events based on their contents. This is a convenient way of filtering out events and later retrieving events only from that group, either directly or by associating that event group to one or more distribution queues and topics. To create an event group, you need to set up an event group profile. When the event server receives an event, the event is matched against all the event groups. If a match is found, a notification is sent to any JMS topic or queues configured for that particular event group. Similarly, an event consumer can invoke the eventAccess.queryEventsByEventGroup() API with a specific event group name to retrieve only events in that group, as shown in the previous section.

See Create event groups to learn how to create an event group using the WebSphere Business Integration Server Foundation 5.1.1 server.

Back to top

Install CEI on WebSphere Business Integration Server Foundation 5.1.1

To deploy a CEI-enabled BPEL process on to WebSphere Business Integration Server Foundation 5.1.1 you need to make sure that CEI is installed on WebSphere Business Integration Server Foundation. The white paper Using the Common Event Infrastructure provides detailed instructions on configuring CEI on the server. There are two mandatory steps that you need to follow:

1. Configure the event database.

   The two databases used by CEI are the event data store and the event catalog. Scripts have been provided to create the CEI data sources for Cloudscape, DB2, and Oracle. They are in %WAS_HOME%/event/dbconfig. The example in Figure 7 shows a DB2 database.

   
   Figure 7. CEI data sources
   
   
2. Install the CEI application that implements the event server.

   The CEI application is packaged as event-application.ear and is in %WAS_HOME%\event\application. You can run the event-application.jacl script to install this application. The default name for the event server application is CommonEventInfrastructureServer, as shown in Figure 8.

   
   Figure 8. CEI event server application
   
   

If you plan to use event distribution (for example, use MDB as event consumers), you'll need to create a JMS queue and queue connection factory, or topic and topic connection factory. They are then associated with an event group. There is a default event group called "All events" that covers all events that arrive to and transmitted by CEI. You can define your own event group using the steps in the next section.

Back to top

Create event groups

To create an event group, you need to create a group profile. To do this using the Adminstration Console:

• Follow Resources > Common Event Infrastructure Provider.
• Make sure that you are currently in the Cell scope.
• Under Additional Properties, follow Event Group Profile List > Event groups list > Event Group Profiles.
• Click New to create a new event group.

Figure 9 shows a sample event group that we created for the odFinance personal loan called odFinance Events. The Event Selector String field is the most important in this panel because that's how we're going to describe which events belong to this event group. The syntax used to specify the selector string is the XML Path Language (XPath). (For more information on XPath, see Resources.)

For our case, the selector string we specified is:

 
CommonBaseEvent[sourceComponentId/@subComponent = "WPC" and @extensionName
= WPC:ProcessInstanceEvent"]

This event group includes all events that were created only by WebSphere Process Choreography, as signified by WPC. It only includes those events that pertain to ProcessInstanceEvent. Optionally, you can associate this event group to one topic (in that case, you'd complete the Topic fields in Figure 9), or you can associate it to one or more distribution queues. We chose a distribution queue for which we had to create a JMS queue connection factory and a destination queue. You associate the queues by clicking the Distribution queues link. As mentioned, these associations automatically route all events that belong to this event group to those topics and queues.

For all of these to work, event distribution must be enabled in CEI. To do this, follow Resources > Common Event Infrastructure Provider > Event Server Profile > Default Common Event Infrastructure event server. On that panel, make sure to click Enable Event Distribution.

Back to top

Summary

This article provides a bird's eye view of the CEI enablement of the WebSphere Process Choreography component in WebSphere Business Integration Server Foundation 5.1.1. It shows how you can use WebSphere Studio Application Developer to produce events from your BPEL business process and how you can consume the generated events. We also showed how you to set up CEI in both the unit test and server environment. Armed with this basic knowledge, you can now explore the more advanced techniques to produce events by using the Java API directly or by configuring the Enterprise JavaBeans (EJB) components deployment descriptor. Similarly, you can also explore using JMS topics and queues to make it easier to filter and consume events.

Back to top

Stay tuned

Upcoming articles in this series focus on WebSphere Extended Deployment, an exciting enhancement to the WebSphere software family of products. WebSphere Extended Deployment provides enhanced quality of services in the areas of operations, adminstrations, performance, and high availability. You'll find out how to use WebSphere Extended Deployment to manage large-scale, continuously available environments such as odFinance. You'll also learn about the core proposition of business performance management; we'll show you how you can understand and adapt your business processes and IT infrastructure to continuously improve your business. We also introduce you to IBM Tivoli® Business Systems Manager and show you how you can to create a single operation view of your business and IT systems, enabling you to perform root-cause analysis.

Back to top

Download

Information about download methods

Resources

• Visit the Series overview page to see the current list of articles in this series.
  
  
• Download the WebSphere Business Integration Server Foundation, Version 5.1.1 white paper Using the Common Event Infrastructure, which includes information relating to technology preview code.
  
  
• WebSphere Studio Application Developer Integration Edition V5.1.1 provides an overview, and links to features and benefits system requirements, the library, success stories, news and more.
  
  
• Download the specification from Specification: Common Base Event.
  
  
• Read more about XML Path Language (XPath) Version 1.0.
  
  
• Organization for the Advancement of Structured Information Standards (OASIS) has a wealth of information about this not-for-profit global consortium.
  
  

About the authors

Christina Lau is a Senior Technical Staff Member at IBM. Christina is an architect on the On Demand Development team focusing on next-generation technologies for the IBM On Demand Operating Environment. You can reach Christina at clau@ca.ibm.com.

Dr. Jamison currently works on incubation projects for the IBM On Demand Development and Strategy team. He is an expert of Performance Analysis/Engineering for J2EE applications and has numerous publications and presentations on the subject matter. He is currently working on Business Process Management for On Demand Systems. You can reach him at wjamison@us.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Enable the personal loan application to generate business events
• Set up the unit test server configuration
• Use the built-in event browser
• Develop your own event consumers
• Use event groups
• Install CEI on WebSphere Business Integration Server Foundation 5.1.1
• Create event groups
• Summary
• Stay tuned
• Download
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community