IBM BPM, V8.0.1, All platforms > Programming IBM BPM > Enterprise Service Bus programming

Error handling in the mediation flow component

This topic provides information on the various ways to deal with errors in the mediation flow, including ways to use the Stop and Fail mediation primitives, where to look for fail information in the message, and how to handle modelled and unmodeled faults.


Fail terminal

Mediation primitives that process messages have a fail terminal. When there is a failure in the mediation primitive, the fail terminal is called and exception information is sent, along with the input message. The exception information is stored in the failInfo element in the message context. A message showing the failInfo is shown in Figure 1. You must wire the fail terminal of a mediation primitive to another mediation primitive in order to access the failInfo.

Figure 1. The failInfo element in the message context


Runtime failure in the mediation primitive

When a failure occurs in a mediation primitive, the unwired fail terminal sends a runtime exception, and the flow is considered to have failed.

If the mediation flow component is running under a global transaction (default), primitives that use resources that participate in the global transaction will rollback.

Figure 2. Runtime failure and rollback transaction

In Figure 2, assume that a global transaction is not configured, and a failure occurs in the Custom mediation primitive. As the fail terminal has not been wired, the flow fails. The log function would still complete as the mediation flow component is not under a global transaction, and therefore still logs to the database.

When the flow is reconfigured, a global transaction is configured, and a failure occurs again in the Custom mediation primitive, the flow fails. If the Log mediation primitive has its transaction mode property set to same, the log entry will be rolled back as a part of the global transaction, and no entry will occur in the database. If the transaction mode property was set to new, then the log to the database commits outside the global transaction so an entry will still occur in the database.


Modelled faults

WSDL operations have three types of messages:

  1. input
  2. output
  3. fault
Modelled faults are business error conditions, that are defined as a fault message in a WSDL operation. In the mediation flow component, modelled faults are handled through Input Fault and Callout Fault nodes, which have a terminal for each unique type of fault message. The Input and Callout Fault nodes are created in the mediation flow editor when there is a modelled fault defined in the source or target operation.

Figure 3. Example of a modelled fault

As shown in Figure 3, an example of when modelled faults can be used within the mediation flow component, is if a fictitious company offers a tiered level of service. The company offers priority booking information about upcoming theatre shows to Gold customers, who pay a premium. Standard customers must manually check the website for any information. An input message can be sent to a Database Lookup mediation primitive that retrieves the membershipType and sets an isValid property in the message. The message then goes onto a Message Filter mediation primitive, to route the message based on the value of isValid. If the membershipType is valid (Gold), the message is sent to the target operation. If the membershipType is not valid, the message is returned to the service requester, through the Input Fault node.


Unmodeled faults

Errors that are returned, and are not defined as WSDL faults are called unmodeled faults. There is no Input or Callout Fault node created for these types of faults in the mediation flow editor. In this case, the input message type is sent to the Callout Response node's fail terminal. The failure information is captured in the failInfo element of the message context.

To handle an unmodeled fault, you can wire the fail terminal of a Callout Response node to a mediation primitive.

For example, you could wire the fail terminal on a Callout Response node to a Message Logger mediation primitive to log all unmodeled faults. You can set a property on the Callout Response node to determine whether the entire request message or just the message header information should be passed out of the fail terminal (there can be a performance overhead if you choose to pass the entire request message).

If the fail terminal on the Callout Response node is not wired and an unmodeled fault is received, a mediation runtime exception will occur.


Stop mediation primitive

The Stop mediation primitive has one input terminal and no out terminals. When the fail or out terminal on a mediation primitive is wired to the Stop mediation primitive, that particular branch comes to an end.

The mediation flow editor generates warnings if the out terminal of a mediation primitive is not wired. The Stop mediation primitive is used to stop these warnings. In the runtime, out terminals that are not wired are automatically propagated to stop.

In Figure 4, the fail terminal of the Message Filter mediation primitive is wired to a Message Logger, so that the failed messages can be stored. To indicate that no more actions are needed, the Message Logger is wired to a Stop mediation primitive.

Figure 4. Stop mediation primitive


Fail mediation primitive

The Fail mediation primitive can be used if you want to stop the flow and send a runtime exception. You can wire the out or fail terminal on a mediation primitive, to the Fail mediation primitive. If the mediation flow component is running under a global transaction, mediation primitives participating in the global transaction will rollback.


Faults in the Service Invoke mediation primitive

There are two types of fault that can occur at the Service Invoke mediation primitive:

Enterprise Service Bus programming