Skip Headers

Oracle Workflow Developer's Guide
Release 2.6.4

Part Number B15853-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

Skip Headers

Oracle Workflow Developer's Guide
Release 2.6.4
Part Number B15853-01
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Error Handling

Error Handling

Oracle Workflow provides default error handling for both workflow processes and event subscription processing. The default handling is defined by error processes provided in a special item type called System: Error, and, for events, by a special subscription to the Unexpected event with a source type of Error. You can also choose to define your own custom error handling by creating custom error processes and subscriptions.

Related Topics

Error Handling for Workflow Processes

Error Handling for Event Subscription Processing

System: Error Item Type and Item Attributes

Default Error Process

Retry-only Process

Default Event Error Process

Error Handling for Workflow Processes

Errors that occur during workflow execution cannot be directly returned to the caller, since the caller generally does not know how to respond to the error. In fact, the caller may be a background engine with no human operator. Instead, Oracle Workflow lets you define the processing you want to occur in case of an error by specifying an error handling process when you create your workflow process in Oracle Workflow Builder.

At design time, you can assign an error handling process for a process, function, or event activity in the activity's Details property page. You must specify the internal names of both the item type that owns the error handling process and the error handling process itself. See: To Define Optional Activity Details.

Details Property Page

the picture is described in the document text

Oracle Workflow provides a special item type called System: Error, which contains error processes called Default Error process and Retry-only process that you can use for generic error handling in any of your processes. However, you cannot modify the error processes in the System: Error item type. If you want to incorporate functionality that is not available in these error processes, you should create your own custom error handling process in your own item type. An error process can branch based on error codes, send notifications, and attempt to deal with the error using automated rules for resetting, retrying, or skipping the failed activity.

Note: Rather than relying on an error process to handle errors due to specific business rule incompatibilities, you should try to model those situations into your workflow process definition. For example, if a function activity can potentially encounter an error because a business prerequisite is not met, you might model your process to send a notification to an appropriate role to correct that situation if it occurs, so that the workflow process can progress forward. If you do not model this situation into your workflow process, and instead rely on the error to activate an error process, the entire workflow process will have an ERROR status and will halt until a workflow administrator handles the error.

At runtime, the Workflow Engine traps errors produced by function activities by setting a savepoint before each function activity. If an activity produces an unhandled exception, the engine performs a rollback to the savepoint, and sets the activity to the ERROR status.

Note: For this reason, you should never commit within the PL/SQL procedure of a function activity. The Workflow Engine never issues a commit as it is the responsibility of the calling application to commit.

The Workflow Engine then attempts to locate an error process to run by starting with the activity which caused the error and then checking each parent process activity until an associated error process is located. If the Workflow Engine finds an error process, it launches that process to handle the error. If no error process is assigned for the running process, the Workflow Engine performs a rollback to the savepoint and sets the activity to the ERROR status, but no error process can be launched.

Note: Both the error item type and the error process must be specified for an error process to be launched.

Customizing Error Notifications for an Item Type

The Default Error process and the Retry-only process both send notifications to inform an administrator that an error occurred. If you assign one of these processes as the error process for your own process activity, you can control the behavior of the error notifications through item type attributes that you define in your own item type. In this way you can customize your error handling without modifying the predefined error processes.

By default, the Default Error process and the Retry-only process send error notifications to the SYSADMIN role. You can optionally specify another role as the recipient of error notifications for your item type by creating an item type attribute named WF_ADMINISTRATOR in your item type and setting the value of this attribute to the role that you want to notify. If your item type includes the WF_ADMINISTRATOR attribute, the Default Error process and the Retry-only process send any error notifications to the role you specify in that attribute, overriding the default.

For example, suppose you have a requisition approval workflow and you want the purchasing administrator, not the system administrator, to resolve any problems that arise from this workflow. You can define an item attribute called WF_ADMINISTRATOR in the item type that owns your requisition approval workflow and set the WF_ADMINISTRATOR attribute to the purchasing administrator's role, which may be PO_ADMIN.

You can also optionally use an item type attribute in your own item type to control whether the error notification activity in the Default Error process or the Retry-only process times out. Create an item type attribute of type number named ERROR_TIMEOUT, and set the value of this attribute to the timeout interval you want, specified in minutes. The Workflow Engine interprets the timeout value of this attribute as a relative offset from the begin date of the activity. If the ERROR_TIMEOUT attribute contains a null value, a value of zero, or is not defined at all, the error notification activity does not time out.

Related Topics

System:Error Item Type and Item Attributes

Default Error Process

Retry-only Process

Error Handling for Event Subscription Processing

The Event Manager uses the status codes returned by event subscription rule functions to monitor the status of subscription processing for an event. If a rule function returns a status code of WARNING or ERROR, indicating that a warning condition or an error occurred during subscription processing, the Event Manager places the event message on a standard error queue. For subscription processing in the database, the event message is placed on the standard WF_ERROR queue associated with the WF_ERROR agent. In Oracle Applications, for subscription processing in the middle tier, the event message is placed on the standard WF_JAVA_ERROR queue associated with the WF_JAVA_ERROR agent.

For a WARNING status, the Event Manager then continues subscription processing for the event. For an ERROR status, the Event Manager halts subscription processing for the event and rolls back any subscriptions already executed for the event.

Note: All subscription processing is rolled back in the case of an error in order to allow the system administrator to handle the error by retrying the event, if appropriate. In this way, Oracle Workflow ensures that no subscription is duplicated when subscription processing is restarted.

Note: If a rule function raises an exception, the Event Manager rolls back all subscription processing for the event and raises the error to the calling application. In this case the event message is not placed on the WF_ERROR queue.

If you want the calling application to be aware of the error, you should raise an exception in your rule function rather than returning an ERROR status, as the ERROR status is handled within Oracle Workflow and is not raised to the calling application.

The WF_ERROR agent is a standard agent for error handling in the database that is automatically defined on the local system when you install Oracle Workflow. In Oracle Applications, Oracle Workflow also provides the standard WF_JAVA_ERROR agent for error handling in the middle tier. Oracle Workflow provides agent listeners to monitor these agents. When a listener dequeues an event message from the WF_ERROR queue or the WF_JAVA_ERROR queue, the message is assigned a source type of Error. The Event Manager then searches for and executes any subscriptions by the local system to that event or to the Any event with the source type Error. If no subscriptions are found, the Event Manager executes any subscriptions by the local system to the Unexpected event with the source type Error.

Oracle Workflow provides one predefined subscription to the Unexpected event with the source type Error. This subscription performs the default error handling for any errored event for which you have not defined a custom Error subscription. The subscription sends the event message to the Default Event Error process in the System: Error item type.

Attention: You must not change or disable the definition of the Unexpected event or of the predefined Error subscription to that event. If you do, the Event Manager will not be able to perform default error handling for event and subscription processing.

The Default Event Error process sends a notification to the system administrator. For a warning condition, no response is required. For an error, the process allows the system administrator to abort or retry the event subscription processing.

You can set up custom error handling for a particular event by defining a subscription to that event with a source type of Error and specifying the custom processing you want to execute as the subscription action. In this case, the Event Manager will not perform the default error handling, since the errored event will no longer be an unexpected event. Instead, your custom error handling will replace the default error handling.

Unexpected Events

Oracle Workflow also uses the Default Event Error process to handle unexpected events. If an event is received from an external source, but the local system does not have any subscriptions to that event, the Event Manager automatically searches for subscriptions to the Unexpected event with the source type External. Oracle Workflow provides a predefined External subscription to the Unexpected event that sends the event message to the Default Event Error process.

The Default Event Error process notifies the system administrator of the unexpected event and allows the system administrator to abort or retry the event subscription processing. For example, the system administrator can create a subscription to handle the event and then re-enqueue the event message to trigger the new subscription.

Note: Oracle Workflow also provides a predefined Local subscription to the Unexpected event that sends the event message to the Default Event Error process when there are no subscriptions to a locally raised event. However, this subscription is disabled by default, because many local events may be raised to which you do not want to subscribe. If you want to enable this subscription, be careful to consider all the events that can be raised on your local system and trigger the subscription.

Related Topics

Unexpected Event

Default Event Error Process

System: Error Item Type and Item Attributes

To view the details of the System: Error item type, choose Open from the File menu in the Oracle Workflow Builder, then connect to the database and select the System: Error item type or connect to a file called wferror.wft in the <ORACLE_HOME>\wf\Data\<Language> directory.

The System: Error item type contains the following item attributes:

These item attributes are referenced by the function, notification, and event activities that make up the error processes called Default Error Process, Retry-only, and Default Event Error Process.

Attention: If you create a custom error handling process in your own item type, Oracle Workflow automatically sets the above item attributes when it calls your error handling process. If these item attributes do not already exist in your process, Oracle Workflow creates them at runtime. However, if you want to reference these item attributes in your error handling process, such as in a message, you must first create them as item attributes in your process's item type at design time using Oracle Workflow Builder.

Related Topics

Default Error Process

Retry-only Process

Default Event Error Process

Default Error Process

DEFAULT_ERROR is the internal name of the Default Error Process. The purpose of this error handling process is to:

The process automatically terminates when the error is no longer active.

Although you cannot edit the Default Error Process, the process is flexible enough for you to customize its behavior. You can define two item type attributes called WF_ADMINISTRATOR and ERROR_TIMEOUT in your item type that calls the Default Error Process to control the error processing that is performed.

Default Error Process Diagram

the picture is described in the document text

'Initialize Error' Function Activity

The Initialize Error activity calls a PL/SQL procedure named WF_STANDARD.INITIALIZEERRORS. This procedure determines if the item type of the errored process has an item type attribute defined with an internal name of WF_ADMINISTRATOR. If it does, it sets the performer of the subsequent notification activity, Notify Administrator, to the role stored in WF_ADMINISTRATOR. If it does not, the subsequent notification activity remains set to the default performer, SYSADMIN.

By checking for an item attribute called WF_ADMINISTRATOR in your errored process's item type, the Initialize Error activity lets you specify who you want a notification to be sent to in the case of an error in your specific process without modifying the error process.

'Notify Administrator' Notification Activity

The Notify Administrator activity sends the Default Retry Error message to a performer (either SYSADMIN or whatever role is stored in your item type's WF_ADMINISTRATOR item attribute). The message indicates that an error has occurred in the specified process and that a response is needed. The response options and their resulting actions are:

The subject and body of the Default Retry Error message are as follows:

Subject: Error in Workflow &ERROR_ITEM_TYPE/&ERROR_ITEM_KEY 

&ERROR_MESSAGE

Body: An Error occurred in the following Workflow.

Item Type = &ERROR_ITEM_TYPE
Item Key = &ERROR_ITEM_KEY
User Key =&ERROR_USER_KEY

Error Name = &ERROR_NAME
Error Message = &ERROR_MESSAGE
Error Stack = &ERROR_STACK

Activity Id = &ERROR_ACTIVITY_ID
Activity Label = &ERROR_ACTIVITY_LABEL
Result Code = &ERROR_RESULT_CODE
Notification Id = &ERROR_NOTIFICATION_ID
Assigned User = &ERROR_ASSIGNED_USER

&MONITOR

The Notify Administrator notification activity has a dynamic timeout value assigned to it. It checks the item type of the errored process for an item type attribute whose internal name is ERROR_TIMEOUT. ERROR_TIMEOUT must be an attribute of type number. The Workflow Engine interprets the value of this attribute as a relative offset from the begin date of the activity, in the unit of minutes, to determine the timeout value of Notify Administrator. If ERROR_TIMEOUT contains a null value, a value of zero, or is not defined at all, then Notify Administrator has no timeout.

'Error Still Active' Function Activity

The Workflow Engine initiates the Error Still Active function activity if the Notify Administrator activity times out or returns Abort or Retry as a result.

The Error Still Active activity calls a PL/SQL procedure called WF_STANDARD.CHECKERRORACTIVE. The purpose of the Error Still Active activity is to determine whether the errored process is still in error before continuing with the error handling. If it is, Error Still Active returns TRUE and the Workflow Engine takes the appropriate transition to either send another notification or abort or retry the errored process. If the errored process is no longer in error, this activity returns FALSE and the error handling process ends, as modelled in the process diagram.

'Retry' Function Activity

The Retry function activity executes the PL/SQL procedure WF_STANDARD.RESETERROR to clear the activity that was in error and run it again. This procedure calls the WF_ENGINE.HandleError API to rerun the activity.

'Abort' Function Activity

The Abort function activity executes the PL/SQL procedure WF_STANDARD.ABORTPROCESS, which in turn calls the WF_ENGINE.AbortProcess API to abort the process that encountered the error.

Related Topics

Workflow Core APIs, Oracle Workflow API Reference

Retry-only Process

RETRY_ONLY is the internal name of the Retry-only error process. The purpose of this error handling process is to alert an administrator when an error occurs in a process and prompt the administrator to retry the process in error. The process automatically terminates when the error is no longer active.

Although you cannot edit the Retry-only process, the process is flexible enough for you to customize its behavior. You can define two item type attributes called WF_ADMINISTRATOR and ERROR_TIMEOUT in your item type that calls the Retry-only process to control the error processing that is performed.

Retry-only Process Diagram

the picture is described in the document text

'Initialize Error' Function Activity

The Initialize Error activity calls a PL/SQL procedure named WF_STANDARD.INITIALIZEERRORS. This procedure determines if the item type of the errored process has an item type attribute defined with an internal name of WF_ADMINISTRATOR. If it does, it sets the performer of the subsequent notification activity, NTF with RETRY Only, to the role stored in WF_ADMINISTRATOR. If it does not, the subsequent notification activity remains set to the default performer, SYSADMIN.

By checking for an item attribute called WF_ADMINISTRATOR in your errored process' item type, the Initialize Error activity lets you specify who you want a notification to be sent to in the case of an error in your specific process without modifying the error process.

'NTF with RETRY Only' Notification Activity

The NTF with RETRY Only activity sends the Retry As Only Option message to a performer (SYSADMIN or whatever role is stored in your item type's WF_ADMINISTRATOR item attribute). The message indicates that an error has occurred in the specified process and prompts the administrator to retry the activity that errored. The error process then transitions to the Retry function activity and ends the Retry-only error process.

Note: The notification message's embedded URL link displays the process in error in the Workflow Monitor with full administrator privileges. You can perform actions such as retrying, skipping, or rolling back part of your process within the Workflow Monitor to resolve the error.

The subject and body of the Retry As Only Option message are as follows:

Subject: Error in Workflow &ERROR_ITEM_TYPE/&ERROR_ITEM_KEY 

&ERROR_MESSAGE

Body: An Error occurred in the following Workflow.

Item Type = &ERROR_ITEM_TYPE
Item Key = &ERROR_ITEM_KEY
User Key =&ERROR_USER_KEY

Error Name = &ERROR_NAME
Error Message = &ERROR_MESSAGE
Error Stack = &ERROR_STACK

Activity Id = &ERROR_ACTIVITY_ID
Activity Label = &ERROR_ACTIVITY_LABEL
Result Code = &ERROR_RESULT_CODE
Notification Id = &ERROR_NOTIFICATION_ID
Assigned User = &ERROR_ASSIGNED_USER

&MONITOR

The NTF with RETRY Only notification activity has a dynamic timeout value assigned to it. It checks the item type of the process in error for an item attribute that has an internal name called ERROR_TIMEOUT. ERROR_TIMEOUT must be an attribute of type number. The Workflow Engine interprets the timeout value of this attribute as a relative offset from the begin date of the activity, in the unit of minutes. If ERROR_TIMEOUT contains a null value, a value of zero, or is not defined at all, then NTF with RETRY Only has no timeout.

'Error Still Active' Function Activity

The Workflow Engine initiates the Error Still Active function activity if the NTF with RETRY Only activity times out.

The Error Still Active activity calls a PL/SQL procedure called WF_STANDARD.CHECKERRORACTIVE. The purpose of the Error Still Active activity is to determine whether the errored process is still in error before continuing with the error handling. If it is, Error Still Active returns TRUE and the Workflow Engine transitions back to the NTF with RETRY Only notification activity to send another notification to the administrator. If the errored process is no longer in error, this activity returns FALSE and the error handling process ends, as modelled in the process diagram.

'Retry' Function Activity

The Retry function activity executes the PL/SQL procedure WF_STANDARD.RESETERROR to clear the activity that was in error and run it again. This procedure calls the WF_ENGINE.HandleError API to rerun the activity.

Related Topics

Workflow Core APIs, Oracle Workflow API Reference

Default Event Error Process

DEFAULT_EVENT_ERROR is the internal name of the Default Event Error Process for the Business Event System. The purpose of this error handling process is to:

Default Event Error Process Diagram

the picture is described in the document text

'Receive Errored Queue Message' Event Activity

The Receive Errored Queue Message activity receives an event message that has encountered an error or warning condition during subscription processing. For instance, if a subscription rule function returns an ERROR or WARNING status code, or if an unexpected event is received, the Event Manager executes default subscriptions that send the event message to the Default Event Error process. See: Predefined Workflow Events.

The Receive Errored Queue Message activity stores the event name, event key, and the complete event message in item type attributes.

'Initialize Event Error' Function Activity

The Initialize Error activity calls a PL/SQL procedure named WF_STANDARD.INITIALIZEEVENTERROR. This procedure determines the error type.

'Event Warning Notification' Activity

The Workflow Engine initiates the Event Warning Notification activity when the errored event has an error type of Event Warning. The activity sends the Default Event Warning message to the system administrator to indicate that a warning condition has occurred during subscription processing. This message is an FYI message and does not require a response.

The subject and body of the Default Event Warning message are as follows:

Subject: Event WARNING : &EVENT_NAME / &EVENT_KEY

Body: A Warning occurred in the following Event 
Subscription: &EVENT_SUBSCRIPTION

Event Error Name: &ERROR_NAME
Event Error Message: &ERROR_MESSAGE
Event Error Stack: &ERROR_STACK

Event Data: &EVENT_DATA_URL

Other Event Details: &EVENT_DETAILS

'External Event Error Notification' Activity

The Workflow Engine initiates the External Event Error Notification activity when the errored event has an error type of External Event Error. The activity sends the Default External Event Error message to the system administrator. This message indicates that an error has occurred during subscription processing for an event received from an external source, and that a response is needed. The response options and their resulting actions are:

The subject and body of the Default External Event Error message are as follows:

Subject: External Event &ERROR_TYPE : &EVENT_NAME / &EVENT_KEY

Body: An Error occurred in the following Event 
Subscription: &EVENT_SUBSCRIPTION

Event Error Name: &ERROR_NAME
Event Error Message: &ERROR_MESSAGE
Event Error Stack: &ERROR_STACK

Event Data: &EVENT_DATA_URL

Other Event Details: &EVENT_DETAILS

'Local Event Error Notification' Activity

The Workflow Engine initiates the Local Event Error Notification activity when the errored event has an error type of Local Event Error. The activity sends the Default Local Event Error message to the system administrator. This message indicates that an error has occurred during subscription processing for an event raised on the local system, and that a response is needed. The response options and their resulting actions are:

The system administrator can choose the level of information to provide to the Event Manager when reraising the event. For example, if an error exists in the event data that was originally provided, the event can be reraised with only the event name and the event key, forcing the Event Manager to regenerate the event data using the event's Generate function.

The system administrator can also attempt to correct the error before reraising the event.

The subject and body of the Default Local Event Error message are as follows:

Subject: Local Event &ERROR_TYPE : &EVENT_NAME / &EVENT_KEY

Body: An Error occurred in the following Event 
Subscription: &EVENT_SUBSCRIPTION

Event Error Name: &ERROR_NAME
Event Error Message: &ERROR_MESSAGE
Event Error Stack: &ERROR_STACK

Event Data: &EVENT_DATA_URL

Other Event Details: &EVENT_DETAILS

'Retry Process Event' Function Activity

The Retry Process Event activity executes the PL/SQL procedure WF_STANDARD.RETRYRAISE. Depending on the notification response selected by the system administrator, this procedure either re-enqueues or reraises an errored event. The responses that can initiate the Retry Process Event activity and their resulting actions are:

Related Topics

Workflow Core APIs, Oracle Workflow API Reference

Managing Business Events