bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming BPM Client Apps

Understanding the BPM Transaction Model

This section explains how transactions are handled in business process management (BPM) applications, including the following topics:

- How a Transaction Is Started

- How the Transaction Is Committed

- How Exceptions Are Handled

- How to Force a New Transaction to Start

- Examples of Transactions

For an overview of transactions, and details describing transaction processing and EJBs, see Programming WebLogic JTA in the WebLogic Server documentation set, available at the following URL:

>     http://e-docs.bea.com/wls/docs70/jta/index.html

How a Transaction Is Started

The following three actions, which trigger the WebLogic Integration process engine to begin or resume its execution of a workflow, may mark the start of a new transaction:

- API method call

- XML event

- Time-based event

Whether or not an API method call also starts a new transaction depends on whether the calling application currently has a transaction context. If an external transaction context currently exists (that is, if the application has created a transaction using JTA or has inherited a JTA transaction), the WebLogic Integration Enterprise JavaBean (EJB) uses it; otherwise, the EJB container automatically creates a new transaction in which to execute the call. With one exception (the Audit EJB), all EJB methods in the public API use container-managed transactions with the TX_REQUIRED transaction attribute.

Both XML and time-based events always start a new transaction. In each case, the transaction is started prior to dequeuing the message from the queue.

Note: The WebLogic Integration Worklist client application executes user commands by calling methods on the Worklist EJB within a discrete transaction. When you work with tasks in the WebLogic Integration Worklist application, the EJB container creates an encompassing transaction in which to execute each command. For example, the EJB container creates one transaction in which to execute a task, another in which to mark a task as done, a third in which to reassign a task to another user or role, and so on.

The Worklist client application is being deprecated as of this release of WebLogic Integration. For information about the features that are replacing it, see the BEA WebLogic Integration Release Notes.

How the Transaction Is Committed

To understand how the transaction is committed, you need to understand:

- How a workflow instance is processed by WebLogic Integration

- How a workflow instance reaches a quiescent state

Each topic is described in detail in the following sections.

How a Workflow Instance Is Processed

When first instantiating a workflow, WebLogic Integration executes the Created actions for all tasks in the workflow. It then processes the Start nodes, as follows:

- In the case of an event- or time-triggered workflow, the system activates the Start node corresponding to the event.

- In the case of a manually started or called workflow (subworkflow), the system activates all manual or called Start nodes, respectively.

The progress of the transaction after the initial instantiation depends on how the template definition is defined. Activation events propagate outward along the paths emanating from the point of origin, according to the built-in processing rules for each node type.

The following table describes the processing rules for each node type.

Table 7-1 Node Type Processing Rules

Node Type | Processing Rules
--- | ---
Decision | Upon activation, 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.
Done | Upon activation, the Done node executes any associated actions, and marks as complete the current workflow, regardless of whether all Done nodes have been reached.
Event | Upon activation, an Event node checks for any addressed messages that may have previously been received, and, if none are found, registers itself in the Event Watch table. For more information on addressed messages, see Guaranteeing Message Delivery. Once triggered, an Event node performs the following tasks in sequence: Initializes variables Executes associated actions Activates successor nodes. The activation of successor nodes proceeds according to the rules for each node type.
Join | Upon activation by any single incoming path, an OR Join node evaluates the OR condition; upon activation by all incoming paths, the AND Join node evaluates the AND condition. If conditions are met, the Join node activates its successor nodes.
Start | Upon activation, a Start node performs the following tasks in sequence: Initializes variables Executes associated actions Activates any successor nodes The activation of successor nodes proceeds according to the rules for each node type.
Task | Upon activation, a Task node executes the list of Activated tasks in sequence. The following summarizes the subsequent actions that may be taken: If the task is executed, either by an action or API request, the Execute actions listed are executed. If a task is marked done by an action or API request, the MarkedDone actions are executed. If an action marks the workflow as complete, or if it aborts the workflow, no further processing occurs.

How a Workflow Instance Reaches a Quiescent State

When processing a workflow, the process engine returns control to the system once there are no more actions to execute synchronously—that is, when the workflow instance enters a quiescent state, in which it waits for the next request.

The workflow instance enters a quiescent state when the following conditions are true:

- All Task nodes are waiting to be activated, executed, or are marked done.

- All Event nodes are waiting to be activated, or have already been triggered.

- All Decision and Join nodes are waiting for the final input to activate them, or they have already been activated.

- All Start nodes either are waiting to be activated or have already been executed.

- All Done nodes are waiting to be activated.

A quiescent state also marks the end of a transaction (and results in the transaction being committed) if and only if a new transaction was started at the point that the process engine was last triggered. If an external transaction context was exported before the API call trigger, then the external transaction remains in effect, and control is returned to the calling application. For more information, see How a Transaction Is Started.

When an action instantiates a subworkflow, all work performed by the subworkflow up to the point at which it enters a quiescent state (if ever) occurs within the same transaction as the calling workflow. This work typically includes execution of actions in all called Start nodes, activation of all successor nodes associated with each Start node, and the actions associated with each successor. This processing propagates through the subworkflow, resulting in either completion or quiescence, according to the rules previously described. If the subworkflow runs to completion (that is, if it does not quiesce), the Completed actions in the parent workflow are also performed within the same transaction. If the Completed actions include an action to mark a task (for example, the parent) as complete, processing continues, the MarkedDone actions are performed, and successor nodes are activated.

How Exceptions Are Handled

When the process engine catches or throws an exception, the decision to commit or roll back the transaction depends on the following two factors:

- Where the exception occurred

- Behavior of the active exception handler

The active exception handler can perform associated corrective actions and identify one of the following methods with which to proceed:

- Roll back the user transaction and rethrow the exception

- Stop processing and commit the return to the caller

- Retry the failed operation

- Ignore the error and continue processing

If the user transaction has not already been set for rollback only and the exception is recoverable (in other words, if the exception is a workflow warning), and the exception occurred while an action was being processed or an event variable was being set, 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, and then rethrows the exception.

If the container creates the transaction, then it commits or rolls back the transaction when control is returned to it from the process engine. (Control is returned when the workflow instance reaches a quiescent state, as described in How a Workflow Instance Reaches a Quiescent State.)

If an application enlists a BPM EJB in an external transaction and this EJB throws an exception that does not result in the user transaction being set for rollback only, the transactional behavior is defined by the application. On the other hand, if the BPM call succeeds, there is no guarantee that the transaction will be committed by the external application (or by the EJB). An exception or other error condition may occur subsequently, resulting in the rollback of the entire transaction.

For XML and time-based events, if a transaction is rolled back, the message is returned to the queue. Redelivery of the message is attempted at specific intervals until the number of retries is exhausted. The maximum number of retries and the retry interval are configurable for each JMS destination using the Redelivery-Limit and RedeliveryDelayOverride attributes for the JMSTemplate elements. For example, for the WebLogic Integration samples domain, the WLI_JMSTemplate is defined as follows:

>     <JMSTemplate ErrorDestination="WLI_FailedEvent"
>     	Name="WLI_JMSTemplate"
>     	RedeliveryDelayOverride="60000"
>     	RedeliveryLimit="10"/>

For more information about these attributes, see the description of the JMSTemplate element within the BEA WebLogic Server Configuration Reference at the following URL:

>     http://e-docs.bea.com/wls/docs70/config_xml/index.html

How to Force a New Transaction to Start

You can force a new transaction by defining a dummy task action that causes the current workflow instance to reach a quiescent state. (For information describing how a workflow instance reaches a quiescent state, see How a Workflow Instance Reaches a Quiescent State.)

For example, you can force a workflow instance to enter a quiescent state by defining one of the following task actions:

- Timed event that performs no actions, with a trigger of one second in the future

- Posting of an XML event that sends a dummy trigger message to itself

Examples of Transactions

When business operations are executed within a workflow instance, the following factors help determine whether the business operations are treated as a single transaction or as multiple transactions:

- How you define the workflow

Specifically, whether the workflow is defined such that the existing transaction enters a quiescent state before all business operations are executed.

- For an EJB business operations, how the EJBs are deployed

If you want an application-defined EJB to participate in the current BPM transaction, then the EJB must be deployed with one of the the following container-managed transactional attributes: Mandatory, Required, or Supports. For a detailed description of these settings, see Section 16.7.2 in the Enterprise JavaBeans Specification 2.0, published by Sun Microsystems, Inc.

The following sections provide examples of workflows that are defined such that business operations are specified as part of the actions of one single task, and the actions of multiple tasks. Each example illustrates the scenarios as both a single transaction and/or multiple transactions.

Example 1: Business Operations Defined as Actions in One Task

For the first example, suppose that you want to execute three EJBs both as separate business operations and as part of the actions of a single task. Based on how you define the task properties, the three business operations can be treated as a single transaction or as multiple transactions.

Single Transaction

To have the specified business operations treated as a single transaction, the following example shows how you might define the task actions on the Activated Actions tab in the Task Properties dialog box.

Figure 7-1 Transaction Example: One Task, Single Transaction

In this example, all business operations are invoked upon task activation, and are treated as a single transaction.

Multiple Transactions

To have the specified business operations treated as multiple transactions, the following example show how you might define the task actions on the Activated and Executed Actions tabs in the Task Properties dialog box.

Figure 7-2 Transaction Example: One Task, Multiple Transactions

In this example, a subset of the business operations (EJB1 and EJB2) are invoked upon task activation, as one transaction. Once the Assign task "EJB1" to user "joe" action is executed, the workflow instance enters a quiescent state, and waits for the next request. The first transaction is marked complete, and the Executed actions are performed. The EJB3 business operation is then invoked, as a separate transaction.

In this example, if an exception occurs during the processing of EJB3, the active exception handler performs the associated corrective actions and identifies the method by which to proceed. The first transaction is not affected by an exception that occurs in the second transaction. For more information, see How Exceptions Are Handled.

Example 2: Business Operations Defined as Actions in Multiple Tasks

For the second example, suppose you want to invoke three EJBs as separate business operations, and as actions in three separate tasks. Again, based on how you define the task properties, the three business operations can be treated as a single transaction or as multiple transactions.

Single Transaction

For this example, consider the following workflow template.

Figure 7-3 Transaction Example: Multiple Tasks, Single Transaction

Suppose the following statements are true:

- Task1 performs the EJB1 business operation and marks itself complete.

- Task2 performs the EJB2 business operation and marks itself complete.

- Task3 performs the EJB3 business operation and marks itself complete.

If these statements are true, then the workflow instance does not enter a quiescent state before the execution of any business operation, and all three business operations are treated as a single transaction.

Multiple Transactions

This example illustrates how you might define a dummy Post XML event to force a quiescent state (and force a new transaction to start). For more information about forcing a new transaction to start, see How to Force a New Transaction to Start.

For this example, consider the following workflow template.

Figure 7-4 Transaction Example: Multiple Tasks, Multiple Transactions

Suppose the following statements are true:

- Task1 performs the EJB1 business operation and marks itself complete.

- Task2 performs the EJB2 business operation and marks itself complete.

- The Event node is triggered, and the workflow enters a quiescent state.

Note: It is possible that the Event Watch may not have been triggered, at the time an incoming event notification is delivered, and the associated message may be missed and/or ignored. You can use addressed messaging to guarantee message delivery by defining the required message header fields and time-to-live value, as described in Guaranteeing Message Delivery.

- Task3 performs the EJB3 business operation and marks itself complete.

If these statements are true, then EJB1 and EJB2 are treated as a single transaction, and EJB3 is treated as a separate transaction.

In this example, if an exception occurs during the processing of EJB3, the active exception handler performs the associated corrective actions and identifies the method by which to proceed. The first transaction is not affected by an exception that occurs in the second transaction. For more information, see How Exceptions Are Handled.