Introduction

The IBM Common Event Infrastructure article discussed the importance of an event infrastructure shared by multiple applications in a distributed environment. The benefits of sharing a single infrastructure and adopting a single API range from reduced development costs to easier data exchange between applications written by different vendors. The IBM Common Event Infrastructure uses the Common Base Event specification as the format for the event information exchanged in the system, which lays a solid foundation for the agreement between the event sources and event consumer in the environment.This article focuses on the CEI Event Catalog, a component that builds on the foundation set by the Common Base Event specification in order to offer a higher-level of agreement for the applications exchanging event data through CEI.

The Common Base Event specification recognizes that a static set of fields cannot represent the entire universe of application fields. Application specific fields on an event are addressed through event extensions. The Common Base Event specification defines the names and data types for the common fields shared by all applications, such as creation time, severity, and originator of the event data. For any other field not represented in this basic set of properties, the Common Base Event specification defines an array of extended data elements, which are generic tree-like data structures that can virtually represent other hierarchical structures such as an XML document. The Common Base Event specification lets applications define the contents of the extended data elements according to a given value for the extensionName event field.

Back to top

Event Catalog structure

In the next sections, we analyze and implement a concrete use case that illustrates the usefulness of the Event Catalog. Before we look into that scenario, take a closer look at the underlying data structure for the CEI Event Catalog, which is represented in the UML diagram in Figure 1.

An event definition object is uniquely associated with an event extension (the extensionName field in the Common Base Event specification). It has the following fields:

• Name: The name of the event definition, which should match the value of the extensionName field in the Common Base Event instances of the same type. All events where the extensionName field has the same value as the name field on an event definition should share that same event definition.
• Parent: This is the name of the parent event definition, which is used to form a hierarchy of event definitions where an event definition inherits the contents of its parent event definition.
• Property descriptions: An event definition can contain multiple property descriptions, which define additional constraints to Common Base Event fields on top of the restrictions defined in the Common Base Event specification. As an example, you could indicate the permitted values for the sourceComponentId.componentIdType field of a Common Base Event event as being ServiceName and Application only.
• Extended data element descriptions: An event definition can contain multiple extended data element descriptions. These descriptions define the expected name, type, and values for an extended data element. Note that these descriptions can also form a hierarchy in order to represent the hierarchies of extended data elements inside an event instance.

Back to top

Case study

We'll assume a hypothetical scenario where a vendor develops an application that processes insurance claims originated at a call center facility.

Call center representatives take phone calls from customers and place their insurance claims on an automated system. This system keeps track of the insurance processing from filing to closure.

This system sends events to indicate the beginning of each step in the processing sequence; we focus on the first event in the chain. During application modeling, this event is defined as highlighted in Figure 2. Note the sample content for this event extension in the lower left of the figure. In the right side, you see the actual content for an event in its XML representation according to the Common Base Event XML schema. The resources section contains a complete XML version of the event used in this example, along with the source code required to create an instance of that event.

Without examining the operations of this company in too much detail, assume that at some point you want to see a display of all claims filed in a certain time period. Assume also that different operators might want to group the data in different ways, such as by policy number or by type of loss.

Representing the underlying event model into the source code for the event browser is not a good idea because any subtle change in the event model requires a corresponding change to the application. Figure 3 illustrates how the CEI Event Catalog can be used as the point of integration between the event sources and event consumer.

The deployment sequence can be described in the following steps:

1. The installation module for the external application registers its event definitions in the CEI Event Catalog. For easy grouping, it also takes advantage of the CEI Event Catalog ability to associate the event definitions with a source category, in this case Insurance Claim Tracker.
2. The configuration module for the external application retrieves all event definitions for the source category called Insurance Claim Tracker. The configuration module displays the event definition names and contents to the system administrator.
3. The system administrator configures views for an event browser, using the names of the event extensions and indicating the fields policy holder name and policy number as columns in the main browser window. Looking at the event definitions, the system administrator identifies that Claim_losses is an array and does not fit into the single line rows in the main browser window
4. At startup, the Event Browser reads the configuration and determines that you should display Insurance_claim_start events. It reads the event definition for this type of event so that it offers new alternatives for the columns for the user.

Creating event definitions

There are two different mechanisms for creating event definitions: through the CEI Java API or through the CEI command-line interfaces.

The programmatic mode is more suitable when you already have an installation module written in Java or when you foresee the generation of the event definitions dynamically as part of the run time for a larger application.

The CEI Event Catalog, as is the rest of the CEI server-side run time, is a Java 2 Platform, Enterprise Edition (J2EE) application and follows the Enterprise JavaBeans (EJB) programming model. Before looking at the J2EE mechanics, take a closer look at the following code snippet for creating the event definition parameter that is passed as a parameter to the Event Catalog methods:

// Create the "Insurance_claim_start" EventDefinition that inherits 
// from base event definition "event"
EventDefinition eventDefinition = new EventDefinition("Insurance_claim_start",
                                                      "event");

// Create the a new PropertyDescription for the event definition      
PropertyDescription propertyDescription = new PropertyDescription("severity",
                                                                  null);   // no path
propertyDescription.setDefaultValue(Short.toString(CommonBaseEvent.SEVERITY_CRITICAL);
propertyDescription.setRequired(false);

// Create the new descriptions for the event definition
ExtendedDataElementDescription policyHolderDescription = 
     new ExtendedDataElementDescription("Policyholder_Name", 
                                        ExtendedDataElement.TYPE_STRING_VALUE);

ExtendedDataElementDescription policyNumberDescription = 
     new ExtendedDataElementDescription("Policy_Number", 
                                        ExtendedDataElement.TYPE_STRING_VALUE);

ExtendedDataElementDescription lossTypeDescription = 
     new ExtendedDataElementDescription("Loss_Type", , 
                                        ExtendedDataElement.TYPE_STRING_VALUE);

ExtendedDataElementDescription claimLossesDescription = 
     new ExtendedDataElementDescription("ClaimLosses",
                                        ExtendedDataElement.TYPE_NO_VALUE_VALUE);
claimLossesDescription.setMaxOccurs(Integer.MAX_VALUE);
claimLossesDescription.setMinOccurs(0);

ExtendedDataElementDescription claimLossDescription = 
     new ExtendedDataElementDescription("ClaimLoss", ,
                                        ExtendedDataElement.TYPE_NO_VALUE_VALUE);
claimLossDescription.setMaxOccurs(Integer.MAX_VALUE);

ExtendedDataElementDescription lossDetailDescription = 
     new ExtendedDataElementDescription("Loss_Description",
                                        ExtendedDataElement.TYPE_STRING_ARRAY_VALUE);

// Adding the descriptions to the event definition.
eventDefinition.addPropertyDescription(propertyDescription);
claimLossDescription.addChild(lossDetailDescription);
claimLossesDescription.addChild(claimLossDescription);
eventDefinition.addExtendedDataElementDescription(policyHolderDescription);
eventDefinition.addExtendedDataElementDescription(policyNumberDescription);
eventDefinition.addExtendedDataElementDescription(lossTypeDescription);
eventDefinition.addExtendedDataElementDescription(claimLossesDescription);

Note that objects of type ExtendedDataElementDescription can be arranged in a hierarchy through the addChild method.

Now you are ready to invoke the Event Catalog EJB component and request the creation of the event definition on the CEI Event Catalog repository. The Event Catalog is a stateless session EJB component, and, therefore, can be invoked with the traditional J2EE programming sequence described in Listing 2.

Context initial = new InitialContext();

Object objref = initial.lookup("ejb/com/ibm/events/catalog/EventCatalog");

EventCatalogHome eventCatalogHome = (EventCatalogHome) 
    PortableRemoteObject.narrow(objref, EventCatalogHome.class);
EventCatalog eventCatalog = eventCatalogHome.create();

// Add the event definition into the catalog
eventCatalog.addEventDefinition(eventDefinition, 
                                true);  // overwrite existing definition with the same name

On the other hand, if you want a more flexible format that allows smaller tweaks after the system has been deployed (such as adjusting the default value for a property) you can also write an XML file according to the CEI Event Catalog XML schema and use the CEI eventcatalog.jacl script to import the XML file.

For the example in our case study, the XML file would have the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<evd:eventDefinitionList
    xmlns:evd="http://www.ibm.com/ac/eventdefinition5_0_1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <eventDefinition name="Insurance_claim_start" parent="event">
        <property name="severity" required="false"> 
          <defaultValue>50</defaultValue> 
        </property>
        <extendedDataElement name="Policyholder_Name" type="string" 
        maxOccurs="1" minOccurs="1" />
        <extendedDataElement name="Policy_Number" type="string" 
        maxOccurs="1" minOccurs="1" />
        <extendedDataElement name="Loss_Type" type="string" 
        maxOccurs="1" minOccurs="1" />
        <extendedDataElement name="ClaimLosses" type="noValue" 
        maxOccurs="unbounded" minOccurs="0">
            <extendedDataElement name="ClaimLoss" type="noValue" 
            maxOccurs="unbounded" minOccurs="1">
                <extendedDataElement name="Loss_Description" type="stringArray" 
                maxOccurs="1" minOccurs="1" />
            </extendedDataElement>
        </extendedDataElement>
    </eventDefinition>
</evd:eventDefinitionList>

And could be imported with the following command (in the Windows platform):

%WAS_HOME%\wsadmin -f %WAS_HOME%\event\bin\eventcatalog.jacl -import -file <filename>

Querying event definitions

Other applications can access an event definition stored in the Event Catalog database. Going back to our case study, we can examine the code for accessing the event definitions in the configuration application, which is illustrated in Listing 4.

// You can reuse the same JNDI lookup code from Listing 3
...

// Retrieve all event definitions from the catalog
EventDefinition eventDefinitions[] = 
    eventCatalog.getEventDefinitions("%",
                                     false);    // do not resolve definitions

Note the parameters used on the call to getEventDefintions. This first parameter is a pattern for event definition names. A "%" character in the pattern matches all characters in the name of the event definitions; for example, "%start" would match all event definitions that end with "start".

The second parameter, false, instructs the CEI Event Catalog to not resolve the contents of the parent event definitions into the returned event definitions, as described later in Event definition hierarchies.

After the event definitions are loaded in memory, it is fairly simple to navigate through their getter methods to access their contents, as illustrated in Listing 5.

for(int i = 0; i < eventDefinitions.length; i++)
{
    System.out.println(eventDefinitions[i].getName());

    // Accessing contents for the event definition
    PropertyDescription properties[]
        eventDefinitions[i].getPropertyDescriptions();
    ExtendedDataElementDescription extendedElementDescriptions [] = 
        eventDefinitions[i].getExtendedDataElementDescriptions();

    // Printing out property definitions for the event definition
    for(int j = 0; j < properties.length ; j++)
    {
         System.out.println(properties[j]);
    }
    
    // Printing out extended data element definitions for the event definition
    for(int j = 0; j < extendedElementDescriptions.length; j++)
    {
        System.out.println(extendedElementDescriptions[j]);

        ExtendedDataElementDescription children[] = 
            extendedElementDescriptions[j].getChildren();
        ...
    }
}

A system administrator expects a more interactive mechanism to browse and select the event definitions. The sample included in the source code was written in Java language using the Swing library and is a good example of how the event definitions can be presented to an end user.

Event definition hierarchies

We now expand our case study to illustrate the usefulness of another feature in the Event Catalog. We introduce special support for auto insurance. As with most common auto insurance policies, there might be several vehicles covered under the same policy. The Vehicle Identification Number (VIN) can be used to identify the vehicle within the claim. Adding the field to the original event definition clutters the event definition for all claims not related to vehicles. Creating a new event definition is the best approach.

During the modeling phase, the system architect finds out that there are major commonalities between the event definitions for home and auto insurance. In fact, for this particular application, the auto insurance only requires the addition of an extended data element to represent the VIN. The support for event definition hierarchies in the CEI Event Catalog can easily solve such situations. You simply have to create the new event definition indicating the name of the parent event definition, and all properties are automatically propagated to the new definition, as shown is Listing 6.

EventDefinition eventDefinition = 
    new EventDefinition("Auto_Insurance_claim_start",     // new definition
                        "Insurance_claim_start");         // parent definition

ExtendedDataElementDescription extendedDataElementDescription = 
    new ExtendedDataElementDescription("VIN",
                                       ExtendedDataElement.TYPE_STRING_VALUE);

eventDefinition.addExtendedDataElementDescription(extendedDataElementDescription);

Event source categories

The case study above represents the mainstream usage scenario for the CEI Event Catalog. When new applications come into the system, the number of event definitions is expected to grow to accommodate the new event extensions used by these applications.

In our example, we suggested that the vendor for the process tracking application could offer a configuration tool that would help a system administrator browse the event definitions interactively. However, as new event definitions are added to the Event Catalog database, it becomes an increasingly difficult task to identify the event definitions related to each application.

The usage of hierarchies for this purpose is somewhat limiting. An event definition inherits the contents of its parent event definition, which makes it cumbersome to associate event definitions that do not share any property description or extended data element description. You might be tempted to create an empty parent event definition for all associated event definitions, which is also not recommended because an event definition might be shared by different applications.

The solution lies in the concept of an event source category, which allows an application to group event definitions under a logical name. In our case study, the installation module can define an event source category named Insurance Claim Tracker and associate all of its event definitions with this category. This approach is illustrated in Listing 7.

// JNDI lookup code for the event catalog EJB
...

// Binding multiple event definitions to the same event source category
String SOURCE_CATEGORY = "Insurance Claim Tracker";
EventDefinition definition1 = ...
EventDefinition definition2 = ...
eventCatalog.bindEventExtensionToSourceCategory(definition1.getName(), 
                                                SOURCE_CATEGORY);            
eventCatalog.bindEventExtensionToSourceCategory(definition2.getName(), 
                                                SOURCE_CATEGORY);

The configuration module can then use the event source categories to narrow down the scope of its initial query. Instead of using the broad query illustrated in Listing 4, we can retrieve the names of the event definitions associated with the event source category named Insurance Claim Tracker and then query only the event definitions with those names.

String extensionNames[] = eventCatalog.getEventExtensionNamesForSourceCategory
("Insurance Claim Tracker");
EventDefinition definitions[] = new EventDefinition[extensionNames.length]; 
for (int i = 0 ; i < definitions ; i++) {
     definition[i] = eventCatalog.getEventDefinition(extensionNames[i], 
                                                     false);
}

Back to top

Next steps

This article has covered a concrete case study that represents the intended usage of the CEI Event Catalog. We recommend a closer look at the IBM WebSphere Business Integrator Server Foundation (WBI-SF) Information Center for more details on the Event Catalog APIs and command line interfaces.

In order to try out the samples in this article, you need the production release of CEI 5.1.0, which is shipped with the WBI-SF 5.1.1 fixpack. WBI-SF 5.1 (without the fix pack) contains only the technology preview release of CEI and does not contain the Event Catalog component.

Resources

• In the Specification: Common Base Event, read about a new mechanism for managing events in business enterprise applications in the Autonomic computing model (developerWorks, July 2003).
  
  
• The article Integrate event management with Common Event Infrastructure (developerWorks, July 2004) provides a brief overview of the IBM Common Event Infrastructure (CEI), a set of modular event processing components that deliver functions such as event transport, event-bus distribution, event persistence, event subscription, event updates, and event queries.
  
  
• Read Standardize messages with the Common Base Event model (developerWorks, February 2004) to see how translating log messages into Common Base Events and analyzing the events with an autonomic manager can heal a failing system.
  
  
• Check out XPath, a language for addressing parts of an XML document.
  
  
• Explore the Tivoli Software Web site for additional links to information related to the IBM Common Event Infrastructure.
  
  
• For several links to components that build the IBM Business Performance Management (BPM) strategy, including the IBM Common Event Infrastructure, visit the BPM Web site.
  
  

About the authors

Denilson Nastacio spent three years in a startup company for software development training. He joined IBM in 1997, working in several technical positions in the area of network topology and event management. For the past two years, he has played the role of Chief Designer for the IBM Common Event Infrastructure. He can be reached at dnastaci@us.ibm.com.

Jason Cornpropst has spent the last five years developing applications to perform event management. For the last two years, he has been the team lead for the event server portion of the IBM Common Event Infrastructure. He is also one of the initial authors of the Common Base Event specification that is being adopted at IBM as the standard for sending events. Before working in event management he worked on APPN and TN3270 in IBM routers. He can be reached at jhcornpr@us.ibm.com.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Event Catalog structure
• Case study
• Next steps
• Resources
• About the authors
• Comments

Dig deeper into Tivoli on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers