CBE Function Component

Directory Integrator, Version 7.1.1

CBE Function Component

The CBE Function Component allows you to generate Common Base Event (CBE) event objects which can be written to CBE logs (which can be then viewed / managed using the Autonomic Computing Toolkit's Log and Trace analyzer) or issued to an IBM Common Event Infrastructure (CEI) server; alternatively, send it to an external application that is listening for CBE events.

Using the FC in Tivoli® Directory Integrator, you must map your work entry attributes to the standard CBE attributes exposed in the Output Map of the CBE FC, so that when the AssemblyLine is run, the CBE FC creates a CBE Event object (and a CBE Event XML) and puts it back into the AssemblyLine's work entry.

You can also map a CBE object to the event attribute or XML representing a CBE object to the eventXml attribute of the OutputMap, so when the AL is run, the CBE FC retrieves all the standard CBE attributes and puts them back to the work entry.

Common Base Event (CBE)

Common Base Event (CBE) facilitates effective intercommunication among disparate enterprise components that support logging, management, problem determination, autonomic computing, and e-business functions.

An event encapsulates message data sent as the result of an occurrence of a situation. Events exchanged between and among applications in complex information technology systems allow these various facets of the system to interoperate, communicate and coordinate their activities. Fundamental aspects of enterprise management and e-business communications, such as performance monitoring, security and reliability, as well as fundamental portions of e-business communications, such as order tracking, are grounded in the viability and fidelity of these events.

The Common Base Event is defined as a new standard for enterprise management and business applications events. The Common Base Event definition ensures completeness of the data by providing properties to publish general information whenever a situation occurs. This general information provided by the Common Base Event is called the 3-tuple.

The following elements constitute the 3-tuple:

The identification of the component that is reporting the situation
The identification of the component that is affected by the situation (which may be the same as the component reporting the situation)
The situation itself

The Common Event Infrastructure (CEI)

The Common Event Infrastructure (CEI) is IBM's implementation of a consistent, unified set of APIs and infrastructure for the creation, transmission, persistence and distribution of a wide range of business, system and network CBE formatted events. CEI is based upon the Autonomic Computing Division's CBE specification, which defines a standard format for event information, which devices and software use to keep track of transactions and other activity.

CEI is an embeddable technology intended to provide basic event management services to applications that require those services. This event infrastructure serves as an integration point for consolidation and persistence of raw events from multiple, heterogeneous sources, and distribution of those events to event consumers. Events are represented using the Common Base Event model, which is a standard defining a common representation of events that is intended for use by enterprise management and business applications. This standard, developed by the IBM Autonomic Computing Architecture Board, supports encoding of logging, tracing, management, and business events using a common XML-based format, making it possible to correlate different types of events that originate from different applications.

Input and Output attributes

This FC's Input and Output Attributes are identical to those of the CBE Parser.

Configuration

The CBE Function Component uses the following parameters:

Logger's Name

The name of the logger. This is an optional attribute and if you not define it defaults to LocalHostIP .

Mode

This specifies whether this Function Component returns either CBE object from an Entry or Entry from a CBE object. Possible values are:

Entry -> CBE: This is the default mode that was used before Tivoli Directory Integrator 7.1.1. In this mode you must provide the required attributes of the OutputMap and receive the CBE object in the "event" attribute (also a XML representation in the "eventXml" attribute) of the InputMap.
CBE -> Entry: This mode that gives the user the ability to convert CBE event object to attributes. The CBE object is expected either in the event attribute of the OutputMap as plain Java object or in the eventXml attribute as XML representation. Then the attributes returned are provided in the InputMap. Specific for the XML is that the value of a tag (<situationType> someValue </situationType>) is taken as it is. This means that if it contains new lines or tabs then these characters will be returned to the attribute the same way.

Validate XML

Specifies whether to validate the XML against the XSD schema of the CBE specification. The default is "true".

Debug

Turns on debug messages. This parameter is globally defined for all Tivoli Directory Integrator components.

Generating a CBE Log XML

One of the primary needs for Tivoli Directory Integrator customers will be to have the ability to generate CBE compliant logs for their products so that other CBE log analyzers, like IBM's Autonomic Computing Toolkit's Log and Trace Analyzer (LTA), etc can be used to generate reports and analyze logs for different systems in a common and consistent manner.

You can create solutions which parse existing log files and generate new log files which are CBE compliant, or you can directly make your products communicate with Tivoli Directory Integrator, which will in turn generate logs in CBE compliant format.

Whatever the scenario, the CBE FC will have to be used to generate CBE events. You could accomplish this using the following steps:

Your put the required attributes to log inside the AssemblyLine's work entry. You may do this by parsing some existing product logs, or by reading a history database, etc.
The attributes are fed into the CBE FC by using the FC's Output Map operation, and the CBE FC generates an instance of a CBE Event object which has its various attributes set as per user passed values.
In one of the hooks (after event generation from CBE FC), a call to the getCBELogXML( ) API (exposed in the CBE FC) can be made, and the newly created event object can be passed. The resulting output string will be an XML fragment which adheres to the Hyades CBE Logging format. The string received from the getCBELogXML( ) API can be (for example) set back into the work entry by calling the work.setAttribute( ) API.
```
var cbe = work.getObject("event"); 
var xmlString = com.ibm.di.fc.cbe.CBEGeneratorFC.getCBELogXml(cbe,false); 
work.setAttribute("logXML",xmlString); 
```
Then, using the File Connector with a LineReader parser, you can write this new attribute (containing the CBE Log XML) to any log file.

Emitting events to a CEI Server

With the aid of the CBE FC, you can emit/receive CBE events directly to the IBM CEI Server component. Currently, the IBM CEI server is a component that is shipped along with IBM WebSphere Process Server version 6.0. For an external Java application (not running inside WAS), the only way to emit events to a CEI server is to make use of the TEC web service available at: https://cs.opensource.ibm.com/projects/mainstream/.

This web service makes use of WS Notification to receive CBE events from external applications, and then making use of the IBM CEI SDK, transmits these CBE events to the CEI Server. This web service does not currently provide any means to consume or subscribe to events - and this is something that the TEC team may consider once WebSphere releases a standardized implementation of WS-notification.

The following steps illustrates how you can configure a solution to emit events to the IBM CEI server:

You put the required attributes inside the AssemblyLine's work entry. You may do this by parsing some existing product logs, or by reading a history database, etc.
The attributes are fed into the CBE FC by using the FC's Output Map operation, and the CBE FC generates an instance of a CBE Event object which has its various attributes set as per user passed values.
The event object is passed to Tivoli Directory Integrator's Axis web service FCs, which will serialize the CommonBaseEvent object; and send it over SOAP to the CEI webservice (on user defined port and WSDL address).
The CEI Web service will transmit this event to the CEI Server.

Function Component API

The CBE FC exposes the following methods (also see the Javadocs for this component):

public String convertCBEEventToXML (CommonBaseEvent event) throws Exception

This method will convert a CommonBaseEvent object to a XML string object. This XML will also be available by default in the eventXml attribute of the Input Map.

public String getCBELogXML (CommonBaseEvent event, boolean isCompleteXML)

This method is a wrapper over the org.eclipse.hyades.logging.java.CommonBaseEventLogRecord class's externalizeCanonicalXmlDocString( ) and externalizeCanonicalXmlString( ) API. This method can be used for obtaining a CBE Log XML. Whether the XML string returned is a complete XML document or just an XML fragment is decided by the isCompleteXML flag.

For more details see: http://archive.eclipse.org/tptp/4.2.0/javadoc/Platform/public/org/eclipse/hyades/logging/java/CommonBaseEventLogRecord.html

Also see Generating a CBE Log XML.

public static String mapCbeToEntry (CommonBaseEvent cbe, Entry entry)

This static method maps the fields of a Common Base Event object into the attributes of a Tivoli Directory Integrator Entry. The process is the reverse of what the CBE FC's 'perform' method does. All attributes in the resulting Entry are of type java.lang.String.

This method is accessible through Javascript in Tivoli Directory Integrator.