Handling errors in message flows

The integration node provides basic error handling for all your message flows. If basic processing is not sufficient, and you want to take specific action in response to certain error conditions and situations, you can enhance your message flows by using message flow node terminals to provide your own error handling.

About this task

For example, you might design a message flow that expects certain errors that you want to process in a particular way. Another example is that your message flow updates a database, and must roll back those updates if other message processing does not complete successfully.

The options that you can use to do this are quite complex in some cases. The options that are provided for MQInput and TimeoutNotification nodes are extensive because these nodes deal with persistent messages and transactions. The MQInput node is also affected by configuration options for WebSphere® MQ.

Because you can decide to handle different errors in different ways, there are no fixed procedures to describe. This section provides information about the principles of error handling, and the options that are available, and you must decide what combination of choices that you require in each situation based on the details that are provided in this section.

There are two general approaches to handling errors in a message flow:
  • Failure checking

    Wire the Failure terminal of a node to explicitly check for any errors that occur within that node. If errors occur, an exception list is propagated to the Failure terminal. The inflight message remains the same as it was before the node was invoked.

    You can introduce more specialized error checking in nodes that can be customized by using ESQL. For example, you can create exit handlers within these nodes. For more information about using ESQL to create exit handlers, see DECLARE HANDLER statement.

  • Catching exceptions

    If you do not wire a Failure terminal, a failure in the node is converted into an exception which is thrown from the node. Any changes that were made to the inflight message before the exception was thrown are reversed. The exception might cause the current transaction to be rolled back, which means that any updates to transactional resources are reversed. Root and Local Environment trees are rolled back in parallel. The Environment tree is not rolled back unless the entire transaction for the flow rolls back.

    You can prevent the transaction from being rolled back, and control the extent to which message changes are reversed, by including a TryCatch node in your message flow. If an exception is thrown beyond the Try terminal of the TryCatch node, then an exception list is propagated to the node's Catch terminal. The inflight message reverts to the state it was in before it reached the TryCatch node.

    Most message flow nodes have a Catch terminal. These nodes are typically at the start of a transaction, where an uncaught exception would cause a rollback. In these nodes, the Catch terminal behaves as though a TryCatch node was wired directly to the Out terminal. Use the Catch terminal to handle any exceptions that are thrown beyond the message flow node. Wire the Failure terminal to handle errors within the node itself.

You can choose one or more of these options in your message flows:

  • Connect the Failure terminal of the node to a sequence of nodes that processes the node's internal exception (the fail flow).
  • Connect the Catch terminal of the node to a sequence of nodes that processes exceptions that are generated beyond it (the catch flow).
  • Insert one or more TryCatch nodes at specific points in the message flow to catch and process exceptions that are generated by the flow connected to the Try terminal.
  • Include a Throw node, or code an ESQL THROW statement, to generate an exception.
  • Ensure that all the messages received by an MQInput node are processed in a transaction, or are not processed in a transaction.
  • Ensure that all the messages received by an MQInput node are persistent, or are not persistent.

If you include user-defined nodes in your message flow, you must see the information provided with the node to understand how you might handle errors with these nodes. The descriptions in this section cover only the built-in nodes.

When you design your error handling approach, consider the following factors:

  • Most of the built-in nodes have Failure terminals. The exceptions are the AggregateControl, AggregateRequest, Input, Label, Output, Passthrough, Publication, Trace, and TryCatch nodes.

    When an exception is detected in a node, the message and the exception information are propagated to the node's Failure terminal. If the node does not have a Failure terminal, or it is not connected, the integration node throws an exception and returns control to the closest upstream node that can process it. This node might be a TryCatch node, an AggregateReply node, or the input node.

    If an MQInput node detects an internal error, its behavior is slightly different. If the Failure terminal is not connected, the MQInput node attempts to put the message to the input queue's backout queue, or if that is not defined, to the dead letter queue of the queue manager that is associated with the integration node.

    For more information, see Handling MQInput node errors.

  • Many built-in nodes have Catch terminals. These nodes are typically at the start of a transaction. For example:
    • Input nodes: FileInput, HTTPInput, JMSInput, MQInput, PeopleSoftInput, SAPInput, SCAInput, SiebelInput, SOAPInput, TCPIPClientInput, TCPIPServerInput
    • Output and response nodes: SCAAsyncResponse, SOAPAsyncResponse
    • Routing nodes: AggregateReply, Collector, Resequence
    • Construction nodes: TryCatch
    • Timer nodes: TimeoutNotification

    A message is propagated to a Catch terminal only if it has first been propagated beyond the node (for example, to the nodes connected to the Out terminal).

  • When a message is propagated to the Failure or Catch terminal, the node creates and populates a new exception list tree with an exception that represents the error that has occurred. The exception list is propagated as part of the message tree. When a message is propagated to the Failure terminal because of a problem that occurred in the Out or Catch flows (for example, repeated parsing errors that caused the backout threshold to be met), the original parsing errors are not in the exception list; the exception list contains the exception that indicates that the backout threshold has been met.
  • The MQInput and TimeoutNotification nodes have additional processing for transactional messages (other input nodes do not handle transactional messages).

    For more information, see Handling MQInput node errors and Handling timeout notification errors.

  • If you include a Trace node that specifies $Root or $Body, the complete message is parsed. This might generate parser errors that are not otherwise detected.
The general principles of error handling are:
  • If you connect the Catch terminal of the input node, you are indicating that the flow handles all the exceptions that are generated anywhere in the out flow. The integration node does not rollback a transaction unless there is an exception on the catch flow. If the catch flow completes successfully, the message is committed. If you want any rollback action after an exception has been raised and caught, you must provide this in the catch flow.
  • If you do not connect the Catch terminal of the input node, you can connect the Failure terminal and provide a fail flow to handle exceptions generated by the node. The fail flow is started immediately when an exception occurs in the node.

    The HTTPInput node does not propagate the message to the Failure terminal if an exception is generated beyond the node and you have not connected the Catch terminal.

  • If a node propagates a message to a catch flow, and another exception occurs that returns control to the same message flow node again, the node handles the message as though the Catch terminal is not connected.
  • If you do not connect either the Failure or Catch terminals of the input node, the integration node provides default processing (which varies with the type of input node).
  • If you need a more comprehensive error and recovery approach, include one or more TryCatch nodes to provide more localized areas of error handling.
  • If you have a common procedure for handling particular errors, you might find it appropriate to create a subflow that includes the sequence of nodes required. Include this subflow wherever you need that action to be taken.
  • If you have set security processing in an input node, and a security exception is thrown, then the message is not propagated on the message flow. The message is either backed out, or an error is returned. For more information, see Security exception processing.
  • Parsing exceptions are passed straight to the Failure terminal. If the Failure terminal is not connected, or an exception occurs in the fail flow, then the message is backed out. The backouts in the fail flow continue until the backout threshold has been exceeded once, and not twice as before.

For more information, see Connecting Failure terminals, and Catching exceptions in a TryCatch node.

If your message flows include database updates, the way in which you configure the nodes that interact with those databases can also affect the way that errors are handled:

  • You can specify whether updates are committed or rolled back. You can set the node property Transaction to specify whether database updates are committed or rolled back with the message flow (option Automatic), or are committed or rolled back when the node itself terminates (option Commit). You must ensure that the combination of these property settings and the message flow error processing give the correct result.
  • You can specify how database errors are handled. You can set the properties Treat warnings as errors and Throw exception on database error to change the default behavior of database error handling.

For more information about coordinated database updates, see Configuring transactionality for message flows.

Message flows for aggregation involve additional factors that are not discussed in this topic. For information about message flows for aggregation, see Handling exceptions in aggregation flows.