Skip Headers

Oracle Workflow Developer's Guide
Release 2.6.4

Part Number B15853-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

Skip Headers

Oracle Workflow Developer's Guide
Release 2.6.4
Part Number B15853-01
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Managing Business Events

Managing Business Events

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:

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:

Event Manager for Standalone Oracle Workflow

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

Events

Systems

Agents

Event Subscriptions

Raising Events

Signing Up Systems

Synchronizing Systems

Workflow Agent Ping/Acknowledge

Events

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:

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:

See: Access Protection for Business Event System Data, Oracle Workflow Administrator's Guide.

Related Topics

To Define an Event

To Define an Event Group

To Find Events

To Update or Delete an Event

Defining Events

To Define an Event

  1. 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.

  2. 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

    the picture is described in the document text

  3. 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> 
    
    
  4. Enter a Display Name for the event. This name appears in the Events list.

  5. Enter an optional description for the event.

  6. 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.

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

  8. 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.

  9. You can review the customization level for the event.

  10. 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

  1. 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.

  2. 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

    the picture is described in the document text

  3. 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> 
    
    
  4. Enter a Display Name for the event group. This name appears in the Events list.

  5. Enter an optional description for the event group.

  6. 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.

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

  8. You can review the customization level for the event group.

  9. 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.

  10. 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

    the picture is described in the document text

  11. In the Add to Group page that appears, enter search criteria to locate the event you want to add. The search criteria are:

  12. Choose the Go button. The Add to Group page displays a list of events that match your search criteria.

  13. 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.

  14. 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.

  15. 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.

  16. 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.

  17. 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.

  18. 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.

  19. 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

  1. 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 picture is described in the document text

  2. The Find Event/Group page appears. The Find Event/Group page lets you enter search criteria to locate specific events. The search criteria are:

  3. Choose the Go button. The Events page appears, displaying a list of events that match your search criteria.

To Update or Delete an Event

  1. 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.

  2. 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.

  3. 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.

  4. 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.

Systems

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.

Local System

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.

Local System Properties
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

To Find Systems

To Update or Delete a System

Defining Systems

To Define a System

  1. 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 picture is described in the document text

  2. 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

    the picture is described in the document text

  3. 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.

  4. Enter a Display Name for the system. This name appears in the Systems list.

  5. Enter an optional description for the system.

  6. 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.

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

  1. 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 picture is described in the document text

  2. The Find System page appears. The Find System page lets you enter search criteria to locate specific systems. The search criteria are:

  3. 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

  1. 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

    the picture is described in the document text

  2. 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.

  3. 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.

  4. 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

  1. For a field that supports a list of values, click on the field's up-arrow icon to display a list of values window.

  2. 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.

  3. 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.

Agents

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.

Assigning a Direction to an Agent

When you define an agent in the Event Manager, you must specify the direction of communication that the agent supports on its local system.

Assigning a Protocol to an Agent

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:

  1. Define AQ queues to hold pending inbound and outbound messages.

  2. Provide code that propagates messages to and from the AQ queues.

  3. 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.

  4. 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.

Assigning a Queue to an Agent

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.

Standard Agents

When you install Oracle Workflow, several standard agents are automatically defined for the Business Event System.

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.

WF_CONTROL Agent Properties
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.

WF_DEFERRED Agent Properties
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.

WF_ERROR Agent Properties
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.

WF_IN Agent Properties
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.

WF_JMS_IN Agent Properties
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.

WF_JMS_OUT Agent Properties
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.

WF_NOTIFICATION_IN Agent Properties
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.

WF_NOTIFICATION_OUT Agent Properties
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.

WF_OUT Agent Properties
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

To Find Agents

To Update or Delete an Agent

Defining Agents

To Define an Agent

  1. 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 picture is described in the document text

  2. 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.

  3. 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.

  4. Enter a Display Name for the agent.

  5. Enter an optional description for the agent.

  6. Select the message communication protocol that the agent supports.

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

  8. 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.

  9. 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.

  10. 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.

  11. 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.

  12. 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.

  13. 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

  1. 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 picture is described in the document text

  2. The Find Agent page appears. The Find Agent page lets you enter search criteria to locate specific agents. The search criteria are:

  3. Choose the Find button. The Agents page appears, displaying a list of agents that match your search criteria.

To Update or Delete an Agent

  1. 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

    the picture is described in the document text

  2. 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.

  3. 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.

Event Subscriptions

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

When you install Oracle Workflow, several default subscriptions to predefined Workflow events are automatically created. You can 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:

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.

Defining the Subscriber

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

Each subscription defines an action on exactly one system, so you should define a separate subscription for each system involved in the processing you want to perform. For example, if you want to propagate data from one system to another, you should define one subscription for the sending system, and another subscription for the receiving system.

Defining How a Subscription is Triggered

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

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

You can also optionally restrict the subscription to be triggered only by events received from a specific source agent. However, in most cases you do not need to specify a source agent.

Controlling How a Subscription is Executed

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.

Defining the Action for a Subscription

Subscription processing can include the following types of processing:

Running a Rule Function

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

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

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:

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:

A rule function may read or write to the event message or perform any other database action. However, you should never commit within a rule function. The Event Manager never issues a commit as it is the responsibility of the calling application to commit. Additionally, the function must not change the connection context in any way, including security and NLS settings. If a rule function returns an error, subscription processing is halted.

If the subscription processing that you want to perform for an event includes several successive steps, you may find it advantageous to define multiple subscriptions to the event with simple rule functions that you can reuse, rather than creating complex specialized rule functions that cannot be reused. You can enter phase values for the subscriptions to specify the order in which they should be executed.

Note: If you enter a rule function other than one of the default functions, you can still enter workflow and agent information for your function to reference, but Oracle Workflow does not automatically send the event message to the specified workflow and agent. Instead, you must either explicitly include the send processing in your rule function, or define a separate subscription that does use the default rule function to perform the send processing.

Sending the Event to a Workflow Process

By sending an event to a workflow process, you can model complex processing or routing logic beyond the options of directly running a predefined function or sending the event to a predefined recipient. For example, you can branch to different functions, initiate subprocesses, send notifications, or select recipient agents, based on the contents of the event message, or modify the event message itself.

Events are represented within workflow processes by event activities. See: Event Activity.

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

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

Note: You can call WF_EVENT_FUNCTIONS_PKG.AddCorrelation() during subscription processing to add a correlation ID to the event message. To use AddCorrelation(), you must enter a subscription parameter named ITEMKEY that specifies a function to generate the correlation ID. The function must be specified in the following format:

ITEMKEY=<package_name.function_name> 

See: AddCorrelation, Oracle Workflow API Reference.

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

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

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

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

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

Sending the Event to an Agent

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 want an event message to become available to the recipient at a future date, rather than being available immediately as soon as it is propagated, you can set the SEND_DATE attribute within the event message to the date you want. You should set the send date during subscription processing before the event is sent, either in a prior subscription or earlier in the rule function before the send processing. The event message is propagated to the To Agent but does not become available for dequeuing until the specified date.

Documenting Identifying Information for a Subscription

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:

See: Access Protection for Business Event System Data, Oracle Workflow Administrator's Guide.

Deferred Subscription Processing

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:

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.

Deferring Subscription Processing Using a Future Send Date

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

When an event is raised with a future send date, the Event Manager immediately places the event message on the WF_DEFERRED queue, without executing any of the subscriptions for the event. All subscriptions to the event are deferred, regardless of their phase number. The event remains in a WAIT state until the send date. When the send date arrives, the event message becomes available for dequeuing and will be dequeued the next time an agent listener runs on the WF_DEFERRED queue. The amount of time by which subscription processing is deferred depends on the send date you specify as well as on the schedule defined for the listener.

When the listener dequeues the event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If the event message does not contain a subscription ID, meaning that all subscription processing for the event was deferred immediately after the event was raised, then the Event Manager proceeds to execute all subscriptions to the event, in ascending phase order.

Note: If an event was deferred when it was raised, the Event Manager executes all eligible subscriptions to the event when the event is dequeued from the WF_DEFERRED queue, regardless of the subscription phase numbers. Subscriptions will not be deferred a second time, even if they have a phase number of 100 or higher.

See: Raise, Oracle Workflow API Reference.

Deferring Subscription Processing Using Subscription Phase Numbers

You can also use the phase number for a subscription to control whether the subscription is executed immediately or is deferred. The Event Manager treats subscriptions with a phase number of 100 or higher as deferred subscriptions. Both Local and External subscriptions can be deferred in this way.

Note: For this deferral method to take effect when an event is raised locally, the event must not be raised with a future send date, and the Event Manager must be in the normal synchronous mode for subscription processing. Otherwise, the event message will immediately be placed on the WF_DEFERRED queue, and the Event Manager will not execute any subscriptions until the event is dequeued from there.

When a triggering event is raised or received, the Event Manager executes subscriptions to that event in phase order until it encounters a subscription with a phase number of 100 or higher. The Event Manager sets that subscription into the ERROR_SUBSCRIPTION attribute within the event message, as well as setting the priority specified in the subscription properties into the PRIORITY attribute. Then the event message is placed on the standard WF_DEFERRED queue.

The amount of time by which subscription processing is deferred depends on the schedule defined for the agent listener monitoring the WF_DEFERRED agent. When the listener dequeues an event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If a subscription ID is present, meaning that subscription processing was deferred from that subscription onwards, the Event Manager begins by executing that subscription, and then continues executing any other subscriptions to the event with the same or a higher phase number.

Note: The Event Manager resumes subscription processing at the phase number of the subscription set into the event message. It does not necessarily begin with the phase number 100, if there were no subscriptions with that phase number when the event was originally processed.

Deferring Subscription Processing Using the Event Manager Dispatch Mode

If you raise an event from a local application, you can also choose to defer all subscription processing for that event every single time it is raised. To do so, call the SetDispatchMode() API with the mode 'ASYNC', indicating deferred (asynchronous) processing, just before calling the Raise() API. See: SetDispatchMode, Oracle Workflow API Reference.

This method is not recommended, however, and should only be used in exceptional circumstances, since it requires hard-coding the deferral in your application. To retain the flexibility to modify subscription processing without intrusion into the application, you can simply raise the event with a future send date or mark some or all of the individual subscriptions for deferral using the subscription phase numbers.

When an event is raised after the dispatch mode is set to deferred processing, the Event Manager immediately places the event message on the WF_DEFERRED queue, without executing any of the subscriptions for the event. All subscriptions to the event are deferred, regardless of their phase number.

The amount of time by which subscription processing is deferred depends on the schedule defined for the agent listener monitoring the WF_DEFERRED agent. When the listener dequeues the event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If the event message does not contain a subscription ID, meaning that all subscription processing for the event was deferred immediately after the event was raised, then the Event Manager proceeds to execute all subscriptions to the event, in ascending phase order.

Note: If an event was deferred when it was raised, the Event Manager executes all eligible subscriptions to the event when the event is dequeued from the WF_DEFERRED queue, regardless of the subscription phase numbers. Subscriptions will not be deferred a second time, even if they have a phase number of 100 or higher.

Related Topics

To Define an Event Subscription

To Find Event Subscriptions

To Update or Delete an Event Subscription

Standard API for an Event Subscription Rule Function

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

Defining Event Subscriptions

To Define an Event Subscription

  1. 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 picture is described in the document text

  2. 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.

  3. 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.

  4. In the Triggering Condition region, specify the type of source system to which the subscription applies in the Source Type field.

  5. 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.

  6. 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.

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

  8. 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.

  9. In the Rule Data field, specify the event information required by the subscription.

  10. In the Action region, define the subscription processing you want to perform when the triggering event occurs. Subscription processing can include:

  11. 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.

  12. 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.

  13. 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.

    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.

  14. 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.

  15. 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.

  16. 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.

  17. You can review the customization level for the subscription.

  18. Enter an optional description for the subscription.

  19. 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

  1. 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 picture is described in the document text

  2. The Find Subscription page appears. The Find Subscription page lets you enter search criteria to locate specific event subscriptions. The search criteria are:

  3. 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

  1. 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

    the picture is described in the document text

  2. 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.

  3. 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.

Raising Events

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

  1. 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.

  2. The Raise Event page appears.

  3. In the Event Name field, select the event that you want to raise.

  4. Enter an event key that uniquely identifies this instance of the event.

  5. 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.

  6. 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.

Signing Up Systems

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:

  1. 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.

  2. 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

  1. 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.

  2. 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

  1. 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.

  2. The System Signup page appears, displaying the internal name of the System Signup event.

  3. Enter an event key that uniquely identifies this instance of the event.

  4. Copy the XML document containing the destination system identifier information into the Event Data field. See: To Retrieve System Identifier Information.

  5. 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

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

  1. Sign up the source and target systems with each other. See: Signing Up Systems.

  2. On the source system, copy the predefined subscription to the Seed Event Group with the Local source type and modify the copy as follows.

  3. 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.

  4. 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

Predefined Workflow Events

Synchronize Event Systems Event

Seed Event Group

To Define an Event Subscription

Event Manager for Oracle Applications

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:

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

Events

Event Subscriptions

Agents

Systems

Events

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.

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:

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.

Event Groups

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 View and Maintain Events

To Create or Update an Event

To Create or Update an Event Group

To Raise a Test Event

Defining Events

To View and Maintain Events

  1. 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.

  2. Search for the events you want to display. The main search option is:

    You can also enter the following additional search criteria:

  3. 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.

  4. If you have workflow administrator privileges, you can use the administration icons and buttons in the Events page to perform administrative operations.

To Create or Update an Event

  1. 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.

  2. 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> 
    
  3. Enter a display name for the event.

  4. Enter an optional description for the event.

  5. 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.

  6. 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.

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

  8. Review the customization level for the event.

To Create or Update an Event Group

  1. 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.

  2. 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> 
    
  3. Enter a display name for the event group.

  4. Enter an optional description for the event group.

  5. 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.

  6. 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.

  7. Review the customization level for the event group.

  8. Select the Apply button to save the event group definition.

  9. 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.

  10. In the Add Events to Group page, search for the events you want to add. The main search option is:

    You can also enter the following additional search criteria.

  11. Select the event or events that you want to add to your event group, and select the Add to Group button.

  12. You can optionally enter new search criteria to search for other events to add to the event group.

  13. After you finish adding events to the event group, select the Apply button to save the event group members.

  14. 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

  1. Navigate to the Test Business Event page.

  2. In the Event Identifier region, specify the event you want to raise.

  3. 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.

  4. 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.

Event Subscriptions

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

When you install Oracle Workflow, several default subscriptions to predefined Workflow events are automatically created. You can 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:

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.

Defining the Subscriber

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

Each subscription defines an action on exactly one system, so you should define a separate subscription for each system involved in the processing you want to perform. For example, if you want to propagate data from one system to another, you should define one subscription for the sending system and another subscription for the receiving system.

Defining How a Subscription is Triggered

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

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

You can also optionally restrict the subscription to be triggered only by events received from a specific source agent. However, in most cases you do not need to specify a source agent.

Controlling How a Subscription is Executed

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:

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.

Defining the Action for a Subscription

Subscription processing can include the following types of processing:

Sending the Event to a Workflow Process

By sending an event to a workflow process, you can model complex processing or routing logic beyond the 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 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:

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.

Sending the Event to an Agent

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.

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

Sending a Notification

If the only processing you need to perform when an event occurs is sending a notification, you can define a subscription that simply performs that action. In this case you do not need to define and run a complete workflow process to send the notification.

However, you must specify a message template for the notification you want to send. The message template must be a message defined within an item type in the Workflow Builder and stored in your database. You can either select a standard message provided by Oracle Applications or define a custom message.

You must also specify the role that should receive the notification. The notification will appear in the recipient's worklist.

You can optionally specify a custom callback function you want the Notification System to use for communication of SEND and RESPOND source message attributes. Otherwise, Oracle Workflow uses a standard default callback function. See: Custom Callback Function, Oracle Workflow API Reference.

You can also optionally enter context information that you want to pass to the callback function. With the standard Oracle Workflow callback function, the Notification System requires a context to obtain values for item type attributes. If you do not specify a context, do not reference any item type attributes in the message attributes. Otherwise the message body will not display correctly. The context information consists of the item type, item key, and activity ID in the following format:

<itemtype>:<itemkey>:<activityid>

If you specify a custom callback function, then you can enter the context information that is appropriate for your function.

You can also optionally enter a comment to include with the message, a due date, and a priority for the message.

After sending the notification, the Event Manager sets the notification ID into the event parameter list as a parameter named #NID. If you want to use the notification ID in further processing, raise the event using WF_EVENT.Raise3(), which returns the event parameter list after the Event Manager completes subscription processing for the event. You can then call WF_EVENT.GetValueForParameter() to obtain the value of the #NID parameter. See: Raise3, Oracle Workflow API Reference and GetValueForParameter, Oracle Workflow API Reference.

For example, if the notification requires a response, you can retrieve the response values from the user's reply by obtaining the notification ID and using it to call WF_NOTIFICATION.GetAttrText(), WF_NOTIFICATION.GetAttrNumber(), or WF_NOTIFICATION.GetAttrDate() for the RESPOND attributes. See: GetAttribute, Oracle Workflow API Reference.

See: SendNotification, Oracle Workflow API Reference.

Receiving and Sending Oracle XML Gateway Messages

If you use Oracle XML Gateway, you can define subscriptions either to receive an Oracle XML Gateway message from your trading partner, or to generate an Oracle XML Gateway message and send the message to your trading partner. Oracle Workflow and Oracle XML Gateway provide these actions to support business-to-business (B2B) integration scenarios.

The event that triggers such a subscription must include the trading partner information within its event parameter list. Oracle XML Gateway then uses a standard workflow process defined in the XML Gateway Standard item type to send or receive the message.

You can optionally specify the priority with which the recipient should dequeue a message. Messages are dequeued in ascending priority order.

See: XML Gateway Standard Item Type, Oracle XML Gateway User's Guide.

Running a Custom Rule Function

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:

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.

Documenting Identifying Information for a Subscription

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.

Deferred Subscription Processing

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:

Note: Additionally, if an event is raised by PL/SQL code or received by a PL/SQL agent listener, the Event Manager always defers processing of any Java subscriptions to the event, regardless of their phase numbers.

When subscription processing for an event is deferred by any of these methods, the event message is placed on a standard deferred agent. If the subscription at which processing is deferred is a PL/SQL subscription, the event is placed on the standard WF_DEFERRED agent. If the subscription at which processing is deferred is a Java subscription, the event is placed on the standard WF_JAVA_DEFERRED agent. You must ensure that agent listeners are running to monitor the WF_DEFERRED and WF_JAVA_DEFERRED agents. See: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide.

The listener dequeues event messages from the WF_DEFERRED agent or WF_JAVA_DEFERRED agent in priority order. The event messages retain their original source type, whether Local or External. The amount of time by which subscription processing for these events is deferred depends on the schedule defined for the listener, and, for future-dated events, on the specified effective date.

Note: If an event was deferred when the Event Manager encountered a Java subscription during subscription processing in the database, the Event Manager executes all remaining subscriptions to the event when the event is dequeued from the WF_JAVA_DEFERRED queue, including both Java and PL/SQL subscriptions, regardless of the subscription phase numbers. Subscriptions will not be deferred a second time.

Deferring Subscription Processing Using a Future Send Date

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.

Deferring Subscription Processing Using Subscription Phase Numbers

You can also use the phase number for a subscription to control whether the subscription is executed immediately or is deferred. The Event Manager treats subscriptions with a phase number of 100 or higher as deferred subscriptions. Both Local and External subscriptions can be deferred in this way.

Note: For this deferral method to take effect when an event is raised locally, the event must not be raised with a future send date, and the Event Manager must be in the normal synchronous mode for subscription processing. Otherwise, the event message will immediately be placed on the deferred queue, and the Event Manager will not execute any subscriptions until the event is dequeued from there.

When a triggering event is raised or received, the Event Manager executes subscriptions to that event in phase order until it encounters a subscription with a phase number of 100 or higher. The Event Manager sets that subscription into the ERROR_SUBSCRIPTION attribute within the event message, as well as setting the priority specified in the subscription properties into the PRIORITY attribute. Then the event message is placed on the appropriate deferred queue.

Note: Additionally, if an event is raised by PL/SQL code or received by a PL/SQL agent listener, and the Event Manager encounters a Java subscription to the event, it always defers the remaining subscription processing beginning with that subscription, regardless of the subscription phase number.

The amount of time by which subscription processing is deferred depends on the schedule defined for the agent listener monitoring the WF_DEFERRED or WF_JAVA_DEFERRED agent. When the listener dequeues an event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If a subscription ID is present, meaning that subscription processing was deferred from that subscription onwards, the Event Manager begins by executing that subscription, and then continues executing any other subscriptions to the event with the same or a higher phase number.

Note: The Event Manager resumes subscription processing at the phase number of the subscription set into the event message. It does not necessarily begin with the phase number 100, if there were no subscriptions with that phase number when the event was originally processed.

Deferring Subscription Processing Using the Event Manager Dispatch Mode

If you raise an event from a local application in PL/SQL code, you can also choose to defer all subscription processing for that event every single time the application raises it. To do so, call the SetDispatchMode() API with the mode 'ASYNC', indicating deferred (asynchronous) processing, just before calling the Raise() API. See: SetDispatchMode, Oracle Workflow API Reference.

This method is not recommended, however, and should only be used in exceptional circumstances, since it requires hard-coding the deferral in your application. To retain the flexibility to modify subscription processing without intrusion into the application, you can simply raise the event with a future send date or mark some or all of the individual subscriptions for deferral using the subscription phase numbers.

When an event is raised after the dispatch mode is set to deferred processing, the Event Manager immediately places the event message on the WF_DEFERRED queue, without executing any of the subscriptions for the event. All subscriptions to the event are deferred, regardless of their phase number.

The amount of time by which subscription processing is deferred depends on the schedule defined for the agent listener monitoring the WF_DEFERRED agent. When the listener dequeues the event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If the event message does not contain a subscription ID, meaning that all subscription processing for the event was deferred immediately after the event was raised, then the Event Manager proceeds to execute all subscriptions to the event, in ascending phase order.

Note: If an event was deferred when it was raised, the Event Manager executes all eligible subscriptions to the event when the event is dequeued from the WF_DEFERRED queue, regardless of the subscription phase numbers. Subscriptions will not be deferred a second time, even if they have a phase number of 100 or higher.

Subscription Processing for PL/SQL and Java Subscriptions

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.

Defining Event Subscriptions

To View and Maintain Event Subscriptions

  1. 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.

  2. Search for the subscriptions you want to display. The main search option is:

    You can also enter the following additional search criteria.

  3. If you have workflow administrator privileges, you can use the administration icons and buttons to perform administrative operations.

To Create or Update an Event Subscription

  1. 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.

  2. In the Subscriber region, select the system where the subscription executes.

  3. In the Triggering Event region, specify the event source to which the subscription applies in the Source Type field.

  4. Select the event that triggers the subscription in the Event Filter field. You can specify an individual event or an event group.

  5. 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.

  6. 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.

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

  8. In the Rule Data field, specify the event information required by the subscription.

  9. In the Action Type region, select the subscription processing you want to perform when the triggering event occurs.

  10. 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.

    See: Error Handling for Event Subscription Processing.

  11. Choose the Next button to define the details of the subscription action, depending on the action type you selected.

  12. If you selected Launch Workflow as the action type, enter the following details.

  13. If you selected Send to Agent as the action type, enter the following details.

  14. If you selected Send Notification as the action type, enter the following details.

  15. 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.

  16. If you selected Custom as the action type, enter the following details.

  17. 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.

  18. Review the customization level for the subscription.

  19. Enter an optional description for the subscription.

Agents

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.

Assigning a Direction to an Agent

When you define an agent in the Event Manager, you must specify the direction of communication that the agent supports on its local system.

Assigning a Protocol to an Agent

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:

  1. Define AQ queues to hold pending inbound and outbound messages.

  2. Provide code that propagates messages to and from the AQ queues.

  3. 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.

  4. 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.

Assigning a Queue to an Agent

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.

Agent Groups

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.

Standard Agents

When you install Oracle Workflow, several standard agents are automatically defined for the Business Event System.

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.

WF_CONTROL Agent Properties
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.

WF_DEFERRED Agent Properties
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.

WF_ERROR Agent Properties
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.

WF_JAVA_DEFERRED Agent Properties
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.

WF_JAVA_ERROR Agent Properties
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.

WF_IN Agent Properties
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.

WF_JMS_IN Agent Properties
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.

WF_JMS_OUT Agent Properties
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.

WF_NOTIFICATION_IN Agent Properties
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.

WF_NOTIFICATION_OUT Agent Properties
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.

WF_OUT Agent Properties
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.

WF_WS_JMS_IN Agent Properties
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.

WF_WS_JMS_OUT Agent Properties
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

Agents on External Systems

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.

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.

  1. 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.

  2. 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.

Related Topics

To View and Maintain Agents

To Create or Update an Agent

To Create or Update an Agent Group

Defining Agents

To View and Maintain Agents

  1. 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.

  2. Search for the agents you want to display. The main search option is:

    You can also enter the following additional search criteria.

  3. If you have workflow administrator privileges, you can use the administration icons and buttons to perform administrative operations.

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

  1. 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.

  2. 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.

  3. Enter a display name for the agent.

  4. Enter an optional description for the agent.

  5. Select the message communication protocol that the agent supports.

  6. 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.

  7. Select the system in which the agent is defined.

  8. 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.

    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.

  9. 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.

  10. 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.

  11. 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

  1. 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.

  2. 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.

  3. Enter a display name for the agent group.

  4. Enter an optional description for the agent group.

  5. 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.

  6. 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.

  7. Select the Apply button to save the agent group definition.

  8. 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.

  9. In the Add Agents to Group page, search for the agents you want to add. The main search option is:

    You can also enter the following additional search criteria.

  10. Select the agent or agents that you want to add to your agent group, and select the Add Agents to Group button.

  11. You can optionally enter new search criteria to search for other agents to add to the agent group.

  12. After you finish adding agents to the agent group, select the Apply button to save the agent group members.

  13. 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.

Systems

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.

Local System

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.

Local System Properties
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.

Registering External Systems

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:

  1. 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.

  2. Register the destination system identifier information in the Event Manager in the source system.

Synchronizing Systems

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:

  1. Register the source and target systems with each other. See: Registering External Systems.

  2. On the source system, copy the predefined subscription to the Seed Event Group with the Local source type and modify the copy as follows.

  3. 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.

  4. 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.

Automatic Replication

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.

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

To View and Maintain Systems

To Create or Update a System

To Retrieve Local System Identifier Information

To Register an External System

Predefined Workflow Events

Synchronize Event Systems Event

Seed Event Group

To View and Maintain Event Subscriptions

Defining Systems

To View and Maintain Systems

  1. 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.

  2. Search for the systems you want to display. The main search option is:

    You can also enter the following additional search criteria:

    If you display the local system, its internal name is marked with an asterisk (*).

  3. 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.

  4. 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.

  5. If you have workflow administrator privileges, you can use the administration icons and buttons in the System Details page to perform administrative operations.

To Create or Update a System

  1. 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.

  2. 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.

  3. Enter a display name for the system.

  4. Enter an optional description for the system.

  5. Optionally enter a master system from which you want this system to receive Event Manager object definition updates.

To Retrieve Local System Identifier Information

  1. 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.

  2. 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.

  3. 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

  1. 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.

  2. In the Event Identifier region, specify the identifying information for the System Signup event.

  3. 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.

  4. 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.

    Note: You must provide the system identifier information in order to register a system. You cannot leave the event data XML content blank.

  5. 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.

Workflow Agent Ping/Acknowledge

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.

How Workflow Agent Ping/Acknowledge Works

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

Ping Agent Events

The Workflow Agent Ping/Acknowledge Item Type

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.

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  

Summary of the Master Ping Process

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 picture is described in the document text

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.

Master Ping Process Activities

Following is a description of each activity in the process, listed by the activity's display name.

Start (Node 1)

This Standard function activity marks the start of the process.

Variable Description
Function WF_STANDARD.NOOP
Result Type None
Prerequisite Activities None

Spawn Detail Processes (Node 2)

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

Wait for Flow (Node 3)

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

End (Node 4)

This Standard function activity marks the end of the process.

Variable Description
Function WF_STANDARD.NOOP
Result Type None
Prerequisite Activities Wait for Flow

Summary of the Detail Ping Process

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 picture is described in the document text

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.

Detail Ping Process Activities

Following is a description of each activity in the process, listed by the activity's display name.

Start (Node 1)

This Standard function activity marks the start of the process.

Variable Description
Function WF_STANDARD.NOOP
Result Type None
Prerequisite Activities None

Send Event (Node 2)

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

Receive Event (Node 3)

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

Continue Flow (Node 4)

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

End (Node 5)

This Standard function activity marks the end of the process.

Variable Description
Function WF_STANDARD.NOOP
Result Type None
Prerequisite Activities Continue Flow