Handling Workflow Exceptions

The following sections explain how to handle internally and externally generated workflow exception conditions:

Workflow Exception Handling Overview

The workflow exception handling facility enables you to generate, trap, and respond to internally and externally generated exception conditions at run time. Exceptions may be abnormal conditions that you define within the workflow, or they may be typical run-time server exceptions that you trap and respond to accordingly.

Exception handling within WebLogic Process Integrator is performed at the workflow level, rather than at the task level. All workflow template definitions have at least one exception handler, the system exception handler. The system exception handler, is by default, the initial exception handler and is invoked whenever an exception occurs. The system exception handler responds to exceptions by marking the active transaction for rollback only and rethrowing the exception to the client.

The initial exception handler is the handler that is active as soon as WebLogic Process Integrator attempts to create a workflow instance from the workflow template definition. The workflow template definition can change its active exception handler throughout the course of the workflow by using the Set Exception Handler action. Once the workflow invokes the Set Exception Handler action, the initial exception handler becomes inconsequential. The concept of the "initial exception handler" is required, since exceptions can occur prior to a workflow invoking the Set Exception Handler action. For example, exceptions can occur during the initialization of variables in a Start node.

The workflow exception handling facility allows you to define customized exception handlers to act as the initial exception handler and specify actions to be executed in response to exceptions. You set such exception handlers using the Set Workflow Exception Handler action; an exception handler, when set, persists through the workflow instance until the next Set Workflow Exception Handler action is reached within that workflow or until the workflow completes (whichever occurs first).

At any point in its life cycle, a workflow instance has a "current" exception handler. You can change the current exception handler at run-time using the Set Workflow Exception Handler action. You invoke custom exception handlers through use of the Invoke Exception Handler action. Similarly, applications such as custom worklist interfaces can invoke a user-defined exception handler through the following API method: WorkflowProcessor.invokeWorkflowErrorHandler. Further, you can define an XML document within the Invoke Exception Handler action, allowing workflow variables to be populated by values from this XML document.

Exception handlers have commit and rollback processing paths. You specify certain actions within a workflow to be executed in each of these paths. When an exception occurs, if the currently active transaction is marked for rollback only, the exception handler executes the rollback processing path for the transaction. If the transaction is not marked for rollback only, the exception handler executes its commit path.

The following figure illustrates the workflow exception handling process within WebLogic Process Integrator.

Figure 7-1 Workflow Exception Handling

Understanding the WebLogic Process Integrator Transaction Model

All Enterprise Java Bean (EJB) methods in the public API (with the one exception of the Audit EJB) use container-managed transactions with the TX_REQUIRED transaction attribute. The WebLogic Process Integrator Worklist application executes user commands by calling a method on the Worklist EJB within a discrete transaction. If another application or EJB calls a WebLogic Process Integrator API method, the transactional behavior depends on whether the caller has a transaction context. If there is a transaction context, the WebLogic Process Integrator EJB uses it; otherwise, the EJB container automatically creates a new one in which to execute the call.

The workflow template definition determines what WebLogic Process Integrator does when processing such API calls. For example, when instantiating a workflow, WebLogic Process Integrator first executes the Created actions for all tasks in the workflow. It then processes Start node(s) as follows:

Upon activation, a Start node first initializes variables, then activates its associated actions. Next, it activates any successor nodes. The activation of these successor nodes proceeds according to the rules for each node type (decision, event, task, and so on). For example, a Decision node first evaluates its condition, executes the appropriate list of true or false actions, and finally activates its true or false successor nodes.

Similarly, a Task node has a list of Activated actions, which it executes in sequence. If one of these actions marks a task as complete, that task executes its Done actions before activating the successor nodes. If an action marks the workflow as complete or aborts the workflow, no further processing occurs.

If an exception occurs, WebLogic Process Integrator invokes the current exception handler (by default, the System exception handler). The exception handler can perform compensating actions and determines how to proceed afterwards.

Possible outcomes are:

Likewise, when you work with tasks in the WebLogic Process Integrator Worklist application, the EJB container creates an encompassing transaction in which to execute each command. Such commands include:

Activation events propagate outwards along the paths emanating from the point of origin, according to the built-in processing rules for each node type. When a Start Workflow action instantiates a sub-workflow, the instantiation and unitization of the sub-workflow follows the pattern described above, but it is encompassed by the outer transaction in which the action itself is executing.

When WebLogic Process Integrator catches or throws an exception, the transaction commit/rollback behavior depends upon where the exception occurred and on what the active exception handler does. If the user transaction has not already been set for rollback only and the exception is recoverable (in other words, it is a workflow warning) and occurred while processing an action or setting an event variable, the system allows the exception handler to decide the outcome. Otherwise, the system sets the user transaction for rollback only, invokes the active exception handler then rethrows the exception.

If an application enlists a WebLogic Process Integrator EJB in a global transaction and this EJB throws an exception that does not result in the user transaction being set for rollback only, the behavior is application defined. Similarly, even if such a WebLogic Process Integrator call succeeds, there is no guarantee that the transaction will eventually be committed by the external application (or EJB). An exception or other error condition may subsequently occur, resulting in the entire transaction being rolled back.

If the calling application creates the transaction context, then the calling application has control over committing and rolling back the transaction. However, if the container creates the transaction, then it commits the transaction when it successfully gets control back from WebLogic Process Integrator. WebLogic Process Integrator returns control to the container when it has no more work to do in processing the request.

In cases involving workflow processing (such as task execution, workflow instantiation, event or timer processing), WebLogic Process Integrator returns control when there are no more actions to execute synchronously (when the workflow instance enters a quiescent state, waiting for the next request).

Defining Exception Handlers

Use the exception handler definition facility to define custom exception handlers to act as the initial exception handler and specify actions to be executed in response to exceptions. If you do not define any exception handlers, the system exception handler is, by default, used. The system exception handler responds to exceptions by rolling back the transaction and rethrowing the exception.

The initial exception handler is the handler that is active as soon as WebLogic Process Integrator attempts to create a workflow instance from the workflow template definition. The workflow template definition can change its active exception handler throughout the course of the workflow by using the Set Exception Handler action.

To define an exception handler for a workflow template definition within WebLogic Process Integrator, proceed as follows:

Using Exception Handling Actions

This section defines and describes how to use the following exception handling actions:

Invoke Exception Handler

Use this action to allow the invocation of a specific exception handler within the workflow. Upon execution of the Invoke Exception Handler action, WebLogic Process Integrator sends the user-defined XML document to the exception processor and invokes the specified exception handler.

Set Workflow Exception Handler

Use this action to make a specified exception handler the active exception handler for a workflow template definition. If this action is not used in the workflow template definition and no other exception handler is defined and marked as the initial exception handler, the system exception handler, by default, is used and invoked whenever an exception occurs. The system exception handler responds to exceptions by rolling back the transaction and rethrowing the exception.

The exception handler you set for the workflow persists throughout the instance of the workflow until a subsequent Set Workflow Exception Handler action is executed within the same workflow.

Figure 7-4 Set Workflow Exception Handler

Exit Exception Handler

Use this action to exit an exception handler using one of four methods: rollback, stop, retry, or continue.

Figure 7-5 Exit Exception Handler

Note: In the Rollback path, the only exit option available in the Exit Exception Handler action is Rollback. When a transaction is rolled back, there are no other options other than rollback.

Certain Enterprise Java Beans (EJBs) can either mark a transaction for rollback only by calling a UserTransaction method, or they can throw an unchecked exception across a container boundary. In either of these two cases, WebLogic Server (WLS) rolls back the transaction.

WebLogic Process Integrator Error Messages

The following is a list of error messages that may be encountered in WebLogic Process Integrator and handled by the exception handler.

Table 7-1 WebLogic Process Integrator Error Messages