Release 2.6.4
Part Number B15853-04
Contents
Previous
Next
| Oracle Workflow Developer's Guide Release 2.6.4 Part Number B15853-04 | Contents | Previous | Next |
This chapter describes how Oracle Workflow handles errors in workflow processes and event subscription processing.
This chapter covers the following topics:
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
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
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.
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
The Event Manager uses the status codes returned or exceptions raised by event subscription rule functions to monitor the status of subscription processing for an event. By default, when an error occurs, the Event Manager performs a type of error handling called Stop and Rollback.
In Stop and Rollback error handling, the Event Manager halts all subscription processing for the event and rolls back any subscriptions already executed for the event. If the subscription rule function trapped an error and returned a PL/SQL ERROR status code or a Java BusinessEventException, the Event Manager places the event message on a standard error queue for further handling within Oracle Workflow.
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.
However, if the subscription rule function raised an unhandled exception, the Event Manager reraises that exception directly to the calling application after rolling back all subscription processing for the event. In this case the event message is not placed on an error queue.
Note: With Stop and Rollback error handling, if you want the calling application to be aware of the error, you should raise an unhandled exception in your rule function, as errors trapped by the rule function are handled within Oracle Workflow and are not raised to the calling application.
Rolling back all subscription processing allows you 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. If you later retry subscription processing for the event, the Event Manager re-executes all subscriptions to the event.
In Oracle Applications only, you can optionally assign a subscription a different type of error handling, called Skip to Next. In Skip to Next error handling, the Event Manager rolls back only this subscription. The Event Manager then places the event message on the standard WF_ERROR or WF_JAVA_ERROR agent, regardless of whether the subscription trapped an error or raised an unhandled exception. The exception is not raised to the calling application. Finally, the Event Manager continues processing the next subscription for the event according to the subscription phase order.
Skipping to the next subscription lets you continue processing without waiting in cases where the calling application does not depend on the successful completion of a subscription and the subscription does not impact the execution of any other subscriptions to the same event. If you later retry subscription processing for the event, the Event Manager re-executes only the errored subscription.
Note: Skip to Next error handling is not available for subscriptions with a source type of Error. If an additional error occurs during such a subscription, processing for that event will be halted until the error is addressed.
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.
Important: 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 subscription processing.
The Default Event Error process sends a notification to the system administrator, who can then 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.
Note: If an event has multiple subscriptions, and the Event Manager encounters an ERROR status or exception during subscription processing, check which subscription caused the error to help determine how to handle the error. This check is particularly important when different applications own subscriptions to the same event.
For additional information about diagnostic and mass event reprocessing scripts, see: Handling Business Event System Errors, Oracle Workflow Administrator's Guide.
A PL/SQL rule function can return a status code of WARNING, indicating that a warning condition occurred, but the subscription processing was completed without a blocking error. In this case the Event Manager places a copy of the event message on the standard WF_ERROR queue associated with the WF_ERROR agent and then continues subscription processing for the event.
The predefined subscription to the Unexpected event with the source type Error performs the default error handling for events with warnings, just as it does for errored events. The subscription sends the event message to the Default Event Error process in the System: Error item type.
The Default Event Error process sends a notification to the system administrator to alert the administrator to the warning condition. This notification does not require a response.
You can also define custom Error subscriptions to perform custom handling for warning conditions.
Note: In Oracle Applications, both the WARNING status code and the Skip to Next error handling type allow subscription processing to continue. However, in Skip to Next error handling, the Event Manager rolls back the processing performed for the errored subscription before continuing, while for the WARNING status code, the Event Manager completes the subscription that returned the warning and continues without rolling back any subscription processing.
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
Specifying Error Handling for a Subscription (for Oracle Applications)
Standard API for an Event Subscription Rule Function
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:
Error Activity ID
Error Activity Label
Error Assigned User
Error Item Type
Error Item Key
Error User Key
Error Message
Error Name
Error Notification ID
Error Result Code
Error Stack
Error Monitor URL
Timeout Value
Event Name
Event Details
Event Message
Event Key
Event Data URL
Event Subscription
Error Type
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.
Important: 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 is the internal name of the Default Error Process. The purpose of this error handling process is to:
send an administrator a notification when an error occurs in a process
provide information to the administrator about the error
allow the administrator to abort the process, retry the errored activity, or resolve the problem that caused the error to occur
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.
WF_ADMINISTRATOR - Specify the role to which Oracle Workflow sends the error notification. The default is the SYSADMIN role.
ERROR_TIMEOUT - Specify whether the error notification times out.
Default Error Process Diagram
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.
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:
Abort the process - executes the Error Still Active activity to verify if the error is still present and if it is, calls the Abort function activity and ends the default error process.
Retry the process - executes the Error Still Active activity to verify if the error is still present and if it is, calls the Retry function activity and ends the default error process.
Resolved the process - ends the default error process because you addressed the errored process directly through some external means or using the embedded URL link to the Workflow Monitor.
Note: The notification message's embedded monitor URL 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 to resolve the error.
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.
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.
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.
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 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.
WF_ADMINISTRATOR - Specify the role to which Oracle Workflow sends the error notification. The default is the SYSADMIN role.
ERROR_TIMEOUT - Specify whether the error notification times out.
Retry-only Process Diagram
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.
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.
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.
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 is the internal name of the Default Event Error Process for the Business Event System. The purpose of this error handling process is to:
send an administrator a notification when an error or warning condition occurs during event subscription processing
provide information to the administrator about the error
allow the administrator to abort or retry the event subscription processing
Default Event Error Process Diagram
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 a PL/SQL ERROR or WARNING status code or a Java BusinessEventException, if a subscription with Skip to Next error processing raises an unhandled exception, 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.
The Initialize Error activity calls a PL/SQL procedure named WF_STANDARD.INITIALIZEEVENTERROR. This procedure determines the error type.
Event Warning - A warning condition occurred, but subscription processing continued. For this error type, the Workflow Engine sends the Event Warning Notification.
External Event Error - An error occurred in subscription processing for an event received from an external source. For this error type, the Workflow Engine sends the External Event Error Notification.
Local Event Error - An error occurred in subscription processing for an event raised on the local system. For this error type, the Workflow Engine sends the Local Event Error Notification.
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
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:
Abort - aborts subscription processing and ends the Default Event Error process. For example, if the event data contained in an event message is corrupted, the system administrator can abort subscription processing on that event message.
Enqueue Event - executes the Retry Process Event activity to enqueue the event message back onto the queue where it was originally received, and ends the Default Event Error process. The event message is enqueued with a priority of -1 so that it will be the first message to be dequeued the next time the listener runs.
The system administrator can attempt to correct the error before re-enqueuing the event. For example, the system administrator can create a subscription to handle an unexpected event and then re-enqueue the event message to trigger the new subscription.
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
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:
Abort - aborts subscription processing and ends the Default Event Error process.
Raise Event with Event Key - executes the Retry Process Event activity to reraise the event with only the event name and event key, and ends the Default Event Error process.
Raise Event with Event Key and Event Data - executes the Retry Process Event activity to reraise the event with only the event name, event key, and event data, and ends the Default Event Error process.
Raise Event with Event Key, Event Data and Parameters - executes the Retry Process Event activity to reraise the event with the event name, event key, event data, and parameters, and ends the Default Event Error process.
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
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:
Enqueue Event - enqueues an errored external event message back onto the queue where it was originally received. The event message is enqueued with a priority of -1 so that it will be the first message to be dequeued the next time the listener runs.
Raise Event with Event Key - reraises a local errored event with only the event name and event key.
Raise Event with Event Key and Event Data - reraises a local errored event with only the event name, event key, and event data.
Raise Event with Event Key, Event Data and Parameters - reraises a local errored event with the event name, event key, event data, and parameters.
Related Topics
Workflow Core APIs, Oracle Workflow API Reference
