Introduction

WebSphere® Integration Developer and WebSphere Process Server introduced Common Event Infrastructure (CEI) as a way of providing basic event management services. CEI processes Common Base Events (CBEs) as defined by the CBE specifications. CEI provides a standard XML-based format for events, which enables generic mechanisms to both log and query events. Built-in support for CEI in WebSphere Integration Developer generates CBE events. For example, you can select a Business Process Execution Language (BPEL) activity and then select activity-started or activity-stopped events, which automatically generate CBEs. However, you might need to generate business-level events that do not correspond to WebSphere Integration Developer events. You can use the Business Process Engine (BPE) API for this. However, because this API exposes the CBE format as well as other CEI-specific attributes, the relevant parts of the API are contained in an easy-to-use set of artifacts that support logging, querying, and viewing events. This article explains these artifacts and how to use them in a composite application.

Capturing business-level events

In order to measure a composite application, you need to capture business-level events. Business-level events are events that capture information relevant to a business. For example, an event is logged when bank funds transfer from one account to another. Business-level events help us understand and improve how an enterprise does business. After business events are logged, you can aggregate them to identify business trends, which, in turn, can provide the needed measurement to improve the business. However, business-level events do not necessarily correlate to any specific WebSphere Integration Developer activity. A WebSphere Integration activity can correspond to a series of WebSphere Integration Developer steps. Figure 2 shows some typical WebSphere Integration Developer activities. A business-level event can correspond to a series of WebSphere Integration Developer activities.

Another requirement to be fully measurable is the capability to persist arbitrary data in an event. This arbitrary data has meaning at a business level. The CBE specification supports persisting arbitrary data using the ExtendedDataElement section of the CBE. This section formats application-specific data as a set of name value pairs.

Back to top

Generating CBE events

Each type of monitorable component, such as business processes, business rules, and so on, has a set of predefined business events in WebSphere Integration Developer (see Table 1). However, sometimes these predefined events do not provide the flexibility to generate business-level events. Therefore, to provide your composite application with the capability to be fully measurable, you need to generate business-level events any time.

Note: In Table 1, the events identified as Audit Log are generated as audit events in the process choreographer database. The events identified as CEI are generated in the CEI data store.

Back to top

Viewing CBEs

There are two options available to retrieve and analyze CBEs.

• The CBE Event Browser, which WebSphere Process Server provides, offers a simple view of CBEs and can be launched in WebSphere Integration Developer from the server view or from a browser at http://localhost:9060/ibm/console/cbebrowser. This option is useful for developers who want to view generated events (see Figure 1).
• You can use a program to retrieve events and perform custom analysis and presentation. The artifacts address this option.

Back to top

Using reusable CEI artifacts

In order to process business-level events, see Downloads for three generic artifacts. Business-level events can be emitted with the CEIEventEmitter, queried with the CEIQueryService, or viewed with the CEIMeteringViewPortlet.

Using the CEIEventEmitter

The CEIEventEmitter (see Figure 2) allows us to generate business-level events from either a Java™ snippet or as a Service Component Architecture (SCA) component invoked from a business process. The event can be correlated to a business-level event, and it can contain an arbitrary set of name value pairs.

Emitting an event from Java code

Listing 1 shows an example of emitting a business-level event from Java code. You can use a Factory Pattern to create the event emitter and then invoke it with the appropriate data. You can either generate a log event (emitLogMessage) that contains a simple message or a standard event (emitEvent) that contains an eventName, an eventTrackingId, and a set of name value pairs containing the data for the event.

ICEIEventEmitter eventEmitter = CEIEventManagementFactory.createEventEmitter();
eventEmitter.emitLogMessage(String application, String eventTrackingId, String message);
eventEmitter.emitEvent(String application, String eventTrackingId, String event,
                       String[] eventDataName, String[] eventDataValue)
                       throws CEIEventException;

An eventTrackingId correlates all related events. For example, you might use the same eventTrackingId for one business process. The event is a string that identifies the business-level event that has occurred. You can use colons to create semantically meaningful event names, such as WPS:BusinessLevelEvent:FundTransferEvent.

Listing 2 is an example code snippet used in a banking application to log a business-level event during an account transfer.

// Bean implementation class for Enterprise Bean: AccountTransferService
public class AccountTransferServiceBean implements javax.ejb.SessionBean {
  //some code is ignored here
  public void makeTransfer( String bankId, String fromAccId, String toAccId,
                            BigDecimal amount, String description)
                             throws EJBException, TransferException {
    // some code is ignored here
    try {
      fromTransaction = transactionsLocalHome.create(time.toString(),
                                                   fromAccId,fromBankId,"Transfer",time);
      fromTransaction.setDescription(description);
      fromTransaction.setTotal(amount);
      fromTransaction.setToaccid(toAccId);
    } catch (CreateException e2) {  e2.printStackTrace();} 
		
    meterDebitEvent(fromBankId,fromAccount.getCustomerid(),fromAccId,amount);
    meterCreditEvent(toBankId,toAccount.getCustomerid(),toAccId,amount);
  }

  private void meterDebitEvent( String bankId,String userId,String fromAcc,
                                BigDecimal amount) {
    try {
      ICEIEventEmitter emitter = CEIEventManagementFactory.createEventEmitter();
      emitter.emitEvent("Jivaro", "Jivaro", "transfer_funds", new String[] {
                        "OpCode", "AgentID", "BfsID", "SubscriberID", "UserID",
                        "HostName", STATIC_Metering_ACTID, STATIC_Metering_AMOUNT},
                        new String[] {  STATIC_Metering_DEBIT_OPCODE,
                        STATIC_Metering_AGENTID, STATIC_Metering_BFSID, bankId, userId,
                        java.net.InetAddress.getLocalHost().getHostName().toString(),
                        fromAcc, amount.toString()});
    } catch(Exception e)  { e.printStackTrace(); }
  }

  private void meterCreditEvent(String bankId,String userId,String toAcc,
                                BigDecimal amount) {
  }
  // some code is ignored here
}

Emitting an event from an SCA component

The CEIEventEmitterRouter (in the downloadable artifacts) wraps the CEIEventEmitter as a Web service. You can then import the Web service into WebSphere Integration Developer and wire an invoking SCA component to it (see Figure 3), which enables the CEIEventEmitter to be invoked as a service. If performance is an issue, you can include the artifacts in the SCA module and call it as a standard Java bean.

Using the CEIQueryService

The CEIQueryService (see Figure 6) enables you to query the CEI persistent state and return data from CBEs within a specified correlation sphere. The correlation sphere groups all related CBEs together.

When the CEIEventEmitter persists events, a trackingId forms a correlation sphere, which is used to correlate related events. You can retrieve all the related CBE events. The interface to this artifact is a Web service, and the events are returned in a Plain Old Java Object (POJO), instead of a CBE, for easy access.

This artifact has two parts. The first part is the actual Web service and its related artifacts, which are contained in EAR file CEIQueryServiceEAR. These artifacts are deployed on the WebSphere Process Server instance. The second part of the CEIQueryService artifact is the client interface to the Web service and its related proxy classes. This is contained in EAR file CEIQueryServiceClientEAR. The client interface is an EAR file for easy access to the WAR for testing. The client project provides the WebService proxy and the needed classes to invoke the operations on the CEIQueryService. Typically, you start the Web service by instantiating the CEIQueryServiceProxy and then invoking the desired operation on the Web service. The data returns in a CEIQueryEvent object that contains an array of CEIQueryEventData objects.

There are some samples of how to invoke the CEIQueryWebService located in CEIQueryServiceClientWeb\WebContent\sampleCEIQueryServiceProxy. The sample enables you to test the Web service using the generated proxy. Select TestClient.jsp, and then Run > Run on Server. A Web browser opens, and you can select an operation to run. Remember to change the endpoint if the service is deployed on a remote host.

Note: In order to compile all projects successfully, make sure the WPS_RUNTIME/CEI/client/events-client.jar file is in the project build path. WPS_RUNTIME is the directory where WebSphere Process Server is installed, such as C:/Program Files/IBM/Rational/SDP/6.0/runtimes/bi_v6.

Using the CEIMeteringViewPortlet

The CEIMeteringViewPortlet (see Figure 5) is a portlet that enables you to view metering events that were created with the CEIEventEmitter. The CEIMeteringPortlet retrieves events using the CEIQueryService and then lists them in a portlet page (see Figure 6). The portlet enables the user to filter events based on date, agent, or subscriber.

The filtering criteria fields are optional. The portlet uses only the available criteria to filter events. This feature is especially useful for many events.

One of the features of this portlet is the capability to use an XPATH query string to filter. The CEIMeteringPortlet constructs an XPATH query string from the user-specified criteria and sends this query string to the CEIQueryService. The CEIQueryService then takes the XPATH query string and retrieves the events, filtering out the non-compliant events.

You can select an event to see its attributes in detail (see Figure 7).

Back to top

Conclusion

This article describes why making your composite application measurable is important. It describes the role of business-level events and presents three artifacts you can use to generate, query, and view business-level events in the context of a composite application. With the help of these reusable artifacts, your composite application can be measurable, thus laying the groundwork for improving the entire business process.

Back to top

Downloads

Information about download methods

Note

1. The artifacts are provided in Project Interchange Format. In order to import the artifacts simply select File>Import and then Project Interchange.

Resources

Learn

• Use an RSS feed to request notification for the upcoming articles in this series. (Find out more about RSS feeds of developerWorks content.)
  
  
• Get the specification and related material for Business Process Execution Language for Web Services.
  
  
• Refer to the Common Base Event specification.
  
  
• Learn more from Best Practices for the Common Base Event and Common Event Infrastructure.
  
  
• See Event Management Best Practice for more about event management.
  
  
• Refer to Common Base Event best practices: Getting it right the first time.
  
  
• Learn more from Common Base Event best practices: Properties and elements at a glance.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• The IBM SOA Web site offers an overview of SOA and how IBM can help you to get there.
  
  
• Visit the SOA and Web services zone on developerWorks to learn more about SOA.
  
  

Discuss

• Participate in developerWorks blogs and get involved in the developerWorks community.
  
  
• Collaborate with a community of architects and developers in the SOA and Web services discussion forums.
  
  

About the authors

Javier Garcia is an advisory software engineer with over 20 years of development experience. He is currently working in the SWG Strategy and Technology department with a focus on SOA and composite applications.

DuoWei (David) Sun is a staff software engineer in China Software Development Lab (CSDL). He is currently working in the SOA development area.

Zhi Gan is a software engineer at the IBM China Development Lab. He joined IBM after receiving a Ph.D. in computer security from Shanghai JiaoTong University. He has extensive experience in SOA, AOP, and Eclipse. Now he focuses mainly on model-driven development with patterns.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Capturing business-level events
• Generating CBE events
• Viewing CBEs
• Using reusable CEI artifacts
• Conclusion
• Downloads
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Integration Developer (in the SOA Sandbox: Connect)
• Demo: Process automation, adoption pattern
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Integration Developer (in the SOA Sandbox: Connect)

Dig deeper into SOA and Web services on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers