Previous	Next		Contents	Index	Glossary

When you install Oracle Workflow, several default subscriptions to predefined Workflow events are automatically created. You can enable, disable, or copy 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 eligible subscriptions. To be eligible, a subscription must meet the following requirements:

• The subscriber must be the local system.

• The triggering event must be the event that was raised or received, an event group that includes that event, or the Any event.

• Both the subscription and its triggering event must be marked as active by having a status of Enabled.

• The source type of the subscription must match the source of the event, either local or external.

Oracle Workflow provides default error handling for subscription processing through a predefined Error subscription to the Unexpected event and the Default Event Error process in the System: Error item type. You can also define custom error handling for your events. See: Error Handling for Event Subscription Processing.

Defining the Subscriber

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.

Defining How a Subscription is Triggered

• Local--The subscription applies only to events raised on the subscribing system.

• External--The subscription applies only to events received by an inbound agent on the subscribing 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.

• Error--The subscription applies to only to errored events dequeued from the WF_ERROR queue.

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.

Controlling How a Subscription is Executed

If you define multiple subscriptions to the same event, the phase numbers for the subscriptions also control the order in which the Event Manager executes those subscriptions. Subscriptions are executed in ascending phase order. For example, you can enter 10 for the subscription that you want to execute first when an event occurs, 20 for the subscription that you want to execute second, and so on. You can use phases to ensure that different types of actions are performed in the appropriate order, such as executing subscriptions that perform validation before subscriptions that perform other types of processing.

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.

Additionally, you can use phase numbers to ensure that your subscriptions are unique, so that the Workflow XML Loader can properly download and upload the subscription definitions. Each subscription must have a unique combination of subscribing system, source type, triggering event, source agent, phase, owner name, and owner tag. If you are defining several subscriptions with similar properties, assign each subscription a different phase number to differentiate it from the others.

The phase number 0 (zero) is reserved for Oracle Workflow seeded subscriptions.

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. For locally raised events, the Event Manager checks each subscription before executing it to determine whether the subscription requires the complete event data. If the event data is required but is not already provided, the Event Manager runs 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.

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.

Defining the Action for a Subscription

• Run a function on the event message.

• Send the event message to a workflow process.

• Send the event message to an agent.

To run a function on the event message, you must specify the rule function that you want to execute. You can also specify any additional parameters that you want to pass to the function.

Oracle Workflow provides a standard default rule function named WF_RULE.Default_Rule 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:

• Sending the event message to a workflow process, if specified in the subscription definition

• Sending the event message to an agent, if specified in the subscription definition

Oracle Workflow also provides additional standard rule functions that you can use for advanced processing, testing, debugging, or other purposes. Commonly used rule functions including the following:

• Default_Rule2 - Performs the basic subscription processing only if the parameter list within the event message includes parameters whose names and values match all the parameters defined for the subscription. See: Default_Rule2, Oracle Workflow API Reference.

• Default_Rule3 - Sets the parameter name and value pairs from the subscription parameters into the parameter list within the event message before performing the basic subscription processing. See: Default_Rule3, Oracle Workflow API Reference.

• SendNotification - Sends a notification as specified by the parameter list within the event message. This rule function lets you send a notification outside of a workflow process. See: SendNotification, Oracle Workflow API Reference.

• Instance_Default_Rule - Sends the event to all existing workflow processes that have eligible receive event activities waiting to receive it, identified by a business key attribute. See: Instance_Default_Rule, Oracle Workflow API Reference.

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:

• Performing validation

• Processing inbound messages as a Receive message handler for an application

• Making modifications to an outbound message, such as adding a correlation ID that associates this message with other messages

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, Oracle Workflow API Reference.

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 one of the default functions, 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

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.

To send the event to a particular workflow process using the Default_Rule, Default_Rule2, or Default_Rule3 rule functions, you must specify the item type and process name of the process. The item key for the process is determined either by the correlation ID specified in the event message, or by the event key if no correlation ID is specified. The event can either start a new process with that item key or continue an existing process identified by that item key that is waiting to receive it.

Note: The item key for a process instance can only contain single-byte characters. It cannot contain a multibyte value.

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, Oracle Workflow API Reference.

If you want to send the event to multiple existing workflow processes, instead of to one particular process, you can use the Instance_Default_Rule rule function instead. This rule function does not require you to specify an item type and process name. In this case, the Event Manager sends the event to all existing workflow process instances that have eligible receive event activities waiting to receive it, marked by a business key attribute that matches the event key. For each receive event activity that you want to receive the event, you must define an activity attribute named #BUSINESS_KEY, and set an item type attribute as the default value for that activity attribute. Then include logic to set that item attribute value to match the event key of the corresponding event at runtime.

Note: With the Instance_Default_Rule rule function, the event is only sent to continue existing processes. If you want to launch a new process instance with the event, use the Default_Rule, Default_Rule2, or Default_Rule3 rule functions.

If you want to specify additional parameters to set as item attributes for the workflow process, you can enter these parameters in the Parameters field of a subscription and use WF_RULE.SetParametersIntoParameterList() in the subscription rule function to set the subscription parameters into the event message parameter list. The event parameters will then be set as item attributes for the workflow process when the process receives the event. See: SetParametersIntoParameterList, Oracle Workflow API Reference.

Note: To send an event to a workflow process, you must either use a standard rule function provided by Oracle Workflow or include send processing in your custom rule function. See: Standard API for an Event Subscription Rule Function.

When an event subscription sends an event to a workflow process, the Workflow Engine performs the following processing:

• Sets any parameters in the event message parameter list as item type attributes for the process, creating new item type attributes if a corresponding attribute does not already exist for any parameter.

• Sets the subscription's globally unique identifier (GUID) as a dynamic item attribute so that the workflow process can reference other information in the subscription definition.

• If the event was originally raised by a Raise event activity in another workflow process, the item type and item key for that process are included in the parameter list within the event message. In this case, the Workflow Engine automatically sets the specified process as the parent for the process that receives the event, overriding any existing parent setting. See: SetItemParent, Oracle Workflow API Reference.

• Searches for receive event activities that are eligible to accept the event. For an activity to be eligible, the event must match the activity's event filter, and the activity must either be marked as a Start activity or have a status of 'NOTIFIED', meaning the process has transitioned to the event.

Note: If you use the Instance_Default_Rule rule function, an activity must have a status of 'NOTIFIED' to be eligible and must have a business key attribute that matches the event key.

• If an event arrives at a Start activity to launch a new process instance, the Workflow Engine also searches for all other receive event activities that are marked as Start activities and that do not have any incoming transitions, regardless of their event filter. For these activities, the Workflow Engine sets the activity status to 'NOTIFIED' so that they will be ready to receive an event if any more events are sent to this process. This feature lets you design a workflow process that requires multiple events to be received when you do not know in advance the order in which the events will arrive.

• Stores the event name, event key, and event message in item type attributes, as specified in each eligible activity node's event details.

• Marks all the eligible event activity nodes with a status of 'COMPLETED' and continues the thread of execution from each of those nodes.

To send an event to an agent, you must specify either the Out Agent that you want to send the outbound message, or the To Agent that you want to receive the inbound message, or both.

• If you specify both a To Agent and an Out Agent, Oracle Workflow places the event message on the Out Agent's queue for propagation, addressed to the To Agent.

• If you specify a To Agent without an Out Agent, Oracle Workflow selects an outbound agent on the subscribing system whose queue type matches the queue type of the To Agent. The event message is then placed on this outbound agent's queue for propagation, addressed to the To Agent.

• If you specify an Out Agent without a To Agent, Oracle Workflow places the event message on the Out Agent's queue without a specified recipient.

• You can omit the To Agent if the Out Agent uses a multi-consumer queue with a subscriber list. (The standard Workflow queue handlers work only with multi-consumer queues.) In this case the queue's subscriber list determines which consumers can dequeue the message. If no subscriber list is defined for that queue, however, the event message is placed on the WF_ERROR queue for error handling.

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 or Oracle Streams Advanced Queuing User's Guide and Reference.

• You can also omit the To Agent if the Out Agent uses a single-consumer queue for which you have defined a custom queue handler. For a single-consumer queue, no specified consumer is required.

Note: To send an event to an agent, you must either use a standard 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.

Documenting Identifying Information for a Subscription

Each subscription is assigned a customization level that determines whether you can update the subscription definition. Oracle Workflow uses the customization level to protect Oracle Applications seed data and to preserve your customizations in an upgrade. A subscription can have one of the following customization levels:

• Core - No changes can be made to the subscription definition. This level is used only for subscriptions seeded by Oracle Applications.

• Limit - The subscription status can be updated to Enabled or Disabled, but no other changes can be made to the subscription definition. This level is used only for subscriptions seeded by Oracle Applications.

• User - Any property in the subscription definition can be updated. This level is automatically set for subscriptions that you define.

Deferred Subscription Processing

You can defer subscription processing by three different methods:

• Raise the event with a future date in the SEND_DATE attribute. Use this method when you want to defer all subscription processing for a locally raised event until a particular effective date.

• Define subscriptions to the event with phase numbers of 100 or higher. Use this method when you want to defer processing of particular subscriptions for either local or external events.

• Set the dispatch mode of the Event Manager to deferred processing before raising the event. This method can be used to defer all subscription processing for a locally raised event. This method is not recommended, however, and should only be used in exceptional circumstances.

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

You can defer subscription processing for a local event until a particular future effective date by raising the event with that date in the SEND_DATE attribute. For example, you could enter information for a new employee in a human resources application as soon as the employee was hired, but defer payroll processing until the employee's start 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.

See Also

Deferring Subscription Processing Using Subscription 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. Both Local and External subscriptions can be deferred in this way.

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. See: SetDispatchMode, Oracle Workflow API Reference.

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.

See Also

To Find Event Subscriptions

To Update or Delete an Event Subscription

Standard API for an Event Subscription Rule Function

Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide