Managing Business Events

This chapter tells you how to manage business events using the Oracle Workflow Event Manager Web pages.

This chapter covers the following topics:

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

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.

Note: To ensure that your customizations are handled appropriately in conjunction with the Online Patching feature introduced in Release 12.2, follow the instructions in Deploying Customizations in Oracle E-Business Suite Release 12.2, My Oracle Support Document 1577661.1.

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, execute custom code, or invoke a Web service.

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 Enterprise Manager online help, Oracle Enterprise Manager Support, Oracle Streams Advanced Queuing User's Guide and Reference, Oracle Workflow Manager Overview, Oracle Workflow 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.

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.

Predefined events are also provided with some Oracle E-Business Suite products. For more information on application-specific workflow events, consult the documentation or help for that specific Oracle E-Business Suite product, the Oracle E-Business Suite Electronic Technical Reference Manual, available from My Oracle Support, and the business event interface information in the Integration Repository. For information about using the Integration Repository, see: Oracle E-Business Suite Integrated SOA Gateway User's Guide.

Defining an Event Name

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.

Defining a Generate Function

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

Generating Service Data Object Metadata

A service data object (SDO) represents a row of data in a service view object (SVO) in Oracle Application Framework. If you want to set the XML metadata for a service data object as the event data for an event, you can define the Java generate function for the event using a special format to retrieve the SDO metadata.

For Oracle Workflow to access the SDO metadata, all Java class files related to the service data object must be available in your CLASSPATH. Additionally, all XML artifacts for the service application module (SAM), service view object (SVO), and entity object (EO), as well as the server.xml file, must be available in the same locations as the corresponding class files.

Specify the Java generate function to retrieve SDO metadata in the following format:

sdo://<SAM><SDO><FILTER><KEYS>

The following example shows the complete Java generate function value:

sdo://oracle.apps.fnd.wf.bes.sample.WorkflowAgentSAM:Agent/oracle/apps/fnd/wf/bes/sample/AgentFilter?Name

For more information about service data objects, refer to the Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.

Documenting Identifying Information for an Event

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.

Reviewing the Customization Level and License Status for an Event

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 E-Business Suite 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 E-Business Suite 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 E-Business Suite installation may include seeded events owned by Oracle E-Business Suite 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 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 E-Business Suite Maintenance 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 the Events tab. See: Oracle Workflow Developer Navigation Paths.

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

    • Name - Enter the internal name of the event you want to display. You can enter a partial value to search for events whose internal names contain that value.

    You can also enter the following additional search criteria:

    • Display Name - Enter the display name of the event you want to display.

    • Type - Select Event or Group as the type of the events you want to display.

    • Status - Select Enabled or Disabled as the status of the events you want to display.

    • Owner Name - Enter the name of the program or application that owns the event you want to display.

    • Owner Tag - Enter the application short name of the application that owns the event you want to display.

  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.

    • If you have workflow administrator privileges, you can define a new subscription to the event by selecting the Create Subscription button. The Create Event Subscription page appears with the event name automatically entered in the Event Filter field. See: To Create or Update a Subscription.

    • If you have workflow administrator privileges, you can update an existing subscription by selecting the update icon for that subscription. See: To Create or Update a Subscription.

      Note: For seeded subscriptions with a customization level of Limit, you can only update the subscription status. For seeded subscriptions with a customization level of Core, you cannot update any properties; you can only view the subscription definition.

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

    • To update an event, choose the update icon for that event. See: To Create or Update an Event and To Create or Update an Event Group.

      Note: For seeded events with a customization level of Limit, you can only update the event status. For seeded events with a customization level of Core, you cannot update any properties; you can only view the event definition.

    • To manually raise a test event, select the test icon for the event you want. See: To Raise a Test Event.

      Note: You cannot raise an event group. You must raise each event individually.

    • To delete an event, select the event and select the Delete button.

      Note: You can only delete events that do not have any subscriptions referencing them and that do not belong to any event groups.

      Additionally, you cannot delete any event seeded by Oracle E-Business Suite that has a customization level of Core or Limit.

    • To create a new individual event, select the Create Event button. See: To Create or Update an Event.

    • To create a new event group, select the Create Event Group button. See: To Create or Update an Event Group.

To Create or Update an Event

  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 E-Business Suite installation may include seeded events owned by Oracle E-Business Suite 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.

    • To assign the event a PL/SQL generate function, enter the PL/SQL procedure in the Generate Function field in the following format:

      <package_name>.<function_name>

    • To assign the event a Java generate function, enter the Java API in the Java Generate Function field in the following format:

      <customPackage>.<customClass>

      Alternatively, if you want to use the XML metadata corresponding to a service data object (SDO) as the event data, you can define the Java generate function in a special format to retrieve the SDO metadata. See: Generating Service Data Object Metadata.

  7. Identify the program or application that owns the event by selecting the application short name in the Owner Tag field. By default, Oracle Workflow sets the Owner Name field to the application name associated with that application short name. However, you can optionally enter a different name in the Owner Name field, such as a particular program or component within the application.

  8. Review the customization level for the event.

    • Core - No changes can be made to the event definition. This level is used only for events seeded by Oracle E-Business Suite.

    • Limit - The event status can be updated to Enabled or Disabled, but no other changes can be made to the event definition. This level is used only for events seeded by Oracle E-Business Suite.

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

To Create or Update an Event Group

  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 E-Business Suite installation may include seeded event groups owned by Oracle E-Business Suite 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 selecting the application short name in the Owner Tag field. By default, Oracle Workflow sets the Owner Name field to the application name associated with that application short name. However, you can optionally enter a different name in the Owner Name field, such as a particular program or component within the application.

  7. Review the customization level for the event group.

    • Core - No changes can be made to the event group definition. This level is used only for event groups seeded by Oracle E-Business Suite.

    • Limit - The event group status can be updated to Enabled or Disabled, but no other changes can be made to the event group definition. This level is used only for event groups seeded by Oracle E-Business Suite.

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

  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:

    • Name - Enter the internal name of the event you want to add. You can enter a partial value to search for events whose internal names contain that value.

    You can also enter the following additional search criteria.

    • Display Name - Enter the display name of the event you want to add.

    • Type - You can only add individual events as members of the group.

    • Status - Select Enabled or Disabled as the status of the events you want to add.

    • Owner Name - Enter the name of the program or application that owns the event you want to add.

    • Owner Tag - Enter the program ID of the program or application that owns the event you want to add.

  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.

    • Event Name - Select the internal name of the event.

      Note: You cannot raise an event group. You must raise each event individually.

    • Event Key - Enter an event key that uniquely identifies this instance of the event.

    • Send Date - Optionally specify the date when the event message is available for dequeuing. If you set the send date to a future date when you raise the event, the event message is placed on the WF_DEFERRED queue, and subscription processing does not begin until the specified date.

  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 or JSON document to describe what occurred in the event.

    • To enter the event data manually, select Write XML/JSON in the Upload Option field and enter the XML or JSON document in the XML/JSON Content field. You can enter up to 4000 characters.

    • To upload an XML or JSON file from your file system, select Upload XML/JSON in the Upload Option field. Enter the full path and file name of the XML or JSON file containing your event data in the File Name field, and select the Upload XML/JSON File button.

    Note: You can also assign generate functions in the event definition to generate the event data, or raise the event using the WF_EVENT.Raise() API instead of using the Test Business Event page. These methods let you provide the event data as a CLOB storing up to four gigabytes of data. See: To Create or Update an Event and Raise, Oracle Workflow API Reference.

  5. Choose the tier where you want to raise the event and begin event processing.

    • To raise the event in the database, select the Raise in PLSQL button.

    • To raise the event in the application tier, select the Raise in Java button.

    The Test Business Event page displays a confirmation message together with the values you submitted for you to review. If the event triggers a Web service subscription that is executed synchronously and returns an XML response, the page also displays that response.

  6. To clear all fields except the Event Name field, select the Clear button. You can then optionally raise another event.

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 E-Business Suite 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 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 E-Business Suite Maintenance Guide and Synchronizing License Statuses, Oracle Workflow Administrator's Guide.

If you upgrade from an Oracle E-Business Suite 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.

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.

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 E-Business Suite 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 E-Business Suite 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 E-Business Suite installation may include seeded subscriptions owned by Oracle E-Business Suite 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 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 E-Business Suite Maintenance 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.

Specifying Error Handling for a Subscription

For each subscription, you can specify the type of error handling to perform if the Event Manager encounters an error while processing that subscription.

For errored events placed on the WF_ERROR and WF_JAVA_ERROR agents, Oracle Workflow provides default error handling 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 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 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.

Note: The rule function used for the Launch when Business Key Matches option, Instance_Default_Rule(), may take some time to complete, depending on how many existing workflow processes include receive event activities, how many of those processes are eligible to receive this event, and what activities in those processes the Workflow Engine must execute after the event has been received. Consequently, when you select this option, it is strongly recommended that you set the phase number for the subscription to 100 or higher to defer the subscription and allow the rule function processing to be completed in the background by an agent listener.

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 E-Business Suite 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 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.

Invoking a Web Service

You can use Oracle E-Business Suite Integrated SOA Gateway with the Oracle Workflow Business Event System to leverage service-oriented architecture (SOA)-based applications. In Oracle Workflow, you can define an event subscription to invoke a Web service. When the triggering business event occurs, the Business Event System invokes the Web service using the JAX-WS (Java API for XML-based Web Services) Dispatch from Oracle WebLogic Server. In this way you can integrate Oracle E-Business Suite with SOA-based applications built using Oracle Fusion Middleware or other standards-based technologies. For more details about using Oracle E-Business Suite Integrated SOA Gateway with the Oracle Workflow Business Event System, see the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

When you raise an event to trigger a Web service subscription, provide the content for the Simple Object Access Protocol (SOAP) body of the XML input message in the event data payload. If you want to use the XML metadata corresponding to a service data object (SDO) as the event data payload, define the generate function for the event to retrieve the SDO metadata. See: Generating Service Data Object Metadata.

If the input message definition for your Web service operation requires other parts within the message, you can provide those parts in the event parameters. For example, you can use an event parameter to provide any header part that may be required to embed the application context into the SOAP envelope. The event parameters that contain input message parts must be identified by parameter names in the following format:

WFBES_INPUT_<PartName>

Replace <PartName> with the name of the part as it appears in the input message definition from the WSDL. For example:

WFBES_INPUT_header

Do not omit any of the parts specified in the input message definition. If any of the parts are optional, you must still create corresponding event parameters for those parts and set those parameters to a null value so that the Web service subscription can properly identify the part that should contain the SOAP body.

You can use additional parameters to include further pre-invocation and post-invocation processing. You can specify the following parameters both within the event parameter list and within the subscription parameter list. If the triggering event contains any of the same parameters as the subscription, the event parameter values override the subscription parameter values.

You can also specify a parameter named SERVICE_SOAP_ADDRESS within the event parameter list. This parameter lets you provide a SOAP address at which to invoke the web service. If the triggering event contains the SERVICE_SOAP_ADDRESS parameter, then the SOAP address specified in that parameter overrides the SOAP address derived from the WSDL URL in the subscription definition.

By default, Web service subscriptions use a Java rule function called oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription. The oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription Java class is a standard rule function that implements the SubscriptionInterface Java interface. This rule function sends the event data to the Web service when the subscription is executed.

When defining a subscription that invokes a Web service, ensure that you select Message as the rule data. You must also specify the URL where the Web Services Description Language (WSDL) description for the Web service is located. For example:

http://www.example.com/myservice.wsdl

If the Web service is a BPEL process, you can specify a relative URL using the prefix bpel:// followed by a relative path to the WSDL description on the BPEL server. For example:

bpel://mybpelservice.wsdl

Note: You must specify the bpel:// prefix in lowercase letters.

At runtime, Oracle Workflow replaces the bpel:// prefix with the host name and port for the BPEL server specified in the WF: BPEL Server profile option. This profile option lets you quickly change the BPEL server setup for all subscriptions that invoke BPEL processes, such as if you move these subscription definitions from a test instance to a production instance. See: Specifying the BPEL Server, Oracle Workflow Administrator's Guide.

After entering the WSDL URL, you can select the service name, port, and operation for the Web service from that WSDL description that you want to invoke. A port is a single communication endpoint defined by a combination of a network address and a binding. The binding specifies concrete protocol and data format specifications for the operations and messages defined by the port type. The port type is the set of abstract operations that includes the operation to invoke. The operation is an abstract description of an action supported by the service. For more information about Web Services Description Language (WSDL), see: http://www.w3.org/TR/wsdl.

You can also specify the user name and password for the Web service in the subscription action details.

Internally, Oracle Workflow stores the WSDL URL, service name, port, operation, associated port type, user name, and password in subscription parameters named SERVICE_WSDL_URL, SERVICE_NAME, SERVICE_PORT, SERVICE_OPERATION, SERVICE_PORTTYPE, WFBES_SOAP_USERNAME, and WFBES_SOAP_PASSWORD_MOD and WFBES_SOAP_PASSWORD_KEY, respectively. The oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription rule function references the Web service properties through these parameters.

You can also specify the WFBES_IN_XSL_FILENAME, WFBES_OUT_XSL_FILENAME, WFBES_CALLBACK_EVENT, and WFBES_CALLBACK_AGENT parameters for the subscription. However, if the triggering event contains any of the same parameters as the subscription, the event parameter values override the subscription parameter values. If the triggering event contains the SERVICE_SOAP_ADDRESS parameter, then the SOAP address specified in that parameter overrides the SOAP address derived from the WSDL URL in the subscription definition.

Additionally, you can include custom processing by extending the oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription class and overriding the following methods.

See: Standard API for an Event Subscription Rule Function and WebServiceInvokerSubscription, Oracle Workflow API Reference.

If you want to provide specific Web service details in the administrator notifications for any errors in a Web service subscription, you can define a custom error handling subscription that sends the event to the Default Event Error Process (One Retry Option) instead of the Default Event Error Process. See: Error Handling for Event Subscription Processing and Default Event Error Process (One Retry Option).

Invoking a REST Service

You can use Oracle E-Business Suite Integrated SOA Gateway with the Oracle Workflow Business Event System to leverage Representational State Transfer (REST) services. In Oracle Workflow, you can define an event subscription to invoke a REST service when the triggering business event occurs. Oracle E-Business Suite Integrated SOA Gateway supports REST service invocation through the GET or POST HTTP methods with an XML or JSON payload. For more details about using Oracle E-Business Suite Integrated SOA Gateway with the Oracle Workflow Business Event System, see the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

To invoke a REST service, identify the triggering business event, identify the service endpoint and other properties for the REST service, and define a subscription to your event specifying those properties. When the event occurs, the Business Event System executes the subscription and invokes the REST service.

When you raise an event to trigger a REST service subscription, provide the content for the body of the XML or JSON request message in the event data payload.

You can use additional parameters to specify the REST service properties. You can specify the following parameters within the event parameter list.

Note: These properties are also set as subscription parameters when you define the REST service metadata for a REST service invoker subscription. If the triggering event contains any of the same parameters as the subscription, the event parameter values override the subscription parameter values.

By default, REST service subscriptions use a Java rule function called oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription. The oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription Java class is a standard rule function that implements the SubscriptionInterface Java interface. This rule function sends the event data to the REST service when the subscription is executed.

When defining a subscription that invokes a REST service, ensure that you select Message as the rule data. You must define the service endpoint by specifying the resource base and relative resource path for the endpoint. You can optionally specify any additional query parameters to be appended to the service endpoint.

You must specify whether the REST service uses POST or GET as its HTTP method, whether its request content is in XML or JSON format, and whether it accepts a response in the XML or JSON format.

You can also specify the user name and password for the REST service if required to authenticate the user invoking the REST service through HTTP basic authentication.

You can optionally specify advanced configuration parameters, such as parameters for digest or signature HTTP headers, callback, and any custom parameters.

Internally, Oracle Workflow stores subscription metadata in the subscription parameters named WFBES_REST_RESOURCE_BASE, WFBES_REST_RESOURCE_PATH, WFBES_REST_QUERY_STRING, WFBES_REST_HTTP_VERB, WFBES_REST_USERNAME, WFBES_REST_PASSWORD_MOD, WFBES_REST_PASSWORD_KEY, and WFBES_REST_HEADER_DIGEST. The oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription rule function references the REST service properties through these parameters.

However, if the triggering event contains any of the same parameters as the subscription, the event parameter values override the subscription parameter values.

Additionally, you can include custom processing by extending the oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription class and overriding the following methods.

See: Standard API for an Event Subscription Rule Function and RESTServiceInvokerSubscription, Oracle Workflow API Reference.

If you want to provide specific REST service details in the administrator notifications for any errors in a REST service subscription, you can define a custom error handling subscription that sends the event to the Default Event Error Process (One Retry Option) instead of the Default Event Error Process. See: Error Handling for Event Subscription Processing and Default Event Error Process (One Retry Option).

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

Note: If you use custom PL/SQL rule functions, you can optionally enable Oracle Workflow to call your custom functions statically to enhance performance. See: Enabling Static Function Calls for Custom PL/SQL Functions, Oracle Workflow Administrator's Guide.

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.

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

Note: Deferral applies only to subscriptions with a source type of Local or External. The Event Manager executes subscriptions with a source type of Error as soon as an agent listener dequeues event messages from the WF_ERROR or WF_JAVA_ERROR agents. Such subscriptions are not deferred, regardless of the event send date or the subscription phase number. However, you can still use the subscription phase number to control the order in which the subscriptions are executed.

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 application 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 the Subscriptions tab. See: Oracle Workflow Developer Navigation Paths.

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

    • System - Select the system for which you want to display subscriptions.

    You can also enter the following additional search criteria.

    • Source Type - Select Local, External, or Error as the type of source system for which you want to display subscriptions.

    • Event - Select the event for which you want to display subscriptions.

    • Status - Select Enabled or Disabled as the status of the subscriptions you want to display.

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

    • To update a subscription, choose the update icon for that subscription. See: To Create or Update an Event Subscription.

      Note: For seeded subscriptions with a customization level of Limit, you can only update the subscription status. For seeded subscriptions with a customization level of Core, you cannot update any properties; you can only view the subscription definition.

    • To delete a subscription, select the subscription and select the Delete button.

      Note: You cannot delete any subscription seeded by Oracle E-Business Suite that has a customization level of Core or Limit.

    • To create a new subscription, select the Create Subscription button. See: To Create or Update an Event Subscription.

To Create or Update an Event Subscription

  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 E-Business Suite installation may include seeded subscriptions owned by Oracle E-Business Suite 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.

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

    • External - The subscription applies only to events received by an inbound agent on the subscribing system.

      Note: All event messages received by an inbound agent on the subscribing system are considered to have an External source, whether the sending agent is located on a remote system or on the local system.

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

  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.

  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.

    • Key - The subscription requires only the event key.

    • Message - The subscription requires the complete event data.

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

    • Launch Workflow - Send the event message to launch or continue a workflow process.

    • Send to Agent - Send the event message to a Business Event System agent.

    • Send Notification - Send a notification using a standard or custom message template.

    • Receive Trading Partner Message - Receive an Oracle XML Gateway message from your trading partner.

    • Send Trading Partner Message - Generate an Oracle XML Gateway message and send the message to your trading partner.

    • Invoke Web Service - Invoke a Web service.

    • Invoke REST Service - Invoke a REST service.

    • Custom - Execute custom business logic defined as a PL/SQL rule function or as a Java rule function.

  10. Specify the error handling to perform if Oracle Workflow encounters an error while processing this subscription.

    • Stop and Rollback - The Event Manager halts all subscription processing for the event and rolls back any subscriptions already executed for the event.

    • Skip to Next - The Event Manager rolls back only this subscription and then continues processing the next subscription for the event according to the subscription phase order.

    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.

    • Select the workflow item type and process name for the workflow process to which you want to send the event. Ensure that the process contains a receive event activity that will be able to accept the event. The event can either launch a new process instance or continue an existing process instance that is waiting to receive the event.

      Note: The list of values for the Workflow Process field includes only the runnable processes within the item type you specify.

    • Select Normal, High, or Low as the priority for the subscription. Oracle Workflow uses the priority to help determine the order in which deferred subscriptions are processed. The default priority is Normal.

    • You can optionally select an additional option to control how the subscription is executed.

      • Add Subscription Parameters - Set the subscription parameters into the parameter list within the event message before sending the event to the specified workflow process. All the event parameters will be set as item attributes for the workflow process when the process receives the event.

      • Launch when Business Key Matches - Send the event to all existing workflow process instances that have eligible receive event activities waiting to receive it, marked by a business key attribute that matches the event key. This option lets you send the event to multiple processes. However, note that with this option the event is only sent to continue existing processes. If you want to launch a new process instance with the event, do not select this option.

        Note: If you select this option, the Event Manager ignores the specified workflow item type and process name. Instead, it uses the business key attribute to identify the workflow processes that should receive the event.

        Note: The rule function used for the Launch when Business Key Matches option, Instance_Default_Rule(), may take some time to complete, depending on how many existing workflow processes include receive event activities, how many of those processes are eligible to receive this event, and what activities in those processes the Workflow Engine must execute after the event has been received. Consequently, when you select this option, it is strongly recommended that you set the phase number for the subscription to 100 or higher to defer the subscription and allow the rule function processing to be completed in the background by an agent listener.

      • Launch when Parameters Match - Send the event to the specified workflow process only if the event message includes parameters whose names and values match all the parameters defined for the subscription. This option lets you specify additional conditions to control whether or not the subscription is executed. Ensure that you include the required parameters in the parameter list within the event message, either by providing them when the event is raised or by adding them during prior subscription processing.

    • If you selected the Add Subscription Parameters option or the Launch when Parameters Match option, specify the parameters for the subscription. Enter the name and value for each parameter with no spaces.

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

    • Enter either the Out Agent that you want to send the outbound message, or the To Agent that you want to receive the inbound message, or both.

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

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

      • If you specify an Out Agent without a To Agent, Oracle Workflow places the event message on the Out Agent's queue without a specified recipient. The Out Agent must use either a multi-consumer queue with a subscriber list or a single-consumer queue.

      Note: The Out Agent must be located on the subscribing system. The list of values for the Out Agent field includes only agents with a direction of Out.

      The list of values for the To Agent field includes only agents with a direction of In.

    • Select Normal, High, or Low as the priority for the subscription. Oracle Workflow uses the priority to help determine the order in which deferred subscriptions are processed. The default priority is Normal.

    • You can optionally select an additional option to control how the subscription is executed.

      • Add Subscription Parameters - Set the subscription parameters into the parameter list within the event message before placing the event message on the outbound agent.

      • Launch when Parameters Match - Place the event message on the outbound agent only if the event message includes parameters whose names and values match all the parameters defined for the subscription. This option lets you specify additional conditions to control whether or not the subscription is executed. Ensure that you include the required parameters in the parameter list within the event message, either by providing them when the event is raised or by adding them during prior subscription processing.

    • If you selected the Add Subscription Parameters option or the Launch when Parameters Match option, specify the parameters for the subscription. Enter the name and value for each parameter with no spaces.

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

    • Select the workflow item type and message name for the message you want to send.

      Note: You do not need to define or run a workflow process to send a notification from a subscription with the Send Notification action type. However, you do need to define the message you want to send within a workflow item type. The list of values for the Message Name field includes only the messages within the item type you specify.

    • Select the role that should receive the notification.

    • Optionally enter a custom callback function you want the Notification System to use for communication of SEND and RESPOND source message attributes. See: Custom Callback Function, Oracle Workflow API Reference.

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

      <itemtype>:<itemkey>:<activityid>

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

    • Optionally enter a comment to send with the message.

    • Select Normal, High, or Low as the priority for the message. Oracle Workflow also uses the priority to help determine the order in which deferred subscriptions are processed. The default priority is Normal.

  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 Invoke Web Service as the action type, enter the Web service details in the Invoke Web Service wizard.

    • Enter the URL where the Web Services Description Language (WSDL) description for the Web service is located, and choose Next. For example:

      http://www.example.com/myservice.wsdl

      If the Web service is a BPEL process, you can specify a relative URL using the prefix bpel:// followed by a relative path to the WSDL description on the BPEL server. For example:

      bpel://mybpelservice.wsdl

      Note: You must specify the bpel:// prefix in lowercase letters.

      At runtime, Oracle Workflow replaces the bpel:// prefix with the host name and port for the BPEL server specified in the WF: BPEL Server profile option. This profile option lets you quickly change the BPEL server setup for all subscriptions that invoke BPEL processes, such as if you move these subscription definitions from a test instance to a production instance. See: Specifying the BPEL Server, Oracle Workflow Administrator's Guide.

    • Oracle Workflow displays the WSDL source and description that you specified. Select the name of the Web service from that description that you want to consume, and choose Next.

    • Oracle Workflow displays the WSDL source, WSDL description, and service name that you specified, and lists the name and endpoint of each available port. Select the port to use for the service and choose Next.

    • Oracle Workflow displays the WSDL source, WSDL description, service name, and port that you specified, and lists the name, port type, and operation type of each available service operation. Select the operation to invoke, and choose Next.

    • In the Web Service Security region, enter a user name and password if required to authenticate the user invoking the Web service.

      Note: For a subscription seeded by Oracle E-Business Suite with a customization level of Core or Limit, if the seeded subscription definition includes a user name, then you cannot update that user name. However, if no user name was provided in the seeded subscription definition, then you can add or update the user name. If the Web service requires a password, you can update the password in the subscription definition, regardless of the customization level.

    • By default, Oracle Workflow uses oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription as the Java rule function for a Web service subscription. If you have extended this class with a custom class, enter your custom class instead.

      You can optionally specify additional parameters for the subscription to define further pre-invocation and post-invocation processing. Enter the name and value for each parameter with no spaces.

      Oracle Workflow converts the list of subscription parameters into a text string of name and value pairs, separated by spaces, in the following format:

      <name1>=<value1> <name2>=<value2> ... <nameN>=<valueN>

      If you define a custom rule function, the function can reference the parameters from this format.

  17. If you selected Invoke REST Service as the action type, enter the following details.

    • Enter the resource base for the REST service. The resource base should start with either http:// or https://

    • Optionally enter a resource path for the REST service.

      Oracle Workflow displays the service endpoint for the REST service derived from the specified resource base and resource path.

    • Specify whether the REST service uses POST or GET as its HTTP method, whether its content is in XML or JSON format, and whether it accepts the XML or JSON format.

    • Enter any additional query parameters that the REST service requires. Enter the name and value for each parameter with no spaces. These parameters are appended to the REST service endpoint.

    • In the REST Service Security region, enter a user name and password if required to authenticate the user invoking the REST service through HTTP basic authentication.

      Note: For a subscription seeded by Oracle E-Business Suite with a customization level of Core or Limit, if the seeded subscription definition includes a user name, then you cannot update that user name. However, if no user name was provided in the seeded subscription definition, then you can add or update the user name. If the REST service requires a password, you can update the password in the subscription definition, regardless of the customization level.

    • By default, Oracle Workflow uses oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription as the Java rule function for a REST service subscription. If you have extended this class with a custom class, enter your custom class instead.

    • In the Documentation region, identify the program or application that owns the subscription by selecting the application short name in the Owner Tag field. By default, Oracle Workflow sets the Owner Name field to the application name associated with that application short name. However, you can optionally enter a different name in the Owner Name field, such as a particular program or component within the application.

    To enter advanced configuration parameters, choose Advanced Configuration.

    • If the request for the REST service requires a digest HTTP header, select the digest algorithm, either SHA-256 or SHA-512.

    • If the request requires a signature HTTP header, select the signing algorithm, either rsa-sha256 or rsa-sha512. Then specify the location of your PKCS #12 keystore file in .p12 or .pfx format , the keystore password, the alias associated with the digital certificate used for signing the headers, the key ID, and the headers to be signed. By default, the content-type accept header will be signed.

    • Enter any additional header parameters that the REST service requires. Enter the name and value for each parameter with no spaces.

    • If a REST service has an output or a response message, configure the callback for the REST service by specifying the callback agent and callback event.

    • You can optionally specify additional parameters for the REST service invoker rule function to define further pre-invocation and post-invocation processing. Enter the name and value for each parameter with no spaces.

      Oracle Workflow converts the list of REST service invoker parameters into a text string of name and value pairs, separated by spaces, in the following format:

      <name1>=<value1> <name2>=<value2> ... <nameN>=<valueN>

      If you define a custom rule function, the function can reference the parameters from this format.

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

    • Enter the rule function that contains the custom business logic you want to run on the event message. You can define the rule function either as a Java class or as a PL/SQL function. In either case, the rule function must be defined according to a standard API. See: Standard API for an Event Subscription Rule Function.

      • For a Java subscription, enter the Java rule function in the following format:

        <customPackage>.<customClass>

        In this case, you should leave the PL/SQL Rule Function field blank.

      • For a PL/SQL subscription, enter the PL/SQL rule function in the following format:

        <package_name>.<function_name>

        In this case, you should leave the Java Rule Function field blank.

      Note: If you enter a rule function other than WF_RULE.Default_Rule, Oracle Workflow does not automatically send the event message to the specified workflow and agent. You must explicitly include the send processing in your custom rule function instead.

    • If your rule function will send the event to a workflow process, you can specify the workflow item type and process name for the function to reference. Ensure that the process contains a receive event activity that will be able to accept the event.

      Note: The list of values for the Workflow Process field includes only the runnable processes within the item type you specify.

    • If your rule function will send the event to an agent, you can specify the outbound and inbound agents for the function to reference. Depending on the send processing in your function, you may need to specify either the Out Agent that you want to send the outbound message, or the To Agent that you want to receive the inbound message, or both.

      Note: The Out Agent must be located on the subscribing system. The list of values for the Out Agent field includes only agents with a direction of Out.

      The list of values for the To Agent field includes only agents with a direction of In.

    • Select Normal, High, or Low as the priority for the subscription. Oracle Workflow uses the priority to help determine the order in which deferred subscriptions are processed. The default priority is Normal.

    • You can optionally specify additional parameters for the subscription, to be referenced by the rule function. Enter the name and value for each parameter with no spaces.

      Oracle Workflow converts this list of subscription parameters into a text string of name and value pairs, separated by spaces, in the following format:

      <name1>=<value1> <name2>=<value2> ... <nameN>=<valueN>

      The rule function can reference the parameters from this format.

  19. For all action types, in the Documentation region, identify the program or application that owns the subscription by selecting the application short name in the Owner Tag field. By default, Oracle Workflow sets the Owner Name field to the application name associated with that application short name. However, you can optionally enter a different name in the Owner Name field, such as a particular program or component within the application.

  20. Review the customization level for the subscription.

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

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

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

  21. 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 Enterprise Manager online help, Oracle Enterprise Manager Support, Oracle Streams Advanced Queuing User's Guide and Reference, Oracle Workflow Manager Overview, Oracle Workflow Administrator's Guide, and Setting Up the Business Event System, Oracle Workflow Administrator's Guide.

You can run a diagnostic test through Oracle Diagnostics Framework 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. 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 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.EXAMPLE.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 email 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 application 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 application 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 Enterprise Manager online help, Oracle Enterprise Manager Support, Oracle Streams Advanced Queuing User's Guide and Reference , Oracle Workflow Manager Overview, Oracle Workflow Administrator's Guide, and Setting Up the Business Event System, Oracle Workflow Administrator's Guide.

You can run a diagnostic test through Oracle Diagnostics Framework 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 additional agents named WF_REPLAY_IN and WF_REPLAY_OUT, 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 application 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.

    • You must associate the agent with the non-Workflow system to which it belongs.

    • You must specify the protocol by which you will communicate with the agent.

    • For an inbound agent, you must also specify the address at which you will communicate with the agent.

    • You can leave the queue name and queue handler blank if the agent is not implemented as an Oracle Advanced Queueing queue.

Related Topics

To 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 the Agents tab. See: Oracle Workflow Developer Navigation Paths.

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

    • Name - Enter the internal name of the agent you want to display. You can enter a partial value to search for agents whose internal names contain that value.

    You can also enter the following additional search criteria.

    • Protocol - Select the protocol of the agent you want to display.

    • Address - Enter the address of the agent you want to display.

    • System - Select the system of the agent you want to display.

    • Direction - Select In or Out as the direction of the agents you want to display.

    • Type - Select Agent or Group as the type of the agents you want to display.

    • Status - Select Enabled or Disabled as the status of the agents you want to display.

  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. See: 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 Register External System 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.

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

    • To assign the agent a PL/SQL queue handler, enter the PL/SQL package name in the Queue Handler field in all uppercase. You can run both PL/SQL and Java agent listeners on an agent with a PL/SQL queue handler.

    • To assign the agent a Java queue handler, enter the Java package name in the Java Queue Handler field. You can run only Java agent listeners on an agent with a Java queue handler.

    Note: For an agent that is not implemented as a queue, such as an agent on a non-Oracle system, you can leave the Queue Handler and Java Queue Handler fields blank.

  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.

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

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

    • Name - Enter the internal name of the agent you want to add. You can enter a partial value to search for agents whose internal names contain that value.

    You can also enter the following additional search criteria.

    • Protocol - Select the protocol of the agent you want to add.

    • Address - Enter the address of the agent you want to add.

    • System - Select the system of the agent you want to add.

    • Status - Select Enabled or Disabled as the status of the agents you want to add.

  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.

    • If Oracle Workflow is installed on the destination system, you can use the Generate Local System Identifier page on the destination system to generate and save an XML document containing the system identifier information. See: To Generate Local System Identifier Information.

      Note: If you do not have access to the Oracle Workflow installation on the destination system, ask the workflow administrator for that system to perform this step.

    • If Oracle Workflow is not installed on the destination system, you will need to manually gather the information needed to create definitions for the system and its inbound agents.

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

    • If Oracle Workflow is installed on both the source system and the destination system, you can use the Register External System Web page on the source system to register the information by raising the System Signup event with the system identifier XML document from the destination system as the event data. When the System Signup event is raised on the source system, Oracle Workflow executes a predefined subscription that loads the system identifier information to the Event Manager in that system. See: To Register an External System.

      Note: If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.

    • If Oracle Workflow is installed on the source system but not on the destination system, you must manually create system and agent definitions for the destination system in the Event Manager of the source system. See: To Create or Update a System and To Create or Update an Agent.

    • If Oracle Workflow is not installed on the source system but is installed on the destination system, you must store the system and inbound agent information for the destination system in the source system according to that non-Workflow source system's requirements. You can optionally make use of the system identifier XML document generated by the Generate Local System Identifier page on the destination system, but you must manually perform whatever steps are necessary to store that information in the non-Workflow source system.

Synchronizing Systems

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.

    • Specify the inbound agent on the target system that you want to receive the event message, or specify a workflow process that sends the event message to the target system.

      Note: If you want to send the event message to more than one target system, you can specify an agent group to receive the event message.

    • Enable the subscription.

      Note: If you do not have access to the Oracle Workflow installation on the source system, ask the workflow administrator for that system to perform this step.

  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 Generate 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 the Systems tab, and choose the System Details tab in the side navigation. See: Oracle Workflow Developer Navigation Paths.

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

    • Name - Enter the internal name of the system you want to display. You can enter a partial value to search for systems whose internal names contain that value.

    You can also enter the following additional search criteria:

    • Display Name - Enter the display name of the system you want to display.

    • Master - Select the master system for the system you want to display.

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

  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.

    • If you have workflow administrator privileges, you can define a new subscription for the system by selecting the Create Subscription button. The Create Event Subscription page appears with the system name automatically entered as the subscriber in the System field. See: To Create or Update an Event Subscription.

    • If you have workflow administrator privileges, you can update an existing subscription by selecting the update icon for that subscription. See: To Create or Update an Event Subscription.

      Note: For seeded subscriptions with a customization level of Limit, you can only update the subscription status. For seeded subscriptions with a customization level of Core, you cannot update any properties; you can only view the subscription definition.

  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 update a system, choose the update icon for that system. See: To Create or Update a System.

    • To delete a system, select the system and select the Delete button.

      Note: You can only delete systems that do not have any agents defined on them or any subscriptions referencing them. Also, you cannot delete the local system.

    • To create a new system definition, select the Create System button. See: To Create or Update a System.

      Note: You should use the Create System page only to manually create system definitions for external systems that are not Workflow-enabled. For a Workflow-enabled system, you should use the Register External System page instead to automatically register the system identifier information. See: Registering External Systems.

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 Register External System 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.

    Important: 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 Generate 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 the Systems tab, and choose the Generate Local System Identifier tab 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 the Systems tab, and choose the Register External System tab 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.

    • Event Name - Oracle Workflow automatically displays the internal name of the System Signup event, oracle.apps.wf.event.system.signup.

    • Event Key - Enter an event key that uniquely identifies this instance of the event.

    • Send Date - Optionally specify the date when the event message is available for dequeuing. If you set the send date to a future date when you raise the event, the event message is placed on the WF_DEFERRED queue, and subscription processing does not begin until the specified date.

  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 Generate Local System Identifier Information.

    • To enter the system identifier information manually, select Write XML in the Upload Option field and paste the XML document into the XML Content field. You can enter up to 4000 characters.

    • To upload the system identifier XML file from your file system, select Upload XML in the Upload Option field. Enter the full path and file name of the XML file containing the system identifier information in the XML File Name field, and select the Upload XML File button.

    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

The Workflow Agent Ping/Acknowledge workflow consists of two processes, the Master Ping process and the Detail Ping process. To ping all inbound agents, launch the Master Ping process, specifying a unique item key and the outbound agent on the local system for sending the pings. To ping a particular inbound agent, specify that agent as well when you launch the process.

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 without specifying a particular agent to ping, 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. If you do specify an inbound agent to ping, the Workflow Engine launches a Detail Ping process only for that agent.

Note: The Workflow Agent Ping/Acknowledge workflow tests all inbound agents except the standard WF_DEFERRED and WF_ERROR agents and agents that do not use the WF_EVENT_QH queue handler.

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

Running Workflow Agent Ping/Acknowledge

The following examples describe how to perform ping tests for different use cases.

Case 1: Broadcast Ping to Local Inbound Agents Only

Follow this procedure if you send events only to inbound agents on your local system and do not have any connections set up to external systems.

  1. Schedule propagation for the outbound agent on the local system that you want to use to send the pings, such as WF_OUT. You can use the Distributed Database Management feature to manage AQ, including scheduling propagation, through Oracle Enterprise Manager. See: Oracle Enterprise Manager Support, Oracle Streams Advanced Queuing User's Guide and Reference, and Distributed Management in the Oracle Enterprise Manager online help.

    You can also schedule propagation manually by running the DBMS_AQADM.Schedule_Propagation API. For example:

    begin
DBMS_AQADM.Schedule_Propagation('APPLSYS.WF_OUT', null, sysdate, null, 'SYSDATE+(120/86400)', 60);
end;
/

  2. Launch the Workflow Agent Ping/Acknowledge workflow, selecting the Master Ping process as the process to run and specifying a unique item key and the outbound agent on the local system for sending the pings. You can use the Launch Processes Web page to launch the Workflow Agent Ping/Acknowledge workflow. See: Testing Workflow Definitions Using the Developer Studio.

    You can also launch the workflow manually. For example:

    declare
itype varchar2(8):='WFPING';
ikey varchar2(10):='<item_key>';
wfprocess varchar2(10):='WFMSTPNG';
outAg varchar2(100):='WF_OUT@<local_system>';

begin
fnd_global.APPS_INITIALIZE( 0, -1, -1 , 0 );
wf_engine.createprocess(itemtype=>itype, itemkey=>ikey, process=>wfprocess);

wf_engine.SetItemAttrText(itemtype=>itype, itemkey=>ikey, aname=>'OUTAGENT', avalue=>outAg);

wf_engine.startprocess(itemtype=>itype, itemkey=>ikey);
commit;
end;
/

  3. Verify that the Ping Agent event was enqueued on the WF_OUT agent's queue and propagated to the inbound agents' queues. You can use Oracle Workflow Manager to verify the processing of the Ping Agent event messages. See: Agents, Oracle Workflow Administrator's Guide.

    You can also use SQL*Plus commands to verify the processing of the events. For example, to check the WF_OUT agent's queue, use the following command:

    SQL> select o.* from applsys.aq$wf_out o where trunc (enq_time) >= trunc(sysdate) order by enq_time desc ;

    To check the WF_IN agent's queue, use the following command:

    SQL> select i.* from applsys.aq$wf_in i where trunc (enq_time) >= trunc(sysdate) order by enq_time desc ;

    You can also check the other inbound agents using similar commands.

  4. Run agent listeners on the inbound agents to process the Ping Agent events. You can use Oracle Workflow Manager to submit and manage agent listeners. See: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide and the Oracle Applications Manager online help.

    You can also run listeners for inbound agents manually by running the WF_EVENT.Listen API. For example, to run listeners for the WF_IN and WF_REPLAY_IN agents, use the following commands. You can add similar commands to run listeners for any other inbound agents as well.

    set serveroutput on size 1000000;

declare
l_replay varchar2(100) := 'WF_REPLAY_IN';
l_wfin varchar2(10):='WF_IN';
l_agent varchar2(20);
l_msg_count number := 15;
l_err_count number :=0;
l_corrid varchar2(100);

begin
fnd_global.APPS_INITIALIZE( 0, -1, -1 , 0 );

l_agent := l_replay;
wf_event.listen(p_agent_name=>l_agent, p_wait=>dbms_aq.no_wait, p_correlation=>l_corrid, p_message_count=>l_msg_count, p_max_error_count=>l_err_count);

dbms_output.put_line(l_agent||' Processed Messages: '||l_msg_count);
dbms_output.put_line(l_agent||' Errored Messages : '||l_err_count);
commit;

l_agent := l_wfin;
wf_event.listen(p_agent_name=>l_agent, p_wait=>dbms_aq.no_wait, p_correlation=>l_corrid, p_message_count=>l_msg_count, p_max_error_count=>l_err_count);

dbms_output.put_line(l_agent||' Processed Messages: '||l_msg_count);
dbms_output.put_line(l_agent||' Errored Messages : '||l_err_count);
commit;
end;

  5. Verify that the Acknowledge Ping events are enqueued on one of the inbound agents, such as WF_IN. There should be one Acknowledge Ping event for each inbound agent to which a Ping Agent event was originally sent. The Business Event System enqueues all the Acknowledge Ping events on the first inbound agent it finds on the local system, often WF_IN. You can either use Oracle Workflow Manager or perform the verification using SQL*Plus commands, as in step 3.

  6. Run an agent listener on the inbound agent where the Acknowledge Ping events are enqueued to process those events. You can use Oracle Workflow Manager to run an agent listener or run a listener manually, as in step 4.

  7. Use the Status Monitor to check the progress of the Workflow Agent Ping/Acknowledge workflow and verify that the Master Ping process and all the Detail Ping processes are complete. See: Viewing Workflows in the Status Monitor, Oracle Workflow Administrator's Guide.

Case 2: Point-to-Point Ping to External Inbound Agent

Follow this procedure if you want to test a particular inbound agent on an external system.

  1. Define database links from your local system to the external system and from the external system to your local system. You can use Oracle DBA Studio in Oracle Enterprise Manager to create database links. See the Oracle Enterprise Manager online help.

    You can also create database links manually in SQL*Plus. For example, if your local system is system A and the external system is system B, use the following syntax on system A to create a database link to system B:

    SQL>
CREATE PUBLIC DATABASE LINK B.example.com
CONNECT TO apps IDENTIFIED BY <password>
USING '(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=<host_name>)(PORT=<port_number>))
(CONNECT_DATA=(SID=B)))';

    Use a similar command on system B to create a database link to system A.

  2. On both the local system and the external system, schedule propagation from the outbound agent that you want to use to send the pings, such as WF_OUT, to the other system. You can use the Distributed Database Management feature to manage AQ, including scheduling propagation, through Oracle Enterprise Manager. See: Oracle Enterprise Manager Support, Oracle Streams Advanced Queuing User's Guide and Reference, and the Oracle Enterprise Manager online help.

    You can also schedule propagation manually by running the DBMS_AQADM.Schedule_Propagation API. For example, use the following command to schedule propagation from the WF_OUT agent on system A to system B:

    begin
DBMS_AQADM.Schedule_Propagation('APPLSYS.WF_OUT', B.example.com, sysdate, null, 'SYSDATE+(120/86400)', 60);
end;
/

    Use a similar command on system B to schedule propagation to system A.

  3. Register both systems with each other so that each system has the definition of the other system and that system's inbound agents stored in its Event Manager. See: Registering External Systems.

  4. Launch the Workflow Agent Ping/Acknowledge workflow, selecting the Master Ping process as the process to run and specifying a unique item key, the outbound agent on the local system for sending the ping, and the inbound agent on the external system that should receive the ping. You can use the Launch Processes Web page to launch the Workflow Agent Ping/Acknowledge workflow. See: Testing Workflow Definitions Using the Developer Studio.

    You can also launch the workflow manually. For example, to send a point-to-point ping to the WF_IN agent on the external system, use the following commands:

    declare
ename varchar2(100):=null;
itype varchar2(8):='WFPING';
ikey varchar2(10):='<item_key>';
wfprocess varchar2(10):='WFMSTPNG';
outAg varchar2(100):='WF_OUT@<local_system>';
toAg varchar2(100):='WF_IN@<external_sytem>';
ekey varchar2(100);

begin
fnd_global.APPS_INITIALIZE( 0, -1, -1 , 0 );
wf_engine.createprocess(itemtype=>itype, itemkey=>ikey, process=>wfprocess);

wf_engine.SetItemAttrText(itemtype=>itype, itemkey=>ikey, aname=>'EVNTKEY', avalue=>ekey);
wf_engine.SetItemAttrText(itemtype=>itype, itemkey=>ikey, aname=>'OUTAGENT', avalue=>outAg);
wf_engine.SetItemAttrText(itemtype=>itype, itemkey=>ikey, aname=>'TOAGENT', avalue=>toAg);

wf_engine.startprocess(itemtype=>itype, itemkey=>ikey);
commit;
end;
/

  5. Run an agent listener on the inbound agent on the external system to process the Ping Agent event. You can use Oracle Workflow Manager to run an agent listener or run a listener manually, as in step 4 of case 1.

  6. Run an agent listener on the inbound agent on the local system where the Acknowledge Ping event is received to process that event. You can use Oracle Workflow Manager to run an agent listener or run a listener manually, as in step 4 of case 1.

  7. Use the Status Monitor to check the progress of the Workflow Agent Ping/Acknowledge workflow and verify that the Master Ping process and the Detail Ping process are complete. See: Viewing Workflows in the Status Monitor, Oracle Workflow Administrator's Guide.

Case 3: Broadcast Ping to All Local and External Inbound Agents

Follow this procedure if you want to test all inbound agents on your local system as well as any inbound agents on external systems registered in your local system.

  1. Define database links from your local system to all the external systems you want to connect to, and from the external systems to your local system. You can use Oracle DBA Studio in Oracle Enterprise Manager to create database links or create the database links manually, as in step 1 of case 2.

  2. On the local system schedule propagation from the outbound agent that you want to use to send the ping messages, such as WF_OUT, to the other systems. On the external systems, schedule propagation from the outbound agent there to your local system. You can use the Distributed Database Management feature to manage AQ, including scheduling propagation, through Oracle Enterprise Manager, or schedule propagation manually, as in step 2 of case 2.

  3. Register all the external systems with your local system, and register the local system with each external system. See: Registering External Systems.

  4. Launch the Workflow Agent Ping/Acknowledge workflow, selecting the Master Ping process as the process to run and specifying a unique item key and the outbound agent on the local system for sending the ping. Leave the inbound agent parameter null to send a broadcast ping to all inbound agents on the local system or external systems. You can use the Launch Processes Web page to launch the Workflow Agent Ping/Acknowledge workflow. See: Testing Workflow Definitions Using the Developer Studio.

    You can also launch the workflow manually. For example:

    declare
ename varchar2(100):=null;
itype varchar2(8):='WFPING';
ikey varchar2(10):='<item_key>';
wfprocess varchar2(10):='WFMSTPNG';
outAg varchar2(100):='WF_OUT@<local_system>';
toAg varchar2(100):=null;
ekey varchar2(100);

begin
fnd_global.APPS_INITIALIZE( 0, -1, -1 , 0 );
wf_engine.createprocess(itemtype=>itype, itemkey=>ikey, process=>wfprocess);

wf_engine.SetItemAttrText(itemtype=>itype, itemkey=>ikey, aname=>'EVNTKEY', avalue=>ekey);
wf_engine.SetItemAttrText(itemtype=>itype, itemkey=>ikey, aname=>'OUTAGENT', avalue=>outAg);
wf_engine.SetItemAttrText(itemtype=>itype, itemkey=>ikey, aname=>'TOAGENT', avalue=>toAg);

wf_engine.startprocess(itemtype=>itype, itemkey=>ikey);
commit;
end;
/

  5. Run agent listeners on the inbound agents on the local system and the external systems to process the Ping Agent events. You can use Oracle Workflow Manager to run agent listeners or run listeners manually, as in step 4 of case 1.

  6. Run an agent listener on the inbound agent on the local system where the Acknowledge Ping events are received to process those events. You can use Oracle Workflow Manager to run an agent listener or run a listener manually, as in step 4 of case 1.

  7. Use the Status Monitor to check the progress of the Workflow Agent Ping/Acknowledge workflow and verify that the Master Ping process and all the Detail Ping processes are complete. See: Viewing Workflows in the Status Monitor, 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 Developer Studio. You can optionally provide a to agent, event name, out agent, event key, and event message. See: Testing Workflow Definitions Using the Developer Studio.

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, Out 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