WebSphere WebSphere Enterprise Service Bus, Version 6.0.2 Operating Systems:

Event Emitter mediation primitive

Use the Event Emitter mediation primitive to emit business events from within a mediation flow, if an unusual event occurs.

Introduction

The Event Emitter mediation primitive sends out business events, during a mediation flow. The events are generated in the form of Common Base Events (CBE) and 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 generate events that include all or part of the message being processed. Alternatively, you can generate events that do not include any part of the message being processed.

You can generate events that include all or part of the message being processed, by setting the Root property. The Root property is an XPath expression that specifies the section of the Service Message Object (SMO) that is included in the CBE application specific elements (extended data elements). The Root property can specifiy the complete SMO, a subtree or a leaf element.

If you do not set the Root property then you generate events that do not contain any part of the message being processed. You also generate events that do not include the message in another way. If you specify the Root property, but its value does not match any of the elements in the SMO when the message is mediated.

The Event Emitter mediation primitive has one input terminal and two output terminals. One output terminal is for successful output and one for failure output. The input terminal is wired to accept a message and the output terminals are wired to propagate a message. The successful output terminal propagates the original message. If an exception occurs during the processing of the input message, then the fail terminal propagates the original message, together with any exception information.

Details

A CBE event generated by the Event Emitter always contains the three extended data elements described in the table below.
Table 1. 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 table below.
Table 2. 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

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 below.

The Event Emitter mediation primitive enhances your monitoring capability by allowing you to send business events from within 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.

Usage

The recommended best practice is to use the Event Emitter mediation primitive to indicate an unusual event, such as notification of a failure within the flow or an unusual path executed in a flow. When you place event emitters within a flow you should consider the possible number of events that may be generated as well as the size of the message that will be stored within the event. Placing an event emitter within the normal flow execution path will generate many events compared to placing it within 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

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 this is overridden to 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 then 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. The Default means that events are sent to the CEI server using the default setting in the CEI emitter. If you specify Existing then events are sent to the CEI server within the flow’s transaction; and if you specify New then 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: /, /body, /headers, or your own XPath expression. / refers to the complete SMO, /body refers to the body section of the SMO, /headers refers to the headers of the SMO. If you specify your own XPath expression then the part of the SMO you specify is processed.
Table 3. 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 response
Transaction mode String: Existing, New or Default Default
Root String: an XPath expression representing the root of the SMO that will be stored in the event  

Considerations

Consider the following when using the Event Emitter mediation primitive:

Detailed event contents

The events emitted from the Event Emitter mediation primitive conform to the Common Base Event 1.0.1 structure. The Common Base Event specification is part of the IBM Autonomic Computing Toolkit. For more information about the specification, visit the IBM Autonomic Computing Web site at http://www.ibm.com/autonomic/.

The information below describes some of the contents of the event generated from the Event Emitter primitive.

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.
contextDataElements
These are included to provide context data information.
extendedDataElements
The event contains some extended data elements that are for the runtime's internal use only. However, the following extended data elements refer to the application specific data.
ModuleName
This contains a string value corresponding to the mediation module name. The following is an example extended data element, as XML.
<extendedDataElements name=”ModuleName” type=”string”>
	<values>CustomerMediation</values>
</extendedDataElements>
MediationName
This contains a string value corresponding to the Event Emitter primitive's name. The following is an example extended data element, as XML.
<extendedDataElements name=”MediationName” type=”string”>
	<values>ServiceFailureEvent</values>
</extendedDataElements>
Root
This contains a string value corresponding to the Event Emitter primitive Root property. If the Root property was not specified then the value contained in this field will be No Data. The following is an example extended data element, as XML.
<extendedDataElements name=”Root” type=”string”>
	<values>/body/operation1/input1/customerID</values>
</extendedDataElements>
Message
This extended data element contains the information in the message that was configured by the mediation primitive Root property to be stored within the event. If the Root property evaluates to a single leaf element within the message, the value will be contained in this one extended data element. The following is an example extended data element, as XML.
<extendedDataElements name=”Message” type=”string”>
	<values>ABCDE12345</values>
</extendedDataElements>
If the Root property evaluates to a sub-tree within the message, the Message extended data element will contain child extended data elements corresponding to the message tree structure. For example, the message defined by the XSD type definitions described below:
<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>
would 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 has not been specified as part of the Event Emitter primitive property configuration, or if Root has been specified but the property does not evaluate to an element in the message, then the Message extended data element will not appear within the event.

Reference topic

Terms of Use | Rate this page

Timestamp iconLast updated: 29 Oct 2006
http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.wbit.help.medprim602.doc\ref\rwesb_EventEmittermediationprimitive.html

(C) Copyright IBM Corporation 2005. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)