This topic applies only to the IBM Business Automation Workflow Advanced configuration.

Using fault handlers

Edit online
Draft comment:
This topic only applies to BAW, and is located in the BAW repository. Last updated on 2025-03-13 12:15
A fault handler is a collection of specific activities that run when a fault is thrown on the activity with which the handler is associated.

About this task

The activities within the handler represent the necessary course of action to deal with the fault. Fault handlers are used on both invoke and scope activities. They run either when a fault is thrown by the process as a whole, by the invoke activity, or by an activity inside the scope activity. In these cases, the operation within the parent activity has not been committed, and it is possible to easily reverse the transaction. Place activities on paths within the handler to either deal with anticipated faults, or you can attempt to find another way to complete the operation. Each path within the fault handler is preceded by either a catch, or a catch-all element.
The following points apply when designing a fault handler:
  • Catch a fault and try to correct the problem so that the business process continues to normal completion.
  • Catch a fault and find that it is not resolvable at this scope. In this case, you have the following additional options:
    • Throw a new fault.
    • Rethrow the original fault so that another scope can handle it.
    • Reply with a fault to the process initiator.
    • Start a human task to correct the issue. If the fault handler cannot resolve the issue, you might need to roll back the process and compensate it.
    • For long-running processes, consider using the Stop on unhandled faults property on the process to handle a fault situation administratively.
Note: If you catch a fault using a fault handler and you are using Oracle in IBM® Workflow Server, you must not delete the default namespace. Also, you must provide a namespace if you are using Oracle with IBM Workflow Server on versions 6.1 through 7.0.0.2. IBM Integration Designer does not create a default namespace. See the technote at http://www-01.ibm.com/support/docview.wss?uid=swg21433700 External link opens a new window or tab for details.

To create a fault handler on an activity, do the following instructions:

Procedure

  1. Click the scope or invoke activity for which you want to handle a fault.
    The action bar displays.
  2. In the action bar, click the fault handler icon as shown in this image. The fault handler in the action bar
    A fault handler is created with one default catch element, and shown in the canvas in association with the parent activity. You can place as many paths in this handler as necessary, and each one is preceded by either of the following elements:
    Option Description
    Catch element The Catch element ity icon Use this element to intercept and deal with a specific fault. You can use as many of these elements as is appropriate.
    Catch all elementThe Catch all element icon Use this element to intercept and deal with any fault that is not already defined in an existing catch element. You can use only one per fault handler.
  3. Populate the existing catch path with the activities that are appropriate to deal with the specific exception that has occurred.
  4. To add another path, click the fault handler to launch the action bar, and choose the appropriate element.

Results

If a fault matches more than one fault handler, then the following rules determine which catch element processes the fault:
  • If the fault has no associated fault data, a catch activity with the matching fault name is selected (providing the fault handler has no variable assigned). Otherwise, the default catch-all element is chosen.
  • If the fault does have fault data associated with it, then a catch element with matching fault name and variable values is selected. If there is no fault name specified, then a fault with a matching fault type is selected. Otherwise, the default catch-all element is chosen.
If no catch or catch all element is selected, then the fault is rethrown to the enclosing scope. If the fault occurs in (or is rethrown to) the global scope, and there is no matching fault handler, the process terminates.

Example

To see an example of how to use a fault handler in a BPEL process that you can build and run yourself, go to http://publib.boulder.ibm.com/bpcsamp/index.html External link opens a new window or tab, and click Samples for V7.0 > Advanced BPEL features > Fault handling.
Note: This example was created using an earlier version of the product, but the example can be run in later versions as well.