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.
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.
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. The WF_JAVA_ERROR agent is a standard 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 that does not have a specific 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.
Oracle Workflow also provides a predefined subscription with the source type Error for the oracle.apps.wf.notification.wl.response.message event, which represents a notification response whose processing has been deferred. The subscription sends the event message to the Error Process for Notification Response Processing in the System: Error item type. That process sends a notification to the workflow administrator specified in the Workflow Configuration page, who can retry the notification response processing. For more information about deferred notification response processing and the workflow administrator role, see: Setting Global User Preferences.
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.
For example, if you want to provide specific Web service details for any errors in subscriptions that invoke Web services, or if you want to present a simpler administrative notification for local errored events, you can define custom error handling subscriptions that send the event to the Default Event Error Process (One Retry Option) instead of the Default Event Error Process. See: Default Event Error Process (One Retry Option).
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.
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: 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.