Oracle Workflow Developer's Guide Release 2.6.3.5 Part Number B12161-02 |
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:
Note: Additionally, for events and subscriptions seeded by Oracle Applications products, both the subscription and its triggering event must be owned by products that are licensed with a status of Shared or Installed, in order for the subscription to be executed.
You can use the License Manager AD utility to review which products you currently have licensed. To ensure that the license status of the seeded events and subscriptions in the Business Event System is updated according to the status of the products you currently have licensed, you can run the Synchronize Product License and Workflow BES License concurrent program. See: License Manager, Oracle Applications AD Utilies Reference Guide and Synchronizing License Statuses, Oracle Workflow Administrator's Guide.
If you upgrade from an Oracle Applications release earlier than Release 11.5.9, you should run the Synchronize Product License and Workflow BES License concurrent program once after the upgrade to update the license status of the existing events and subscriptions in your Event Manager. Subsequently, when you license a product, Oracle Workflow automatically updates the license status for all the events and subscriptions owned by that product.
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.
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.
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.
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.
Your Oracle Applications installation may include seeded subscriptions owned by Oracle Applications products that you have not licensed. For such subscriptions, the Update Subscription page displays a notice that the subscription is not licensed. Oracle Workflow will not execute any of these subscriptions. Additionally, Oracle Workflow will not execute any subscriptions to events that you have not licensed, even if the subscriptions themselves are owned by a product that you have licensed.
You can use the License Manager AD utility to review which products you currently have licensed. To ensure that the license status of the seeded events and subscriptions in the Business Event System is updated according to the status of the products you currently have licensed, you can run the Synchronize Product License and Workflow BES License concurrent program. See: License Manager, Oracle Applications AD Utilies Reference Guide and Synchronizing License Statuses, Oracle Workflow Administrator's Guide.
Note: Any subscriptions that you define with a customization level of User are always treated as being licensed.
By sending an event to a workflow process, you can model complex processing or routing logic beyond the standard action options. 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: 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 prior 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.
You can also define additional subscription parameters to be used in one of two ways:
Note: With this option the event is only sent to continue existing processes. If you want to launch a new process instance with the event, do not select this option.
When an event subscription sends an event to a workflow process, the Workflow Engine performs the following processing:
Note: If you chose the Launch when Business Key Matches option, an activity must have a status of 'NOTIFIED' to be eligible and must have a business key attribute that matches the event key.
Note: You can also send an event to a workflow process by choosing the custom action option and including send processing in your custom rule function. See: Standard API for an Event Subscription Rule Function.
Default_Rule2, Oracle Workflow API Reference
Default_Rule3, Oracle Workflow API Reference
Instance_Default_Rule, Oracle Workflow API Reference
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 or Oracle Streams Advanced Queuing User's Guide and Reference.
You can optionally specify the priority with which the recipient should dequeue a message. Messages are dequeued in ascending priority order.
You can also define additional subscription parameters to be used in one of two ways:
Note: You can also send an event to an agent by choosing the custom action option and including send processing in your custom rule function. See: Standard API for an Event Subscription Rule Function.
Default_Rule2, Oracle Workflow API Reference
Default_Rule3, Oracle Workflow API Reference
Sending a Notification
If the only processing you need to perform when an event occurs is sending a notification, you can define a subscription that simply performs that action. In this case you do not need to define and run a complete workflow process to send the notification.
However, you must specify a message template for the notification you want to send. The message template must be a message defined within an item type in the Workflow Builder and stored in your database. You can either select a standard message provided by Oracle Applications or define a custom message.
You must also specify the role that should receive the notification. The notification will appear in the recipient's worklist.
You can optionally specify a custom callback function you want the Notification System to use for communication of SEND and RESPOND source message attributes. Otherwise, Oracle Workflow uses a standard default callback function. See: Custom Callback Function, Oracle Workflow API Reference.
You can also optionally enter context information that you want to pass to the callback function. With the standard Oracle Workflow callback function, the Notification System requires a context to obtain values for item type attributes. If you do not specify a context, do not reference any item type attributes in the message attributes. Otherwise the message body will not display correctly. The context information consists of the item type, item key, and activity ID in the following format: <itemtype>:<itemkey>:<activityid>
If you specify a custom callback function, then you can enter the context information that is appropriate for your function.
You can also optionally enter a comment to include with the message, a due date, and a priority for the message.
After sending the notification, the Event Manager sets the notification ID into the event parameter list as a parameter named #NID. If you want to use the notification ID in further processing, raise the event using WF_EVENT.Raise3(), which returns the event parameter list after the Event Manager completes subscription processing for the event. You can then call WF_EVENT.GetValueForParameter() to obtain the value of the #NID parameter. See: Raise3, Oracle Workflow API Reference and GetValueForParameter, Oracle Workflow API Reference .
For example, if the notification requires a response, you can retrieve the response values from the user's reply by obtaining the notification ID and using it to call WF_NOTIFICATION.GetAttrText(), WF_NOTIFICATION.GetAttrNumber(), or WF_NOTIFICATION.GetAttrDate() for the RESPOND attributes. See: GetAttribute, Oracle Workflow API Reference.
Receiving and Sending Oracle XML Gateway Messages
If you use Oracle XML Gateway, you can define subscriptions either to receive an Oracle XML Gateway message from your trading partner, or to generate an Oracle XML Gateway message and send the message to your trading partner. Oracle Workflow and Oracle XML Gateway provide these actions to support business-to-business (B2B) integration scenarios.
The event that triggers such a subscription must include the trading partner information within its event parameter list. Oracle XML Gateway then uses a standard workflow process defined in the XML Gateway Standard item type to send or receive the message.
You can optionally specify the priority with which the recipient should dequeue a message. Messages are dequeued in ascending priority order.
Running a Custom Rule Function
Custom rule functions must be defined according to a standard PL/SQL or Java 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, 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.
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.
If you want to send the event message to a workflow process or to an agent as part of your custom processing, you can specify the workflow item type, process name, Out Agent, and To Agent in the subscription definition, for your rule function to reference. Note, however, that you must explicitly include the send processing in your rule function.
You can optionally specify the priority with which the the event message should be dequeued if it is placed on an agent, such as a standard agent for deferred subscription processing. Messages are dequeued in ascending priority order.
Oracle Workflow provides standard rule functions that perform subscription processing for the standard subscription actions. You can also use these rule functions in a custom subscription if you choose. Oracle Workflow also provides some standard rule functions that you can use for testing and debugging or other purposes. See: Event Subscription Rule APIs, Oracle Workflow API Reference.
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.
You can run a diagnostic test through Oracle Diagnostics to verify that the rule functions that are defined for event subscriptions exist in the database and are valid. See: Oracle Workflow Diagnostic Tests, Oracle Workflow Administrator's Guide.
You can defer subscription processing by three different methods:
Note: Additionally, if an event is raised by PL/SQL code or received by a PL/SQL agent listener, the Event Manager always defers processing of any Java subscriptions to the event, regardless of their phase numbers.
When subscription processing for an event is deferred by any of these methods, the event message is placed on a standard deferred agent. If the subscription at which processing is deferred is a PL/SQL subscription, the event is placed on the standard WF_DEFERRED agent. If the subscription at which processing is deferred is a Java subscription, the event is placed on the standard WF_JAVA_DEFERRED agent. You must ensure that agent listeners are running to monitor the WF_DEFERRED and WF_JAVA_DEFERRED agents. See: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide.
The listener dequeues event messages from the WF_DEFERRED agent or WF_JAVA_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.
Note: If an event was deferred when the Event Manager encountered a Java subscription during subscription processing in the database, the Event Manager executes all remaining subscriptions to the event when the event is dequeued from the WF_JAVA_DEFERRED queue, including both Java and PL/SQL subscriptions, regardless of the subscription phase numbers. Subscriptions will not be deferred a second time.
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 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 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 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 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 appropriate deferred queue.
Note: Additionally, if an event is raised by PL/SQL code or received by a PL/SQL agent listener, and the Event Manager encounters a Java subscription to the event, it always defers the remaining subscription processing beginning with that subscription, regardless of the subscription 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 or WF_JAVA_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 in PL/SQL code, you can also choose to defer all subscription processing for that event every single time the application raises it. 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.
If the Event Manager encounters a PL/SQL subscription that is deferred, it stops processing and places the event message on the WF_DEFERRED agent. Subscription processing for the event resumes when the Workflow Deferred Agent Listener or another agent listener runs on that agent.
If the Event Manager encounters any Java subscription, or if the event has a Java generate function, the Event Manager stops processing and places the event message on the WF_JAVA_DEFERRED agent, regardless of the subscription phase number. Subscription processing for the event resumes when the Workflow Java Deferred Agent Listener or another agent listener runs on that agent.
If an event is raised locally from Java code, or received on an agent and processed by a Java agent listener, the Event Manager performs subscription processing in the middle tier. It begins processing the subscriptions to the event in phase order, executing Java subscriptions in Java and PL/SQL subscriptions using Java Database Connectivity (JDBC), as long as the subscriptions are not deferred.
If the Event Manager encounters a Java subscription that is deferred, it stops processing and places the event message on the WF_JAVA_DEFERRED agent. Subscription processing for the event resumes when the Workflow Java Deferred Agent Listener or another agent listener runs on that agent.
If the Event Manager encounters a PL/SQL subscription that is deferred, it stops processing and places the event message on the WF_DEFERRED agent. Subscription processing for the event resumes when the Workflow Deferred Agent Listener or another agent listener runs on that agent.
To Create or Update an Event Subscription
Standard API for an Event Subscription Rule Function
Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide.
Previous | Next | Contents | Index | Glossary |