Introduction

Monitoring SOA applications is a very important part of understanding the performance of different services and is critical to business performance management (BPM). SOA applications, built for WebSphere Process Server, contain many built-in events that can be enabled, generated by the WebSphere Process Server, and used for measuring business performance. Events can be generated when a component is called, or when a response is returned. Events can also be generated when specific actions occur or states change within the execution of a component. Based on these built-in events, a monitoring application can report the execution behavior and performance for an application. Unfortunately, these built-in events are not always specific enough for monitoring every aspect of the application, especially when monitoring at the instance level. Instance-level information may not be included with built-in events, which makes it difficult to distinguish the originating instances, and report results correctly. To get accurate information, you might need to use custom events that report instance specific information.

When looking at processing built-in and custom events together to report the performance of a single application, correlation becomes an important piece of the event processing. To correlate the events, the processor must recognize some identifier in all events, and based on the value of this identifier, it will be combined with other events and processed.

Identifiers in the event can be part of the business data or can be part of the event context or header. If you use the same identifier in all events for an originating instance, correlation of the events becomes a simple exercise. In many enterprise applications however, where events are coming from different systems and from different applications, and are transported via different protocols, a single identifier may not be an option for event correlation. You might need multiple identifiers and logic to recognize how additional events and their (new) identifiers are related to prior events with different identifiers.

WebSphere Business Monitor v6.0.2 lets you monitor events regardless of whether they are built-in or custom, and provides ways to correlate events with different identifiers.

Scenario

For this article, you monitor the order processing application shown in Figure 1. The order processing application is based on a BPEL business process that is responsible for coordinating the different activities that must be completed as an order is filled. The BPEL process checks to see if the order is above $1000. If it is above $1000, then a manual approval is required. If it is equal to or under $1000, then the order is automatically approved. Once the order has been approved, a business rule is called to apply a discount to all orders above $10,000. The BPEL process will then call the service that interacts with a fictitious legacy system, to establish the invoice for shipping the order. To interact with the legacy system, a mediation flow is used. Once the invoice is created, the order can be shipped.

To monitor the business performance of this application,you first need to analyze the important business metrics and determine the key performance indicators for the business. This information helps determine what events are needed from what part of the application as well as the correct information to include in the event.

We did not include details on how to perform this analysis in this article, however there are other resources (listed in the Resource section) that describe the methodology for determining the correct events to generate. For the purposes of this article, assume that we need to enable different default and custom events (Figure 2), and we need to correlate these events.

All of the events generated from these application components share a common value(OrderNumber) that we can use for correlation. The ShipItems component is the only component that does not generate events with this value. Correlation of this event with the others is the primary challenge that this article describes how to overcome.

Back to top

Exploring different event generation options

WebSphere Process Server (hereafter called Process Server) is the runtime environment for integration applications based on SOA. With WebSphere Integration Developer, you can build different components for integrating different applications using business processes, human tasks, business rules, interface maps and mediation flows. As described earlier, it provides built-in events for these components, and you define custom events to monitor with WebSphere Business Monitor. With WebSphere Integration Developer, you can enable the built-in events, and you can also create custom events within SOA applications. You enable the built-in events at the SCA component level or within individual component types, such as business processes, human tasks, and business rules. You can generate custom events using a variety of techniques. For mediation flows, you specify custom events with the event emitter primitive. You can also specify custom events programmatically, with the Visual Snippet editor, and with the Java editor. This section describes each of these types of events.

Built-in component-generic events (available for any component)

For the purpose of this article, let's assume that we've already defined the components and connected with one another. We provide a project interchange for you to import into WebSphere Integration Developer to explore the different built-in and custom event options. See the Download section for more details.

You use the Assembly editor to enable the default event generation options, available at the component level. Each service component is represented in the Assembly Diagram, shown in Figure 3:

To enable default events for the OrderProcess component, use the Details tab of the Properties view. The default events are available on the interface definition for the component. For the OrderProcess component, expand Interfaces - BPELOrder and select the processOrder operation. On the right side of the Properties view, select the Event Monitor tab.

For every component, you can enable a number of built-in events to generate when an operation on the component is called. An event can also be generated when a response is returned or if a fault is returned. For most monitoring applications, generating events for Entry and Exit is sufficient to monitor their execution

You can also control the amount of information that is generated, with these options: .

1. Empty -- event contains only basic information, such as the event name and type.
2. Digest -- event contains a subset of the full business data, available at the point the event is generated.
3. Full -- event contains all of the business data, available at the point the event is generated.

The Event Content is an important setting, especially if your monitoring application uses business payload data for correlation purposes. Fields in the business payload used for correlation must be included in the generated event.

Each event has a corresponding Label field (located to its right). You use this field to place a text value in the event. You can use this field to add a value that identifies the kind of event. However, every event of this kind produced at runtime (every event instance) will contain the same value in this field. To correlate events from the same process or service execution, you need a value that uniquely identifies each execution (such as "order number"). Obviously, this value must be dynamically created and cannot be entered up-front in a configuration panel.

After you enable the events, and save the Assembly editor, icon decorators (small yellow flags) appear that indicate events have been enabled for the component, as Figure 7 shows:

You can enable similar built-in events for other components, such as ShipItems, ManualOrderProcessing, and AutomatedOrderProcessing.

Built-in component-specific events (depending on the kind of component)

Each component can generate built-in events that are specific to the behavior of the component when it is invoked. These events typically fire when a state change occurs, or an important event during the invocation of the component occurs. Some of these events may overlap with events at the SCA level discussed in the previous section, which are component-generic (available for any kind of component). The decision to enable events at the SCA level or at the component level again is one based on the level of granularity needed from the events. In most situations, it is better to choose the higher level, which allows the events to be more easily correlated with other events, even from a different component. If there are specific pieces of processing within the component that merit specific monitoring, such as state changes of a process activity(which can be suspended, resumed, cancelled, etc) then you must use events at the component level.

To enable component-specific default events, open the component in the appropriate editor, and select the Properties view. The Properties view contains an Event Monitor tab, which lists the component specific default events. For example, the OrderProcess business process you can enable component specific default eventsto be generated when a state changes in the overall process (such as "process suspended", "process resumed", etc.), as Figure 8 shows:

In certain component types, such as the OrderProcess business component, you can enable additional specific built-in events. For example, you can enable specific built-in events in the RulesDiscount invoke activity to be generated when the activity is invoked, completes, and other state changes. As stated above, the best place to enable these events is usually at the higher level such as at the component, especially since this activity is using a reference partner to call a business rules component. You can enable the events at the component instead of at the activity in the business process.

You might also notice an option named All, which specifies to generate all of the built-in events for that activity or component at a specific Event Content level (Figure 9). Using this All option allows for all of the events to be enabled quickly. Enabling all events is not recommended, because each event incurs a certain amount of overhead, and many events are only of interest in very specific situations which are not applicable for general business performance monitoring.

When you save, icon decorators appear on the OrderProcess itself in the Process editor and the RulesDiscount invoke activities, which are the two components for which we have enabled events (Figure 10).

Human task components also have component specific default events that you can enable for specific state changes of human task instances. The Properties view of the ManualOrderProcessing human task shows the different component specific default events (Figure 11).

For most of the default Human Task events, there is no business data contained in the event even with an Event Content setting of Full. However, the Output Set event does report the business data and thus can be used for correlation, based on a unique identifier within the business data section (for example, OrderNumber). More information on what is included in the Event Content of built-in events for the different settings is available in the WebSphere Process Server Information Center.

Custom activity editor events

You can generate custom events from within the execution logic of some of the individual components. WebSphere Integration Developer assists in the generation of custom events within applications. For example, in the Activity Editor (Visual Snippet Editor), you can add the appropriate code to generate a custom event. Custom events allow for more specific information to be passed with an event, and generated in conditional situations, which the built-in events may not support.

The OrderProcess business process component has a snippet activity, where a custom event can be generated. Select the AlertHighOrder snippet activity shown in Figure 12.

The Details tab lists the activity implementation, and contains logic that only generates an event (HighOrderEvent), when the order amount is over $10,000. We specified this custom event using the standard snippet event emitter. You must define all custom event definitions (event structure and attributes) prior to using them in a visual snippet activity. (To create custom events, select File - New - Event Definition. For more details on creating a custom event, see the WebSphere Integration Developer Information Center) To add a custom event to the visual snippet activity, select the Standard snippet option. In the Add a Standard Visual Snippet window, expand events and select event emitter (Figure 13). Then select OK.

The Event Selection window shows the list of custom events that have been defined in the module. At this point you can select HighOrderEvent (Figure 14), and then, in the visual snippet editor, specify which data the event should include.

Figure 15 shows wrapping the event emitter in logic so that events are generated only for orders over $10,000.

Custom mediation flow events

You can also use the custom event generation option in Mediation Flow components. In the GetInvoiceMediation mediation flow in the SampleWESB module, select the connection between the requestInvoiceNumber operation under RequestInvoice and the requestInvoceNumber operation under RequestInvoicePartner, as Figure 16 shows.

Select the Response: requestInvoiceNumber tab, which represents the mediation flow for the response.

The Mediation Flow editor lets you insert a primitive in a flow to generate events. The response flow shown in Figure 18 has the CorrelationEvent primitive specified; you can view itsdetails in the Properties view under the Details tab.

For the event emitter primitive, the contents of the event are based on an XPath expression that references some part of the Service Message Object (SMO). For the CorrelationEvent primitive, the body of the SMO is specified.

Custom programmatic events

You can also generate custom events using the appropriate Java APIs. The ShipItems component in Figure 20 is an example of a component with a custom event.

Let's examine the code for the shipOrder method. The method starts by creating an instance of the ECSEmitter, which generates common base events. Notice the value HighShippingEvent, which is passed to the createCommonBaseEvent method. It determines the type of the event (the structure of its variable payload) and can be used for filtering on the event consumer side (WebSphere Business Monitor). After we create the event, we must specify its contents. Custom payload information is typically placed into attributes of an ExtendedDataElement.

Listing 1. ShipItems component for custom event generation

ECSEmitter myEmitter = 
      new ECSEmitter("com/ibm/events/configuration/emitter/Default", null);

CommonBaseEvent myEvent = myEmitter.createCommonBaseEvent("HighShippingEvent");

// Add ExtendedDataElements

  myEvent.addExtendedDataElement("InvoiceNumber", 
          input1.getString("invoiceNumber"));
   myEvent.addExtendedDataElement("Shipper", 
          input1.getString("shipper"));
   myEvent.addExtendedDataElementWithFloatValue("ShippingCost", 
          input1.getFloat("shippingCost"));

// get Situation object
   Situation mySituation = myEvent.getSituation();

// set Situation properties
	mySituation.setCategoryName("ReportSituation");
	mySituation.setReportSituation("EXTERNAL", "STATUS");

// send the event
	try {
		myEmitter.sendEvent(myEvent);

The generated event does not contain the correlation value (OrderNumber) used by the other events. However, it copies the InvoiceNumber to the event, which you can use as an alternate correlation key. We'll discuss correlation of this event using this value in the next section.

Back to top

Creating the monitoring model

All built-in events that we enabled and all custom events that we have added can be monitored. By defining correlation predicates in a monitor model, you can specify which sets of events originate from the same observed instance (for example, from an application run or a process execution) and correlate them within a common monitoring context. The model also defines items like metrics, counters, stopwatches, triggers, and key performance indicators, which again are specific to the entity being observed.

The challenge with monitoring the different built-in and custom events is establishing the correlation between these events, such that the information they carry can be viewed in the form of a single business transaction, and not as a set of individual, unrelated events. There are a number of different correlation strategies you can use with the help of the WebSphere Business Monitor Toolkit. Each strategy has advantages and disadvantages to consider before creating the monitor models that define the boundaries of the monitoring context. In the next sections we compare two of these strategies.

Option 1: Use multiple monitor models, one per monitored component

This option is the default in the WebSphere Business Modeler Toolkit. You can create Monitor models for individual components at the SCA level, business process component level, human task component level and mediation flow component level. Each of these (child) monitor models defines a separate monitoring context that can monitor that component in isolation.

With this setup, to correlate events from SCA components, business process components, and human task components into a single viewable business transaction, you have to send additional events from one monitor model to another (parent monitor model) through the definition of triggers, outbound and inbound events. The different monitor models define outbound events, which may be received in an overarching parent model representing the business transaction end-to-end.

Each monitor model can use a different correlation key to correlate the events it subscribes to, however, you need a truly global ID for correlation with the overarching parent monitor model. This global ID may be the same as used in the individual monitor models, however in many cases it will be different.

While this option requires less development time (since we are reusing the generated, per-component monitor models) and still allows for the definition of a single monitoring model for monitoring the end-to-end business transactions, it does introduce some disadvantages:

• You must maintain the different monitoring models individually in the development environment.
• You deploy each monitor model as a separate EAR file, which incurs additional resources in the runtime environment as well as higher management and maintenance costs.
• There is additional event traffic between the subordinate (per-component) monitor models, and the single, end-to-end model representing the business transaction.
• You must create the parent model manually, and while doing so, why not define it in such a way that it subscribes directly to the events from individual components, rendering the component-level models obsolete?

Advantages

• Reuse pre-generated monitor models (less development time)
• Single overall monitoring model and context available for monitoring end-to-end

Disadvantages

• Must maintain multiple monitor models in the development environment
• Must maintain multiple monitoring EARs in the runtime environment
• Additional (internal) event traffic to update the parent model based on changes in the child models
• Need to manually define the overarching parent model

Option 2: Use a single monitoring model

This option uses a single monitoring model to capture all events. To facilitate the development of this single model, you can use the generated, component-level models as a starting point and manually merge them into the single monitoring model that you then deploy. This option does not necessarily require a single global ID value to correlate all events. To establish additional correlation keysto be used by any events from that point on, you can use metric values (metric keys) that can be set at any time in the monitoring model. While this manual step requires extra work compared to using all of the generated, component-level models, it is easier to maintain and manage in the long run.

Advantages

• Single monitoring model and context maintained in the development environment
• Monitoring module and context only contains information that is of importance to monitoring the events (extraneous event information is not included)
• Single monitor module EAR to deploy and manage
• Allows for events that do not contain the same global ID to share a single monitoring context

Disadvantages

• Correlation at development time may be more difficult, because multiple keys are not obvious, since they do not exist until later in the business transaction
• Cannot maintain order of events without additional timestamp or some other order checking
• Higher level of development work

For example, you can initialize a monitoring context by setting its key to the OrderNumber. Later, a createInvoice event populates a simple metric invoiceNumber, which you then can use to correlate all events related to invoice processing. While invoiceNumber is just an ordinary metric, not a key, it can still be used for correlation.

Additional considerations for event correlation options

• Metric keys are alternate keys. That is, when you set a metric key, you can identify the Monitoring Context instance by either the key or the metric key (or both). This introduces some fairly strict requirements.
• If you use metric keys, event ordering now becomes critical. Only a few events contain both the known (established) key and the new metric key, that can be used to initialize the new key. Subsequent events may use the metric-key for correlation, but must occur after the event(s) that established this secondary key. If they arrive out of sequence, a "no correlation matches" exception could occur if the metric key has not been set.
• The metric key must truly be unique to allow events that only contain this key to be correlated.
• Using the single monitoring context option for metric keys: If there are two metric keys in a single monitoring context you need to add specific code in the correlation expression to identify which metric key to set.
• Using multiple monitoring models and parent/child monitoring contexts:
  • You can use a child context to bundle information identified by the metric key (secondary key) when it has a different lifespan than the primary (parent) monitoring context.
  • You must define a child monitoring context when, for each value of the primary (parent) key, there can be more than one value of the secondary (child) key.
  • Using child monitoring contexts allows both keys to be true keys of a monitoring context. You can use the correlation event containing both keys as the creation event for the child monitoring context. The events that only have the second key must be received in the child context, and can be correlated using expressions that only check against this secondary key.
  • While in general, a child MC key value is only required to be unique amongst children of the same parent, it must be globally unique if a child context is used to bundle metrics indexed by a secondary key as described above (like invoiceNumber in the earlier example). Events that are correlated using that key may not contain the key of the parent context, and thus will have to be matched with their target context based on that secondary key value alone.
• Frequency of correlation sphere change
  • The correlation sphere is the boundary at which a key value is valid. If your monitoring application requires frequent changes of correlation spheres, (i.e. the correlation key changes many times throughout the business transaction) or there are many different correlation sphere activities at one time that you must correlate in a parent context, you may want to reexamine your monitor models. Such models would be much more complex to implement using a single monitoring context, given the number of metric keys that would be required and the difficulty of accurately describing the model to keep track of when a specific event will have a key value set that will be specific to the correlation sphere of the child context. It may be better for the child context and correlation sphere to only send a few events to the correlation sphere of the parent context.
• Dashboard identifiers: The Dashboards allow the instance data to be sorted based on the key values, but not based on metric keys.
• Keys guard against changes in the key value during the life of the monitoring context instance. Metric keys provide no such protections.

For the remainder of this article, we'll use option 2, because it provides the most flexibility and simplifies the view of the monitor solution.

Types of identifiers

For correlation of different events, an identifier must be recognized in each event, and then used to group the event with other events, by correlating all of them with a single monitoring context. The identifier can be business data, non-business data, or a combination of both.

Business data is typically available in the application at the time the event is generated. The business data is specific to that instance. Things like order number, patient ID, or invoice number are examples of business data values that tend to be instance specific.

Non-business data is typically a value created by the event producer, and is generated by the runtime environment (not part of any business data, which is available at the time the event is generated). A service in the environment provides an ID value, which has been associated with the instance. This ID can then be attached to the generated events. A transaction ID, which identifies the instance, is an example of a typical non-business data identifier.

WebSphere Process Server provides a number of non-business data values for correlation. For any request handled by WebSphere Process Server, it establishes a session with a SessionID. The events, which are generated during the entire handling of a request, contain that SessionID. However, the SessionID is not passed when the processing of a request requires a call to a service over a transport, such as JMS or Web service (SOAP/HTTP or SOAP/JMS). Therefore, when a request comes back to WebSphere Process Server, although it is part of the larger business transaction, Process Server establishes a new SessionID to be used in subsequent events. Because of these boundaries of the SessionID, its use for correlation of large applications is limited.

Business processes that are executed on WebSphere Process Server have another set of ID values that can be used for correlation, besides the SessionID. It is a combination of two values, named ECSParentID and ECSCurrentID. When a business process runs, the current activity's ID is reported in the ECSCurrentID and the process instance ID in the ECSParentID. This defined pattern for the ECSCurrentID and ECSParentID values lets you correlate the events generated at the different activities. The limitation with using the ECSParentID and ECSCurrentID values for correlation is that solutions that are not executed from beginning to end as a single business process running in Process Server will not have these values in all issued events.

Because of the propagation limitations with the SessionID and ECSParentID and ECSCurrentID, an approach that uses business data values for correlation can be the most straight-forward strategy for monitoring large enterprise applications.

The main consideration for using business data values is that a value must be unique to the instance and available in all events. Because different business data may be available when events are generated from different applications on different systems, it may not be possible to use a single business data value throughout. At this point it becomes necessary to correlate using several unique business data values as described under option 2 above.

The WebSphere Business Monitor Toolkit can generate monitoring models that correlate based on SessionID, or ECSParentID and ECSCurrentID. This approach is not sufficient for monitoring contexts that use business data for event correlation; however, it can still be very useful to jumpstart building a monitoring model.

Back to top

Creating event definitions

After you have determined what should be monitored in your application and the different points that will generate the events with the correct business data, the next step in creating a monitor model is to generate all the event definitions for the monitor model. There are five sources for events in our example, for which you need to create event definitions:

• Built-in component-generic events (events available for any kind of component)
• Business process and human task events you enabled
• Events added in the Activity Editor (Visual Snippet Editor)
• Event from the event emitter primitive in our Mediation Flow Component, which also must be correlated based on the InvoiceNumber secondary key
• Events generated programmatically

To create the event definitions for the default component-generic events, start in the Business Integration view:

1. Expand the SampleBPEL module
2. Right-click on Assembly Diagram and select Monitor Tools - Generate Event Definitions, as Figure 21 shows:
   
   Figure 21. Generating event definition option for components
   
   
   

   You will see a pop up window confirming generation of event definitions that can be viewed in the Business Monitoring perspective.

3. Click OK. It is important to note that you can only view custom event definitions in the Business Integration view. Switch to the Business Monitoring perspective to see the other built-in event definitions.

To generate the event definitions for the business process and human task events, you perform similar steps:

1. In the Business Integration view, under SampleBPEL expand Business Logic - Processes.
2. Right-click OrderProcess and select Monitor Tools - Generate Event Definitions.
3. Click OK on the confirmation message.
4. In the Business Integration view, under SampleBPEL expand Business Logic - Human Tasks.
5. Right-click ManualOrderProcessing and select Monitor Tools - Generate Event Definitions.
6. Click OK to the confirmation message.

For the event emitter primitive in the Mediation Flow component, GetInvoiceMediation, you can generate the event definition using similar steps:

1. In the Business Integration view, under SampleWESB mediation module, expand Mediation Logic - Flows.
2. Right-click on GetInvoiceMediation, and select Monitor Tools - Generate Event Definitions.
3. Click OK on the confirmation message.

For the custom events, defined with the Activity Editor (Visual Snippet Editor) and programmatically, you cannot generate the event definitions for the custom event automatically. You must manually create the definition using the Event Definition editor.

Back to top

Creating the initial monitoring model

You can jumpstart creation of the OrderProcess monitoring model by generating an SCA monitor model. The SCA monitoring model uses the SessionID to correlate the different Common Base Events, generated by the SCA components. Even though you may not correlate all of your events on the SessionID, you can still use this model as a starting point.

You need to consider a few things if you are planning on using the monitoring model. You will find a key that is set to the value of the SessionID, and the generated Inbound Entry events all have a policy of "Create new Instance", if no instance of this monitoring context is found. Basically this is because the tooling currently does not have an algorithm for determining which Common Base Events are creation events. Each of the Inbound Entry events will set the key. Another item to consider for the SCA model is that it does not set a termination trigger because the tool does not determine which events are termination events. You need to manually change those aspects of the model.

1. To create the SCA monitoring model, expand the SampleBPEL module.
2. Right-click on the Assembly Diagram, and select Monitor Tools - Generate Monitor Model, as Figure 22 shows:
   
   Figure 22. Generate event monitor model option for components
   
   
   
3. Because this is the first Monitoring project, click on the New project... button and specify the following value:

Name: OrderProcesingMM

1. Click on Next, and a list of referenced projects appears.
2. Click the check boxes for SampleBPEL and SampleWESB, which allow the event definitions in the different projects to be used by the monitoring models defined in this project (Figure 23):
   
   Figure 23. Projects selected with event definitions
   
   
   
3. Click Finish to complete the creation of the project.
4. In the Generate Monitor Model window, specify the following value, as Figure 24 shows::

   Target monitor model name: OrderProcessing

   
   
   Figure 24. Single monitor model settings
   
   
   
5. Click Finish.

A Tour of the Model

At this point, it might be a good idea to expand the OrderProcessing Monitor Model Editor to its full size. Let's tour the interesting points about the model. First off, you'll see a Timestamp (UTC). This is important because the version of the model is based on this timestamp.

Second, expand the OrderProcessing Monitoring Model. The first layer is the OrderProcessing Monitoring Context. As explained, from an ease of use perspective, having a single monitoring context is ideal.

Now click OrderProcessing Key, to see in the Key Value maps that set this key to the WBISESSIONID by each of the three ENTRY inbound events, e.g.:

ManualOrderProcessing.ManualOrderProcess.manualOrderProcess_ENTRY/
     propertyData/WBISESSION_ID

You will see that there are seven SCA ENTRY and EXIT Events. Note that the Filter Condition is empty for all of them. This is because the SCA Event Types are unique enough to serve as the filter by themselves. Also notice that all correlation expressions check the Inbound Event's SessionID against the value of the OrderProcessing Key. e.g.:

ShipItems.Shipping.shipOrder_EXIT/propertyData/WBISESSION_ID 
   = OrderProcessing_Key.

To use this monitoring model for Option 2, you need to complete several tasks:

1. Change the correlation key from SessionID to OrderNumber.
2. Change the correlation expressions for all seven SCA events to correlate either on the OrderNumber, or on the secondary key of InvoiceNumber. This step specifies to use payload data to correlate on the payload rather than the SessionID.
3. Add the events from the WebSphere ESB Emitter and from the business process invocation of the business rules for the discount calculation. This step brings these events into the single monitor model to correlate with the other events.
4. Add the event from the Visual Snippet for a HighOrder. This step also brings this event into the single monitor model to correlate it with the other events.
5. Add the triggers for the model to set the metric with a correlation value and to terminate the monitor context.
6. Add the InvoiceNumber metric to use to correlate the other monitored events.

Back to top

Setting the correlation key and expressions

Next you need to create a new correlation key for the OrderNumber, and change the existing Inbound Event correlation expressions to use this new key instead of the server-generated, default non-business data correlation key (SessionID).

1. Right-click OrderProcessing MC.
2. Choose New - Key andspecify the following value (Figure 25):

   Name: OrderNumber

   
   
   Figure 25. Settings for OrderNumber key
   
   
   
3. Click OK.
4. The SCA Entry Event for OrderProcess initially sets the key. For the OrderNumber key, click Add for Key Value Maps.
5. Double-click <no expression> entry to open the Expression Dialog. Press Ctrl+Spacebar to get content assist, and navigate to OrderNumber for this event:

   OrderProcessing - OrderProcessing MC - OrderProcess.BPELOrder.processOrder ENTRY - ExtendedData - Argument 0 - orderNumber

6. Save the monitoring model.

You will see a couple of error messages like this:

CWMMV0108E: This key metric does not receive a value when 
              /OrderProcessing/MDM/OrderProcessing_MC/AutomatedOrderProcessing.AutomatedOrder.
                                autoOrderProcessing_ENTRY creates this context.

We'll fix these errors in a moment. These messages indicate that there are creation events that do not set OrderNumber in their key, which is required for all creation events. We'll change these in the Inbound Entry events.

Next you need to change the correlation expression for the Inbound Events from using the server generated SessionID to using the OrderNumber key instead. We'll start with theAutomatedOrderProcessing Entry and Exit events:

1. Select the AutomatedOrderProcessing.AutomatedOrder.autoOrderProcessing ENTRY Inbound Event.
2. Change the expression, by changing the value of the correlation expression to this value (as Figure 26 shows:)

   AutomatedOrderProcessing.AutomatedOrder.autoOrderProcessing_ENTRY/ extendedData/'Argument 0'/orderNumber = OrderNumber.

   
   
   
   Figure 26. Correlation value for AutomatedOrder entry event
   
   
   
3. You can also change the expression by deleting the original contents and using content assist to select

   OrderProcessing - OrderProcessing MC - AutomatedOrderProcessing.AutomatedOrder.autoOrderProcessing ENTRY - ExtendedData - Argument 0 - orderNumber.

4. Add the expression = OrderNumber to the end of the correlation expression, as Figure 27 shows:
   
   Figure 27. Complete correlation for AutomatedOrder entry event
   
   
   
5. Change the If no instances found to Treat as Error using the pull down menu
6. Make sure the value of If one instance found is Deliver to the instance.
7. Finally, be sure the value of If multiple instances are found is Treat as, as Figure 28 shows. Save your model.
   
   Figure 28. Settings for matching events to the monitor context
   
   
   

Now you need to update the correlation expressions in all of the Inbound Events in a similar way.

AutomatedOrderProcessing.AutomatedOrder.autoOrderProcessing EXIT.

1. Select the Inbound Event AutomatedOrderProcessing.AutomatedOrder.autoOrderProcessing EXIT.
2. Change the value of the correlation expression to (using content assist if you'd like):

   AutomatedOrderProcessing.AutomatedOrder.autoOrderProcessing_EXIT/ extendedData/'Output 0'/orderNumber = OrderNumber.

   
   
3. Change the value of If no instances found to Treat as Error, using the pull down menu for the Inbound Event.
4. Make sure the value of If one instance found is Deliver to the instance.
5. Make sure the value of If multiple instances are found is Treat as Error, using the pull down menu.

ManualOrderProcessing.ManualOrderProcess.manualOrderProcess ENTRY

1. Select the Inbound Event ManualOrderProcessing.ManualOrderProcess.manualOrderProcess ENTRY.
2. Change the Expression by changing the value of the correlation expression to

   ManualOrderProcessing.ManualOrderProcess.manualOrderProcess_ENTRY/ extendedData/'Argument 0'/orderNumber = OrderNumber

   
   
3. Add the expression = OrderNumber to the end of the correlation expression.
4. Change the value of If no instances found to Treat as Error,using the pull down menu for the Inbound Event.
5. Make sure the value of If one instance found is Deliver to the instance.
6. Make sure the value of If multiple instances are found is Treat as Error using the pull down menu.

ManualOrderProcessing.ManualOrderProcess.manualOrderProcessEXIT

1. Select the Inbound Event ManualOrderProcessing.ManualOrderProcess.manualOrderProcessEXIT.
2. Change the Expression, by changing the value of the correlation expression to

   ManualOrderProcessing.ManualOrderProcess.manualOrderProcess_EXIT/ extendedData/'Output 0'/orderNumber = OrderNumber.

   
   
3. Add the expression = OrderNumber to the end of the correlation expression.
4. Change the value of If no instances found to Ignore, using the pull down menu for the Inbound Event.
5. Make sure the value of If one instance found is Deliver to the instance.
6. Make sure the value of If multiple instances are found is Treat as Error, using the pull down menu.

OrderProcess.BPELOrder.processOrder ENTRY.

1. Select the Inbound Event OrderProcess.BPELOrder.processOrder ENTRY.
3. Change the Expression, by changing the value of the correlation expression to

   OrderProcess.BPELOrder.processOrder_ENTRY/ extendedData/'Argument 0'/orderNumber = OrderNumber.

   
   
4. Add the expression = OrderNumber to the end of the correlation expression
5. Leave the Create new Instance settings, this is the true create event as in our monitor model this is the very first event that we want to create our monitor context for each instance. In other words, when a new order process starts, it is this event that is generated and will cause a new monitor context to be started for monitoring this context.
6. Select the Inbound Event OrderProcess.BPELOrder.processOrder EXIT.
7. Change the Expression, by changing the value of the correlation expression to

   OrderProcess.BPELOrder.processOrder_EXIT/ extendedData/'Ouput 0'/orderNumber = OrderNumber.

   
   
8. Add the expression = OrderNumber to the end of the correlation expression.
9. Change the value of If no instances found to Treat as Error, using the pull down menu for the Inbound Event.
10. Since a business data key is going to be used for event correlation, the generated non-business data key can be deleted. Delete OrderProcessing Key.
11. Save your model.

You'll see one error for the ShippingItems event, which we'll fix in a later section.

Back to top

Adding in the non-SCA events to the model

Next we need to add two business process events to the model. The BPEL events are of type Activity Message. What makes the business process events different from the SCA components events, is that the event name by itself is not usually sufficient as a filter criterion. You need to add additional filter criteria to receive the correct events, including the Event Nature, Process Valid From, Process Name, etc.

You can retrieve all of the criteria by inspecting the various parts of the business process, but the easiest thing to do is generate a business process monitor model, using the same filtering expressions for those events, and copy them to the model. Then create the appropriate correlation expression for those events using the OrderNumber.

The Custom Event, from the visual snippet, will contain the unique OrderNumber, which can be used for correlation.

The same is true of the EventEmitter Inbound Event from the SampleWESB module, which also has the OrderNumber in the event payload.

Creating a BPEL monitoring model

1. To build the BPEL monitoring model (from which we will merely copy some constructs), switch to the Business Integration Perspective, using Windows Perspectives - Business Integration Perspective.
2. In the Business Integration perspective, expand the SampleBPEL module and expand Business Logic - Processes.
3. Right-click OrderProcess,choose Monitoring Tools - Generate Monitor Model, as Figure 29 shows:
   
   Figure 29. Generate event monitor model option for the OrderProcess business process
   
   
   
4. Select the OrderProcessingMM project from the pull down menu, and use OrderProcesingBPEL as the monitor model name (Figure 30):
   
   Figure 30. Business Process monitor model settings
   
   
   
5. Click Next, to move to the Select BPEL process panel. This panel shows all of the items in the business process, and the events that have been enabled.
6. Now you can select the events to be monitored from the business process. You can choose to monitor those enabled built-in events, or a subset of those events. Since we were selective in what events weenabled, we want all enabled events registered in the monitor model. Click Select All to select all the events previously enabled, as Figure 31 shows:
   
   Figure 31. Option to select all events for event definitions
   
   
   
7. Click Finish, and select Yes when prompted to enter the Business Monitoring perspective.

Declaring business process events

The generated business process monitor model will contain inbound event definitions for the events produced by the business process. These are the events that we want to use in the single option 2 monitoring model that we are creating. Therefore you can copy the details of these business process inbound events from this newly generated model to our work-in-progress model. We'll start by declaring the business process events in the single monitoring model OrderProcessing, in the RulesDiscount_Entry event.

Tip: You could also create these inbound events by cutting and pasting from the XML view of the monitor models, however, this can be error prone.

1. Switch to the Monitoring Model Editor for the OrderProcessing model.
2. Right-click on the OrderProcessing MC, select New - Inbound Event, as Figure 32 shows:
   
   Figure 32. Option to create Inbound Event
   
   
   
3. Specify the following value (Figure 33) and click OK.

   Name: RulesDiscount_ENTRY

   
   
   Figure 33. Setting for RulesDiscount entry inbound event
   
   
   
4. For the Type, click Browse and expand SampleBPEL-Events -BPC.BFM.ACTIVITY.MESSAGE_SampleBPEL_com_ibm_sample_OrderProcess_b_10_RulesDiscount.cbe - 'BPC.BFM.ACTIVITY.MESSAGE#bV2FXHQ5L1zGB2uMCg6mHg' and click OK(Figure 34):
   
   Figure 34. Type for RulesDiscount invoke activity entry event
   
   
   
5. Next, create the RulesDiscount_Exit event in the single monitoring model. Right-click on the OrderProcessing MC, select New - Inbound Event.
6. Specify the following value:

   Name: RulesDiscount_EXIT

7. Click OK.
8. For the Type, click Browse and expand

   SampleBPEL - Events - BPC.BFM.ACTIVITY.MESSAGE_SampleBPEL_com_ibm_sample_OrderProcess_b_10_RulesDiscount.cbe -'BPC.BFM.ACTIVITY.MESSAGE#bV2FXHQ5L1zGB2uMCg6mHg'

9. Click OK.

Setting filter expressions

As stated earlier, you need to set a more complex filter on these events, generated from a business process, because the event type is not specific enough to indicate the type of event that is actually generated. We will copy them from the generated inbound event definitions for the business process monitor model.

1. Open the OrderProcessingBPEL monitor model in the editor.
2. Expand OrderProcessingBPEL - OrderProcess - RulesDiscount (Figure 35):
   
   Figure 35. Setting for RulesDiscount entry inbound event
   
   
   
3. There are two Inbound Events of interest, RulesDiscount_ENTRY, and RulesDiscount_EXIT. Copy the Filter expression for each to the corresponding Inbound Events in the OrderProcessing MC.

   RulesDiscount_ENTRY:

   RulesDiscount_ENTRY/extendedData/processTemplateName = 'OrderProcess' and RulesDiscount_ENTRY/extendedData/processTemplateValidFrom = 'Fri 2007-02-23 18:22:23.000' and RulesDiscount_ENTRY/extendedData/EventNature = 'ENTRY' and RulesDiscount_ENTRY/extendedData/bpelId = '10'

   
   

   RulesDiscount_EXIT:

   RulesDiscount_EXIT/extendedData/processTemplateName = 'OrderProcess' and RulesDiscount_EXIT/extendedData/processTemplateValidFrom = 'Fri 2007-02-23 18:22:23.000' and RulesDiscount_EXIT/extendedData/EventNature = 'EXIT' and RulesDiscount_EXIT/extendedData/bpelId = '10'

   
   
4. Save your model.

Updating correlation expressions

For these events, you also need to update the correlation expression to use the business data.

1. For the RulesDiscount_ENTRY, add the correlation expression:

   RulesDiscount_ENTRY/extendedData/message/input1/orderNumber = OrderNumber

   
   
2. For the RulesDiscount_EXIT, add the correlation expression:

   RulesDiscount_EXIT/extendedData/message/output1/orderNumber = OrderNumber .

   
   
3. For BOTH RulesDiscount_ENTRY and RulesDiscount_EXIT:
   1. Change the value of If no instances found to Treat as Error,using the pull down menu for the Inbound Event.
   2. Make sure the value of If one instance found is Deliver to the instance.
   3. Make sure the value of If multiple instances are found is Treat as Error, using the pull down menu, as Figure 36 shows:
      
      Figure 36.Settings for matching to the monitor context
      
      
      
4. Save the monitoring model again.

Adding inbound events

Next, you'll add the mediation flow Event Emitter Inbound Event to the single monitoring model OrderProcessing:

1. Right-click on the OrderProcessing MC,and select New - Inbound Event.
2. Specify the following value, as Figure 37 shows:

   Name: CorrelationEvent.

   Tip: We chose the name CorrelationEventto emphasize that the event will be used to set the metric value for correlation. A different name could have been used, such as requestInvoiceNumberEvent

   
   
   Figure 37. Settings for CorrelationEvent inbound event
   
   
   
3. For the Type, browse to the following and click OK (Figure 38):

   SampleWESB -events- SampleWESBGetInvioiceMediation_EventEmitter1_Res_SampleWESB_com_ibm_sample_GetInvoiceMediation _m.cbe-SampleWESB_GetInvoiceMediation_EventEmitter1_Res.

   
   
   Figure 38. Type for custom HighShippingEvent event
   
   
   

   No additional filter is needed, because the event type is specific enough to indicate the type of event.

4. This event must also be correlated with the other events in the model. Add thefollowingCorrelation Expression:

   OrderProcessingOrderProcessing MCCorrelationEvent - ExtendedData/Message/requestInvoiceNumberResponse/output1/orderNumber

5. Then add = OrderNumber to the expression (Figure 39):
   
   Figure 39. Correlation expression for CorrelationEvent
   
   
   
6. For the Inbound Event, change the value of If no instances found to Treat as Error.
7. Make sure the value of If one instance found is Deliver to the instance.
8. Make sure the value of If multiple instances are found is Treat as Error, using the pull down menu, as Figure 40 shows:
   
   Figure 40. Settings for matching to the monitor context
   
   
   

Registering custom events

You also need to register the custom event (HighValue), defined in the Activity editor (Visual Snippet), in OrderProcessing.

1. Right-click on OrderProcessing MC and select New - Inbound Event, and for the name, specify HighValue(Figure 41):
   
   Figure 41. Settings for custom HighValue inbound event
   
   
   
2. For the Type, browse to SampleBPEL - HighOrderEvent.cbe - HighOrderEvent
3. You also need to set the correlation expression for the event to use the business data. Set the Correlation Expression to HighValueEvent/extendedData/OrderNumber = OrderNumber.
4. Change the value of If no instances found to Treat as Error,using the pull down menu, for the Inbound Event.
5. Make sure the value of If one instance found is Deliver to the instance.
6. Make sure the value of If multiple instances are found is Treat as Error, using the pull down menu.

The last event that you need to register is the custom event in the Ship Item Java component. To add the custom event (HighShipping):

1. Right-click OrderProcessing MC and select New - Inbound Event
2. Specify the following value (Figure 42):

   Name: HighShipping.

   
   
   Figure 42. Settings for custom HighShipping inbound event
   
   
   
3. For the Type, browse to SampleBPEL - HighShippingEvent.cbe - HighShippingEventm (Figure 43):
   
   Figure 43. Type for custom HighShipping event
   
   
   
4. As explained above, the ShipItem Java component generates an event that uses a different unique value for correlation instead of OrderNumber. The unique value is actually in the InvoiceNumber. Set the Correlation Expression to

   HighShipping/extendedData/InvoiceNumber = InvoiceNumber.

   
   
5. Change the value of If no instances found to Treat as Error.
6. Make sure the value of If one instance found is Deliver to the instance.
7. Make sure the value of If multiple instances are found is Treat as Error.

Save the monitoring model. All of the events should now be registered in the OrderProcessing single monitoring context.

Back to top

Correlating events using a metric

As mentioned above, option 2 outlines how to use a metric value for correlation purposes. (Metrics are more commonly used for counts, aggregations, and other data reporting, but the use as an event correlation mechanism is also an acceptable usage pattern). As option 2 also points out, before you can use a metric value for event correlation, it must be received in another Inbound Event. For this scenario, the Ship Item component generates an event that should be correlated based on InvoiceNumber rather than OrderNumber. (You just registered this Inbound Event, and set the correlation expression to use InvoiceNumber.) The CorrelationEvent from the mediation flow event emitter primitive has both the OrderNumber and InvoiceNumber , and can be used to set a metric with the InvoiceNumber value. When this metric has been initialized with the InvoiceNumber value, you can correlate the HighShipping event from the Ship Item component with the other events via a common monitoring context (instance).

1. Start by creating the trigger, and associating it with the CorrelationEvent Inbound Event. Right-click OrderProcessing MC - New - Trigger
2. Specify the following value (Figure 44) and click OK

   Name: InvoiceSetTrigger

   
   
   Figure 44. Settings for trigger for setting metric value
   
   
   
3. Under Trigger Sources, click Add, and choose the CorrelationEvent Inbound Event to trigger on, as Figure 45 shows:
   
   Figure 45. Event for trigger to set metric value
   
   
   

Now that you've created the trigger, you can create the metric and associate it with the trigger.

1. Right click on the OrderProcessing MC - New - Metric.
2. Specify the following value:

   Name: InvoiceNumber

3. Click OK.
4. Under Metric Value Maps, click Add, and for the trigger, double-click on the trigger cell, and choose InvoiceSetTrigger.
5. For the Expression, navigate to (Figure 46):

   OrderProcessing - OrderProcessing MC - CorrelationEvent - ExtendedData - Message - requestInvoiceNumberResponse - output1 - invoiceNumber.

   
   
   Figure 46. Settings setting the metric value
   
   
   
6. Click OK, and save the monitoring model.

Other Inbound Events, besides the HighShipping event, can use the metric for correlation. The ShipItems.Shipping.shipOrder EXIT event, which will contain the InvoiceNumber value, can correlate on the metric as well. You need to update the correlation expression of the ShipItems event to use the metric, which has been assigned the InvoiceNumber.

1. In the OrderProcessing model, click the ShipItems.Shipping.shipOrder EXIT Inbound Event.
2. Use the content assistto navigate to the first part of the expression:

   OrderProcessing - OrderProcessing MC - ShipItems.Shipping.shipOrder EXIT - ExtendedData - 'Output 0' - invoiceNumber

3. Add the final piece of the expression, to check against the InvoiceNumber as the correlator, so the result is:

   ShipItems.Shipping.shipOrder_EXIT/extendedData/'Output 0'/invoiceNumber = InvoiceNumber.

   
   
4. Save the monitoring model.

Back to top

Adding a termination trigger

The last step is to terminate the single monitoring model when the business transaction is complete. You can associate a trigger with an Inbound Event and set it to terminate the monitoring context.

1. Right-click on the OrderProcessing MC - New - Trigger.
2. Specify the following value for the Trigger

   Name: ApplicationEndTrigger

3. Click OK.
4. Under Trigger Sources, click Add, and choose the ShipItems.Shipping.shipOrder EXIT Inbound Event to trigger on (Figure 47):
   
   Figure 47. Event for trigger to terminate the monitor context instance
   
   
   
5. Check the Terminate monitoring context checkbox.
6. Save the monitoring model.

Back to top

Summary

In this article, you looked at the different built-in events that you can enabled for WebSphere Process Server to generate, as well as ways to generate custom events. You then looked at the different event correlation options for monitoring all of these different events, in the context of a single business transaction. Using a single monitoring model, you then merged the event definitions from the different built-in and custom events and established the event correlation using a key and metric value. Because you created a single monitoring model and correlated the different events together within one monitoring context, you could then use a single context in production to monitor each instance of the end-to-end business transaction.

Acknowledgements

Thanks to Richard Johnson and Jim Frank for their input and suggestions as we prepared this article.

Back to top

Downloads

Information about download methods

Resources

• Understand more about business activity monitoring (BAM) with WebSphere Business Monitor through the Jump-start series (Part 1, Part 2, Part 3, Part 4, Part 5, and Part 6)
  
  
• RSS feed for this series (Find out more about RSS.)
  
  
• WebSphere Business Monitor education: Descriptions, schedules, and enrollment information for WebSphere Business Monitor courses.
  
  
• Business Integration Zone, WebSphere Business Integration products integrate data, applications, processes, and people across and beyond the enterprise to leverage existing IT investments.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  
• What's new in IBM WebSphere Business Monitor 6.0.2?" (developerWorks, Nov 2006): This article describes updates, changes, and new functions in IBM WebSphere Business Monitor 6.0.2.
  
  
• Check out IBM WebSphere Business Monitor 6.0.2 InfoCenter, which has useful information covering all aspects of IBM WebSphere Business Monitor 6.0.2.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Exploring different event generation options
• Creating the monitoring model
• Creating event definitions
• Creating the initial monitoring model
• Setting the correlation key and expressions
• Adding in the non-SCA events to the model
• Correlating events using a metric
• Adding a termination trigger
• Summary
• Downloads
• Resources
• About the authors
• Comments

Next steps from IBM

Rational Tester for SOA Quality is an automated web services testing and SOA testing tool that supports Web services SOAP, HTTP(S), JMS, WS-Security, UDDI, and RESTful standards.

---

• Try: The no-charge Rational Service Tester for SOA Quality helps quality assurance professionals validate web service based SOA application..
• Article: See the whats new with Rational Service Tester for SOA Quality, and its Generic Service Client, which provides a single client to interact with any SOA service type.
• Tutorial: Get hands-on experience with this Transport for SOAP feature tutorial using Rational Tester for SOA Quality.
• Buy: Rational Service Tester for SOA Quality

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers