Exploiting user exits
Your message flows can benefit from user exits.
Before you begin
- Read User exits.
- Read Why use a user exit?
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.
- (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.
- (cciPropagatedMessageCallback) The message is propagated to the message flow node for processing.
- (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.
- (cciNodeCompletionCallback) Node processing completes.
- (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.
- 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.
- 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
- 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.