Release 2.6.4
Part Number B15853-01
Contents
Previous
Next
| Oracle Workflow Developer's Guide Release 2.6.4 Part Number B15853-01 | Contents | Previous | Next |
The Oracle Workflow Business Event System is an application service that leverages the Oracle Advanced Queuing (AQ) infrastructure to communicate business events between systems. The Business Event System consists of the Event Manager and workflow process event activities.
The Event Manager contains a registry of business events, systems, named communication agents within those systems, and subscriptions indicating that an event is significant to a particular system. Events can be raised locally or received from an external system or the local system through AQ. When a local event occurs, the subscribing code is executed in the same transaction as the code that raised the event, unless the subscriptions are deferred.
Subscriptions can include the following types of processing:
Executing custom code on the event information
Sending event information to a workflow process
Sending event information to other queues or systems
Business events are represented within workflow processes by event activities. By including event activities in a workflow process, you can model complex processing or routing logic for business events beyond the options of directly running a predefined function or sending the event to a predefined recipient. See: Event Activity.
The uses of the Business Event System include:
System integration messaging hubs - Oracle Workflow with the Business Event System can serve as a messaging hub for complex system integration scenarios. The Event Manager can be used to "hard-wire" routing between systems based on event and originator. Workflow process event activities can be used to model more advanced routing, content-based routing, transformations, error handling, and so on.
Distributed applications messaging - Applications can supply generate and receive event message handlers for their business entities. For example, message handlers can be used to implement master/copy replication for distributed applications.
Message-based system integration - You can set up subscriptions which cause messages to be sent from one system to another when business events occur. In this way, you can use the Event Manager to implement point-to-point messaging integration.
Business event-based workflow processes - You can develop sophisticated workflow processes that include advanced routing or processing based on the content of business events.
Non-invasive customization of packaged applications - Analysts can register interesting business events for their internet or intranet applications. Users of those applications can register subscriptions to those events to trigger custom code or workflow processes.
The Oracle Workflow Event Manager lets you register interesting business events that may occur in your applications, the systems among which events will be communicated, named communication agents within those systems, and subscriptions indicating that an event is significant to a particular system. You can use the Event Manager Web pages to define and maintain these events, systems, agents, and subscriptions.
Note: You must have workflow administrator privileges to access the Event Manager Web pages.
Note: When defining internal names for Business Event System objects in the Event Manager, use only characters from the ASCII character set.
You can use the Workflow XML Loader to upload and download XML definitions for Business Event System objects between a database and a flat file. See: Using the Workflow XML Loader, Oracle Workflow Administrator's Guide.
When an event is raised by a local application or received from a local or external system, the Event Manager executes any subscriptions to that event. Depending on the action defined in the subscription, the Event Manager may call custom code, send the event information to a workflow process, or send the event information to an agent.
After you finish setting up the Business Event System, you can use the Event Manager to raise events manually, sign up systems to receive business events from each other, and synchronize systems with each other. You can test your setup using Workflow Agent Ping/Acknowledge.
Note: For information about the version of the Event Manager available in Oracle Applications, see: Event Manager for Oracle Applications.
You can use the Oracle Workflow Manager component available through Oracle Enterprise Manager to review the statuses of the messages being held on local queues. For more information, please refer to the Oracle Workflow Manager online help.
Related Topics
Workflow Agent Ping/Acknowledge
A business event is an occurrence in an internet or intranet application or program that might be significant to other objects in a system or to external agents. For instance, the creation of a purchase order is an example of a business event in a purchasing application. You can define your significant events in the Event Manager.
Oracle Workflow provides several predefined events for significant occurrences within the Business Event System. See: Predefined Workflow Events
When an event occurs in an application on your local system, an event key must be assigned to uniquely identify that particular instance of the event. Then the event must be raised to the Event Manager.
You can raise an event by any of the following methods:
Raise the event from the application where the event occurs using the WF_EVENT.Raise() API. See: Raise, Oracle Workflow API Reference.
Raise the event from a workflow process using a Raise event activity. See: Event Activity.
Raise the event manually using the Raise Events page. See: Raising Events.
Additionally, the Event Manager can receive events sent from the local system or remote systems.
When you define an event in the Event Manager, you must assign it a unique internal name, which is case-sensitive. The suggested format for these internal names is a compound structure of identifiers separated by periods (.) as follows:
<company>.<family>.<product>.<component>.<object>.<event>
This format allows you to organize the events you define into a classification hierarchy.
You can also define event groups that let you associate any events you want with each other and reference them as a group in event subscriptions. An event group is a type of event composed of a set of individual member events. The internal names of event groups should follow the same format as the names of individual events. Once you have defined an event group, you can register a subscription to the group rather than having to create separate subscriptions for each individual event within it. The subscription will be executed whenever any one of the group's member events occurs.
Note: Event groups cannot be used to raise events. You must raise each event individually.
Any detail information needed to describe what occurred in an event, in addition to the event name and event key, is called the event data. For example, the event data for a purchase order event includes the item numbers, descriptions, and cost. The event data can be structured as an XML document.
The application where the event occurs can include the event data when raising the event to the Event Manager. If the application will not provide the event data, you should specify a generate function for the event that can produce the complete event data from the event name, event key, and an optional parameter list. The generate function must follow a standard API. See: Raise, Oracle Workflow API Reference and Standard API for an Event Data Generate Function.
The Event Manager checks each subscription before executing it to determine whether the subscription requires the event data. If the event data is required but is not already provided, the Event Manager calls the generate function for the event to produce the event data. If the event data is required but no generate function is defined for the event, Oracle Workflow creates a default set of event data using the event name and event key.
Note: If the generate function is costly, and you want to return control to the calling application more quickly after raising the event, you can defer all the subscriptions that require the complete event data. Then the Event Manager will not run the generate function until those subscriptions are executed at a later time. See: Deferred Subscription Processing.
If you use a program to create event definitions automatically, the program can set its own name and brief identifier as the owner name and owner tag for the events. The program can then use this identifying information to locate the events that it owns. You can use the Edit Event and Edit Group pages to update the owner name and owner tag manually if necessary.
Each event is assigned a customization level that determines whether you can update the event definition. Oracle Workflow uses the customization level to protect Oracle seed data and to preserve your customizations in an upgrade. An event can have one of the following customization levels:
Core - No changes can be made to the event definition. This level is used only for events seeded by Oracle.
Limit - The event status can be updated to Enabled or Disabled, but no other changes can be made to the event definition. This level is used only for events seeded by Oracle.
User - Any property in the event definition can be updated. This level is automatically set for events that you define.
See: Access Protection for Business Event System Data, Oracle Workflow Administrator's Guide.
Related Topics
To Define an Event
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.listevents
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Events Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
The Events page appears, displaying a list of existing events. The Events page summarizes the internal name, display name, type, and status of each event.
Choose the Add Event button to open the Edit Event page.
Note: For seeded events with a customization level of Limit, you can only update the event status. For seeded events with a customization level of Core, you cannot update any properties; you can only view the event definition.
Edit Event Page
Enter the internal name of the event in the Name field. All Oracle Workflow APIs, SQL scripts, and PL/SQL procedures refer to the internal name when identifying an event. The internal name is case-sensitive. The suggested format is a compound structure of identifiers separated by periods (.) as follows:
<company>.<family>.<product>.<component>.<object>.<event>
Enter a Display Name for the event. This name appears in the Events list.
Enter an optional description for the event.
In the Status field, select Enabled or Disabled as the event status. If you disable an event, it still remains in the Events list for reference, but you cannot use the event in active subscriptions.
If you are defining an event that occurs on your local system, enter the Generate Function for the event. The generate function is a PL/SQL procedure that can produce the complete event data from the event name, event key, and an optional parameter list. See: Standard API for an Event Data Generate Function.
You can optionally identify the program or application that owns the event by entering the program name in the Owner Name field and the program ID in the Owner Tag field. The Owner Name and Owner Tag are not required if you are defining an event manually in the Edit Event page. However, if you use a program to create event definitions automatically, the Event Manager displays the owner information set by that program in these fields. You can use the Edit Event page to update this information manually if necessary.
You can review the customization level for the event.
Core - No changes can be made to the event definition. This level is used only for events seeded by Oracle.
Limit - The event status can be updated to Enabled or Disabled, but no other changes can be made to the event definition. This level is used only for events seeded by Oracle.
User - Any property in the event definition can be updated. This level is automatically set for events that you define.
Choose the Submit button to save the event and return to the Events page. The Events page displays an updated list of events.
You can also choose the Cancel button to return to the Events page without saving the event.
To Define an Event Group
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.listevents
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Events Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
The Events page appears, displaying a list of existing events. Choose the Add Group button to open the Edit Group page.
Note: For seeded event groups with a customization level of Limit, you can only update the event group status. For seeded events with a customization level of Core, you cannot update any properties; you can only view the event group definition.
Edit Group Page
Enter the internal name of the event group in the Name field. All Oracle Workflow APIs, SQL scripts, and PL/SQL procedures refer to the internal name when identifying an event group. The internal name is case-sensitive and should have a compound structure of identifiers separated by periods (.) in the following format:
<company>.<family>.<product>.<component>.<object>.<event>
Enter a Display Name for the event group. This name appears in the Events list.
Enter an optional description for the event group.
In the Status field, select Enabled or Disabled as the event group status. If you disable an event group, it still remains in the Events list for reference, but you cannot use the event group in active subscriptions.
You can optionally identify the program or application that owns the event group by entering the program name in the Owner Name field and the program ID in the Owner Tag field. The Owner Name and Owner Tag are not required if you are defining an event group manually in the Edit Group page. However, if you use a program to create event group definitions automatically, the Event Manager displays the owner information set by that program in these fields. You can use the Edit Group page to update this information manually if necessary.
You can review the customization level for the event group.
Core - No changes can be made to the event group definition. This level is used only for event groups seeded by Oracle.
Limit - The event group status can be updated to Enabled or Disabled, but no other changes can be made to the event group definition. This level is used only for event groups seeded by Oracle.
User - Any property in the event group definition can be updated. This level is automatically set for event groups that you define.
Choose the Submit button to save the event group.
Note: You can also choose the Cancel button to return to the Events page without saving the event group.
After you save the event group definition, the Edit Group page displays the list of member events for that group, including the name, display name, and status of each event.
To add a member event to the group, choose the Add Event button.
Note: An event group can contain only individual events as its members. It cannot contain another group.
Add to Group Page
In the Add to Group page that appears, enter search criteria to locate the event you want to add. The search criteria are:
Name - enter the internal name of the event you want to add.
Display Name - enter the display name of the event you want to add.
Status - choose Enabled or Disabled as the status of the event you want to add. Choose Any to search for events of any status.
Choose the Go button. The Add to Group page displays a list of events that match your search criteria.
Select the event or events that you want to add to your event group. You can choose the Select All button to select all the events in the list, or choose the Deselect All button to deselect all the events in the list.
If you want to search for different events, enter new search criteria and choose the Go button. The Add to Group page displays the list of events that match your new search criteria.
You can also choose the Cancel button to cancel your current search and return to your previous search results.
When you have finished selecting the events you want to add, choose the Add button to add the selected events to your event group. The Edit Group page appears, displaying the updated list of event group members.
Choose the Submit button to save the event group definition.
Note: You can also choose the Cancel button to return to the Add to Group page with your latest search results.
If you want to remove a member event from the group, select the event or events you want to delete in the Edit Group page. Choose Select All to select all the events in the list, or choose Deselect All to deselect all the events in the list.
Choose the Delete button to remove the selected events from your event group. The Edit Group page displays the updated list of event group members.
Note: Removing an individual member event from an event group does not delete the event definition for the individual event. The individual event remains in the Events list.
To view the subscriptions that reference an event, choose the schedule icon in the Subs column for that event. The Event Subscriptions page appears, displaying the list of subscriptions to the event.
Note: For events that do not have any subscriptions yet, a blank schedule icon appears. For events that do have subscriptions referencing them, a full schedule icon appears.
You can begin defining a new subscription to the event by choosing the Add Subscription button in the Event Subscriptions page. The Edit Subscription page appears with the event name automatically entered in the Event Filter field. See Defining Event Subscriptions.
To update an event, choose the pencil icon in the Edit column for that event. The Edit Event page appears. Make your changes to the event definition and save your work. See: To Define an Event.
To Find Events
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.findevent
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Find Event/Group Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
Find Event/Group Page
The Find Event/Group page appears. The Find Event/Group page lets you enter search criteria to locate specific events. The search criteria are:
Name - enter the internal name of the event you want to display.
Display Name - enter the display name of the event you want to display.
Status - choose Enabled or Disabled as the status of the events you want to display, or choose Any to display events of any status.
Type - choose Event or Group as the type of the events you want to display, or choose Any to display events of any type.
Choose the Go button. The Events page appears, displaying a list of events that match your search criteria.
To Update or Delete an Event
Locate the event you want in the Events page. You can use the Find Event/Group page to find the event that you want and display the event in the Events page. See: To Find Events.
To view the subscriptions that reference an event, choose the schedule icon in the Subs column for that event. The Event Subscriptions page appears, displaying the list of subscriptions to the event.
Note: For events that do not have any subscriptions yet, a blank schedule icon appears. For events that do have subscriptions referencing them, a full schedule icon appears.
You can begin defining a new subscription on the event by choosing the Add Subscription button in the Event Subscriptions page. The Edit Subscription page appears with the event name automatically entered in the Event Filter field. See Defining Event Subscriptions.
To update an event, choose the pencil icon in the Edit column for that event. The Edit Event page appears. Make your changes to the event definition and save your work. See: To Define an Event.
Note: For seeded events with a customization level of Limit, you can only update the event status. For seeded events with a customization level of Core, you cannot update any properties; you can only view the event definition.
To delete an event, choose the trash icon in the Delete column for that event, and choose OK in the confirmation window that appears. You can also choose Cancel in the confirmation window to return to the Events page without deleting the event.
Note: You can only delete events that do not have any subscriptions referencing them and that do not belong to any event groups.
Additionally, you cannot delete any event seeded by Oracle that has a customization level of Core or Limit.
A system is a logically isolated software environment such as a host machine or database instance. You should define each system to or from which you will communicate events in the Event Manager.
When you define a system, you can specify whether it is associated with a master system from which you want it to receive Event Manager object definition updates.
Each system can expose one or more addressable points of communication, called agents. After you define your systems, you should define the agents within those systems that you will use to communicate business events. See: Agents.
When you install Oracle Workflow in a database, that database is automatically defined as a system in the Event Manager and set as the local system in the Global Workflow Preferences page. The following table lists the default properties of the local system definition.
| System Property | Value |
|---|---|
| Name | <database global name> |
| Display Name | <database global name> |
| Description | Local System Created by Oracle Workflow Configuration Assistant |
| Master | (blank) |
You can update the local system definition if necessary.
Oracle Workflow sets the status of the local system to Enabled by default. After you finish setting up the Business Event System, you can use the Global Workflow Preferences page to set the system status that you want for event processing. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Related Topics
To Define a System
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.listsystems
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Systems Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
Systems Page
The Systems page appears, displaying a list of existing systems. The Systems page summarizes the internal name, display name, and master system of each system. An asterisk marks the local system.
Choose the Add System button to open the Edit System page.
Edit System Page
Enter the internal name of the system in the Name field. All Oracle Workflow APIs, SQL scripts, and PL/SQL procedures refer to the internal name when identifying a system.
Attention: The internal name must be all-uppercase and should not include any single or double quotation marks (' or ") or spaces.
Enter a Display Name for the system. This name appears in the Systems list.
Enter an optional description for the system.
Optionally enter a Master system from which you want this system to receive Event Manager object definition updates. Click on the Master field's up arrow icon to display a list of systems from which to choose. See: Using a List of Values.
Choose the Submit button to save the system and return to the Systems page. The Systems page displays an updated list of systems.
You can also choose the Cancel button to return to the Systems page without saving the system.
To Find Systems
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.findsystem
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Find System Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
Find System Page
The Find System page appears. The Find System page lets you enter search criteria to locate specific systems. The search criteria are:
Name - enter the internal name of the system you want to display.
Display Name - enter the display name of the system you want to display.
Master - enter the master system for the system you want to display. Click on the field's up arrow icon to display a list of systems from which to choose. See: Using a List of Values.
Choose the Find button. The Systems page appears, displaying a list of systems that match your search criteria. An asterisk marks the local system.
To Update or Delete a System
Locate the system you want in the Systems page. You can use the Find System page to find the system that you want and display the system in the Systems page. See: To Find Systems.
Systems Page
To view the subscriptions for a system, choose the schedule icon in the Subs column for that system. The Event Subscriptions page appears, displaying the list of subscriptions by the system.
Note: For systems that do not have any subscriptions yet, a blank schedule icon appears. For systems that do have subscriptions, a full schedule icon appears.
You can begin defining a new subscription for the system by choosing the Add Subscription button in the Event Subscriptions page. The Edit Subscription page appears with the system name automatically entered in the System field. See Defining Event Subscriptions.
To update a system, choose the pencil icon in the Edit column for that system. The Edit System page appears. Make your changes to the system definition and save your work. See: To Define a System.
To delete a system, choose the trash icon in the Delete column for that system, and choose OK in the confirmation window that appears. You can also choose Cancel in the confirmation window to return to the Systems page without deleting the system.
Note: You can only delete systems that do not have any agents defined on them or any subscriptions referencing them.
Using a List of Values
For a field that supports a list of values, click on the field's up-arrow icon to display a list of values window.
In the Find field, enter search criteria and choose the Find button to retrieve a subset of values that match your criteria. You can also choose the Clear button to clear the Find field. If you do not specify any search criteria and simply choose Find, you retrieve the complete list of values.
Click on a value from the list to select that value and close the list of values window. The value you select populates the original field.
An agent is a named point of communication within a system. Communication within and between systems is accomplished by sending a message from one agent to another. A single system can have several different agents representing different communication alternatives. For example, a system may have different agents to support inbound and outbound communication, communication by different protocols, different propagation frequencies, or other alternatives.
You should define each agent that you will use to communicate events in the Event Manager. Each agent's name must be unique within its system. The agent can be referenced in code within Oracle Workflow by a compound name in the following format:
<agent_name>@<system_name>
For example, the agent WF_IN within the system HUB could be referenced as WF_IN@HUB.
After defining the agents on your local system, you should set them up for event message propagation by scheduling listeners for local inbound agents and propagation for local outbound agents. See: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide and Scheduling Propagation for Local Outbound Agents, Oracle Workflow Administrator's Guide.
When you define an agent in the Event Manager, you must specify the direction of communication that the agent supports on its local system.
In - Inbound communication to the system. The agent receives messages in a specific protocol and presents them to the system in a standard format.
Out - Outbound communication from the system. The agent accepts messages from the system in a standard format and sends them using the specified protocol.
You must associate each agent with the protocol by which it communicates messages. The protocol specifies how the messages are encoded and transmitted. For a message to be successfully communicated, the sending and receiving agents must use the same protocol.
A protocol can represent a network standard, such as SQLNET. It can also represent a business-to-business standard that defines the higher-level message format and handshaking agreements between systems in addition to the network standard.
The Business Event System interacts with an agent through an AQ queue. You can use AQ to perform the propagation of messages by the SQLNET protocol which it supports. In Oracle9i Database and higher, AQ also includes Internet access functionality that lets you perform AQ operations over the Internet by using AQ's Internet Data Access Presentation (IDAP) for messages and transmitting the messages over the Internet using transport protocols such as HTTP or HTTPS. Additionally, the Messaging Gateway feature of AQ in Oracle9i Database and higher enables communication between applications based on non-Oracle messaging systems and AQ, letting you integrate with third party messaging solutions. You can also implement other services to propagate messages by different protocols.
To implement a custom protocol, you must perform the following steps:
Define AQ queues to hold pending inbound and outbound messages.
Provide code that propagates messages to and from the AQ queues.
Define a lookup code for the new protocol in the Event Protocol Type (WF_AQ_PROTOCOLS) lookup type, which is stored in the Standard item type. The Event Manager uses the Event Protocol Type lookup type to validate the protocol for an agent. See: To Create Lookup Codes for a Lookup Type.
Define agents with the new protocol. See: To Define an Agent.
If an agent supports inbound communication, you must specify the address by which systems can communicate with it. The format of the address depends on the agent's protocol. For agents that use the SQLNET protocol, the address must be in the following format to enable AQ propagation:
<schema>.<queue>@<database link>
In this format, <schema> represents the schema that owns the queue, <queue> represents the queue name, and <database link> represents the name of the database link to the instance where the queue is located.
Note: You must enter the database link name exactly as the name was specified when the database link was created. For example, if a database link is named ORA10.US.ORACLE.COM, you must enter that complete name in the address of an agent on that database. You cannot abbreviate the name to ORA10.
The names of the database links that you want to use for the Business Event System should be fully qualified with the domain names. To confirm the names of your database links, use the following syntax:
SELECT db_link FROM all_db_links
See: Creating Database Links, Oracle Workflow Administrator's Guide.
You must associate each agent on a Workflow-enabled system with an AQ queue. The local system uses this queue to interact with the agent. To send messages, the system enqueues the messages on the queue and sets the recipient addresses. To receive messages, the system runs a queue listener on the queue. See: Setting Up Queues, Oracle Workflow Administrator's Guide.
Event messages within the Oracle Workflow Business Event System are encoded in a standard format defined by the datatype WF_EVENT_T. You must assign each agent a PL/SQL package called a queue handler that translates between this standard Workflow format and the format required by the agent's queue. See: Event Message Structure, Oracle Workflow API Reference.
Note: Even if the agent's queue uses WF_EVENT_T as its payload type, a queue handler is still required in order to set native AQ message properties.
Oracle Workflow provides two standard queue handlers, called WF_EVENT_QH and WF_ERROR_QH, for queues that use SQLNET propagation and use the WF_EVENT_T datatype as their payload type. You can use WF_EVENT_QH with queues that handle normal Business Event System processing, while WF_ERROR_QH should be used exclusively with error queues.
Oracle Workflow also provides a standard queue handler called WF_EVENT_OJMSTEXT_QH for queues that use the SYS.AQ$_JMS_TEXT_MESSAGE datatype as their payload type. This queue handler enables communication of JMS Text messages through the Business Event System. See: Mapping Between WF_EVENT_T and SYS.AQ$_JMS_TEXT_MESSAGE, Oracle Workflow API Reference.
If you want to use queues that require a different format, create a custom queue handler for that format. Your custom queue handler must include a set of standard APIs to enqueue and dequeue messages in the custom format. See: Standard APIs for a Queue Handler.
When you install Oracle Workflow, several standard agents are automatically defined for the Business Event System.
WF_CONTROL - Oracle Workflow internal agent, not for customer use
WF_DEFERRED - Standard agent for deferred subscription processing
WF_ERROR - Standard agent for error handling
WF_IN - Default inbound agent
WF_JMS_IN - Default inbound agent for JMS Text messages
WF_JMS_OUT - Default outbound agent for JMS Text messages
WF_NOTIFICATION_IN - Standard inbound agent for e-mail notification responses
WF_NOTIFICATION_OUT - Standard outbound agent for e-mail notifications
WF_OUT - Default outbound agent
These agents use standard queues that are automatically defined when you install Oracle Workflow. See: Setting Up Queues, Oracle Workflow Administrator's Guide.
You can enable or disable the WF_IN, WF_JMS_IN, WF_OUT, and WF_JMS_OUT agents, but you must not make any other changes to their definitions. You must not make any changes to the definitions of the other agents.
Oracle Workflow automatically runs agent listener service components for the standard WF_DEFERRED, WF_ERROR, and WF_NOTIFICATION_IN agents in order to perform deferred subscription processing, error handling for the Business Event System, and inbound e-mail processing for notification mailers, respectively. If you want to use the WF_IN, WF_JMS_IN, WF_OUT, and WF_JMS_OUT agents for event message propagation, schedule listeners for WF_IN and WF_JMS_IN and propagation for WF_OUT and WF_JMS_OUT as well. You do not need to schedule propagation for the WF_CONTROL and WF_NOTIFICATION_OUT agents, however, because the middle tier processes that use WF_CONTROL dequeue messages directly from its queue, and notification mailers send messages placed on the WF_NOTIFICATION_OUT queue. See: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide and Scheduling Propagation for Local Outbound Agents, Oracle Workflow Administrator's Guide.
Note: Oracle Workflow includes three additional agents named WF_REPLAY_IN, WF_REPLAY_OUT, and WF_SMTP_O_1_QUEUE, which are not currently used. Oracle Workflow also includes agents named WF_JAVA_DEFERRED, WF_JAVA_ERROR, WF_WS_JMS_IN, and WF_WS_JMS_OUT, which are currently used only in Oracle Applications.
The following table lists the default properties for the standard WF_CONTROL agent. See: Cleaning Up the Workflow Control Queue, Oracle Workflow Administrator's Guide.
| Agent Property | Value |
|---|---|
| Name | WF_CONTROL |
| Display Name | Workflow Control Out Queue |
| Description | Workflow JMS Text Message Queue used to signal messages to middle tier processes |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_CONTROL@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_CONTROL |
| Direction | Out |
| Status | Enabled |
The following table lists the default properties for the standard WF_DEFERRED agent.
| Agent Property | Value |
|---|---|
| Name | WF_DEFERRED |
| Display Name | WF_DEFERRED |
| Description | WF_DEFERRED |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_DEFERRED@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_QH |
| Queue Name | <workflow schema>.WF_DEFERRED |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_ERROR agent.
| Agent Property | Value |
|---|---|
| Name | WF_ERROR |
| Display Name | WF_ERROR |
| Description | WF_ERROR |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_ERROR@<local database> |
| System | <local system> |
| Queue Handler | WF_ERROR_QH |
| Queue Name | <workflow schema>.WF_ERROR |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_IN agent.
| Agent Property | Value |
|---|---|
| Name | WF_IN |
| Display Name | WF_IN |
| Description | WF_IN |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_IN@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_QH |
| Queue Name | <workflow schema>.WF_IN |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_JMS_IN agent.
| Agent Property | Value |
|---|---|
| Name | WF_JMS_IN |
| Display Name | Workflow JMS In Queue |
| Description | Workflow JMS Text Message Queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_JMS_IN@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_JMS_IN |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_JMS_OUT agent.
| Agent Property | Value |
|---|---|
| Name | WF_JMS_OUT |
| Display Name | Workflow JMS Out Queue |
| Description | Workflow JMS Text Message Queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_JMS_OUT@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_JMS_OUT |
| Direction | Out |
| Status | Enabled |
The following table lists the default properties for the standard WF_NOTIFICATION_IN agent. See: Implementing Notification Mailers, Oracle Workflow Administrator's Guide.
| Agent Property | Value |
|---|---|
| Name | WF_NOTIFICATION_IN |
| Display Name | Workflow Notification In Queue |
| Description | Workflow inbound notification response queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_NOTIFICATION_IN@ <local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_NOTIFICATION_IN |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_NOTIFICATION_OUT agent. See: Implementing Notification Mailers, Oracle Workflow Administrator's Guide.
| Agent Property | Value |
|---|---|
| Name | WF_NOTIFICATION_OUT |
| Display Name | Workflow Notification Out Queue |
| Description | Workflow notification outbound queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_NOTIFICATION_OUT@ <local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_NOTIFICATION_OUT |
| Direction | Out |
| Status | Enabled |
The following table lists the default properties for the standard WF_OUT agent.
| Agent Property | Value |
|---|---|
| Name | WF_OUT |
| Display Name | WF_OUT |
| Description | WF_OUT |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_OUT@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_QH |
| Queue Name | <workflow schema>.WF_OUT |
| Direction | Out |
| Status | Enabled |
Related Topics
To Define an Agent
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.listagents
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Agents Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
Agents Page
The Agents page appears, displaying a list of existing agents grouped by the system where they are located. The Agents page summarizes the internal name, address, protocol, direction, and status of each agent.
Choose the Add Agent button to open the Edit Agent page.
Enter the internal name of the agent in the Name field. The agent's internal name must be unique within the agent's system. Oracle Workflow APIs, SQL scripts, and PL/SQL procedures may refer to the internal name when identifying an agent.
Attention: The internal name must be all-uppercase and should not include any single or double quotation marks (' or ") or spaces.
Enter a Display Name for the agent.
Enter an optional description for the agent.
Select the message communication protocol that the agent supports.
If the agent supports inbound communication to its system, enter the address for the agent. The format of the address depends on the protocol you select.
For agents that use the SQLNET protocol, the address must be in the following format to enable AQ propagation:
<schema>.<queue>@<database link>
<schema> represents the schema that owns the queue, <queue> represents the queue name, and <database link> represents the database link to the instance where the queue is located.
Note: You must enter the database link name exactly as the name was specified when the database link was created. See: Creating Database Links, Oracle Workflow Administrator's Guide.
Enter the system in which the agent is defined. Click on the System field's up arrow icon to display a list of systems from which to choose. See: Using a List of Values.
Enter the Queue Handler for the agent. The queue handler is the PL/SQL package that translates between the Workflow event message format (WF_EVENT_T) and the message format required by the queue associated with the agent. See: Standard APIs for a Queue Handler.
Attention: You must enter the queue handler name in all uppercase.
Enter the name of the queue that the local system uses to interact with the agent. Since only the local system refers to this queue name, the queue name should be within the scope of this system, without requiring a database link. Use the following format to specify the queue name:
<schema>.<queue>
<schema> represents the schema that owns the queue, and <queue> represents the queue name.
Attention: You must enter the queue name in all uppercase.
In the Direction field, select In for an agent that supports inbound communication to its system, or select Out for an agent that supports outbound communication from its system.
In the Status field, select Enabled or Disabled as the agent status. If you disable an agent, it still remains in the Agents list for reference, but you cannot use the agent in active subscriptions.
Choose the Submit button to save the agent and return to the Agents page. The Agents page displays an updated list of agents.
You can also choose the Cancel button to return to the Agents page without saving the agent.
To Find Agents
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.findagent
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Find Agent Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
Find Agent Page
The Find Agent page appears. The Find Agent page lets you enter search criteria to locate specific agents. The search criteria are:
Name - enter the internal name of the agent you want to display.
Protocol - choose the protocol of the agent you want to display, or choose Any to display agents of any protocol.
Address - enter the address of the agent you want to display.
System - enter the system of the agent you want to display. Click on the field's up arrow icon to display a list of systems from which to choose. See: Using a List of Values.
Direction - choose In or Out as the direction of the agents you want to display, or choose Any to display agents of any direction.
Status - choose Enabled or Disabled as the status of the agents you want to display, or choose Any to display agents of any status.
Choose the Find button. The Agents page appears, displaying a list of agents that match your search criteria.
To Update or Delete an Agent
Locate the agent that you want in the Agents page. You can use the Find Agent page to find the agent that you want and display the agent in the Agents page. See: To Find Agents.
Agents Page
To update an agent, choose the pencil icon in the Edit column for that agent. The Edit Agent page appears. Make your changes to the agent definition and save your work. See: To Define an Agent.
To delete an agent, choose the trash icon in the Delete column for that agent, and choose OK in the confirmation window that appears. You can also choose Cancel in the confirmation window to return to the Agents page without deleting the agent.
Note: You can only delete agents that do not have any subscriptions referencing them.
Note: Whenever you make changes to your agents that affect the physical implementation required for message propagation, you should recheck your propagation setup. See: Setting Up the Business Event System, Oracle Workflow Administrator's Guide.
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 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.
If no eligible subscriptions exist for the event that occurred (apart from subscriptions to the Any event), then Oracle Workflow executes any enabled subscriptions by the local system to the Unexpected event with the appropriate source type. See: Any Event and Unexpected Event.
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.
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.
You must specify the source type of the events to which the subscription applies. Events can have the following source types:
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 only to errored events dequeued from the WF_ERROR queue.
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.
The phase number for a subscription controls 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. Subscriptions with a phase number from 1 to 99 are executed immediately, unless processing for the event is deferred by another method. See: Deferred Subscription Processing.
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.
Subscription processing can include the following types of processing:
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
See: Default_Rule, Oracle Workflow API Reference.
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.
See: Event Subscription Rule APIs, 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.
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, then to be eligible an activity must have an event filter that matches the event, a status of 'NOTIFIED' , and 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.
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 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.
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.
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.
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.
User - Any property in the subscription definition can be updated. This level is automatically set for subscriptions that you define.
See: Access Protection for Business Event System Data, Oracle Workflow Administrator's Guide.
If you do not want subscriptions for an event to be executed immediately when the event occurs, you can defer the subscriptions. In this way you can return control more quickly to the calling application and let the Event Manager execute any costly subscription processing at a later time.
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.
When subscription processing for an event is deferred by any of these methods, the event message is placed on the standard WF_DEFERRED queue associated with the WF_DEFERRED agent. You must ensure a listener is running to monitor the WF_DEFERRED agent. See: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide.
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.
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: Raise, Oracle Workflow API Reference.
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.
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.
Related Topics
To Define an Event Subscription
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
To Define an Event Subscription
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.listsubscriptions
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Event Subscriptions Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
Event Subscriptions Page
The Event Subscriptions page appears, displaying a list of existing subscriptions grouped by the subscribing system and triggering event. The Event Subscriptions page summarizes the source type, out agent, to agent, function, workflow, and status of each subscription.
Choose the Add Subscription button to open the Edit Subscription page.
Note: For seeded subscriptions with a customization level of Limit, you can only update the subscription status. For seeded subscriptions with a customization level of Core, you cannot update any properties; you can only view the subscription definition.
In the Subscriber region, enter the system where the subscription executes. Click on the System field's up arrow icon to display a list of systems from which to choose. See: Using a List of Values.
In the Triggering Condition region, specify the type of source system to which the subscription applies in the Source Type field.
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.
Enter the event to which the subscription applies in the Event Filter field. You can specify an individual event or an event group. Click on the Event Filter field's up arrow icon to display a list of events from which to choose. See: Using a List of Values.
Enter an optional Source Agent to which the subscription applies. If you specify a source agent, then the subscription is executed only when the triggering event is received from that agent. Click on the Source Agent field's up arrow icon to display a list of agents from which to choose. See: Using a List of Values.
Note: In most cases, the Source Agent field is left blank.
In the Execution Control region, enter a phase number for the subscription to specify the order in which subscriptions that apply to the same event are executed. The phase number also controls whether a subscription is executed immediately or is deferred, unless processing for the event is deferred by another method.
Note: 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.
Select Enabled or Disabled as the subscription status. If you disable a subscription, it still remains in the Event Subscriptions list for reference, but it can no longer be actively used to respond to events.
In the Rule Data field, specify the event information required by the subscription.
Key - The subscription requires only the event key.
Message - The subscription requires the complete event data.
In the Action region, define the subscription processing you want to perform when the triggering event occurs. Subscription processing can include:
Running a function on the event message.
Sending the event message to a workflow process.
Sending the event message to an agent.
If you want to run a function on the event message, enter the Rule Function to run. The rule function must be defined according to a standard API. See: Standard API for an Event Subscription Rule Function.
If you do not specify a rule function, Oracle Workflow runs a default rule function to send the event message to the workflow process and the agent that you specify.
Note: If you enter a rule function other than the default, Oracle Workflow does not automatically send the event message to the specified workflow and agent. You must explicitly include the send processing in your custom rule function instead. You can still enter workflow and agent information in the Action region for your function to reference, however.
If you want to send the event message to a workflow process, enter the item type that the process belongs to in the Workflow Item Type field and the name of the process in the Workflow Process Name field. Click on each field's up arrow icon to display a list of values from which to choose. See: Using a List of Values.
Note: The list of values for the Workflow Process Name field includes only the runnable processes within the item type you specify.
If you want to send the event message to an agent, enter 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. Click on each field's up arrow icon to display a list of values from which to choose. See: Using a List of Values.
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. The Out Agent must use either a multi-consumer queue with a subscriber list or a single-consumer queue.
Note: The Out Agent must be located on the subscribing system. The list of values for the Out Agent field includes only agents with a direction of Out.
The list of values for the To Agent field includes only agents with a direction of In.
If you want to send the event message to an agent, select Normal, High, or Low as the priority with which the recipient should dequeue the message.
Optionally enter any additional parameters for the rule function in the Parameters field. Use spaces to separate the parameters, and specify the name and value for each parameter in the following format:
<name1>=<value1> <name2>=<value2> ... <nameN>=<valueN>
Note: If you send the event message to a workflow process and you want to specify additional parameters to set as item attributes for the process, you can enter these parameters in the Parameters field for 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.
In the Documentation region, you can optionally identify the program or application that owns the subscription by entering the program name in the Owner Name field and the program ID in the Owner Tag field. The Owner Name and Owner Tag are not required if you are defining a subscription manually in the Edit Subscription page. However, if you use a program to create subscription definitions automatically, the Event Manager displays the owner information set by that program in these fields. You can use the Edit Subscription page to update this information manually if necessary.
You can review the customization level for the subscription.
Core - No changes can be made to the subscription definition. This level is used only for subscriptions seeded by Oracle.
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.
User - Any property in the subscription definition can be updated. This level is automatically set for subscriptions that you define.
Enter an optional description for the subscription.
Choose the Submit button to save the subscription and return to the Event Subscriptions page. The Event Subscriptions page displays an updated list of subscriptions.
You can also choose the Cancel button to return to the Event Subscriptions page without saving the subscription.
To Find Event Subscriptions
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.findsubscription
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Find Subscription Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
Find Subscription Page
The Find Subscription page appears. The Find Subscription page lets you enter search criteria to locate specific event subscriptions. The search criteria are:
System - select the system for which you want to display subscriptions. Click on the field's up arrow icon to display a list of systems from which to choose. See: Using a List of Values.
Source Type - choose Local, External, or Error as the type of source system for which you want to display subscriptions, or choose Any to display subscriptions for any type of source system.
Event - select the event for which you want to display subscriptions. Click on the field's up arrow icon to display a list of events from which to choose. See: Using a List of Values.
Status - choose Enabled or Disabled as the status of the subscriptions you want to display, or choose Any to display subscriptions of any status.
Choose the Find button. The Event Subscriptions page appears, displaying a list of subscriptions that match your search criteria.
If your search criteria included a system or an event, you can choose the Add Subscription button to open the Edit Subscription page with the system and event information you specified automatically entered in the System and Event Filter fields, respectively. You can begin defining a new subscription in this way even if your search did not find any existing subscriptions matching your criteria.
To Update or Delete an Event Subscription
Locate the subscription you want in the Event Subscriptions page. You can use the Find Subscription page to find the subscription that you want and display the subscription in the Event Subscriptions page. See: To Find Event Subscriptions.
Event Subscriptions Page
To update a subscription, choose the pencil icon in the Edit column for that subscription. The Edit Subscription page appears. Make your changes to the subscription definition and save your work. See: To Define an Event Subscription.
Note: For seeded subscriptions with a customization level of Limit, you can only update the subscription status. For seeded subscriptions with a customization level of Core, you cannot update any properties; you can only view the subscription definition.
To delete a subscription, choose the trash icon in the Delete column for that subscription, and choose OK in the confirmation window that appears. You can also choose Cancel in the confirmation window to return to the Event Subscriptions page without deleting the subscription.
Note: You cannot delete any subscription seeded by Oracle that has a customization level of Core or Limit.
In addition to raising events from your applications or through workflows, you can raise events that do not require additional parameters manually using the Raise Event Web page for testing purposes. When you raise an event, the Event Manager searches for and executes any enabled subscriptions by the local system to that event with a source type of Local, and also any enabled subscriptions by the local system to the Any event with a source type of Local.
To Raise an Event
Use a Web browser to connect to the following URL:
<webagent>/wf_event_html.entereventdetails
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
Note: You can also access the Raise Event Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
The Raise Event page appears.
In the Event Name field, select the event that you want to raise.
Enter an event key that uniquely identifies this instance of the event.
Optionally enter event data to describe what occurred in the event.
Note: The maximum length of the data you can enter in the Event Data field is 32 kilobytes. If the event data exceeds 32 Kb, you should assign a generate function in the event definition to generate the event data, rather than entering the data directly in the Event Data field. See: To Define an Event.
You can also choose to raise the event using the WF_EVENT.Raise API instead. This method lets you provide the event data as a CLOB storing up to four gigabytes of data. See: Raise, Oracle Workflow API Reference.
Choose the Submit button to raise the event to the Event Manager. You can also choose the Cancel button to return to the Oracle Workflow home page without raising the event.
If you choose the Submit button, Oracle Workflow raises the event and displays a confirmation message with the event name and event key. Choose the OK button to return to the Raise Event page.
Before you can send business events from one system to another, you must sign up the destination system with the source system as a potential recipient of event messages. Signing up a system means defining the destination system as well as its inbound agents in the Event Manager of the source system, so that event messages from the source system can be addressed to the destination agents.
Usually, both systems should be signed up with each other, so that each system can both send messages to and receive messages from the other system.
To sign up a destination system for receiving event messages from a source system, perform the following steps:
Retrieve the local system and inbound agent definitions, which together make up the system identifier information, from the destination system. You can use the System Identifier Web page on the destination system to generate an XML document containing the system identifier information. See: To Retrieve System Identifier Information.
Note: If you do not have access to the Oracle Workflow installation on the destination system, ask the workflow administrator for that system to perform this step.
Add the destination system identifier information to the Event Manager in the source system. You can use the System Signup Web page on the source system to add the information by raising the System Signup event with the XML document from the destination system as the event data. When the System Signup event is raised on the source system, Oracle Workflow executes a predefined subscription that adds the system identifier information to the Event Manger in that system. See: To Sign Up a System.
Note: If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.
To Retrieve System Identifier Information
Use a Web browser to connect to the following URL on the system you want to sign up as a destination system:
<webagent>/wf_event_html.getsystemidentifier
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as a valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
If you do not have access to the Oracle Workflow installation on the destination system, ask the workflow administrator for that system to perform this step.
Note: You can also access the System Identifier Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
Oracle Workflow produces the system identifier XML document, which contains the definitions of the local system and its inbound agents. Save this document as a text file. You can then copy the document and enter it as the event data for the System Signup event when you sign this system up with a source system. See: To Sign Up a System.
To Sign Up a System
Use a Web browser to connect to the following URL on the source system where you want to sign up a destination system:
<webagent>/wf_event_html.entereventdetails?p_event_name=
oracle.apps.wf.event.system.signup
Replace <webagent> with the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Attention: This URL accesses a secured page, so if you have not yet logged on as valid user in the current Web session, you will be prompted to do so before the page appears. You must have workflow administrator privileges to access the Event Manager Web pages.
If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.
Note: You can also access the System Signup Web page from the Oracle Workflow home page. See: Accessing the Oracle Workflow Home Page, Oracle Workflow Administrator's Guide.
The System Signup page appears, displaying the internal name of the System Signup event.
Enter an event key that uniquely identifies this instance of the event.
Copy the XML document containing the destination system identifier information into the Event Data field. See: To Retrieve System Identifier Information.
Choose the Submit button to raise the System Signup event to the Event Manager. A confirmation message is displayed. When the System Signup event is raised, Oracle Workflow executes a predefined subscription that adds the system identifier information from the event data to the Event Manager. See: System Signup Event.
You can also choose the Cancel button to return to the Oracle Workflow home page without raising the System Signup event.
Synchronizing systems means replicating all the Event Manager objects that are defined on the source system to the target system. You can use the Synchronize Event Systems event to synchronize systems with each other.
To Synchronize Systems
Sign up the source and target systems with each other. See: Signing Up Systems.
On the source system, copy the predefined subscription to the Seed Event Group with the Local source type and modify the copy as follows.
Specify the inbound agent on the target system that you want to receive the event message, or specify a workflow process that sends the event message to the target system.
Note: If you want to send the event message to more than one target system, you can either define additional subscriptions or specify a workflow process that sends the event message to multiple systems.
Enable the subscription.
Note: If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.
On the target system, enable the predefined subscription to the Seed Event Group with the External source type.
Note: If you do not have access to the Oracle Workflow installation on the target system, ask the workflow administrator for that system to perform this step.
On the source system, raise the Synchronize Event Systems event (oracle.apps.wf.event.all.sync) using the Raise Event Web page. Enter a unique event key, but leave the Event Data field blank. See: Raising Events
Note: If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.
When the Synchronize Event Systems event is raised on the source system, it triggers the subscription to the Seed Event Group with the Local source type. The Event Manager generates the event message, which contains the definitions of all the Event Manager objects on the local system, including events, event groups, systems, agents, and subscriptions. Then the event message is sent to the specified inbound agent on the target system, or to the specified workflow process that sends the event message to the target system.
When the Synchronize Event Systems event is received on the target system, it triggers the subscription to the Seed Event Group with the External source type. Oracle Workflow loads the object definitions from the event message into the Event Manager on the target system, creating new definitions or updating existing definitions as necessary.
Automatic Replication
After you enable the subscriptions in steps 2 and 3, these subscriptions will also replicate any subsequent changes you make to Event Manager object definitions on the source system. Whenever you create, update, or delete events, event group members, systems, agents, or subscriptions, Oracle Workflow raises the corresponding predefined events. These events trigger the Local subscription to the Seed Event Group on the source system, which sends the object definition data to the target system. The External subscription to the Seed Event Group on the target system receives the data and adds or updates the object definition in the Event Manager there.
If you do not want to continue automatically replicating changes on the source system to the target system, you can either disable the subscriptions after you finish synchronizing the systems, or disable the predefined events corresponding to those changes.
Master/Copy Systems
If you choose, you can treat one system as a master system that replicates its own Event Manager object definitions to its associated copy systems, but does not accept any object definition changes from those systems. To set up master/copy replication, perform the steps to synchronize the target copy systems with the source master system, as usual. Then, to prevent object definitions from being sent from the copy systems, ensure that the Local subscription to the Seed Event Group on the copy systems is disabled. To prevent object definitions from being received into the master system, ensure that the External subscription to the Seed Event Group on the master system is disabled as well.
Related Topics
Synchronize Event Systems Event
To Define an Event Subscription
The Oracle Workflow Event Manager lets you register interesting business events that may occur in your applications, the systems among which events will be communicated, named communication agents within those systems, and subscriptions indicating that an event is significant to a particular system. The Event Manager also performs subscribtion processing when events occur.
You must have workflow administrator privileges to maintain Business Event System objects in the Event Manager pages. If you have workflow administrator privileges, you can create, update, and delete events, subscriptions, systems, and agents. You can also test business events by manually raising a test event. If you do not have administrator privileges, you can view Business Event System objects in the Event Manager, but you cannot modify them. Workflow administrator privileges are assigned in the Workflow Configuration page. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Note: When defining internal names for Business Event System objects in the Event Manager, use only characters from the ASCII character set.
You can use the Workflow XML Loader to upload and download XML definitions for Business Event System objects between a database and a flat file. See: Using the Workflow XML Loader, Oracle Workflow Administrator's Guide.
When an event occurs in an application on your local system, an event key must be assigned to uniquely identify that particular instance of the event. Then the event must be raised to the Event Manager.
You can raise an event by any of the following methods:
Raise the event from the application where the event occurs using the WF_EVENT.Raise() PL/SQL API or the raise method in the BusinessEvent Java class. See: Raise, Oracle Workflow API Reference and the Oracle Workflow Javadoc.
Raise the event from a workflow process using a Raise event activity. See: Event Activity.
Raise the event manually using the Test Business Event page. See: To Raise a Test Event.
Additionally, the Event Manager can receive events sent from the local system or remote systems.
When an event is raised by a local application or received from a local or external system, the Event Manager executes any subscriptions to that event. Depending on the action defined in the subscription, the Event Manager may send the event information to a workflow process, send the event information to an agent, send a notification, send or receive an Oracle XML Gateway message, or execute custom code.
To communicate event messages between systems, you must schedule propagation for outbound messages and run agent listeners for inbound messages. You can use Oracle Enterprise Manager to schedule propagation and the Workflow Manager component of Oracle Applications Manager to run agent listeners. You can also view the distribution of event messages on different agents in Workflow Manager, drill down to view details about individual event messages, and review queue details for the agents. For more information, please refer to the Oracle Applications Manager online help, Oracle Enterprise Manager online help, Oracle Enterprise Manager Support, Oracle Application Developer's Guide - Advanced Queuing or Oracle Streams Advanced Queuing User's Guide and Reference, Distributed Management, Oracle Enterprise Manager Administrator's Guide, and Setting Up the Business Event System, Oracle Workflow Administrator's Guide.
To test your Business Event System setup, you can run the Workflow Agent Ping/Acknowledge workflow. See: Workflow Agent Ping/Acknowledge.
Note: For information about the version of the Event Manager available in standalone Oracle Workflow, see: Event Manager for Standalone Oracle Workflow.
Related Topics
A business event is an occurrence in an internet or intranet application or program that might be significant to other objects in a system or to external agents. For instance, the creation of a purchase order is an example of a business event in a purchasing application. You can define your significant events in the Event Manager.
Oracle Workflow provides several predefined events for significant occurrences within the Business Event System. See: Predefined Workflow Events.
When you define an event in the Event Manager, you must assign it a unique internal name, which is case-sensitive. The suggested format for these internal names is a compound structure of identifiers separated by periods (.) as follows:
<company>.<family>.<product>.<component>.<object>.<event>
This format allows you to organize the events you define into a classification hierarchy.
Any detail information needed to describe what occurred in an event, in addition to the event name and event key, is called the event data. For example, the event data for a purchase order event includes the item numbers, descriptions, and cost. The event data can be structured as an XML document.
The application where the event occurs can include the event data when raising the event to the Event Manager. If the application will not provide the event data, you should specify a generate function for the event that can produce the complete event data from the event name, event key, and an optional parameter list. The generate function must follow a standard PL/SQL or Java API. See: Raise, Oracle Workflow API Reference and Standard API for an Event Data Generate Function.
Define only one generate function for an event, either PL/SQL or Java. Define the generate function independently of any subscriptions to the event.
PL/SQL generate function - The Business Event System performs PL/SQL subscription processing in the database tier for an event with a PL/SQL generate function. However, if subscription processing for the event moves to the middle tier due to Java subscriptions, the middle tier Business Event System will execute the PL/SQL generate function through Java Database Connectivity (JDBC), if required.
Java generate function - The Business Event System will always perform subscription processing for the event in the middle tier to enable execution of the Java generate function, even if the subscriptions to the event are all PL/SQL subscriptions. If the event is raised from PL/SQL code or received through a PL/SQL agent listener, the Event Manager places the event on the WF_JAVA_DEFERRED queue to move subscription processing to the middle tier.
Note: When raising an event from Java, you can also set a serializable object as a payload for the event. The payload is available to all Java subscriptions to the event.
The Event Manager checks each subscription before executing it to determine whether the subscription requires the event data. If the event data is required but is not already provided, the Event Manager calls the generate function for the event to produce the event data. If the event data is required but no generate function is defined for the event, Oracle Workflow creates a default set of event data using the event name and event key.
Note: If the generate function is costly, and you want to return control to the calling application more quickly after raising the event, you can defer all the subscriptions that require the complete event data. Then the Event Manager will not run the generate function until those subscriptions are executed at a later time. See: Deferred Subscription Processing.
You can run a diagnostic test through Oracle Diagnostics to verify that the generate functions that are defined for events exist in the database and are valid. See: Oracle Workflow Diagnostic Tests, Oracle Workflow Administrator's Guide.
You can associate an event with the program or application to which it belongs by setting the program name and brief identifier as the owner name and owner tag for the event. For instance, in the example of the purchase order event, the owner would be the purchasing application. The program can then use this identifying information to locate the events that it owns.
Each event is assigned a customization level that determines whether you can update the event definition. Oracle Workflow uses the customization level to protect Oracle Applications seed data and to preserve your customizations in an upgrade. An event can have one of the following customization levels:
Core - No changes can be made to the event definition. This level is used only for events seeded by Oracle Applications.
Limit - The event status can be updated to Enabled or Disabled, but no other changes can be made to the event definition. This level is used only for events seeded by Oracle Applications.
User - Any property in the event definition can be updated. This level is automatically set for events that you define.
See: Access Protection for Business Event System Data, Oracle Workflow Administrator's Guide.
Some Oracle Applications products provide seeded events and subscriptions. In these cases, Oracle Workflow executes subscriptions only if the triggering event and the subscription are both owned by products that you have licensed with a status of Installed or Shared.
Your Oracle Applications installation may include seeded events owned by Oracle Applications products that you have not licensed. For such events, the Update Event page displays a notice that the event is not licensed. Oracle Workflow will not execute any subscriptions to these events. Additionally, Oracle Workflow will not execute any subscriptions owned by products that you have not licensed, even if the triggering events for those subscriptions are 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 events that you define with a customization level of User are always treated as being licensed.
You can also define event groups that let you associate any events you want with each other and reference them as a group in event subscriptions. An event group is a type of event composed of a set of individual member events. The internal names of event groups should follow the same format as the names of individual events. Once you have defined an event group, you can register a subscription to the group rather than having to create separate subscriptions for each individual event within it. The subscription will be executed whenever any one of the group's member events occurs.
Note: Event groups cannot be used to raise events. You must raise each event individually.
Related Topics
To Create or Update an Event Group
To View and Maintain Events
Use a Web browser to navigate to the Event Manager, using a responsibility and navigation path specified by your system administrator. Then choose Events in the horizontal navigation. See: Oracle Workflow Developer Navigation Paths.
Search for the events you want to display. The main search option is:
Name - Enter the internal name of the event you want to display. You can enter a partial value to search for events whose internal names contain that value.
You can also enter the following additional search criteria:
Display Name - Enter the display name of the event you want to display.
Type - Select Event or Group as the type of the events you want to display.
Status - Select Enabled or Disabled as the status of the events you want to display.
Owner Name - Enter the name of the program or application that owns the event you want to display.
Owner Tag - Enter the program ID of the program or application that owns the event you want to display.
To view the subscriptions to an event, select the subscription icon for that event.
Note: For events that do not have any subscriptions, a blank subscription icon appears in the Subscription column. For events that do have subscriptions to them, a full subscription icon appears.
If you have workflow administrator privileges, you can define a new subscription to the event by selecting the Create Subscription button. The Create Event Subscription page appears with the event name automatically entered in the Event Filter field. See: To Create or Update a Subscription.
If you have workflow administrator privileges, you can update an existing subscription by selecting the update icon for that subscription. See: To Create or Update a Subscription.
Note: For seeded subscriptions with a customization level of Limit, you can only update the subscription status. For seeded subscriptions with a customization level of Core, you cannot update any properties; you can only view the subscription definition.
If you have workflow administrator privileges, you can use the administration icons and buttons in the Events page to perform administrative operations.
To update an event, choose the update icon for that event. See: To Create or Update an Event and To Create or Update an Event Group.
Note: For seeded events with a customization level of Limit, you can only update the event status. For seeded events with a customization level of Core, you cannot update any properties; you can only view the event definition.
To manually raise a test event, select the test icon for the event you want. See: To Raise a Test Event.
Note: You cannot raise an event group. You must raise each event individually.
To delete an event, select the event and select the Delete button.
Note: You can only delete events that do not have any subscriptions referencing them and that do not belong to any event groups.
Additionally, you cannot delete any event seeded by Oracle Applications that has a customization level of Core or Limit.
To create a new individual event, select the Create Event button. See: To Create or Update an Event.
To create a new event group, select the Create Event Group button. See: To Create or Update an Event Group.
To Create or Update an Event
Navigate to the Create Event page or to the Update Event page. The Create Event page and the Update Event page are identical, except that the fields in the Update Event page are populated with previously defined information for the selected event.
Note: For seeded events with a customization level of Limit, you can only update the event status. For seeded events with a customization level of Core, you cannot update any properties; you can only view the event definition.
Note: Your Oracle Applications installation may include seeded events owned by Oracle Applications products that you have not licensed. For such events, the Update Event page displays a notice that the event is not licensed. Oracle Workflow will not execute any subscriptions to these events.
Enter the internal name of the event in the Name field. The internal name is case-sensitive. The suggested format is a compound structure of identifiers separated by periods (.) as follows:
<company>.<family>.<product>.<component>.<object>.<event> Enter a display name for the event.
Enter an optional description for the event.
Select Enabled or Disabled as the event status. If you disable an event, its definition remains in the Event Manager for reference, but you cannot use the event in active subscriptions.
If you are defining an event that occurs on your local system, enter a generate function for the event. A generate function is a PL/SQL procedure or Java API that can produce the complete event data from the event name, event key, and an optional parameter list. Define only one generate function for an event, either PL/SQL or Java. See: Standard API for an Event Data Generate Function.
To assign the event a PL/SQL generate function, enter the PL/SQL procedure in the Generate Function field in the following format:
<package_name>.<function_name> To assign the event a Java generate function, enter the Java API in the Java Generate Function field in the following format:
<customPackage>.<customClass> Identify the program or application that owns the event by entering the program name in the Owner Name field and the program ID in the Owner Tag field.
Review the customization level for the event.
Core - No changes can be made to the event definition. This level is used only for events seeded by Oracle Applications.
Limit - The event status can be updated to Enabled or Disabled, but no other changes can be made to the event definition. This level is used only for events seeded by Oracle Applications.
User - Any property in the event definition can be updated. This level is automatically set for events that you define.
To Create or Update an Event Group
Navigate to the Create Group page or to the Update Group page. The Create Group page and the Update Group page are identical, except that the fields in the Update Group page are populated with previously defined information for the selected event group.
Note: For seeded event groups with a customization level of Limit, you can only update the event group status. For seeded event groups with a customization level of Core, you cannot update any properties; you can only view the event group definition.
Note: Your Oracle Applications installation may include seeded event groups owned by Oracle Applications products that you have not licensed. For such events, the Update Group page displays a notice that the event group is not licensed. Oracle Workflow will not execute any subscriptions to these event groups.
Enter the internal name of the event group in the Name field. The internal name is case-sensitive. The suggested format is a compound structure of identifiers separated by periods (.) as follows:
<company>.<family>.<product>.<component>.<object>.<event> Enter a display name for the event group.
Enter an optional description for the event group.
Select Enabled or Disabled as the event group status. If you disable an event group, its definition remains in the Event Manager for reference, but you cannot use the event group in active subscriptions.
Identify the program or application that owns the event group by entering the program name in the Owner Name field and the program ID in the Owner Tag field.
Review the customization level for the event group.
Core - No changes can be made to the event group definition. This level is used only for event groups seeded by Oracle Applications.
Limit - The event group status can be updated to Enabled or Disabled, but no other changes can be made to the event group definition. This level is used only for event groups seeded by Oracle Applications.
User - Any property in the event group definition can be updated. This level is automatically set for event groups that you define.
Select the Apply button to save the event group definition.
To add a member event to the group, select the Add Events to Group button.
Note: An event group can contain only individual events as its members. It cannot contain another group.
In the Add Events to Group page, search for the events you want to add. The main search option is:
Name - Enter the internal name of the event you want to add. You can enter a partial value to search for events whose internal names contain that value.
You can also enter the following additional search criteria.
Display Name - Enter the display name of the event you want to add.
Type - You can only add individual events as members of the group.
Status - Select Enabled or Disabled as the status of the events you want to add.
Owner Name - Enter the name of the program or application that owns the event you want to add.
Owner Tag - Enter the program ID of the program or application that owns the event you want to add.
Select the event or events that you want to add to your event group, and select the Add to Group button.
You can optionally enter new search criteria to search for other events to add to the event group.
After you finish adding events to the event group, select the Apply button to save the event group members.
To delete a member event from the group, select the event in the Update Group page and select the Delete button.
Note: Deleting a member event from an event group does not delete the event definition for the individual event. The individual event remains in the Event Manager.
To Raise a Test Event
In the Event Identifier region, specify the event you want to raise.
Event Name - Select the internal name of the event.
Note: You cannot raise an event group. You must raise each event individually.
Event Key - Enter an event key that uniquely identifies this instance of the event.
Send Date - Optionally specify the date when the event message is available for dequeuing. If you set the send date to a future date when you raise the event, the event message is placed on the WF_DEFERRED queue, and subscription processing does not begin until the specified date.
In the Event Parameters region, optionally enter any additional parameter name and value pairs to be stored in the parameter list within the event message. You can enter up to 100 parameters.
In the Event Data region, you can optionally enter an XML document to describe what occurred in the event. You can enter up to 4000 characters.
To enter the event data manually, select the Write XML option and enter the XML document in the XML Content field.
To upload an XML file from your file system, select the Upload XML option and select the Upload XML File button. In the Upload XML File page, enter the full path and file name of the XML file containing your event data, and select the Upload File button.
You can also choose the View link to view the XML file if you have already specified one, or choose the Clear button to remove the previously specified file and enter a different file.
Note: You can also assign generate functions in the event definition to generate the event data, or raise the event using the WF_EVENT.Raise() API instead of using the Test Business Event page. These methods let you provide the event data as a CLOB storing up to four gigabytes of data. See: To Define an Event and Raise, Oracle Workflow API Reference.
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 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.
If no eligible subscriptions exist for the event that occurred (apart from subscriptions to the Any event), then Oracle Workflow executes any enabled subscriptions by the local system to the Unexpected event with the appropriate source type. See: Any Event and Unexpected Event.
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.
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.
You must specify the source type of the events to which the subscription applies. Events can have the following source types:
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 or the WF_JAVA_ERROR queue.
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.
The phase number for a subscription controls 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. Subscriptions with a phase number from 1 to 99 are executed immediately, unless processing for the event is deferred by another method. See: Deferred Subscription Processing.
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.
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.
See: Access Protection for Business Event System Data, Oracle Workflow Administrator's Guide.
Some Oracle Applications products provide seeded events and subscriptions. In these cases, Oracle Workflow executes subscriptions only if the triggering event and the subscription are both owned by products that you have licensed with a status of Installed or Shared.
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.
Subscription processing can include the following types of processing:
Send the event message to a workflow process.
Send the event message to an agent.
Send a notification to a role.
Receive an Oracle XML Gateway message from your trading partner.
Send an Oracle XML Gateway message to your trading partner.
Run a custom function on the event message.
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.
To send the event to a particular 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. 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 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:
If you want to specify additional parameters to set as item attributes for the workflow process, you can enter these parameters for the subscription and choose the Add Subscription Parameters option 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.
If you want to specify additional conditions to control whether or not the subscription is executed, you can enter subscription parameters that describe those conditions and choose the Launch when Parameters Match option. In this case the Event Manager sends the event to the specified workflow process only if the event message includes parameters whose names and values match all the parameters defined for the subscription. Ensure that you include the required parameters in the parameter list within the event message, either by providing them when the event is raised or by adding them during prior subscription processing.
If you want to send the event to multiple existing workflow processes, instead of to one particular process, you can choose the the Launch when Business Key Matches option instead of specifying 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 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:
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 chose the Launch when Business Key Matches option, then to be eligible an activity must have an event filter that matches the event, a status of 'NOTIFIED' , and 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.
See: Default_Rule, Oracle Workflow API Reference, Default_Rule2, Oracle Workflow API Reference, Default_Rule3, Oracle Workflow API Reference, and Instance_Default_Rule, Oracle Workflow API Reference.
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.
To send an event to an agent, you must specify either the Out Agent that should send the outbound message, or the To Agent that should 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.
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:
If you want to add more parameters to the event message before it is sent, you can enter these parameters for the subscription and choose the Add Subscription Parameters option to set the subscription parameters into the event message parameter list.
If you want to specify additional conditions to control whether or not the subscription is executed, you can enter subscription parameters that describe those conditions and choose the Launch when Parameters Match option. In this case the Event Manager sends the event to the specified agent only if the event message includes parameters whose names and values match all the parameters defined for the subscription. Ensure that you include the required parameters in the parameter list within the event message, either by providing them when the event is raised or by adding them during prior subscription processing.
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 prior subscription processing before the event is sent. The event message is propagated to the To Agent but does not become available for dequeuing until the specified date.
See: Default_Rule, Oracle Workflow API Reference, Default_Rule2, Oracle Workflow API Reference, and Default_Rule3, Oracle Workflow API Reference.
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.
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.
See: SendNotification, Oracle Workflow API Reference.
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.
See: XML Gateway Standard Item Type, Oracle XML Gateway User's Guide.
You can extend your subscription processing by creating custom rule functions. A subscription can have either a PL/SQL rule function for processing in the database or a Java rule function for processing in the middle tier.
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:
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.
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 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 associate a subscription with the program or application to which it belongs by setting the program name and brief identifier as the owner name and owner tag for the subscription. The program can then use this identifying information to locate the subscriptions that it owns. The subscription owner may be the same program as the owner of the triggering event, or a different program.
If you do not want subscriptions for an event to be executed immediately when the event occurs, you can defer the subscriptions. In this way you can return control more quickly to the calling application and let the Event Manager execute any costly subscription processing at a later time.
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 from PL/SQL code. 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.
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.
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 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.
See: Raise, Oracle Workflow API Reference.
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 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.
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 an event is raised locally from PL/SQL code, or received on an agent and processed by a PL/SQL agent listener, the Event Manager performs subscription processing in the database tier. It begins processing the subscriptions to the event in phase order and executes PL/SQL subscriptions synchronously, within the same database session, as long as the subscriptions are not deferred.
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.
Related Topics
To View and Maintain Event Subscriptions
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.
To View and Maintain Event Subscriptions
Use a Web browser to navigate to the Event Manager, using a responsibility and navigation path specified by your system administrator. Then choose Subscriptions in the horizontal navigation. See: Oracle Workflow Developer Navigation Paths.
Search for the subscriptions you want to display. The main search option is:
System - Select the system for which you want to display subscriptions.
You can also enter the following additional search criteria.
Source Type - Select Local, External, or Error as the type of source system for which you want to display subscriptions.
Event - Select the event for which you want to display subscriptions.
Status - Select Enabled or Disabled as the status of the subscriptions you want to display.
If you have workflow administrator privileges, you can use the administration icons and buttons to perform administrative operations.
To update a subscription, choose the update icon for that subscription. See: To Create or Update an Event Subscription.
Note: For seeded subscriptions with a customization level of Limit, you can only update the subscription status. For seeded subscriptions with a customization level of Core, you cannot update any properties; you can only view the subscription definition.
To delete a subscription, select the subscription and select the Delete button.
Note: You cannot delete any subscription seeded by Oracle Applications that has a customization level of Core or Limit.
To create a new subscription, select the Create Subscription button. See: To Create or Update an Event Subscription.
To Create or Update an Event Subscription
Navigate to the Create Event Subscription page or to the Update Event Subscriptions page. The Create Event Subscription page and the Update Event Subscriptions page are identical, except that the fields in the Update Event Subscriptions page are populated with previously defined information for the selected subscription.
Note: For seeded subscriptions with a customization level of Limit, you can only update the subscription status. For seeded subscriptions with a customization level of Core, you cannot update any properties; you can only view the subscription definition.
Note: 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.
In the Subscriber region, select the system where the subscription executes.
In the Triggering Event region, specify the event source to which the subscription applies in the Source Type field.
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 or WF_JAVA_ERROR queue.
Select the event that triggers the subscription in the Event Filter field. You can specify an individual event or an event group.
Optionally select a source agent to which the subscription applies. If you specify a source agent, then the subscription is executed only when the triggering event is received from that agent.
Note: In most cases, the Source Agent field is left blank.
In the Execution Condition region, enter a phase number for the subscription to specify the order in which subscriptions triggered by the same event are executed. The phase number also controls whether a subscription is executed immediately or is deferred, unless processing for the event is deferred by another method.
Note: 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.
Select Enabled or Disabled as the subscription status. If you disable a subscription, it still remains in the Event Manager for reference, but it can no longer be executed when events occur.
In the Rule Data field, specify the event information required by the subscription.
Key - The subscription requires only the event key.
Message - The subscription requires the complete event data.
In the Action Type region, select the subscription processing you want to perform when the triggering event occurs.
Launch Workflow - Send the event message to launch or continue a workflow process.
Send to Agent - Send the event message to a Business Event System agent.
Send Notification - Send a notification using a standard or custom message template.
Receive Trading Partner Message - Receive an Oracle XML Gateway message from your trading partner.
Send Trading Partner Message - Generate an Oracle XML Gateway message and send the message to your trading partner.
Custom - Execute custom business logic defined as a PL/SQL rule function or as a Java rule function.
Specify the error handling to perform if Oracle Workflow encounters an error while processing this subscription. Currently, Oracle Workflow supports Stop and Rollback error handling, in which the Event Manager halts all subscription processing for the event, rolls back any subscriptions already executed for the event, and places the event message on the standard WF_ERROR or WF_JAVA_ERROR agent.
Note: The Skip to Next option is reserved for future use.
Choose the Next button to define the details of the subscription action, depending on the action type you selected.
If you selected Launch Workflow as the action type, enter the following details.
Select the workflow item type and process name for the workflow process to which you want to send the event. Ensure that the process contains a receive event activity that will be able to accept the event. The event can either launch a new process instance or continue an existing process instance that is waiting to receive the event.
Note: The list of values for the Workflow Process field includes only the runnable processes within the item type you specify.
Select Normal, High, or Low as the priority for the subscription. Oracle Workflow uses the priority to help determine the order in which deferred subscriptions are processed. The default priority is Normal.
You can optionally select an additional option to control how the subscription is executed.
Add Subscription Parameters - Set the subscription parameters into the parameter list within the event message before sending the event to the specified workflow process. All the event parameters will be set as item attributes for the workflow process when the process receives the event.
Launch when Business Key Matches - Send 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. This option lets you send the event to multiple processes. However, note that 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.
Note: If you select this option, the Event Manager ignores the specified workflow item type and process name. Instead, it uses the business key attribute to identify the workflow processes that should receive the event.
Launch when Parameters Match - Send the event to the specified workflow process only if the event message includes parameters whose names and values match all the parameters defined for the subscription. This option lets you specify additional conditions to control whether or not the subscription is executed. Ensure that you include the required parameters in the parameter list within the event message, either by providing them when the event is raised or by adding them during prior subscription processing.
If you selected the Add Subscription Parameters option or the Launch when Parameters Match option, specify the parameters for the subscription. Enter the name and value for each parameter with no spaces.
If you selected Send to Agent as the action type, enter the following details.
Enter 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. The Out Agent must use either a multi-consumer queue with a subscriber list or a single-consumer queue.
Note: The Out Agent must be located on the subscribing system. The list of values for the Out Agent field includes only agents with a direction of Out.
The list of values for the To Agent field includes only agents with a direction of In.
Select Normal, High, or Low as the priority for the subscription. Oracle Workflow uses the priority to help determine the order in which deferred subscriptions are processed. The default priority is Normal.
You can optionally select an additional option to control how the subscription is executed.
Add Subscription Parameters - Set the subscription parameters into the parameter list within the event message before placing the event message on the outbound agent.
Launch when Parameters Match - Place the event message on the outbound agent only if the event message includes parameters whose names and values match all the parameters defined for the subscription. This option lets you specify additional conditions to control whether or not the subscription is executed. Ensure that you include the required parameters in the parameter list within the event message, either by providing them when the event is raised or by adding them during prior subscription processing.
If you selected the Add Subscription Parameters option or the Launch when Parameters Match option, specify the parameters for the subscription. Enter the name and value for each parameter with no spaces.
If you selected Send Notification as the action type, enter the following details.
Select the workflow item type and message name for the message you want to send.
Note: You do not need to define or run a workflow process to send a notification from a subscription with the Send Notification action type. However, you do need to define the message you want to send within a workflow item type. The list of values for the Message Name field includes only the messages within the item type you specify.
Select the role that should receive the notification.
Optionally enter a custom callback function you want the Notification System to use for communication of SEND and RESPOND source message attributes. See: Custom Callback Function, Oracle Workflow API Reference.
Optionally enter context information for a workflow process instance 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 enter the context information that is appropriate for your function.
Optionally enter a comment to send with the message.
Optionally enter a due date when a response is required. This date is only for the recipient's information; it has no effect on processing.
Select Normal, High, or Low as the priority for the message. Oracle Workflow also uses the priority to help determine the order in which deferred subscriptions are processed. The default priority is Normal.
If you selected Receive Trading Partner Message or Send Trading Partner Message as the action type, select Normal, High, or Low as the priority for the subscription. Oracle Workflow uses the priority to help determine the order in which deferred subscriptions are processed. The default priority is Normal.
Note: You do not need to enter any additional subscription parameters for these action types.
If you selected Custom as the action type, enter the following details.
Enter the rule function that contains the custom business logic you want to run on the event message. You can define the rule function either as a Java class or as a PL/SQL function. In either case, the rule function must be defined according to a standard API. See: Standard API for an Event Subscription Rule Function.
For a Java subscription, enter the Java rule function in the following format:
<customPackage>.<customClass> In this case, you should leave the PL/SQL Rule Function field blank.
For a PL/SQL subscription, enter the PL/SQL rule function in the following format:
<package_name>.<function_name> In this case, you should leave the Java Rule Function field blank.
Note: If you enter a rule function other than WF_RULE.Default_Rule, Oracle Workflow does not automatically send the event message to the specified workflow and agent. You must explicitly include the send processing in your custom rule function instead.
If your rule function will send the event to a workflow process, you can specify the workflow item type and process name for the function to reference. Ensure that the process contains a receive event activity that will be able to accept the event.
Note: The list of values for the Workflow Process field includes only the runnable processes within the item type you specify.
If your rule function will send the event to an agent, you can specify the outbound and inbound agents for the function to reference. Depending on the send processing in your function, you may need to 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.
Note: The Out Agent must be located on the subscribing system. The list of values for the Out Agent field includes only agents with a direction of Out.
The list of values for the To Agent field includes only agents with a direction of In.
Select Normal, High, or Low as the priority for the subscription. Oracle Workflow uses the priority to help determine the order in which deferred subscriptions are processed. The default priority is Normal.
You can optionally specify additional parameters for the subscription, to be referenced by the rule function. Enter the name and value for each parameter with no spaces.
Oracle Workflow converts this list of subscription parameters into a text string of name and value pairs, separated by spaces, in the following format:
<name1>=<value1> <name2>=<value2> ... <nameN>=<valueN> The rule function can reference the parameters from this format.
For all action types, in the Documentation region, identify the program or application that owns the subscription by entering the program name in the Owner Name field and the program ID in the Owner Tag field.
Review the customization level for the subscription.
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.
Enter an optional description for the subscription.
An agent is a named point of communication within a system. Communication within and between systems is accomplished by sending a message from one agent to another. A single system can have several different agents representing different communication alternatives. For example, a system may have different agents to support inbound and outbound communication, communication by different protocols, different propagation frequencies, or other alternatives.
You should define each agent that you will use to communicate events in the Event Manager. Each agent's name must be unique within its system. The agent can be referenced in code within Oracle Workflow by a compound name in the following format:
<agent_name>@<system_name>
For example, the agent WF_IN within the system HUB could be referenced as WF_IN@HUB.
After defining the agents on your local system, you should set them up for event message communication by scheduling agent listeners for local inbound agents and propagation for local outbound agents. You can use Oracle Enterprise Manager to schedule propagation and the Workflow Manager component of Oracle Applications Manager to run agent listeners. In Oracle Workflow Manager you can also view the distribution of event messages on different agents, drill down to view details about individual event messages, and review queue details for the agents. For more information, please refer to the Oracle Applications Manager online help, Oracle Enterprise Manager online help, Oracle Enterprise Manager Support, Oracle Application Developer's Guide - Advanced Queuing or Oracle Streams Advanced Queuing User's Guide and Reference, Distributed Management, Oracle Enterprise Manager Administrator's Guide, and Setting Up the Business Event System, Oracle Workflow Administrator's Guide.
You can run a diagnostic test through Oracle Diagnostics to verify the status of your agents. See: Oracle Workflow Diagnostic Tests, Oracle Workflow Administrator's Guide.
When you define an agent in the Event Manager, you must specify the direction of communication that the agent supports on its local system.
In - Inbound communication to the system. The agent receives messages in a specific protocol and presents them to the system in a standard format.
Out - Outbound communication from the system. The agent accepts messages from the system in a standard format and sends them using the specified protocol.
You must associate each agent with the protocol by which it communicates messages. The protocol specifies how the messages are encoded and transmitted. For a message to be successfully communicated, the sending and receiving agents must use the same protocol.
A protocol can represent a network standard, such as SQLNET. It can also represent a business-to-business standard that defines the higher-level message format and handshaking agreements between systems in addition to the network standard.
The Business Event System interacts with an agent through an AQ queue. You can use AQ to perform the propagation of messages by the SQLNET protocol which it supports. In Oracle9i Database and higher, AQ also includes Internet access functionality that lets you perform AQ operations over the Internet by using AQ's Internet Data Access Presentation (IDAP) for messages and transmitting the messages over the Internet using transport protocols such as HTTP or HTTPS. Additionally, the Messaging Gateway feature of AQ in Oracle9i Database and higher enables communication between applications based on non-Oracle messaging systems and AQ, letting you integrate with third party messaging solutions. You can also implement other services to propagate messages by different protocols.
To implement a custom protocol, you must perform the following steps:
Define AQ queues to hold pending inbound and outbound messages.
Provide code that propagates messages to and from the AQ queues.
Define a lookup code for the new protocol in the Event Protocol Type (WF_AQ_PROTOCOLS) lookup type, which is stored in the Standard item type. The Event Manager uses the Event Protocol Type lookup type to validate the protocol for an agent. See: To Create Lookup Codes for a Lookup Type.
Define agents with the new protocol. See: To Create or Update an Agent.
If an agent supports inbound communication, you must specify the address by which systems can communicate with it. The format of the address depends on the agent's protocol. For agents that use the SQLNET protocol, the address must be in the following format to enable AQ propagation:
<schema>.<queue>@<database link>
In this format, <schema> represents the schema that owns the queue, <queue> represents the queue name, and <database link> represents the name of the database link to the instance where the queue is located.
Note: You must enter the database link name exactly as the name was specified when the database link was created. For example, if a database link is named ORA10.US.ORACLE.COM, you must enter that complete name in the address of an agent on that database. You cannot abbreviate the name to ORA10.
The names of the database links that you want to use for the Business Event System should be fully qualified with the domain names. To confirm the names of your database links, use the following syntax:
SELECT db_link FROM all_db_links
See: Creating Database Links, Oracle Workflow Administrator's Guide.
You must associate each agent on a Workflow-enabled system with an AQ queue. The local system uses this queue to interact with the agent. To send messages, the system enqueues the messages on the queue and sets the recipient addresses. To receive messages, the system runs a listener on the queue. See: Setting Up Queues, Oracle Workflow Administrator's Guide.
Event messages within the Oracle Workflow Business Event System are encoded in a standard format defined by the datatype WF_EVENT_T, or, in Java, the BusinessEvent object. You should assign each agent a PL/SQL or Java package called a queue handler that translates between the standard Workflow format and the format required by the agent's queue. Define only one queue handler for an agent, either PL/SQL or Java. See: Event Message Structure, Oracle Workflow API Reference.
Note: Even if the agent's queue uses WF_EVENT_T as its payload type, a queue handler is still required in order to set native AQ message properties.
Oracle Workflow provides two standard queue handlers, called WF_EVENT_QH and WF_ERROR_QH, for queues that use SQLNET propagation and use the WF_EVENT_T datatype as their payload type. You can use WF_EVENT_QH with queues that handle normal Business Event System processing, while WF_ERROR_QH should be used exclusively with error queues.
Oracle Workflow also provides a standard queue handler called WF_EVENT_OJMSTEXT_QH for queues that use the SYS.AQ$_JMS_TEXT_MESSAGE datatype as their payload type. This queue handler enables communication of JMS Text messages through the Business Event System. See: Mapping Between WF_EVENT_T and SYS.AQ$_JMS_TEXT_MESSAGE, Oracle Workflow API Reference.
If you want to use queues that require a different format, create a custom queue handler for that format. Your custom queue handler must include a set of standard APIs to enqueue and dequeue messages in the custom format. See: Standard APIs for a Queue Handler.
If you define a PL/SQL queue handler, then you can run both PL/SQL and Java agent listeners on this agent. The PL/SQL queue handler is used during both Java and PL/SQL event message processing. Java agent listeners will execute the PL/SQL queue handler through Java Database Connectivity (JDBC).
If you define a Java queue handler, then you can run only Java agent listeners on this agent. The Java queue handler is used during Java event message processing. You cannot run a PL/SQL agent listener on this agent, because a PL/SQL agent listener cannot execute a Java queue handler.
You can also define agent groups that let you associate several inbound agents with each other and reference them as a group in event subscriptions and Send event activities. An agent group is a type of agent composed of a set of individual member agents. Once you have defined an agent group, you can send event messages to the group rather than having to send the messages separately to each individual agent within it.
Agent groups can only be used for inbound communication. All agent groups have a direction of In, and only individual agents with a direction of In can be members of an agent group.
You must associate each agent group with a system to which it belongs. However, you can include agents on other systems within the group.
Ensure that you run an agent listener for each agent within the group to receive inbound messages.
Note: You cannot run an agent listener for an agent group. Agent listeners can be run only for individual agents.
When you install Oracle Workflow, several standard agents are automatically defined for the Business Event System.
WF_CONTROL - Oracle Workflow internal agent, not for customer use
WF_DEFERRED - Standard agent for deferred subscription processing in the database
WF_ERROR - Standard agent for error handling in the database
WF_JAVA_DEFERRED - Standard agent for deferred subscription processing in the middle tier
WF_JAVA_ERROR - Standard agent for error handling in the middle tier
WF_NOTIFICATION_IN - Standard inbound agent for e-mail notification responses
WF_NOTIFICATION_OUT - Standard outbound agent for e-mail notifications
WF_WS_JMS_IN - Default inbound agent for Web service messages
WF_WS_JMS_OUT - Default outbound agent for Web service messages
These agents use standard queues that are automatically defined when you install Oracle Workflow. See: Setting Up Queues, Oracle Workflow Administrator's Guide.
You can enable or disable the WF_IN, WF_JMS_IN, WF_WS_JMS_IN, WF_OUT, WF_JMS_OUT, and WF_WS_JMS_OUT agents, but you must not make any other changes to their definitions. You must not make any changes to the definitions of the other agents.
Oracle Workflow automatically runs PL/SQL agent listeners for the standard WF_DEFERRED, WF_ERROR, and WF_NOTIFICATION_IN agents in order to perform deferred subscription processing, error handling for the Business Event System, and inbound e-mail processing for notification mailers, respectively. Oracle Workflow also automatically runs Java agent listeners for the standard WF_JAVA_DEFERRED and WF_JAVA_ERROR agents in order to perform deferred subscription processing and error handling in the middle tier. Additionally, Oracle Workflow provides a Java agent listener named Web Services IN Agent that you can optionally start for the WF_WS_JMS_IN agent. If you want to use the WF_IN and WF_JMS_IN agents for event message propagation, schedule listeners for those agents as well.
Likewise, if you want to use the WF_OUT and WF_JMS_OUT agents for event message propagation, schedule propagation for those agents. You do not need to schedule propagation for the WF_CONTROL, WF_NOTIFICATION_OUT, or WF_WS_JMS_OUT agents, however. The middle tier processes that use WF_CONTROL dequeue messages directly from its queue, and notification mailers send messages placed on the WF_NOTIFICATION_OUT queue. For WF_WS_JMS_OUT, you can optionally start a Web services outbound component named Web Services OUT Agent, provided by Oracle Workflow. For more information, please refer to the Oracle Applications Manager online help, Oracle Enterprise Manager online help, Oracle Enterprise Manager Support, Oracle Application Developer's Guide - Advanced Queuing or Oracle Streams Advanced Queuing User's Guide and Reference, Distributed Management, Oracle Enterprise Manager Administrator's Guide, and Setting Up the Business Event System, Oracle Workflow Administrator's Guide.
You can run a diagnostic test through Oracle Diagnostics to verify that the WF_DEFERRED queue and the WF_ERROR each have only one subscriber rule defined. No custom subscribers should be added to these queues. See: Oracle Workflow Diagnostic Tests, Oracle Workflow Administrator's Guide.
Note: Oracle Workflow also includes three additional agents named WF_REPLAY_IN, WF_REPLAY_OUT, and WF_SMTP_O_1_QUEUE, which are not currently used.
The following table lists the default properties for the standard WF_CONTROL agent. See: Cleaning Up the Workflow Control Queue, Oracle Workflow Administrator's Guide.
| Agent Property | Value |
|---|---|
| Name | WF_CONTROL |
| Display Name | Workflow Control Out Queue |
| Description | Workflow JMS Text Message Queue used to signal messages to middle tier processes |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_CONTROL@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_CONTROL |
| Direction | Out |
| Status | Enabled |
The following table lists the default properties for the standard WF_DEFERRED agent.
| Agent Property | Value |
|---|---|
| Name | WF_DEFERRED |
| Display Name | WF_DEFERRED |
| Description | WF_DEFERRED |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_DEFERRED@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_QH |
| Queue Name | <workflow schema>.WF_DEFERRED |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_ERROR agent.
| Agent Property | Value |
|---|---|
| Name | WF_ERROR |
| Display Name | WF_ERROR |
| Description | WF_ERROR |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_ERROR@<local database> |
| System | <local system> |
| Queue Handler | WF_ERROR_QH |
| Queue Name | <workflow schema>.WF_ERROR |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_JAVA_DEFERRED agent.
| Agent Property | Value |
|---|---|
| Name | WF_JAVA_DEFERRED |
| Display Name | Workflow Java Deferred In Queue |
| Description | Workflow Java Deferred In Queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_JAVA_DEFERRED@ <local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_JAVA_DEFERRED |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_JAVA_ERROR agent.
| Agent Property | Value |
|---|---|
| Name | WF_JAVA_ERROR |
| Display Name | Workflow Java Error In Queue |
| Description | Workflow Java Error In Queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_JAVA_ERROR@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_JAVA_ERROR |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_IN agent.
| Agent Property | Value |
|---|---|
| Name | WF_IN |
| Display Name | WF_IN |
| Description | WF_IN |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_IN@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_QH |
| Queue Name | <workflow schema>.WF_IN |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_JMS_IN agent.
| Agent Property | Value |
|---|---|
| Name | WF_JMS_IN |
| Display Name | Workflow JMS In Queue |
| Description | Workflow JMS Text Message Queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_JMS_IN@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_JMS_IN |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_JMS_OUT agent.
| Agent Property | Value |
|---|---|
| Name | WF_JMS_OUT |
| Display Name | Workflow JMS Out Queue |
| Description | Workflow JMS Text Message Queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_JMS_OUT@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_JMS_OUT |
| Direction | Out |
| Status | Enabled |
The following table lists the default properties for the standard WF_NOTIFICATION_IN agent. See: Implementing Notification Mailers, Oracle Workflow Administrator's Guide.
| Agent Property | Value |
|---|---|
| Name | WF_NOTIFICATION_IN |
| Display Name | Workflow Notification In Queue |
| Description | Workflow inbound notification response queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_NOTIFICATION_IN@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_NOTIFICATION_IN |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_NOTIFICATION_OUT agent. See: Implementing Notification Mailers, Oracle Workflow Administrator's Guide.
| Agent Property | Value |
|---|---|
| Name | WF_NOTIFICATION_OUT |
| Display Name | Workflow Notification Out Queue |
| Description | Workflow notification outbound queue |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_NOTIFICATION_OUT@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_NOTIFICATION_OUT |
| Direction | Out |
| Status | Enabled |
The following table lists the default properties for the standard WF_OUT agent.
| Agent Property | Value |
|---|---|
| Name | WF_OUT |
| Display Name | WF_OUT |
| Description | WF_OUT |
| Protocol | SQLNET |
| Address | <workflow schema>.WF_OUT@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_QH |
| Queue Name | <workflow schema>.WF_OUT |
| Direction | Out |
| Status | Enabled |
The following table lists the default properties for the standard WF_WS_JMS_IN agent.
| Agent Property | Value |
|---|---|
| Name | WF_WS_JMS_IN |
| Display Name | WebServices JMS In Queue |
| Description | WebServices JMS Text Message Queue for Inbound |
| Protocol | SOAP |
| Address | <workflow schema>.WF_WS_JMS_IN@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_WS_JMS_IN |
| Direction | In |
| Status | Enabled |
The following table lists the default properties for the standard WF_WS_JMS_OUT agent.
| Agent Property | Value |
|---|---|
| Name | WF_WS_JMS_OUT |
| Display Name | WebServices JMS Out Queue |
| Description | WebServices JMS Text Message Queue for Outbound |
| Protocol | SOAP |
| Address | <workflow schema>.WF_WS_JMS_OUT@<local database> |
| System | <local system> |
| Queue Handler | WF_EVENT_OJMSTEXT_QH |
| Queue Name | <workflow schema>.WF_WS_JMS_OUT |
| Direction | Out |
| Status | Enabled |
Systems that will communicate events with each other must store each other's inbound agent definitions in order to address event messages to each other.
For communication between two systems that both have Oracle Workflow installed, Oracle Workflow provides an external system registration procedure that you can use to automatically copy the inbound agent definitions for the other system into the Event Manager of your local system. See: Registering External Systems.
If your local Workflow-enabled system will communicate with a non-Workflow system, the non-Workflow system must provide its own external propagation agents to handle Business Event System event messages.
An inbound agent on a non-Workflow system must be able to dequeue event messages from a Business Event System outbound queue and process the contents of those messages. The inbound agent must have an address at which systems can communicate with the agent.
An outbound agent on a non-Workflow system must be able to enqueue event messages in the appropriate format on a Business Event System inbound queue.
You must manually define the inbound agents for an external non-Workflow system in the Event Manager of your local system. You can optionally define the external system's outbound agents as well.
Before defining agents for a non-Workflow system, you must define the system itself using the Create System page. See: To Create or Update a System.
You can then use the Create Agent page to define an agent for the non-Workflow system, following the same steps as for any other agent. See: To Create or Update an Agent.
You must associate the agent with the non-Workflow system to which it belongs.
You must specify the protocol by which you will communicate with the agent.
For an inbound agent, you must also specify the address at which you will communicate with the agent.
You can leave the queue name and queue handler blank if the agent is not implemented as an Oracle Advanced Queueing queue.
Related Topics
To Create or Update an Agent Group
To View and Maintain Agents
Use a Web browser to navigate to the Event Manager, using a responsibility and navigation path specified by your system administrator. Then choose Agents in the horizontal navigation. See: Oracle Workflow Developer Navigation Paths.
Search for the agents you want to display. The main search option is:
Name - Enter the internal name of the agent you want to display. You can enter a partial value to search for agents whose internal names contain that value.
You can also enter the following additional search criteria.
Protocol - Select the protocol of the agent you want to display.
Address - Enter the address of the agent you want to display.
System - Select the system of the agent you want to display.
Direction - Select In or Out as the direction of the agents you want to display.
Type - Select Agent or Group as the type of the agents you want to display.
Status - Select Enabled or Disabled as the status of the agents you want to display.
If you have workflow administrator privileges, you can use the administration icons and buttons to perform administrative operations.
To update an agent, choose the update icon for that agent. See: To Create or Update an Agent and To Create or Update an Agent Group.
To delete an agent, select the agent and select the Delete button.
Note: You can only delete agents that do not have any subscriptions referencing them and that do not belong to any agent groups.
To create a new individual agent, select the Create Agent button. See: To Create or Update an Agent.
To create a new agent group, select the Create Agent Group button. See: To Create or Update an Agent Group.
Note: Whenever you make changes to your agents that affect the physical implementation required for message propagation, you should recheck your propagation setup. For more information, please refer to the Oracle Applications Manager online help, Oracle Enterprise Manager online help, Oracle Enterprise Manager Support, Oracle Application Developer's Guide - Advanced Queuing or Oracle Streams Advanced Queuing User's Guide and Reference, Distributed Management, Oracle Enterprise Manager Administrator's Guide, and Setting Up the Business Event System, Oracle Workflow Administrator's Guide.
To Create or Update an Agent
Navigate to the Create Agent page or to the Update Agent page. The Create Agent page and the Update Agent page are identical, except that the fields in the Update Agent page are populated with previously defined information for the selected agent.
Note: You should not use the Create Agent page to create agent definitions for inbound agents on external systems that have Oracle Workflow installed. Instead, you should use the External System Registration page to automatically register the system identifier information for that external system, including inbound agent definitions. See: Registering External Systems.
Enter the internal name of the agent in the Name field. The agent's internal name must be unique within the agent's system.
Attention: The internal name must be all-uppercase and should not include any single or double quotation marks (' or ") or spaces.
Enter a display name for the agent.
Enter an optional description for the agent.
Select the message communication protocol that the agent supports.
If the agent supports inbound communication to its system, enter the address for the agent. The format of the address depends on the protocol you select.
For agents that use the SQLNET protocol, the address must be in the following format to enable AQ propagation:
<schema>.<queue>@<database link>
<schema> represents the schema that owns the queue, <queue> represents the queue name, and <database link> represents the database link to the instance where the queue is located.
Note: You must enter the database link name exactly as the name was specified when the database link was created. See: Creating Database Links, Oracle Workflow Administrator's Guide.
Select the system in which the agent is defined.
Enter the queue handler for the agent. A queue handler is a PL/SQL or Java package that translates between the Workflow event message format (WF_EVENT_T datatype or BusinessEvent Java object) and the message format required by the queue associated with the agent. Define only one queue handler for an agent, either PL/SQL or Java. See: Standard APIs for a Queue Handler.
To assign the agent a PL/SQL queue handler, enter the PL/SQL package name in the Queue Handler field in all uppercase. You can run both PL/SQL and Java agent listeners on an agent with a PL/SQL queue handler.
To assign the agent a Java queue handler, enter the Java package name in the Java Queue Handler field. You can run only Java agent listeners on an agent with a Java queue handler.
Note: For an agent that is not implemented as a queue, such as an agent on a non-Oracle system, you can leave the Queue Handler and Java Queue Handler fields blank.
Enter the name of the queue that the local system uses to interact with the agent. Since only the local system refers to this queue name, the queue name should be within the scope of this system, without requiring a database link. Use the following format to specify the queue name:
<schema>.<queue>
<schema> represents the schema that owns the queue, and <queue> represents the queue name.
Attention: You must enter the queue name in all uppercase.
Note: For an agent that is not implemented as a queue, such as an agent on a non-Oracle system, you can leave the Queue field blank.
In the Direction field, select In for an agent that supports inbound communication to its system, or select Out for an agent that supports outbound communication from its system.
Select Enabled or Disabled as the agent status. If you disable an agent, its definition remains in the Event Manager for reference, but you cannot use the agent in active subscriptions.
To Create or Update an Agent Group
Navigate to the Create Agent Group page or to the Update Agent Group page. The Create Agent Group page and the Update Agent Group page are identical, except that the fields in the Update Agent Group page are populated with previously defined information for the selected agent group.
Enter the internal name of the agent group in the Name field. The agent group's internal name must be unique within the agent group's system.
Attention: The internal name must be all-uppercase and should not include any single or double quotation marks (' or ") or spaces.
Enter a display name for the agent group.
Enter an optional description for the agent group.
Select the system on which the agent group is defined.
Note: Although an agent group is defined on a particular system, you can include agents from other systems as members within the group.
Since agent groups are used only for inbound communication, the direction for an agent group is automatically set to In.
Select Enabled or Disabled as the agent group status. If you disable an agent group, its definition remains in the Event Manager for reference, but you cannot use the agent group in active subscriptions.
Select the Apply button to save the agent group definition.
To add a member agent to the group, select the Add Agents to Group button.
Note: An agent group can contain only individual agents as its members. It cannot contain another group.
In the Add Agents to Group page, search for the agents you want to add. The main search option is:
Name - Enter the internal name of the agent you want to add. You can enter a partial value to search for agents whose internal names contain that value.
You can also enter the following additional search criteria.
Protocol - Select the protocol of the agent you want to add.
Address - Enter the address of the agent you want to add.
System - Select the system of the agent you want to add.
Status - Select Enabled or Disabled as the status of the agents you want to add.
Select the agent or agents that you want to add to your agent group, and select the Add Agents to Group button.
You can optionally enter new search criteria to search for other agents to add to the agent group.
After you finish adding agents to the agent group, select the Apply button to save the agent group members.
To delete a member agent from the group, select the agent in the Create Agent Group or Update Agent Group page and select the Delete button.
Note: Deleting a member agent from an agent group does not delete the agent definition for the individual agent. The individual agent remains in the Event Manager.
A system is a logically isolated software environment such as a host machine or database instance. You should define each system to or from which you will communicate events in the Event Manager.
When you define a system, you can specify whether it is associated with a master system from which you want it to receive Event Manager object definition updates.
Each system can expose one or more addressable points of communication, called agents. After you define your systems, you should define the agents within those systems that you will use to communicate business events. See: Agents.
When you install Oracle Workflow in a database, that database is automatically defined as a system in the Event Manager and set as the local system in the Workflow Configuration page. The following table lists the default properties of the local system definition.
| System Property | Value |
|---|---|
| Name | <database global name> |
| Display Name | <database global name> |
| Description | Local System Created by Oracle Workflow Configuration Assistant |
| Master | (blank) |
You can update the local system definition if necessary.
Oracle Workflow sets the status of the local system to Enabled by default. After you finish setting up the Business Event System, you can use the Workflow Configuration page to set the system status that you want for event processing. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Before you can send business events from one system to another, you must register the destination system with the source system as a potential recipient of event messages. Registering a system means defining the destination system as well as its inbound agents in the Event Manager of the source system, so that event messages from the source system can be addressed to the destination agents. Registering a system is also known as signing up a system.
Usually, both systems should be registered with each other, so that each system can both send messages to and receive messages from the other system.
Oracle Workflow provides Web pages to help automate external system registration between two systems that both have Oracle Workflow installed. For communication between a Workflow-enabled system and a non-Workflow system, you must perform manual steps to store the required destination system and agent information in the source system.
To register a destination system for receiving event messages from a source system, perform the following steps:
Retrieve the local system and inbound agent definitions, which together make up the system identifier information, from the destination system.
Note: The system identifier information includes only the definitions for the system itself and its individual inbound agents. The system identifier does not include agent group definitions.
If Oracle Workflow is installed on the destination system, you can use the Local System Identifier page on the destination system to generate and save an XML document containing the system identifier information. See: To Retrieve Local System Identifier Information.
Note: If you do not have access to the Oracle Workflow installation on the destination system, ask the workflow administrator for that system to perform this step.
If Oracle Workflow is not installed on the destination system, you will need to manually gather the information needed to create definitions for the system and its inbound agents.
Register the destination system identifier information in the Event Manager in the source system.
If Oracle Workflow is installed on both the source system and the destination system, you can use the External System Registration Web page on the source system to register the information by raising the System Signup event with the system identifier XML document from the destination system as the event data. When the System Signup event is raised on the source system, Oracle Workflow executes a predefined subscription that loads the system identifier information to the Event Manager in that system. See: To Register an External System.
Note: If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.
If Oracle Workflow is installed on the source system but not on the destination system, you must manually create system and agent definitions for the destination system in the Event Manager of the source system. See: To Create or Update a System and To Create or Update an Agent.
If Oracle Workflow is not installed on the source system but is installed on the destination system, you must store the system and inbound agent information for the destination system in the source system according to that non-Workflow source system's requirements. You can optionally make use of the system identifier XML document generated by the Local System Identifier page on the destination system, but you must manually perform whatever steps are necessary to store that information in the non-Workflow source system.
Synchronizing systems means replicating all the Event Manager objects that are defined on the source system to the target system. You can use the Synchronize Event Systems event to synchronize two Workflow-enabled systems with each other.
To synchronize systems, perform the following steps:
Register the source and target systems with each other. See: Registering External Systems.
On the source system, copy the predefined subscription to the Seed Event Group with the Local source type and modify the copy as follows.
Specify the inbound agent on the target system that you want to receive the event message, or specify a workflow process that sends the event message to the target system.
Note: If you want to send the event message to more than one target system, you can specify an agent group to receive the event message.
Enable the subscription.
Note: If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.
On the target system, enable the predefined subscription to the Seed Event Group with the External source type.
Note: If you do not have access to the Oracle Workflow installation on the target system, ask the workflow administrator for that system to perform this step.
On the source system, raise the Synchronize Event Systems event (oracle.apps.wf.event.all.sync) using the Test Business Event page for the event. Enter a unique event key, but do not enter any event data. See: To Raise a Test Event.
Note: If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.
When the Synchronize Event Systems event is raised on the source system, it triggers the subscription to the Seed Event Group with the Local source type. The Event Manager generates the event message, which contains the definitions of all the Event Manager objects on the local system, including events, event groups, systems, agents, agent groups, and subscriptions. Then the event message is sent to the specified inbound agent on the target system, or to the specified workflow process that sends the event message to the target system.
When the Synchronize Event Systems event is received on the target system, it triggers the subscription to the Seed Event Group with the External source type. Oracle Workflow loads the object definitions from the event message into the Event Manager on the target system, creating new definitions or updating existing definitions as necessary.
After you enable the predefined subscriptions in steps 2 and 3, these subscriptions will also replicate any subsequent changes you make to Event Manager object definitions on the source system. Whenever you create, update, or delete events, event group members, systems, agents, agent group members, or subscriptions, Oracle Workflow raises the corresponding predefined events. These events trigger the Local subscription to the Seed Event Group on the source system, which sends the object definition data to the target system. The External subscription to the Seed Event Group on the target system receives the data and adds, updates, or deletes the object definition in the Event Manager there.
If you do not want to continue automatically replicating changes on the source system to the target system, you can either disable the subscriptions after you finish synchronizing the systems, or disable the predefined events corresponding to those changes.
If you choose, you can treat one system as a master system that replicates its own Event Manager object definitions to its associated copy systems, but does not accept any object definition changes from those systems. To set up master/copy replication, perform the steps to synchronize the target copy systems with the source master system, as usual. Then, to prevent object definitions from being sent from the copy systems, ensure that the Local subscription to the Seed Event Group on the copy systems is disabled. To prevent object definitions from being received into the master system, ensure that the External subscription to the Seed Event Group on the master system is disabled as well.
Related Topics
To Retrieve Local System Identifier Information
To Register an External System
Synchronize Event Systems Event
To View and Maintain Event Subscriptions
To View and Maintain Systems
Use a Web browser to navigate to the Event Manager, using a responsibility and navigation path specified by your system administrator. Then choose Systems in the horizontal navigation, and choose System Details in the side navigation. See: Oracle Workflow Developer Navigation Paths.
Search for the systems you want to display. The main search option is:
Name - Enter the internal name of the system you want to display. You can enter a partial value to search for systems whose internal names contain that value.
You can also enter the following additional search criteria:
Display Name - Enter the display name of the system you want to display.
Master - Select the master system for the system you want to display.
If you display the local system, its internal name is marked with an asterisk (*).
To view the agents on a system, select the agents icon for that system.
If you have workflow administrator privileges, you can update an agent by selecting the update icon for that agent. See: To Create or Update an Agent.
To view the subscriptions for a system, select the subscription icon for that system.
Note: For systems that do not have any subscriptions, a blank subscription icon appears in the Subscription column. For systems that do have subscriptions, a full subscription icon appears.
If you have workflow administrator privileges, you can define a new subscription for the system by selecting the Create Subscription button. The Create Event Subscription page appears with the system name automatically entered as the subscriber in the System field. See: To Create or Update an Event Subscription.
If you have workflow administrator privileges, you can update an existing subscription by selecting the update icon for that subscription. See: To Create or Update an Event Subscription.
Note: For seeded subscriptions with a customization level of Limit, you can only update the subscription status. For seeded subscriptions with a customization level of Core, you cannot update any properties; you can only view the subscription definition.
If you have workflow administrator privileges, you can use the administration icons and buttons in the System Details page to perform administrative operations.
To update a system, choose the update icon for that system. See: To Create or Update a System.
To delete a system, select the system and select the Delete button.
Note: You can only delete systems that do not have any agents defined on them or any subscriptions referencing them. Also, you cannot delete the local system.
To create a new system definition, select the Create System button. See: To Create or Update a System.
Note: You should use the Create System page only to manually create system definitions for external systems that are not Workflow-enabled. For a Workflow-enabled system, you should use the External System Registration page instead to automatically register the system identifier information. See: Registering External Systems.
To Create or Update a System
Navigate to the Create System page or to the Update System page. The Create System page and the Update System page are identical, except that the fields in the Update System page are populated with previously defined information for the selected system.
Note: You should use the Create System page only to manually create system definitions for external systems that are not Workflow-enabled. For a Workflow-enabled system, you should use the External System Registration page instead to automatically register the system identifier information. See: Registering External Systems.
You can use the Update System page to update both systems that are Workflow-enabled and those that are not.
Enter the internal name of the system in the Name field.
Attention: The internal name must be all-uppercase and should not include any single or double quotation marks (' or ") or spaces.
Enter a display name for the system.
Enter an optional description for the system.
Optionally enter a master system from which you want this system to receive Event Manager object definition updates.
To Retrieve Local System Identifier Information
Use a Web browser to navigate to the Event Manager on the system you want to register as a destination system, using a responsibility and navigation path specified by your system administrator. Then choose Systems in the horizontal navigation, and choose Local System Identifier in the side navigation. See: Oracle Workflow Developer Navigation Paths.
Note: If you do not have access to the Oracle Workflow installation on the destination system, ask the workflow administrator for that system to perform this step.
Select the Generate button. Oracle Workflow generates the local system identifier XML document, which contains the definitions of the local system and its inbound agents, and displays that document in the XML Content field.
Select the Save button to save the XML document to your file system as an XML file. You can then enter it as the event data when you register this system with a source system. See: To Register an External System.
To Register an External System
Use a Web browser to navigate to the Event Manager on the source system where you want to register a destination system, using a responsibility and navigation path specified by your system administrator. Then choose Systems in the horizontal navigation, and choose External System Registration in the side navigation. See: Oracle Workflow Developer Navigation Paths.
Note: If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.
In the Event Identifier region, specify the identifying information for the System Signup event.
Event Name - Oracle Workflow automatically displays the internal name of the System Signup event, oracle.apps.wf.event.system.signup.
Event Key - Enter an event key that uniquely identifies this instance of the event.
Send Date - Optionally specify the date when the event message is available for dequeuing. If you set the send date to a future date when you raise the event, the event message is placed on the WF_DEFERRED queue, and subscription processing does not begin until the specified date.
In the Event Parameter region, optionally enter any additional parameter name and value pairs to be stored in the parameter list within the event message. You can enter up to 100 parameters.
In the Event Data region, enter the system identifier XML document for the destination system you want to register. See: To Retrieve Local System Identifier Information.
To enter the system identifier information manually, select the Write XML option and paste the XML document into the XML Content field. You can enter up to 4000 characters.
To upload the system identifier XML file from your file system, select the Upload XML option and select the Upload XML File button. In the Upload XML File page, enter the full path and file name of the XML file containing the system identifier information, and select the Upload File button.
You can also choose the View link to view the XML file if you have already specified one, or choose the Clear button to remove the previously specified file and enter a different file.
Note: You must provide the system identifier information in order to register a system. You cannot leave the event data XML content blank.
Choose the Submit button to raise the System Signup event to the Event Manager. When the System Signup event is raised, Oracle Workflow executes a predefined subscription that loads the system identifier information from the event data to the Event Manager. See: System Signup Event.
You can test your Business Event System setup using the Workflow Agent Ping/Acknowledge workflow. This workflow sends a ping event message to each inbound agent on the local system or on external systems, and waits to receive an acknowledgement event message from each of the agents. If the workflow completes successfully, then the basic Business Event System setup for communication with these agents is complete.
Use the Launch Processes Web page to launch the Workflow Agent Ping/Acknowledge workflow. This workflow consists of two processes, the Master Ping process and the Detail Ping process. To ping all inbound agents, select the Master Ping process, and enter a unique item key. See: Testing Workflow Definitions.
Note: The item key for a process instance can only contain single-byte characters. It cannot contain a multibyte value.
When you launch the Master Ping process, the Workflow Engine identifies all the inbound agents that you have defined on the local system or on external systems and launches a Detail Ping process for each agent. The master process then waits for each detail process to complete.
The Detail Ping process begins by sending a Ping Agent event to the inbound agent identified by the master process. The detail process places a Ping Agent event message on a queue associated with an outbound agent on the local system. The event message is addressed to the inbound agent and contains a correlation ID that identifies the detail process to which it belongs. AQ propagation transmits the event message from the outbound queue to the queue associated with the specified inbound agent.
On the receiving system, the listener for the inbound agent dequeues the Ping Agent message the next time it runs. When the event message is dequeued, the Event Manager searches for and executes any active subscriptions to the Ping Agent event or the Any event on that system that have a source type of External.
When the predefined External subscription to the Ping Agent event is executed, its rule function places an Acknowledge Ping event message on a queue associated with an outbound agent on that system. The event message is addressed to an inbound agent on the originating system and includes the correlation ID from the Ping Agent event message. AQ propagation transmits the Acknowledge Ping event message from the outbound queue to the queue associated with the specified inbound agent.
On the originating system, the listener for the inbound agent dequeues the Acknowledge Ping message the next time it runs. When the event message is dequeued, the Event Manager searches for and executes any active subscriptions to the Acknowledge Ping event or the Any event on that system that have a source type of External.
When the predefined External subscription to the Acknowledge Ping event is executed, its rule function, which is the default rule function, sends the event message to the Detail Ping process. The Workflow Engine uses the correlation ID to match the message with the running detail process to which it belongs. After receiving the event message, the Detail Ping process completes.
Finally, after all the detail processes are complete, the master process also completes.
You can use the Workflow Monitor to check the progress of the Workflow Agent Ping/Acknowledge workflow. You can also use Oracle Workflow Manager to confirm the processing of the Ping Agent and Acknowledge Ping event messages. See: Workflow Monitor, Oracle Workflow Administrator's Guide and the Oracle Workflow Manager online help.
The amount of time needed to complete the Workflow Agent Ping/Acknowledge workflow depends on how often the listeners run to dequeue messages from the inbound agents. See: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide.
Related Topics
The Workflow Agent Ping/Acknowledge process is associated with an item type called Workflow Agent Ping/Acknowledge. Currently there are two workflow processes associated with Workflow Agent Ping/Acknowledge: Master Ping Process and Detail Ping Process.
To view the details of the Workflow Agent Ping/Acknowledge item type in the Workflow Builder, choose Open from the File menu. Then connect to the database and select the Workflow Agent Ping/Acknowledge item type, or connect to a file called wfping.wft in the <ORACLE_HOME>\wf\Data\<language> directory on your file system.
If you examine the property page of Workflow Agent Ping/Acknowledge, you see that it has a persistence type of Temporary and persistence number of days of 0. This means that the runtime data associated with any work items for this item type are eligible for purging as soon as they complete.
The Workflow Agent Ping/Acknowledge item type also has several attributes associated with it. These attributes reference information in the Workflow application tables. The attributes are used and maintained by function activities as well as event activities throughout the process. The following table lists the Workflow Agent Ping/Acknowledge item type attributes.
| Display Name | Description | Type | Length/Format/Lookup Type |
|---|---|---|---|
| To Agent | The inbound agent that receives the event message, in the format <agent>@<system> | Text | |
| Event Name | The internal name of the event | Text | |
| Out Agent | The outbound agent that sends the event message, in the format <agent>@<system> | Text | |
| Event Key | The event key that uniquely identifies the specific instance of the event | Text | |
| Event Message | The event message | Event |
To view the properties of the Master Ping process, select the process in the navigator tree, and then choose Properties from the Edit menu. This process activity is runnable, indicating that it can be initiated as a top level process to run.
When you display the Process window for the Master Ping process, you see that the process consists of four unique activities. To examine the activities of the process in more detail, we have numbered each node for easy referencing below. The numbers themselves are not part of the process diagram.
Master Ping Process Diagram
The Workflow Agent Ping/Acknowledge workflow begins when you launch the Master Ping Process using the Launch Processes Web page. You can optionally provide a to agent, event name, out agent, event key, and event message. See: Testing Workflow Definitions.
The workflow begins at node 1 with the Start activity. At node 2, the master process spawns a detail process for each inbound agent that you have defined on the local system or on external systems. The detail process pings the agent by sending it a Ping Agent event and waits to receive an acknowledgement in the form of an Acknowledge Ping event.
Node 3 is a Wait for Flow activity that waits for all the detail processes to complete. When all the detail processes have completed, the master process ends.
Following is a description of each activity in the process, listed by the activity's display name.
This Standard function activity marks the start of the process.
| Variable | Description |
|---|---|
| Function | WF_STANDARD.NOOP |
| Result Type | None |
| Prerequisite Activities | None |
This function activity identifies all the inbound agents that you have defined on the local system or external systems, and spawns a Detail Ping process for each agent. The function sets the Ping Agent event (oracle.apps.wf.event.test.ping) as the event to be sent to the Detail Ping processes.
| Variable | Description |
|---|---|
| Function | WF_EVENT_PING_PKG.LAUNCH_PROCESSES |
| Result Type | None |
| Prerequisite Activities | None |
| Item Attributes Set by Function | Event Name, To Agent |
This Standard function activity pauses the flow until the corresponding detail processes complete a specified activity.
| Variable | Description |
|---|---|
| Function | WF_STANDARD.WAITFORFLOW |
| Result Type | None |
| Prerequisite Activities | Spawn Detail Processes |
This Standard function activity marks the end of the process.
| Variable | Description |
|---|---|
| Function | WF_STANDARD.NOOP |
| Result Type | None |
| Prerequisite Activities | Wait for Flow |
To view the properties of the Detail Ping process, select its process activity in the navigator tree, and then choose Properties from the Edit menu. This process activity is runnable, indicating that it can be initiated as a top level process to run.
When you display the Process window for the Detail Ping process, you see that the process consists of five unique activities. To examine the activities of the process in more detail, we have numbered each node for easy referencing below. The numbers themselves are not part of the process diagram.
Detail Ping Process Diagram
The Detail Ping process begins when it is launched by the Master Ping process. See: Summary of the Master Ping Process.
The workflow begins at node 1 with the Start activity. At node 2, the process sends a Ping Agent event to the selected inbound agent. At node 3, the process waits to receive an Acknowledge Ping event back from the agent. When the acknowledgement is received, the master process can continue. The detail process ends at this point.
Following is a description of each activity in the process, listed by the activity's display name.
This Standard function activity marks the start of the process.
| Variable | Description |
|---|---|
| Function | WF_STANDARD.NOOP |
| Result Type | None |
| Prerequisite Activities | None |
This event activity sends the Ping Agent event (oracle.apps.wf.event.test.ping) from an outbound agent on the local system to the inbound agent identified by the master process. The event message includes a correlation ID that identifies the detail process to which it belongs.
| Variable | Description |
|---|---|
| Event Action | Send |
| Prerequisite Activities | None |
| Item Attributes Retrieved by Activity | Event Message, Event Name, Event Key, To Agent |
This event activity receives the Acknowledge Ping event (oracle.apps.wf.event.test.ack) that is returned to the originating system from the system that received the Ping Agent event. The Acknowledge Ping event message contains the correlation ID, which the Workflow Engine uses to match the event message with the detail process to which it belongs.
| Variable | Description |
|---|---|
| Event Action | Receive |
| Event Filter | oracle.apps.wf.event.test.ack |
| Prerequisite Activities | Send Event |
| Item Attributes Set by Activity | Event Name, Event Key, Event Message |
This Standard function activity marks the position in the detail process where, upon completion, the corresponding halted master process will continue.
| Variable | Description |
|---|---|
| Function | WF_STANDARD.CONTINUEFLOW |
| Result Type | None |
| Prerequisite Activities | Receive Event |
This Standard function activity marks the end of the process.
| Variable | Description |
|---|---|
| Function | WF_STANDARD.NOOP |
| Result Type | None |
| Prerequisite Activities | Continue Flow |
