Oracle Workflow Guide Release 2.6.2 Part Number A95265-02 |
Previous | Next | Contents | Index | Glossary |
When you install Oracle Workflow, several default subscriptions to predefined Workflow events are automatically created. You can update, enable, or disable these subscriptions to perform the event processing that you want. See: Predefined Workflow Events.
Whenever an event is raised locally or received from an external source, the Event Manager searches for and executes any active subscriptions by the local system to that event or to the Any event. If no active subscriptions exist for the event that occurred (apart from subscriptions to the Any event), then Oracle Workflow executes any active subscriptions to the Unexpected event. See: Any Event and Unexpected Event.
Each subscription defines an action on exactly one system, so you should define a separate subscription for each system involved in the processing you want to perform. For example, if you want to propagate data from one system to another, you should define one subscription for the sending system, and another subscription for the receiving system.
Note: All event messages received by an inbound agent on the subscribing system are considered to have an External source, whether the sending agent is located on a remote system or on the local system.
You can also optionally restrict the subscription to be triggered only by events received from a specific source agent. However, in most cases you do not need to specify a source agent.
Note: If you enter the same phase number for more than one subscription, the Event Manager may execute those subscriptions in any order, relative to each other. However, the Event Manager will still execute that group of subscriptions in their specified place in the phase order, relative to subscriptions with other phase numbers.
You can also use the phase number for a subscription to control whether the subscription is executed immediately or is deferred. The Event Manager treats subscriptions with a phase number of 100 or higher as deferred subscriptions. See: Deferred Subscription Processing.
Note: Even if there are subscriptions that require the complete event data, you can return control to the calling application more quickly after raising the event by deferring all those subscriptions. Then the Event Manager will not run the Generate function until those subscriptions are executed at a later time.
Oracle Workflow provides a standard default rule function to perform basic subscription processing. This function is executed by default if no other rule function is specified for the subscription. The default rule function includes the following actions:
Oracle Workflow also provides some standard rule functions that you can use for testing and debugging or other purposes. See: Event Subscription Rule APIs.
You can extend your subscription processing by creating custom rule functions. Custom rule functions must be defined according to a standard API. See: Standard API for an Event Subscription Rule Function.
You can use a rule function for many different purposes, including:
Note: You can call WF_EVENT_FUNCTIONS_PKG.AddCorrelation() within a custom rule function to add a correlation ID during your custom processing. See: AddCorrelation.
A rule function may read or write to the event message or perform any other database action. However, you should never commit within a rule function. The Event Manager never issues a commit as it is the responsibility of the calling application to commit. Additionally, the function must not change the connection context in any way, including security and NLS settings. If a rule function returns an error, subscription processing is halted.
If the subscription processing that you want to perform for an event includes several successive steps, you may find it advantageous to define multiple subscriptions to the event with simple rule functions that you can reuse, rather than creating complex specialized rule functions that cannot be reused. You can enter phase values for the subscriptions to specify the order in which they should be executed.
Note: If you enter a rule function other than the default function, you can still enter workflow and agent information for your function to reference, but Oracle Workflow does not automatically send the event message to the specified workflow and agent. Instead, you must either explicitly include the send processing in your rule function, or define a separate subscription that does use the default rule function to perform the send processing.
Sending the Event to a Workflow Process
Note: You can call WF_EVENT_FUNCTIONS_PKG.AddCorrelation() during subscription processing to add a correlation ID to the event message. To use AddCorrelation(), you must enter a subscription parameter named ITEMKEY that specifies a function to generate the correlation ID. The function must be specified in the following format:
ITEMKEY=<package_name.function_name>
See: AddCorrelation.
You can specify any additional parameters that you want to set as item attributes for the workflow process. If the corresponding item attributes do not already exist in the item type, Oracle Workflow automatically creates the item attributes when the event is sent to the process. Also, the subscription's globally unique identifier (GUID) is set as a dynamic item attribute so that the workflow process can reference other information in the subscription definition.
By sending an event to a workflow process, you can model complex processing or routing logic beyond the options of directly running a predefined function or sending the event to a predefined recipient. For example, you can branch to different functions, initiate subprocesses, send notifications, or select recipient agents, based on the contents of the event message, or modify the event message itself.
Events are represented within workflow processes by event activities. See: Event Activity.
Note: To send an event to a workflow process, you must either use the default rule function provided by Oracle Workflow or include send processing in your custom rule function. See: Standard API for an Event Subscription Rule Function.
Sending the Event to an Agent
Note: The subscriber list for a multi-consumer queue in Oracle Advanced Queuing is different from event subscriptions in the Oracle Workflow Business Event System. For more information, see: Subscription and Recipient Lists, Oracle Application Developer's Guide - Advanced Queuing.
You can optionally specify the priority with which the recipient should dequeue a message. Messages are dequeued in ascending priority order.
Note: To send an event to an agent, you must either use the default rule function provided by Oracle Workflow or include send processing in your custom rule function. See: Standard API for an Event Subscription Rule Function.
If you want an event message to become available to the recipient at a future date, rather than being available immediately as soon as it is propagated, you can set the SEND_DATE attribute within the event message to the date you want. You should set the send date during subscription processing before the event is sent, either in a prior subscription or earlier in the rule function before the send processing. The event message is propagated to the To Agent but does not become available for dequeuing until the specified date.
You can defer subscription processing by three different methods:
The listener dequeues event messages from the WF_DEFERRED agent in priority order. The event messages retain their original source type, whether Local or External. The amount of time by which subscription processing for these events is deferred depends on the schedule defined for the listener, and, for future-dated events, on the specified effective date.
Deferring Subscription Processing Using a Future Send Date
When an event is raised with a future send date, the Event Manager immediately places the event message on the WF_DEFERRED queue, without executing any of the subscriptions for the event. All subscriptions to the event are deferred, regardless of their phase number. The event remains in a WAIT state until the send date. When the send date arrives, the event message becomes available for dequeuing and will be dequeued the next time an agent listener runs on the WF_DEFERRED queue. The amount of time by which subscription processing is deferred depends on the send date you specify as well as on the schedule defined for the listener.
When the listener dequeues the event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If the event message does not contain a subscription ID, meaning that all subscription processing for the event was deferred immediately after the event was raised, then the Event Manager proceeds to execute all subscriptions to the event, in ascending phase order.
Note: If an event was deferred when it was raised, the Event Manager executes all eligible subscriptions to the event when the event is dequeued from the WF_DEFERRED queue, regardless of the subscription phase numbers. Subscriptions will not be deferred a second time, even if they have a phase number of 100 or higher.
Deferring Subscription Processing Using Subscription Phase Numbers
Note: For this deferral method to take effect when an event is raised locally, the event must not be raised with a future send date, and the Event Manager must be in the normal synchronous mode for subscription processing. Otherwise, the event message will immediately be placed on the WF_DEFERRED queue, and the Event Manager will not execute any subscriptions until the event is dequeued from there.
When a triggering event is raised or received, the Event Manager executes subscriptions to that event in phase order until it encounters a subscription with a phase number of 100 or higher. The Event Manager sets that subscription into the ERROR_SUBSCRIPTION attribute within the event message, as well as setting the priority specified in the subscription properties into the PRIORITY attribute. Then the event message is placed on the standard WF_DEFERRED queue.
The amount of time by which subscription processing is deferred depends on the schedule defined for the agent listener monitoring the WF_DEFERRED agent. When the listener dequeues an event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If a subscription ID is present, meaning that subscription processing was deferred from that subscription onwards, the Event Manager begins by executing that subscription, and then continues executing any other subscriptions to the event with the same or a higher phase number.
Note: The Event Manager resumes subscription processing at the phase number of the subscription set into the event message. It does not necessarily begin with the phase number 100, if there were no subscriptions with that phase number when the event was originally processed.
Deferring Subscription Processing Using the Event Manager Dispatch Mode
If you raise an event from a local application, you can also choose to defer all subscription processing for that event every single time it is raised. To do so, call the SetDispatchMode() API with the mode 'ASYNC', indicating deferred (asynchronous) processing, just before calling the Raise() API. This method is not recommended, however, and should only be used in exceptional circumstances, since it requires hard-coding the deferral in your application. To retain the flexibility to modify subscription processing without intrusion into the application, you can simply raise the event with a future send date or mark some or all of the individual subscriptions for deferral using the subscription phase numbers.
When an event is raised after the dispatch mode is set to deferred processing, the Event Manager immediately places the event message on the WF_DEFERRED queue, without executing any of the subscriptions for the event. All subscriptions to the event are deferred, regardless of their phase number.
The amount of time by which subscription processing is deferred depends on the schedule defined for the agent listener monitoring the WF_DEFERRED agent. When the listener dequeues the event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If the event message does not contain a subscription ID, meaning that all subscription processing for the event was deferred immediately after the event was raised, then the Event Manager proceeds to execute all subscriptions to the event, in ascending phase order.
Note: If an event was deferred when it was raised, the Event Manager executes all eligible subscriptions to the event when the event is dequeued from the WF_DEFERRED queue, regardless of the subscription phase numbers. Subscriptions will not be deferred a second time, even if they have a phase number of 100 or higher.
You must schedule a listener to monitor the WF_ERROR agent. When this listener dequeues the event message from the WF_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. See: Unexpected Event and Default Event Error Process.
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 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.
To Update or Delete an Event Subscription
Standard API for an Event Subscription Rule Function
Scheduling Listeners for Local Inbound Agents
Previous | Next | Contents | Index | Glossary |