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.
Depending on the processing to be performed, a subscription may require the complete set of event information contained in the event data, or it may require only the event key that identifies the instance of the event. You can improve performance by specifying Key as the rule data for subscriptions that do not require the complete event data. If an event is raised locally and any subscriptions to that event require the complete event data, then the Event Manager will run the Generate function for the event to produce the event data. However, if no subscriptions to the event require the event data, then the Event Manager will not run the Generate function, minimizing the resources required to execute the subscriptions.
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
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.
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.
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
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.
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 |