Handling Workflow Exceptions

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

• About Workflow Exception Handling

• Overview of Exception Handler Definition Tasks

• Defining Exception Handlers

• Invoking an Exception Handler from a Workflow

• System Error Messages

 

---

About Workflow Exception Handling

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

Exception handling within WebLogic Integration 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 concept of the initial exception handler is required, since exceptions can occur prior to a specific exception handler being invoked from within the workflow. For example, exceptions can occur during the initialization of variables in a Start node. The system exception handler responds to exceptions by marking the active transaction for rollback only and rethrowing the exception to the client.

The workflow exception handling facility allows you to define customized exception handlers that specify actions to be executed in response to exceptions. 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. For information on the workflow transaction model, see Understanding the BPM Transaction Model in Programming BPM Client Applications.

You can also use workflow functions in conditional expressions to identify particular exceptions that you want to catch, by type, severity, text, and other criteria. For more information, see Obtaining Run-time Workflow Data.

Once you have defined the custom exception handler and its actions, you can invoke it in three ways:

• By setting it to act as the initial exception handler. This causes the specified custom exception handler to catch exceptions as soon as the workflow is instantiated.

• By using the Set Workflow Exception Handler action in any workflow node. This causes the custom exception handler to be the active one from that point until the next Set Workflow Exception Handler action is reached within that workflow or until the workflow completes, whichever occurs first.

• By using the Invoke Exception Handler action in any workflow node.This causes the actions defined within the specified exception handler to be executed at that point, regardless of whether an exception has occurred. It also, optionally, sends an XML document to the exception processor, allowing workflow variables to be populated by values from this XML document. This action is only typically used in a conditional situation to catch an exception specifically thrown by the workflow definition.

 

---

Overview of Exception Handler Definition Tasks

Exception Handlers are like sub-workflows within a workflow in which you can specify various actions on commit and/or rollback paths of the transaction in which an exception has occurred. The exception handler can respond to general exception occurrences, or the handler can use a condition to specify a specific exception to trap. To use a custom exception handler in your workflows, you need to do the following:

Note: You may also want to familiarize yourself with the workflow expression language and the Studio's Expression Builder and XPath Wizard tools before beginning to define exception handlers and actions that reference them. Many of the tasks described in this section, such composing an XML document in the Invoke Exception Handler action, or initializing variables in an exception handlers, require entering expressions into dialog box fields. For complete information on workflow expressions, see Using Workflow Expressions.

1. Create an exception handler and, optionally, set it to be the initial exception handler. Procedures are given in Creating a Custom Exception Handler.

2. Add actions to the exception handler. For complete information on actions, see Defining Actions.

3. Add an exit method to the exception handler. Procedures are given in Exiting an Exception Handler.

4. Add an action to a workflow node that invokes the exception handler. Procedures are given in Invoking an Exception Handler from a Workflow.

 

---

Defining Exception Handlers

You use the exception handler definition facility to define custom exception handlers. If you do not define any exception handlers, the system exception handler is, by default, used.

You can set the custom exception handler to be the initial exception handler, that is, the one that is active as soon as a workflow is instantiated. The template definition can change its active exception handler throughout the course of the workflow by using the Set Exception Handler action. (See Setting the Workflow Exception Handler for information.)

Custom exception handlers defined for the current template definition are displayed in the folder tree under the Exception Handlers folder, and in the properties dialog box for a Template Definition.

Figure 9-1 Template Definition Properties Dialog Box: Exception Handlers Tab

 

When you define a custom exception handler, you can specify actions to be performed for both commit and rollback exception situations. For a commit paths, all workflow actions are available to be performed. For a rollback path, only the following actions are available: Post XML Event, Call Program, Perform Business Operation, Exit Exception Handler, No Operation, and Make Audit Entry. For more information about actions, see Defining Actions.

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 rolls back the transaction.

You can also define workflow variables to be populated by values from the XML message defined within the Invoke Exception Handler action. For more information, see Invoking an Exception Handler.

Creating a Custom Exception Handler

To create an exception handler for a workflow template definition:

1. Do one of the following:

   • In the folder tree, expand the folder for the template definition, right-click the Exception Handlers folder and select Create Exception Handler.

   • From the Exception Handlers tab of the template definition's properties dialog box, click Add.

   The Exception Handler Properties dialog box is displayed.

   Figure 9-2 Exception Handler Properties Dialog Box

   
    

2. In the Name field, enter a meaningful and easily identifiable name for the new exception handler.

3. Optionally, select the Initial Exception Handler check box 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. Optionally, on the Variables tab, click Add to display the Workflow Variable Assignment dialog box, which you can use to initialize any variables you have created in the workflow, by specifying an expression that is evaluated at run time to become the value of the variable.

5. From the Variable drop-down list, select a variable to store incoming data.

6. In the Expression field, enter the expression that is evaluated at run time to produce the value for the variable, by doing one of the following:

   • To specify a constant, use the syntax provided in Using Literals.

   • If you will be using the Invoke Exception Handler action (see Invoking an Exception Handler) to send an XML message containing values to populate variables, use an XPath() function (for information, see XPath()), or the dot notation for XML elements (for information, see XML Element Dot Notation). You can also use the Expression button to invoke the XPath Wizard, from which you can generate XPath expressions automatically from a sample incoming document. For information, see Creating XPath Expressions Using the XPath Wizard.

7. Click OK. The variable initialization appears in the list on the Variables tab of the Exception Handler Properties dialog box.

8. Repeat steps 4 to 7 for all variables you want to initialize.

9. In the Actions on Commit tab, use the Add, Update or Delete buttons to specify actions to be performed if the current active transaction is not marked for rollback only. For information on working with actions, see Defining Actions.

10. In the Actions on Rollback tab, you specify the add, update, or delete 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.

11. On the Actions on Commit or Actions on Rollback tab, add the Exit Exception handler action, to return program control to the main workflow. For more information, see Exiting an Exception Handler.

12. Click OK to add the custom exception handler. The new exception handler appears on the Exception Handlers tab of the template definition's properties dialog box, and under the Exception Handlers folder in the folder tree.

Exiting an Exception Handler

You use the Exit Exception Handler action, which is only available from within the Exception Handler Properties dialog box, to exit an exception handler. (For information, see Defining Exception Handlers.) Be sure to add this action to the Actions on Commit or Actions on Rollback tab of the Exception Handler to return control to the main flow.

In a Rollback path, the only exit option available is Rollback. In a Commit path, you can choose from four options:

• 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.

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

• Retry — Exits the exception 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.)

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 rolls back the transaction.

Figure 9-3 Exit Exception Handler

 

To exit an exception handler:

1. From within the Exception Handler Properties dialog box, invoke the Add Action dialog box, expand the Exception Handling actions folder, select Exit Exception Handler, and click OK to display the Exit Exception Handler dialog box.

   If you are adding the action to the Actions on Rollback tab, the only available option is Rollback. If you are adding the action to the Actions on Commit tab, select one of the Exit Method options.

2. Click OK to add the action.

Updating a Custom Exception Handler

1. Do one of the following to display the Exception Handler Properties dialog box:

   • In the folder tree, expand the Exception Handlers folder, right-click the desired exception handler folder, and select Properties from the pop-up menu.

   • From the Exception Handlers tab of the template definition's properties dialog box, select the desired exception handler and click Update.

2. Make any necessary changes to the exception handler.

3. Click OK to save your changes.

Viewing Exception Handler Usage

To see where an exception handler is referenced within the workflow:

1. In the folder tree, right-click the exception handler folder and select Usage from the pop-up menu to display the Exception Handler Usage dialog box, which lists the places within the workflow where the selected exception handler is referenced.

   Figure 9-4 Exception Handler Usage Dialog Box

   
    

2. Optionally, use the following buttons in the dialog box to do the following:

   • Update — select to open the dialog box for the selected object.

   • Delete — select to delete the selected object.

3. Click OK to close the Exception Handler Usage dialog box.

Deleting a Custom Exception Handler

Once defined, an exception handler can only be deleted if it is not referenced by either the Invoke Exception Handler action or the Set Workflow Exception Handler action (for more information, see Invoking an Exception Handler). To see a list of places where an exception handler is referenced, follow the procedure in Viewing Exception Handler Usage.

To delete an exception handler:

1. Do one of the following:

   • In the folder tree, expand the Exception Handlers folder, right-click the desired exception handler folder, and select Delete from the pop-up menu.

   • From the Exception Handlers tab of the template definition's properties dialog box, select the desired exception handler and click Delete.

2. When prompted, confirm the deletion.

 

---

Invoking an Exception Handler from a Workflow

To invoke an exception handler from a workflow, you use the following exception handling actions:

• Set Workflow Exception Handler—this action sets the exception handler for the workflow to the one you specify. All exceptions from this point, until this action is specified again, will be caught by the exception handler you specify. For more information, see Setting the Workflow Exception Handler.

• Invoke Exception Handler—this action invokes the actions defined in a custom exception handler, and optionally sends an XML message to the exception processor, at a certain point in the workflow. It is typically used in a conditional situation to perform alternate actions for an exception defined specifically in the workflow. For more information, see Invoking an Exception Handler.

• Exit Exception Handler—this action is used from within an exception handler to return control to the main workflow. For more information, see Exiting an Exception Handler.

Setting the Workflow Exception Handler

You use the Set Workflow Exception Handler 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 exception handler you set for the workflow persists throughout the instance of the workflow until you use a subsequent Set Workflow Exception Handler action to reset the exception handler to the system handler or to another custom-defined one.

Figure 9-5 Set Workflow Exception Handler

 

To set the workflow exception handler to a custom handler:

1. From the Add Action dialog box, expand the Exception Handling actions folder, select Set Workflow Exception Handler, and click OK to display the Set Workflow Exception Handler dialog box.

2. From the Exception Handler drop-down list, do one of the following:

   • To set the workflow exception handler to a custom one you have defined, select the exception handler from the Exception Handler drop-down list.

   • To reset the workflow exception handler to the default system exception handler, select (system exception handler) from the Exception Handler drop-down list.

3. Click OK to add the action.

Invoking an Exception Handler

You use the Invoke Exception Handler action to invoke a specific exception handler within the workflow and, optionally, send an XML document that you define to the exception handler. You can use the XML document to send values that will be used to populate variables when the exception handler is invoked. (For information, see Defining Exception Handlers.)

Note that this action does not override the exception handler that is set as the active one. Any exceptions that occur are still handled by that exception handler. Furthermore, upon execution of the Invoke Exception Handler action, actions defined in the exception handler are executed, regardless of whether an exception occurs. Thus, you typically use this action in a conditional situation where you want to invoke the actions defined in the exception handler as a result of an exception being thrown from within the workflow itself. This action will not handle exceptions thrown by business operations.

You can also use this action to simply send an XML document to any exception handler you select.

Figure 9-6 Invoke Exception Handler Dialog Box

 

To invoke a custom exception handler:

1. From the Add Action dialog box, expand the Exception Handling actions folder, select Invoke Exception Handler, and click OK to display the Invoke Exception Handler dialog box.

2. From the Exception Handler drop-down list, do one of the following:

   • Leave the Exception Handler field set to the default system exception handler to simply send an XML document to the event processor at this point in the workflow.

   • Select a custom exception handler you have defined. The actions in the custom-defined exception handler specified here will be invoked when this action is executed, regardless of whether an exception has actually occurred. Note that any exceptions that occur at this point are still handled by the exception handler set as the workflow exception handler.

3. Optionally, define an XML document to send to the event processor when the exception handler is invoked. To specify the XML Document Structure, do one of the following:

   • To create a new free-form document, begin composing the document by clicking the Add Child button to begin adding nodes.

   • To specify an existing XML document, load the document by clicking the Import button.

   • To create a new type-specified XML document, load the appropriateSchema document by clicking the Set Content Type button.

   For detailed procedures for all these options, see Composing and Editing XML Documents.

   The XML document you define is stored in the workflow template definition.

4. Click OK to add the action.

 

---

System Error Messages

As described in Obtaining Run-time Workflow Data, the WorkflowAttribute() function may be used with four attributes that allow the exception handler to interrogate the following information:

• The Java exception class name

• The error number

• The error message text

• The error 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):

  • 0: Unknown error type, internal use only

  • 1: A fatal exception occurred while processing a user request

  • 2: A fatal, illegal condition such as inconsistent workflow state

  • 3: A non-fatal workflow condition that the user can rectify manually

  • 4: A custom error raised either by an application calling WorkflowProcessor.invokeWorkfowErrorHandler, or by a workflow executing the Invoke Error handler action

The following table lists workflow error messages by number and text.

Table 9-1 Workflow 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.