Exploiting user exits

Your message flows can benefit from user exits.

Before you begin

About this task

The following diagram illustrates how a user exit works. The numbered events are described after the diagram. The MQInput node is used as an example, but the function applies to all input nodes, including user-defined input nodes. Similarly, the Compute and MQOutput nodes could be replaced by any equivalent nodes.

Basic message flow events
  1. (cciInputMessageCallback) The message is dequeued from the input source (read into the flow).

    Built-in nodes and user-defined nodes differ slightly in the way in which user exits are called. For built-in input nodes, the user exit is called as soon as possible after the data has been read from the external source. For user-defined input nodes, the user exit is called just before the node propagates the message.

  2. (cciPropagatedMessageCallback) The message is propagated to the message flow node for processing.
  3. (cciOutputMessageCallback). A request message is sent to the output node's transport, and transport-specific destination information is written to WrittenDestination in the LocalEnvironment (for example, this information includes the queueName and msgId for an MQ message). The call is made when a node successfully puts a message to a transport, from either an output or a request node. The outputMessageEvent is called by built-in nodes only. The topic for each node that supports WrittenDestination information contains details about the data that it contains.
    Note: If you use a destination list with WebSphere® MQ or JMS nodes, a single callback is made after the message is sent to the last destination in the list. The node provides details of the message sent to each destination in the WrittenDestination information in the LocalEnvironment tree.
  4. (cciNodeCompletionCallback) Node processing completes.
  5. (cciTransactionEventCallback) The user exit is called after the transaction has completed, so that user exit processing is not part of that transaction. The user exit is invoked even if no transactional processing is completed by the flow.

    Where the message flow property Commit Count is greater than one, many-to-one ratios exist between events 1 and 5. This ratio also exists for some scenarios that are specific to the particular input node; for example, when an MQInput node is configured with the Commit by Message Group property selected.

You can write a user exit to track any number of these events. For each of these events, the following data is available to the user exit. All access is read-only, unless stated otherwise:
  • The message is dequeued:
    • Bit stream
    • Input node
    • Environment tree (read and write)
  • The message is propagated to the node:
    • Message tree (body element read and write)
    • LocalEnvironment tree (read and write)
    • Exception list
    • Environment tree (read and write)
    • Source node
    • Target node
  • A message is sent to a transport:
    • Message tree (body element read and write)
    • LocalEnvironment tree (read and write)
    • Exception list
    • Environment tree (read and write)
    • Output or request node
  • Message flow node processing completes:
    • Message tree (body element read and write)
    • LocalEnvironment tree (read and write)
    • Exception list
    • Environment tree (read and write)
    • Message flow node
    • Upstream node
    • Exception (if any)
  • The end of the transaction:
    • Input node
    • Exception (if any)
    • Environment tree (read and write)

You can register multiple user exits, and, if they are registered, they are invoked in a defined order (see mqsichangeflowuserexits command). Any changes that are made to the message assembly (the message and environment) by a user exit are visible to subsequent user exits.

When the user exit is invoked, it can query the following information:
  • Message flow information:
    • Message flow name
    • Integration node name
    • Integration node's queue manager name
    • Integration server name
    • Message flow's commit count property
    • Message flow's commit interval property
    • Message flow's coordinated transaction property
  • Message flow node information:
    • Message flow node name
    • Message flow node type
    • Terminal name
    • Message flow node properties
The user exit can also perform the following tasks:
  • Navigate and read the message assembly (Message, LocalEnvironment, ExceptionList, Environment)
  • Navigate and write the Message body, LocalEnvironment, and Environment tree

You can register the user exits on a dynamic basis, without needing to redeploy the configuration.