Handling Workflow Exceptions

 

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

• Workflow Exception Handling Overview

• Understanding the WebLogic Process Integrator Transaction Model

• Defining Exception Handlers

• Using Exception Handling Actions

• WebLogic Process Integrator Error Messages

 

---

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:

• 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 (sub-workflow), it activates all manual or called Start nodes respectively.

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:

• Rollback the User Transaction and rethrow the exception.

• Stop processing and commit return to the caller.

• Retry the failed operation.

• Ignore the error and continue processing.

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:

• Executing a task

• Marking a task as done

• Marking a task as not done

• Reassigning a task to another user or role

• ...

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.

Note: Once defined, an exception handler cannot be deleted if it is referenced by either the Invoke Error Handler action or the Set Workflow Error Handler action. See Using Exception Handling Actions.

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

1. In the folder tree, right-click the Exception Handlers folder (located within the selected workflow template definition folder), and select Create Exception Handler to display the Exception Handler Properties dialog box.

   Note: You can also define exception handlers by accessing the Exception Handlers tab of the Template Definition Properties dialog box. (See Specifying Workflow Template Definition Properties in Defining and Maintaining Workflows.)

   The Exception Handler Properties dialog box allows you to define actions for commit and rollback exception situations. You can also define workflow variables to be populated by values from the XML message defined within the Invoke Exception Handler action.

   Figure 7-2 Exception Handler Properties Dialog Box

   

    

2. Enter a meaningful and easily identifiable name for the new exception handler in the Name field.

3. Optionally select the Initial Exception Handler checkbox to mark the exception handler as the default initial exception handler in the workflow. When a workflow encounters an exception, this is the first exception handler that is called.

4. In the Variables tab, assign workflow variables to be populated by values from XML message defined within the Invoke Exception Handler action or the API.

5. Click Add to display the Workflow Variable Assignment dialog box and assign XML expressions to the variables assigned to the workflow. The variables in the pull-down list are those defined in the Variables Properties dialog box. (See Defining Variables in Working with Workflow Components.)

   Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

   Figure 7-3 Workflow Variable Assignment Dialog Box

   

    

6. In the Actions on Commit tab, assign actions to be performed if the current active transaction is not marked for rollback only.

7. In the Actions on Rollback tab, assign actions to be performed if the currently active transaction is programmatically marked for rollback only. The workflow is rolled back to the beginning of the currently active transaction. Only the following actions are available: Post XML Event, Call Program, Perform Business Operation, Exit Exception Handler, No Operation, and Make Audit Entry.

   Note: 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.

8. In the Notes tab, enter notes pertaining to the exception handler and its assigned actions.

 

---

Using Exception Handling Actions

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

• Invoke Exception Handler

• Set Workflow Exception Handler

• Exit Exception Handler

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.

For instructions on using the Invoke Exception Handler action, see Using XML Actions in Understanding WebLogic Process Integrator Events and XML Documents.

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

 

View or enter information in the Set Workflow Exception Handler dialog box.

• Exception Handler — Displays a list of exception handlers to choose from. If you have not defined an exception handler, the list only displays the system exception handler.

• Notes — Free-form text box for notes on the action.

Exit Exception Handler

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

Note: This action is only displayed in the Add Actions dialog box when this dialog box is accessed from the Actions on Commit and Actions on Rollback tabs of the Exception Handler Properties dialog box. See Defining Exception Handlers.

Figure 7-5 Exit Exception Handler

 

View or enter information in the Exit Exception Handler dialog box.

• Exit Method — Select one of the following exception handler exit methods:

  • Rollback — Marks the user transaction for rollback only, returning the workflow to the state in which it existed prior to the start of the transaction. The exception is propagated to the client (if any) as a WorkflowException.

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.

• Stop — Exits the error handler and does not execute any follow-on actions.

• Retry — Exits the error handler and attempts to retry the failed operation. (The failed operation is an action or the setting of a variable)

• Continue — Stops the execution of the exception handler and attempts to continue the execution of the workflow at the next operation. (The next operation is the next action or the next variable to be set.)

 

---

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.

Refer to Table 6-5 in Using Expressions and Conditions, to obtain a list of Workflow Attribute values. Four error-related values allow you to obtain context about the cause of an exception. These attributes allow the exception handler to interrogate the following information:

• The exception class name.

• The WebLogic Process Integrator error number.

• The error message text.

• The severity code (which also tells you if the exception handler was called—via action or API—or was raised as a result of a caught exception).

  Table 7-1 WebLogic Process Integrator Error Messages

ErrorNumber	ErrorText
0	Unknown error
1	System error
2	Workflow error
3	Workflow warning
4	Nested exception is:
5	The server was unable to complete your request.
6	The server was unable to complete your request.
7	This workflow cannot be modified, because it is complete.
8	This task's properties do not allow it to be marked done.
9	This task's properties do not allow it to be unmarked done.
10	This task's properties do not allow it to be reassigned.
11	This task's properties do not allow it to be modified.
12	Cannot take this task, because it is already done.
13	Cannot assign this task, because it is already done.
14	Cannot execute this task, because it is already done.
15	Cannot execute this task, because it is inactive.
16	Cannot execute this task, because the workflow is complete.
17	Cannot execute this task, because it is not assigned to you.
18	Source and destination of reroute must be different.
19	The effective date must be on or before the expiry date.
20	Source user is already rerouted during the period specified.
21	Specified reroute would create a circular reference.
22	Task names must be unique within a workflow.
23	"{0}" is already in use as an organization name.
24	Role names must be unique within an organization.
25	The specified user "{0}" is already defined.
26	Report names must be unique.
27	Variable names must be unique.
28	Workflow template names must be unique.
29	Workload graph names must be unique.
30	"{0}" is already used as business calendar name.
31	User "{0}" is currently logged on and cannot be deleted.
32	Cannot delete user "{0}", because there are tasks assigned to the user. Please reassign all tasks first.
33	You do not have permission to maintain users.
34	You do not have permission to maintain roles.
35	You do not have permission to maintain organizations.
36	You do not have permission to define workflows.
37	You do not have permission for workflow monitoring.
38	You do not have permission to do task rerouting.
39	You do not have permission to modify the server configuration.
40	The variable "{0}" cannot be deleted, because it is referenced by the ID expression or the trigger definition.
41	The variable "{0}" cannot be deleted, because it is referenced by one or more actions.
42	The variable "{0}" cannot be deleted, because it is referenced by one or more decisions.
43	Variable names cannot be blank.
44	Cannot delete role "{0}", because there are tasks assigned to the role. Please reassign all tasks first.
45	The workflow "{0}" cannot be deleted, because it is referenced by one or more actions.
46	The task "{0}" cannot be deleted, because it is referenced by one or more actions.
47	The role "{0}" cannot be deleted, because it is referenced by one or more actions.
48	The user "{0}" cannot be deleted, because it is referenced by one or more actions.
49	This workflow cannot be modified, because it is suspended.
50	Cannot delete a business calendar's template rules.
51	No business calendar ID specified in expression.
52	No XML defined for calendar.
53	The system could not find the specified business calendar "{0}".
54	Business calendar "{0}" has no rules defined for the year {1}.
55	The system could not find the processor for business calendar "{0}".
56	{0}, {1}: unexpected token "{2}" in business calendar rule.
57	{0}, {1}: unexpected character "{2}" in business calendar rule.
58	The timezone identifier "{0}" is not recognized.
59	EJB home environment not set.
61	Unable to get initial context: environment may be invalid; {0}.
62	Unable to load class object for home interface of type "{0}"; {1}.
63	Unable to load class object for remote interface of type "{0}"; {1}.
64	No object is bound to "{0}" in specified context; {1}.
65	The object bound to "{0}" does not implement home interface "{1}".
66	No home method was found on "{0}" matching "{1}"; {2}.
67	No remote method was found on "{0}" matching "{1}"; {2}.
68	Unable to load class for method return value of type "{0}"; {1}.
69	No remote object(s) were found.
70	EJB "{0}" method invocation failed; {1}.
71	"{0}" object returned from method invocation not of expected type "{1}".
72	Wrong number of parameters for method: expected {1}, found {2}.
73	Unable to load class (wrapped if primitive) for parameter {0} of type "{1}"; {2}.
74	Unable to load class (unwrapped if primitive) for parameter {0} of type "{1}"; {2}.
75	Value for parameter {0} cannot be cast to required type "{1}".
76	The home method did not return a session bean.
77	Workflow template (ID={0}) not found.
78	Workflow template definition (ID={0}) not found.
79	The system could not find an active, effective template definition to start.
80	XML syntax error at line {0}, column {1}.
81	Unable to load class object for "{0}"; {1}.
82	No matching constructor was found on "{0}"; {1}.
83	Creation of new "{0}" failed; {1}.
84	No method was found on "{0}" matching "{1}"; {2}.
85	"{0}" method invocation failed; {1}.
86	The workflow template is currently locked by {0}.
87	The interval "from" date is invalid.
88	The interval "to" date is invalid.
89	The date "{0}" is invalid.
90	Invalid month name: "{0}".
91	Invalid day name: "{0}".
92	The system could not find the specified task instance: "{0}".
93	Mandatory input variable "{0}" not set.
94	The system could not find the specified join instance: "{0}".
95	The system could not find the specified variable instance: "{0}".
96	The system could not find the specified organization: "{0}".
97	The system could not find the specified role: "{0}".
98	The system could not find the specified user: "{0}".
99	User "{0}" does not belong to organization "{1}".
100	The system could not add user "{0}" to organization "{1}".
101	The system could not add user "{0}" to role "{1}".
102	The system could not remove user "{0}" from organization "{1}".
103	The system could not remove user "{0}" from role "{1}".
104	The specified user "{0}" does not belong to the organization within which the role "{1}" is defined.
105	No security realm has been installed.
106	The installed security realm "{0}" is not listable.
107	The security realm "{0}" is not manageable.
108	Unable to connect to database.
109	The role "{0}" is empty.
110	Fixup error: missing reference "{0}".
111	Invalid interval unit: "{0}".
112	Illegal type conversion: from "{0}" to "{1}".
113	Cannot instantiate a workflow, because the template definition is inactive.
114	The system could not find the target task "{0}".
115	The system could not find the target event "{0}".
116	The system could not find the target action "{0}".
117	The system could not find the specified business operation "{0}".
118	Error calling program: "{0}" with arguments "{1}".
119	User "{0}" does not have an e-mail address.
120	User "{0}" in role "{1}" does not have an e-mail address.
121	The routing table failed to identify a suitable assignee.
122	No workflow organization defined for user "{0}".
123	Wrong start date expression: "{0}".\n"(1)".
124	The system could not find the error handler "{0}".
125	An exception occurred during error handler processing.
126	An error handler exceeded the maximum number of retries allowed.
127	The application or workflow instance invoked an error handler.
128	The system could not find the specified workflow instance: {0}.
129	An error occurred when parsing an XML document.
130	The definition was created with a later of version of the product. Upgrade your WebLogic Process Integrator Studio to version {0} or later.