Previous  Next          Contents  Index  Glossary

Event Subscriptions

An event subscription is a registration indicating that a particular event is significant to a particular system and specifying the processing to perform when the triggering event occurs. You can define your event subscriptions in the Event Manager.

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 raises the Unexpected event and executes any active subscriptions to that event. See: Any Event and Unexpected Event.

Defining the Subscriber

To begin defining a subscription, you specify which system is the subscriber. The subscriber is the system where you want the subscription to execute.

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

You must specify the source type of the events to which the subscription applies. Events can have the following source types:

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.

Next, select the event that you want to trigger the subscription. You can choose either an individual event or an event group. If you choose an event group, the subscription will be triggered whenever any one of the group's member events occurs.

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, you can control the order in which the Event Manager executes those subscriptions by specifying a phase number for each subscription. Subscriptions are executed in ascending phase order. For example, you can enter 1 for the subscription that you want to execute first when an event occurs, 2 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.

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.

Defining the Action for a Subscription

Subscription processing can include the following types of processing:

Running a Rule Function

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 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:

See: Default_Rule.

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

To send the event to a workflow process, 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.

You can specify any additional parameters that you want to set as item attributes for the workflow 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

To send an event to an agent, you specify the To Agent that you want to receive the inbound message. You can also optionally specify the Out Agent that you want to send the outbound message. If you do not specify an Out Agent, Oracle Workflow selects an outbound agent on the subscribing system whose queue type matches the queue type of the To 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.

Documenting Identifying Information for a Subscription

If you use a program to create subscription definitions automatically, the program can set its own name and brief identifier as the owner name and owner tag for the subscriptions. The program can then use this identifying information to locate the subscriptions that it owns. You can use the Edit Subscription page to update the owner name and owner tag manually if necessary.

Error Handling

If a rule function returns a status code of WARNING or ERROR, indicating that a warning condition or an error occurred during subscription processing, the Event Manager places the event message on the standard WF_ERROR queue associated with the WF_ERROR agent. For a WARNING status, the Event Manager then continues subscription processing for the event. For an ERROR status, the Event Manager halts subscription processing for the event and rolls back any subscriptions already executed for the event.

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.

Oracle Workflow provides one predefined subscription to the Any event with the source type Error. This 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 Any event or of the predefined Error subscription to that event. If you do, the Event Manager will not be able to perform 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: Any 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.

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.

See Also

To Define an Event Subscription

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

         Previous  Next          Contents  Index  Glossary