Configuring monitoring event sources by using monitoring properties

In the Message Flow editor, use the Monitoring tab on the properties of a message flow node to add one or more monitoring events.

1. In the Message Flow editor, select the relevant node to display the properties for that node.
2. Select the Monitoring tab.
3. Click Add.

   The Add event window is displayed.

4. In the Event Source field, select the source of the event.
   When you select the event source, the corresponding value for Event Source Address is displayed as a read-only property. The event source information is used to populate the attributes of the wmb:eventPointData/wmb:messageFlowData/wmb:node element of the event.

   Tip: If you decide to enable or disable events by using the mqsichangeflowmonitoring command, you must specify a value for Event Source Address, not Event Name.
5. In the Event Name field, select either Literal or Data location.

   Every monitoring event has a name that is placed in the wmb:eventPointData/wmb:eventIdentity/@wmb:eventName attribute of the event. The default names are shown in the following table:

   Event source	Default event name	Example
   Transaction start	nodeLabel.TransactionStart	MQInput.TransactionStart
   Transaction end	nodeLabel.TransactionEnd	MQInput.TransactionEnd
   Transaction rollback	nodeLabel.TransactionRollback	MQInput.TransactionRollback
   Terminal	nodeLabel.terminal_label.Terminal	MQInput.OutTerminal

   You can override the default value in the following ways:

   • By specifying an alternative literal string.
   • By specifying an XPath query. The query extracts the event name from a field in the input message. Click Edit to use the XPath Expression Builder.
6. Optional: In the Event Filter section, provide an XPath expression to control whether the event is emitted.

   Type in the expression (for example, $Body/StockTrade/Details/Value > 10000) or click Edit to launch the XPath Expression Builder.

   The expression must evaluate to true or false, and can reference fields in the message tree, or elsewhere in the message assembly. The default value is true(), which means that the event is always produced.
7. Optional: Complete the Event Payload field if the event must contain selected data fields that are extracted from the message.

   Click Add to launch the Add Data Location dialog box. You can then type in the location (for example, $LocalEnvironment/File/Name) or click Edit to launch the XPath Expression Builder.

   You can extract one or more fields from the message data and include them with the event. The fields can be simple or complex. Simple content is contained in the wmb:applicationData/wmb:simpleContent field of the event; complex data is contained in the wmb:applicationData/wmb:complexContent field.

   This facility is used commonly for communicating significant business data in a business event. If the event contains the input bit stream, this facility can also be used to extract key fields. You can then use another application to provide an audit trail or to resubmit failed messages.

8. Optional: Select Include bitstream data in payload if the event must capture message bitstream data.
   If you select this option, you must provide the following information:

   Content

   Select from Headers, Body, and All.

   Encoding

   Select from CData (the original text, without encoding), HexBinary, and base64Binary.

   When this option is selected, it is possible that the bitstream that is included is not the same as the message that is written from a transport output node. Monitoring serializes the whole message tree, whereas transport output nodes use the parts of the message tree that they recognize. The bitstream that is included in a monitoring message is generated from all the headers that occur before the first message body in the message tree. Any headers that occur after the message body are not included.

9. Optional: Select the Correlation tab to provide details for event correlation.

   Every monitoring event must contain at least one correlation attribute, and can contain up to three. If you do not specify any correlation information, the first event source in the message flow allocates a unique identifier that all later event sources in the same transaction use.

   1. In the Local transaction correlator field, select one of the following options.

      Automatic

      The local correlator that is used by the most recent event for this invocation of the message flow is used. If no local correlator exists, a new unique value is generated.

      Specify location of correlator

      Enter a value, or click Edit to launch the XPath Expression Builder. The local correlator is read from the specified location in the message tree. Ensure that the specified location contains a correlator value that is unique to this invocation of the message flow.

   2. In the Parent transaction correlator field, select one of the following options to extract a correlation field from the parent transaction.

      Automatic

      The parent correlator that is used by the most recent event for this invocation of the message flow is used. If no parent correlator exists, no parent correlator is used.

      Specify location of correlator

      Enter a value, or click Edit to launch the XPath Expression Builder. The parent correlator is read from the specified location in the message tree. Ensure that the specified location contains a suitable value for the parent correlator.

   3. In the Global transaction correlator field, select one of the following options to extract a correlation field from a global transaction.

      Automatic

      The global correlator that is used by the most recent event for this invocation of the message flow is used. If no global correlator exists, no global correlator is used.

      Specify location of correlator

      Enter a value, or click Edit to launch the XPath Expression Builder. The global correlator is read from the specified location in the message tree. Ensure that the specified location contains a suitable value for the global correlator.

10. Optional: On the Transaction tab, choose how the emission of monitoring events by a message flow is coordinated. You can choose to coordinate with the message flow transaction, in an independent unit of work, or not in a unit of work.
    Select one of the following options.

    Message flow

    The event, and all other events with this setting, are emitted only if the message flow commits its unit of work successfully.

    If the transaction start event is included in the message flow unit of work, but the message processing fails and this unit of work is not published, the transaction start event is included in an independent unit of work. This behavior ensures that your monitoring application receives a pair of events (start and rollback), rather than receiving a rollback event in isolation.

    Independent

    The event is emitted in a second unit of work, independent of the main unit of work. The event, and all other events with this setting, are emitted regardless of whether the main unit of work commits successfully.

    An independent transaction can be started only if the main transaction is either committed or rolled back. If the Commit count property of the flow is greater than one, or the Commit by message group property is set, the events that are targeted for the independent transaction are emitted out of sync point. A message is also issued with this information.

    None

    The event is emitted out of sync point (not in any unit of work.) The event is emitted when the message passes through the event source, and is available for reading immediately.

    Not all of these options are available on all event types. The default and allowed values are shown in the following table:

    Event source	Allowed values	Default
    Transaction start	Message flow Independent None	Message flow
    Transaction end	Message flow None	Message flow
    Transaction rollback	Independent None	Independent
    Terminal	Message flow Independent None	Message flow

11. Click Finish.

    The Events table in the Monitoring tab of the Properties view for the node is updated with details of the event that you added, and the event is enabled.

12. Save the message flow.
13. When all events are added to the flow, add the message flow to the BAR file, and deploy the BAR file.

    Monitoring is inactive for the flow; deploying the BAR file does not activate monitoring.

14. Activate monitoring for the flow by using the mqsichangeflowmonitoring -c command.