WebSphere

Event Emitter mediation primitive

Use the Event Emitter mediation primitive to emit significant business events from inside a mediation flow.

Introduction

The Event Emitter mediation primitive sends out events, during a mediation flow. Because the events are generated in the form of Common Base Events (CBE) they have a standard XML-based format. The events are sent to a Common Event Infrastructure (CEI) server. For information on CEI resources and services refer to the runtime product documentation and runtime online help.

You can decide whether generated events contain the message being processed, or not.

The Event Emitter mediation primitive has one input terminal (in), one output terminal (out) and a fail terminal (fail). The in terminal is wired to accept a message and the other terminals are wired to propagate a message. The out terminal propagates the original message. If an exception occurs during the processing of the input message, the fail terminal propagates the original message, together with any exception information contained in the failInfo element.

Details

If a generated event contains the message being processed, the event format can be version 6.1 or version 6.0.2. By default, Event Emitter mediation primitives emit events in version 6.1 format, when running on a version 6.1 system.

The version 6.1 format, stores the message as an XML element in the xsd:any slot of a CBE. Because the message is stored in an xsd:any slot, you can retrieve it as an XML instance and use existing XML technologies to process it in an efficient way.

The version 6.0.2 format, stores the message in CBE extended data elements, after either shredding the message or serializing it as a hex value. You can choose to emit events in the version 6.0.2 format, by choosing the appropriate setting in WebSphere® Integration Developer.

To fully utilize Event Emitter information, event consumers need to understand the structure of the CBE. The mechanism for modeling this data is described in more detail in the Detailed event contents section.

6.1 format

A 6.1-format event, generated by the Event Emitter primitive, can contain the elements described in the following table.
Table 1. 6.1-format event elements
Element Sub-elements Description
event eventPointData ModuleName The name of the module instance
MediationName The name of the Event Emitter instance
EventEmitterLabel The Label property value
Root The Root property value
applicationData content value Application data
Note:
  • If a generated event does not contain the message being processed, the applicationData child element of the event element is absent.
  • If the Root property of the Event Emitter primitive specifies a single leaf element, the applicationData element contains the value of the leaf element. At run time this would generate the following CBE element: event/applicationData/content/value.
  • If the Root property of the Event Emitter primitive specifies a business object, the applicationData element stores the specified business object. For example, if the business object contained an accountID and creditLimit, at run time this would generate CBE elements: event/applicationData/content/value/accountID and event/applicationData/content/value/creditLimit.

6.0.2 format

A 6.0.2-format event, generated by the Event Emitter primitive, always contains the three extended data elements described in the following table.
Table 2. 6.0.2-format mandatory extended data elements
Extended Data Element Description
ModuleName The name of the module instance
MediationName The name of the Event Emitter instance
Root The Root property value
If the Root property is specified and resolves to a location in the SMO an additional extended data element is included in the event, as described in the following table.
Table 3. 6.0.2-format optional extended data elements
Extended Data Element Description
Message Contains the section of the SMO specified by the Root property. This extended data element can contain other, nested, extended data elements corresponding to elements in the specified section of the SMO

Usage

The Event Emitter mediation primitive enhances your monitoring capability by allowing you to send business events from a mediation flow component. You can then view the Event Emitter events using the CBE browser, on the application server, or other CBE consumer applications.

The recommended best practice is to use the Event Emitter mediation primitive to indicate an unusual event. For example, notification of a failure in the flow or an unusual path in the flow. When you place event emitters in a flow you should consider the possible number of events that can be generated, and the size of the message that will be stored in the event. Placing an event emitter in the normal flow path generates many events compared to placing it in an unusual event or failure path. In addition, consider configuring the emitter to store only significant message data, rather than the complete message, to reduce the overall size of the event.

You can use the Event Emitter mediation primitive to record a failure in another mediation primitive, and then continue processing. To do this you wire the fail terminal of the previous mediation primitive to the input terminal of the Event Emitter mediation primitive; and wire the output terminal of the Event Emitter mediation primitive to the next step in the flow.

You can also use the Event Emitter mediation primitive, in combination with the Message Filter mediation primitive, to generate business events based on message content. To do this you wire one of the output terminals of the Message Filter mediation primitive to the input terminal of the Event Emitter mediation primitive; and wire the output terminal of the Event Emitter mediation primitive to the next step in the flow.

Properties

Enabled
By default the mediate action of this mediation primitive is enabled. You can suspend the mediate action by clearing the checkbox.
Label
Allows you to define a unique identifier for the event. The unique identifier maps to the extension name of the CBE. WebSphere Integration Developer provides a default label, but it is strongly recommended that you provide a more meaningful event label for your particular event type. Events are emitted to the CEI server, which can be accessed by many different event consumer applications; therefore, event names should be unique across the system in order to distinguish different event types. If two Event Emitter mediation primitives generate exactly the same event type, it might be acceptable to have the same Label name.
Transaction mode
Lets you override the transaction mode set on the emitter. (An event source, such as an Event Emitter mediation primitive, does not interact directly with the event server; instead it interacts with an object called an emitter.) The transaction mode can be configured in the CEI infrastructure or overridden at the Event Emitter mediation primitive level. If you specify the Default transaction mode, events are sent to the CEI server using the default setting in the CEI emitter. If you specify the Existing transaction mode, events are sent to the CEI server in the flow's transaction; and if you specify the New transaction mode, events are sent to the CEI server outside the flow's transaction.
Root
An XPath 1.0 expression representing the part of the message to be included in the CBE. You can specify: /, /headers, /context, /body or your own XPath expression. / refers to the complete SMO, /headers refers to the headers of the SMO, /context refers to the context of the SMO, and /body refers to the body section of the SMO. If you specify your own XPath expression, the part of the SMO you specify is processed.
Table 4. Event Emitter mediation primitive properties
Property Valid Values Default
Label String Combination of module name, flow name and flow type. The flow type indicates whether the flow is a request or a response
Enabled Clear the checkbox if you want to suspend mediate action. Selected
Transaction mode String: Existing, New or Default Default
Root String: an XPath expression representing the root of the SMO that is stored in the event  

Considerations

Consider the following when using the Event Emitter mediation primitive:

Detailed event contents

The events emitted by the Event Emitter mediation primitive conform to the CBE 1.0.1 structure. The CBE specification is part of the IBM® Autonomic Computing Toolkit. For more information about the specification, see: http://www.ibm.com/autonomic/.

The following elements are common to all Event Emitter events:

extensionName
The value of this field corresponds to the value of the Event Emitter mediation primitive Label property.
sourceComponentID
The sub-elements of this field are automatically completed with information specific to the environment that the mediation primitive is running in; for example, component and hostname.
situation
The situation type is ReportSituation.
The following information can only occur in 6.1-format events:
event
In the CBE schema, there is a section whose type is xsd:any. If a 6.1-format event is emitted, this section contains the event data.
eventPointData
Contains information about the Event Emitter primitive that generated this event. It contains the following child elements:
ModuleName
Contains a string value corresponding to the mediation module name. The following is an example element, in XML form:
<esb:ModuleName>Test2</esb:ModuleName>
MediationName
Contains a string value corresponding to the Event Emitter primitive's name. The following is an example element, in XML form:
<esb:MediationName>EventEmitter1</esb:MediationName>
EventEmitterLabel
Contains a string value corresponding to the Event Emitter primitive Label property. The following is an example element, in XML form:
<esb:EventEmitterLabel>Test2_Test2_EventEmitter1_Req</esb:EventEmitterLabel>
Root
Contains a string value corresponding to the Event Emitter primitive's Root property. If the Root property is not specified, the Root element is not included. The following is an example element, in XML form:
<esb:Root>/body/operation1/input1/field1</esb:Root>
applicationData
If the Event Emitter primitive Root property is specified, the applicationData element holds a content element with a name attribute set to Message.
If the Root property evaluates to a single leaf element in the message, the leaf element value is contained in a single value element, appropriately typed. The following is an example content element, in XML form:
<wbi:content wbi:name="Message">
	 <wbi:value xsi:type="xsd:string">hello</wbi:value>
</wbi:content>
If the Root property evaluates to a subtree in the message, the content element contains child elements corresponding to the message tree structure. For example, the message defined by the following XSD type definitions:
<xsd:complexType name="MyBO">
        <xsd:sequence>
                <xsd:element name="value1" type="xsd:string"/>
                <xsd:element name="value2" type="bons0:MySubBO"/>
        </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="MySubBO">
        <xsd:sequence>
                <xsd:element name="value1" type="xsd:string"/>
                <xsd:element name="value2" type="xsd:int"/>
        </xsd:sequence>
</xsd:complexType>
could produce the following example Message element:
<wbi:content wbi:name="Message" wbi:businessObjectName="MyBO" wbi:targetNamespace="http://Test" >
        <wbi:value xsi:type="p:MyBO" >
                <value1>hello</value1>
                <value2>
                        <value1>world</value1>
                        <value2>1234</value2>
                </value2>
        </wbi:value>
</wbi:content>
The following information can only occur in 6.0.2-format events:
extendedDataElements
The following extended data elements refer to the application specific data.
ModuleName
Contains a string value corresponding to the mediation module name. The following is an example extended data element, in XML form:
<extendedDataElements name="ModuleName" type="string">
	<values>CustomerMediation</values>
</extendedDataElements>
MediationName
Contains a string value corresponding to the Event Emitter primitive's name. The following is an example extended data element, in XML form:
<extendedDataElements name="MediationName" type="string">
	<values>ServiceFailureEvent</values>
</extendedDataElements>
Root
Contains a string value corresponding to the Event Emitter primitive Root property. If the Root property is not specified, the value contained in this field is: No Data. The following is an example extended data element, in XML form:
<extendedDataElements name="Root" type="string">
	<values>/body/operation1/input1/customerID</values>
</extendedDataElements>
Message
Contains the information in the message that was configured by the mediation primitive Root property to be stored in the event. If the Root property evaluates to a single leaf element in the message, the value is contained in this one extended data element. The following is an example extended data element, in XML form:
<extendedDataElements name="Message" type="string">
	<values>ABCDE12345</values>
</extendedDataElements>
If the Root property evaluates to a subtree in the message, the Message extended data element contains child extended data elements corresponding to the message tree structure. For example, the message defined by the following XSD type definitions:
<xsd:complexType name="MyBO">
	<xsd:sequence>
		<xsd:element name="value1" type="xsd:string"/>
		<xsd:element name="value2" type="bons0:MySubBO"/>
	</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="MySubBO">
	<xsd:sequence>
		<xsd:element name="value1" type="xsd:string"/>
		<xsd:element name="value2" type="xsd:int"/>
	</xsd:sequence>
</xsd:complexType>
could produce the following example Message extended data element:
<extendedDataElements name="Message" type="noValue">
	<children name="value1" type="string">
		<values>ABCDE</values>
	</children>
	<children name="value2 type="noValue">
		<children name="value1" type="string">
			<values>ZYXWV</values>
		</children>
		<children  name="value2" type="int">
			<values>12345</values>
		</children>
	</children>
</extendedDataElements>
Note: If the Root property is not specified as part of the Event Emitter primitive property configuration, or if Root is specified but the property does not evaluate to an element in the message, the Message extended data element does not appear in the event.

reference Reference topic

Terms of use | Feedback


Timestamp icon Last updated: 20 June 2010 00:39:55 BST (DRAFT)


http://publib.boulder.ibm.com/infocenter/dmndhelp/v6r2mx/topic//com.ibm.wbit.help.medprim620.doc/ref/rwesb_EventEmittermediationprimitive.html
Copyright IBM Corporation 2005, 2010. All Rights Reserved.
This information center is powered by Eclipse technology (http://www.eclipse.org).
iDoc on