Introduction

Components of business systems employ different formats and infrastructures to collect information. When a business-critical application fails, it's often difficult to consolidate, correlate, and visualize events from disparate components in a cohesive way, and you may have to scrutinize several dozen event logs that span different systems to determine the root cause.

The Common Event Infrastructure (CEI) is an IBM® implementation of a consistent, unified format for the creation, transmission, persistence, and distribution of a wide range of business, system, and network events. CEI is based on the Autonomic Computing Division's Common Base Event (CBE) specification, which focuses on consistent quality and content of event data. IBM products will adopt this technology as both a producer and consumer of events. IBM has also proposed CBE for consideration as a new standard to the Organization for the Advancement of Structured Information Standards (OASIS), and it has been accepted by the Eclipse Hyades Open Source Project.

The common elements of CEI are:

• Public interfaces to build event sources
• Public interfaces to receive real-time events
• Public interfaces to query historical event data
• Capability for pluggable event stores

Back to top

Enabling CEI in the Application Developer IE test environment

There are two ways to take advantage of CEI in WebSphere® Business Integration Server Foundation. A business process can be enabled to log all of the process events into the CEI database (see Capturing CBE Events in a Business Process below), or any J2EE client or server application can log its events into the CEI database using the CEI API. To learn how to develop CEI enabled applications, see "About the Common Event Infrastructure in WebSphere Application Server" in the WebSphere Information Center. In both cases, you must first enable a WebSphere Business Integration Server Foundation V5.1.1 test environment server for CEI. Here are the steps for enabling the test environment:

1. Creating a CEI Enabled server and server configuration
2. Setting a JMS provider for the server configuration
3. Configuring security (optional)

Creating a CEI-enabled server and server configuration

To enable your J2EE applications for CEI, you need to create a CEI-enabled WebSphere Business Integration Server Foundation V5.1.1 server. Ensure that the Business Integration perspective is opened, then do the following steps:

1. From the menu, select File => New => Other. The Select page opens.
2. From the navigation tree, clickServer.
3. From the pane, click Server and Server Configuration.
4. Click Next. The Create a new server and server configuration page opens.
5. From the navigation tree for the server type, click WebSphere Version 5.1 => Integration Test Environment.
6. In the Server name field, type WBI-SF-CEI.
7. Click Next. The WebSphere Server Configuration Settings page opens:
8. Select Enable the Common Event Infrastructure.
9. Click Finish.

Setting a JMS provider for the server configuration

CEI uses messaging to register and generate events. Specifically, it uses queues and publish/subscribe services. Application Developer IE preconfigures the default JMS settings for CEI, as shown in the server configuration editor on the JMS tab:

By default, event distribution is enabled for the server. Event distribution requires topic-based messaging; therefore, either WebSphere MQ or WebSphere MQ Embedded Messaging must be installed and properly configured, since the MQ Simulator for Java™ Developers does not support topics. If you do not need event distribution, it can be disabled, which lets you continue working with MQ Simulator only. The configuration of JMS providers is described below:

• Configuring WebSphere Embedded Messaging as the JMS provider
• Configuring WebSphere MQ as the JMS provider
• Configuring MQ Simulator for Java developers as the JMS provider

Configuring WebSphere Embedded Messaging as the JMS provider

Follow these steps to set up WebSphere MQ Embedded Messaging as the JMS provider. See the appendix for information on installing or reinstalling embedded messaging.

1. Click the Servers tab.
2. From the table, double-click on WBI-SF-CEI. The editor opens for WBI-SF-CEI server configuration.
3. Click the JMS tab.
4. Click Embedded Messaging:
5. Click the Variables tab.
6. Under the Defined variables for the Node Settings, set MQ_INSTALL_ROOT to where embedded messaging was installed, for example, C:/Program Files/IBM/WebSphere MQ.
7. Similarly, set WAS_PUBSUB_ROOT to where embedded publish/subscribe is installed, for example C:/Program Files/IBM/WebSphere MQ/WEMPS:

Configuring WebSphere MQ as the JMS provider

Since Application Developer IE has CEI preconfigured to use embedded messaging, you need to do some extra steps to use WebSphere MQ as the JMS provider, as described in the following sections:

• Installing WebSphere MQ
• Reinstalling the CEI messaging application
• Configuring the queues and topics for WebSphere MQ
• Pointing the UTE to the WebSphere MQ install

Installing WebSphere MQ

WebSphere Business Integration Server Foundation V5.1.1 requires IBM WebSphere MQ V5.3 with CSD 07.

1. Install IBM WebSphere MQ V5.3. See the MQ documentation for installation information.
2. Install IBM WebSphere MQ CSD 07, since this is the level required by WebSphere Business Integration Server Foundation.
3. Install IBM MQSeries® Publish/Subscribe V5.3. This article uses this version.
4. Create a queue manager called WAS_localhost_server1. We did this from the MQ Explorer; we set it as the default queue manager and left the defaults. You can also use an existing queue manager, just ensure your server configuration points to the correct one (the steps to do this are below).
5. Ensure that the queue manager is running.
6. Create a local queue called CommonEventInfrastructure_Queue. This was also done from MQ Explorer using the defaults. You also need to create a queue called SYSTEM.JMS.REPORT.QUEUE.
7. Start the broker at a prompt with the command: WebSphereMQInstallDir\bin\strmqbrk

Reinstalling the CEI messaging application

When configuring a server for CEI, one of two messaging applications must be installed: one is for use when embedded messaging is used and one is for another JMS provider. Since Application Developer IE configures CEI to use embedded messaging, the CEI embedded messaging application must be uninstalled, and the one for another JMS provider must be installed.

1. In the Servers view, double-click on the WBI-SF-CEI server to open the server configuration editor and on the Configuration tab,. Check Enable administration console. We are enabling this console since the application can only be uninstalled through the administration console; it does not appear in the server configuration editor. As with some other steps that follow, you can save time and uninstall the application by editing the server configuration files if you are familiar with them.
2. While the editor is open, ensure that MQ Simulator for Java Developers is selected for the JMS provider on the JMS page. (When these steps are finished it will not actually use the MQ Simulator, but will instead use the full WebSphere MQ.)
3. Close and save the editor, then start the server.
4. Once the server is running, right-click on the server and select Run administrative console. Log in and go to Applications => Enterprise Applications. Select the check box next to CommonEventInfrastructureMessageApp and click the Stop button above it. Select the check box again and click Uninstall.
5. Save your change, log out, and restart the server.
6. Copy cei-installer.jar from WSADIEInstallDir\runtimes\ee_v51\event\lib to WSADIEInstallDir\runtimes\ee_v51\classes (create the classes directory if it is not already there), where WSADIEInstallDir is the directory where you installed Application Developer IE.
7. Open event-message.jacl in WSADIEInstallDir\runtimes\ee_v51\event\application with a text editor and comment out line 319 (search for createListenerPort). The listener port will not be created by the script and will have to be created manually, because of a limitation of this installation script in the context of the test environment server.
8. From a command prompt, change directories to WSADIEInstallDir\runtimes\ee_v51\event\application and run the command:

   WSADIEInstall Dir\runtimes\ee_v51\bin\wsadmin -f event-message.jacl -profile event-profile.jacl -action install -earfile event-message.ear -node localhost -server server1 -qjndi jms/cei/EventQueue -qcfjndi jms/cei/EventQueueConnectionFactory -appname CommonEventInfrastructureMessageApp

   
   
9. Create the listener port manually. Log in again to the administration console (you could also set these values on the EJB tab of the server configuration editor), navigate to Servers => Application Servers => Server1 => Message Listener Service => Listener Ports. Click New. Enter the following values:
   • Name: CommonEventInfrastructureMessageApp-ListenerPort
   • Description: Listener Port used by CommonEventInfrastructureMessageApp
   • ConnectionFactory JNDI Name: jms/cei/EventQueueConnectionFactory
   • Destination JNDI Name: jms/cei/EventQueue
10. Click Apply and save to the master configuration.
11. As a result of reinstalling CommonEventInfrastructureMessageApp in the test environment server, the application's deployment descriptor must be edited. Switch to the Package Explorer view and navigate to Servers => WBI-SF-CEI.wsc => cells => localhost => applications => CommonEventInfrastructureMessageApp.ear => deployments => CommonEventInfrastructureMessageApp and open deployment.xml:
12. Change the value of binariesURL to "${WS_EAR_CommonEventInfrastructureMessageApp}":

Configuring the queues and topics for WebSphere MQ

1. Navigate to Resources => WebSphere MQ JMS Provider. Select the server scope and click Apply:
2. Click WebSphere MQ Queue Connection Factories, click New, and enter these values:
   • Name: CommonEventInfrastructure_QueueCF
   • JNDI Name: jms/cei/EventQueueConnectionFactory
   • QueueManager: WAS_localhost_server1
   Leave the rest as-is and click OK (we will save this to the master configuration at the end).
3. Click WebSphere MQ JMS Provider => WebSphere MQ Topic Connection Factories => New and enter these values:
   • Name: CommonEventInfrastructure_AllEventsTopicCF
   • JNDI Name: jms/cei/notification/AllEventsTopicConnectionFactory
   • QueueManager: WAS_localhost_server1
   • Broker Version: Basic (assuming you used the MA0C pub/sub from the download mentioned in the beginning of this section)
   Leave the rest as-is and click OK.
4. Click WebSphere MQ JMS Provider => WebSphere MQ Queue Destinations => New and enter these values:
   
   • Name: CommonEventInfrastructure_Queue
   • JNDI Name:jms/cei/EventQueue
   • Basic Queue Name: CommonEventInfrastructure_Queue
   • Basic Queue Manager Name: WAS_localhost_server1
   Leave the rest as-is and click OK.
   
5. Click WebSphere MQ JMS Provider => WebSphere MQ Topic Destinations => New and enter these values:
   • Name: CommonEventInfrastructure_AllEventsTopic
   • JNDI Name: jms/cei/notification/AllEventsTopic
   • Base Topic Name: jms.cei.notification.AllEventsTopic
   Leave the rest as-is and click Apply, then save to the master configuration.

Pointing the UTE to the WebSphere MQ install

1. On the Variables tab in the server configuration (or using the administration console), set MQ_INSTALL_ROOT and WAS_PUBSUB_ROOT to where you installed WebSphere MQ. Do not use quotes if you have spaces in any directory names, and use forward slashes.
2. Restart the server.

Configuring MQ Simulator for Java developers as the JMS provider

CEI can also be set up to work with the MQ Simulator for Java Developers. However, as mentioned earlier, this type of JMS provider does not support topics. The steps below show how to disable event distribution so that topics are not used:

1. After creating the server, ensure that the JMS provider on the JMS tab is set to MQ Simulator for Java Developers.
2. Open the server configuration editor for the new server (double-click on the server).
3. Select the Configuration page and select Enable the administration console:
4. Close and save the editor.
5. Start the server, then right-click on WBI-SF-CEI and select Run administrative console.
6. Log in to the administration console and select Resources => Common Event Infrastructure Provider.
7. Select Cell and click Apply.
8. Click on Event Server Profile, the click Default Common Event Infrastructure event server.
9. Clear the Enable Event Distribution check box:
10. Click Apply, save to the master configuration, then log off from the administration console.
11. Restart the server.

Configuring security (optional)

If you want to enable security, you must change some security settings:

1. Click the Security tab and select Enable Security. (This only uses operating system authentication; using another method, such as LDAP, is beyond the scope of this article.)
2. From the table, select local host/BPEAuthDataAliasEmb_localhost_server1.
3. Click Edit. The Edit JAAS Authentication Entry window opens.
4. In the User ID field, type your user ID.
5. In the Password field, type your password and click OK.
6. From the table, select local host/Commencement.
7. Click Edit. The Edit JAAS Authentication Entry window opens.
8. In the User ID field, type your user ID.
9. In the Password field, type your password and click OK.
10. From the table, select local host/local host/server1/EventAuthDataAliasCloudScape.
11. Click Edit. The Edit JAAS Authentication Entry window opens.
12. In the User ID field, type your user ID.
13. In the Password field, type your password and click OK.
14. Save and close the WBI-SF-CEI server configuration.

Back to top

Using the CEI Web client

In the Application Developer IE UTE, the CBE Events are accumulated in a Cloudscape database. To view the events, use the Web application (CBE Event Browser) supplied with Application Developer IE.

Capturing CBE events in a business process

Activities that are marked in the BPEL Editor as "Business Relevant" will be logged as CBE Events.

For example, in the following business process, the Approve activity is marked as "Business Relevant" and therefore, when invoked, will be captured as a CBE event:

Starting the CBE Event Browser

Once you run a business process, you can view its events in the CBE Event Browser. To start the CBE Event Browser:

1. Click the Servers tab.
2. Right-click on the WBI-SF-CEI server and from the pop-up menu, select Launch CBE Event Browser. The CBE Event Browser Web application opens:

Browsing CBE events

Before you can browse information associated with the activities, you must first collect the CBE data:

1. Switch to the Application Developer IE Web Browser window with the CBE Event Browser Web application.
2. Click Get data to switch to the Get event data page:
3. Click Get data. You should see the Record count updated with the number of CBE events captured by the CEI framework. In the following example, 16 CBE events were captured:
4. You are now ready to browse the CBE events. First, select from the View data section one of the four links:

   For example, if you click Processes, you switch to the View processes pane:

5. In this view, the Process column lists all of the process templates. If you click one of the templates in the Process column, you will see the instances of that template (process instances) in the Instance column. By clicking a Process instance in the Instance column, in the pane to the right you will see a list of the activities that were executed in a process instance. Finally, if you click one of the activities, you will see in the Event data pane the event data:

Back to top

Conclusion

The Common Event Infrastructure will be used as a key integrating technology for applications and solutions that need to produce and consume Common Base Events and exchange those events across the IBM Enterprise Service Bus. This article has shown how to enable and configure CEI using various JMS providers in Application Developer IE.

Back to top

Appendix: Installing WebSphere MQ Embedded Messaging for Application Developer IE servers

If you have an older version of embedded messaging installed from a version prior to V5.1 of Application Developer IE or WebSphere Application Server, you need to bring it up to the V5.3.0.7 level. Once uninstalled, it is simplest to get embedded messaging running by reinstalling it using the Application Developer IE launchpad. This allows the system path and queue manager to be automatically set up for use with the Application Developer IE test environment servers. Here are some tips to a successful reinstallation:

• Ensure that messaging processes (those found in C:\Program Files\IBM\WebSphere MQ\bin are shown in the Task Manager) are completely stopped before uninstalling. Normally, this is the case if the server is stopped at the time you are uninstalling.
• After uninstallation, check that the registry key, HKEY_LOCAL_MACHINE\SOFTWARE\IBM\WebSphereEmbeddedMessagingPublishAndSubscribe is deleted from the registry (use regedit). This key may be left behind if any messaging processes were running during the uninstallation.
• Ensure that the directory C:\Program Files\IBM\WebSphere MQ is deleted.
• Install Embedded Messaging with the Application Developer IE launchpad. It is on Disk 1 of the Application Developer IE installation CDs:

If you have a current version of embedded messaging installed as a result of installing WebSphere Application Server V5.1 or later, (see WebSphere Business Integration Server Foundation => Installing => Getting started => Installing the product => Tips for installing the embedded messaging feature), some additional steps are required to get it to work in a Application Developer IE test environment server. These steps are outlined in the Application Developer IE documentation under WebSphere Studio => Testing => Testing and publishing Web and J2EE applications => Application testing and publishing => Testing Applications on a server => Testing J2EE projects => Testing JMS applications => Setting a local WebSphere test environment or server to use Embedded Messaging.

Resources

• developerWorks WebSphere Studio zone. Access to WebSphere Studio how-to articles, downloads, tutorials, education, product information, and more.
  
  
• Trial downloads for WebSphere Studio. No-charge trial downloads for the latest WebSphere Studio products.
  
  
• Trial downloads for IBM software products. No-charge trial downloads for selected IBM DB2, Lotus, Rational, Tivoli, and WebSphere products.
  
  
• Browse for books on these and other technical topics.
  
  
• WebSphere forums. Product-specific forums where you can ask questions and share your opinions with other WebSphere users.
  
  
• developerWorks blogs. Ongoing, free-form columns by software experts, with space for you to add your comments. Check out Grady Booch's blog on Software architecture and engineering.
  
  

About the authors

Richard Gregory is a software developer at the IBM Toronto Lab. He works on the WebSphere Business Integration Tooling team. His responsibilities include working on the evolution and delivery of test tools for WebSphere Studio Application Developer Integration Edition. You can reach Richard at gregoryr@ca.ibm.com.

Paul Pacholski is an IBM Certified I/T Specialist. As a part of the Worldwide Technical Sales team he is supporting WebSphere Business Process Choreography tools. You can reach Paul at pacholsk@ca.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Enabling CEI in the Application Developer IE test environment
• Using the CEI Web client
• Conclusion
• Appendix: Installing WebSphere MQ Embedded Messaging for Application Developer IE servers
• 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

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers