An event subscription is a registration indicating that a particular event is significant to a particular system and specifying the processing to perform when the triggering event occurs. You can define your event subscriptions in the Event Manager.
When you install Oracle Workflow, several default subscriptions to predefined Workflow events are automatically created. You can enable, disable, or copy these subscriptions to perform the event processing that you want. See: Predefined Workflow Events.
Whenever an event is raised locally or received from an external source, the Event Manager searches for and executes any eligible subscriptions. To be eligible, a subscription must meet the following requirements:
The subscriber must be the local system.
The triggering event must be the event that was raised or received, an event group that includes that event, or the Any event.
Both the subscription and its triggering event must be marked as active by having a status of Enabled.
The source type of the subscription must match the source of the event, either local or external.
If no eligible subscriptions exist for the event that occurred (apart from subscriptions to the Any event), then Oracle Workflow executes any enabled subscriptions by the local system to the Unexpected event with the appropriate source type. See: Any Event and Unexpected Event.
Note: Additionally, for events and subscriptions seeded by Oracle 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 and Synchronizing License Statuses.
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.
To begin defining a subscription, you specify which system is the subscriber. The subscriber is the system where you want the subscription to execute.
Each subscription defines an action on exactly one system, so you should define a separate subscription for each system involved in the processing you want to perform. For example, if you want to propagate data from one system to another, you should define one subscription for the sending system and another subscription for the receiving system.
You must specify the source type of the events to which the subscription applies. Events can have the following source types:
Local - The subscription applies only to events raised on the subscribing system.
External - The subscription applies only to events received by an inbound agent on the subscribing system.
Note: All event messages received by an inbound agent on the subscribing system are considered to have an External source, whether the sending agent is located on a remote system or on the local system.
Error - The subscription applies to only to errored events dequeued from the WF_ERROR queue or the WF_JAVA_ERROR queue.
Next, select the event that you want to trigger the subscription. You can choose either an individual event or an event group. If you choose an event group, the subscription will be triggered whenever any one of the group's member events occurs.
You can also optionally restrict the subscription to be triggered only by events received from a specific source agent. However, in most cases you do not need to specify a source agent.
The phase number for a subscription controls whether the subscription is executed immediately or is deferred. The Event Manager treats subscriptions with a phase number of 100 or higher as deferred subscriptions. Subscriptions with a phase number from 1 to 99 are executed immediately, unless processing for the event is deferred by another method. See: Deferred Subscription Processing.
If you define multiple subscriptions to the same event, the phase numbers for the subscriptions also control the order in which the Event Manager executes those subscriptions. Subscriptions are executed in ascending phase order. For example, you can enter 10 for the subscription that you want to execute first when an event occurs, 20 for the subscription that you want to execute second, and so on. You can use phases to ensure that different types of actions are performed in the appropriate order, such as executing subscriptions that perform validation before subscriptions that perform other types of processing.
Note: If you enter the same phase number for more than one subscription, the Event Manager may execute those subscriptions in any order, relative to each other. However, the Event Manager will still execute that group of subscriptions in their specified place in the phase order, relative to subscriptions with other phase numbers.
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:
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.
See: Access Protection for Business Event System Data.
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 and Synchronizing License Statuses.
Note: Any subscriptions that you define with a customization level of User are always treated as being licensed.
For each subscription, you can specify the type of error handling to perform if the Event Manager encounters an error while processing that subscription.
Stop and Rollback - The Event Manager halts all subscription processing for the event and rolls back any subscriptions already executed for the event. If the subscription trapped an error and returned a PL/SQL ERROR status code or a Java BusinessEventException, the Event Manager places the event message on the standard WF_ERROR or WF_JAVA_ERROR agent, as appropriate. If the subscription raised an unhandled exception, the Event Manager raises that exception to the calling application.
If you later retry subscription processing for the event, the Event Manager re-executes all subscriptions to the event.
Skip to Next - The Event Manager rolls back only this subscription. The Event Manager then places the event message on the standard WF_ERROR or WF_JAVA_ERROR agent, regardless of whether the subscription trapped an error or raised an unhandled exception. The exception is not raised to the calling application. Finally, the Event Manager continues processing the next subscription for the event according to the subscription phase order.
If you later retry subscription processing for the event, the Event Manager re-executes only the errored subscription.
Note: Skip to Next error handling is not available for subscriptions with a source type of Error. If an additional error occurs during such a subscription, processing for that event will be halted until the error is addressed.
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.
Subscription processing can include the following types of processing:
Send the event message to a workflow process.
Send the event message to an agent.
Send a notification to a role.
Receive an Oracle XML Gateway message from your trading partner.
Send an Oracle XML Gateway message to your trading partner.
Invoke a Web service.
Run a custom function on the event message.
By sending an event to a workflow process, you can model complex processing or routing logic beyond the standard action options. For example, you can branch to different functions, initiate subprocesses, send notifications, or select recipient agents, based on the contents of the event message, or modify the event message itself.
Events are represented within workflow processes by event activities. See: Event Activity.
To send the event to a particular workflow process, you must specify the item type and process name of the process. The item key for the process is determined either by the correlation ID specified in the event message, or by the event key if no correlation ID is specified. The event can either start a new process with that item key or continue an existing process identified by that item key that is waiting to receive it.
Note: The item key for a process instance can only contain single-byte characters. It cannot contain a multibyte value.
Note: You can call WF_EVENT_FUNCTIONS_PKG.AddCorrelation() during prior subscription processing to add a correlation ID to the event message. To use AddCorrelation(), you must enter a subscription parameter named ITEMKEY that specifies a function to generate the correlation ID. The function must be specified in the following format:
ITEMKEY=<package_name.function_name>
See: AddCorrelation.
You can also define additional subscription parameters to be used in one of two ways:
If you want to specify additional parameters to set as item attributes for the workflow process, you can enter these parameters for the subscription and choose the Add Subscription Parameters option to set the subscription parameters into the event message parameter list. The event parameters will then be set as item attributes for the workflow process when the process receives the event.
If you want to specify additional conditions to control whether or not the subscription is executed, you can enter subscription parameters that describe those conditions and choose the Launch when Parameters Match option. In this case the Event Manager sends the event to the specified workflow process only if the event message includes parameters whose names and values match all the parameters defined for the subscription. Ensure that you include the required parameters in the parameter list within the event message, either by providing them when the event is raised or by adding them during prior subscription processing.
If you want to send the event to multiple existing workflow processes, instead of to one particular process, you can choose the 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:
Sets any parameters in the event message parameter list as item type attributes for the process, creating new item type attributes if a corresponding attribute does not already exist for any parameter.
Sets the subscription's globally unique identifier (GUID) as a dynamic item attribute so that the workflow process can reference other information in the subscription definition.
If the event was originally raised by a Raise event activity in another workflow process, the item type and item key for that process are included in the parameter list within the event message. In this case, the Workflow Engine automatically sets the specified process as the parent for the process that receives the event, overriding any existing parent setting. See: SetItemParent.
Searches for receive event activities that are eligible to accept the event. For an activity to be eligible, the event must match the activity's event filter, and the activity must either be marked as a Start activity or have a status of 'NOTIFIED', meaning the process has transitioned to the event.
Note: If you chose the Launch when Business Key Matches option, then to be eligible an activity must have an event filter that matches the event, a status of 'NOTIFIED' , and a business key attribute that matches the event key.
If an event arrives at a Start activity to launch a new process instance, the Workflow Engine also searches for all other receive event activities that are marked as Start activities and that do not have any incoming transitions, regardless of their event filter. For these activities, the Workflow Engine sets the activity status to 'NOTIFIED' so that they will be ready to receive an event if any more events are sent to this process. This feature lets you design a workflow process that requires multiple events to be received when you do not know in advance the order in which the events will arrive.
Stores the event name, event key, and event message in item type attributes, as specified in each eligible activity node's event details.
Marks all the eligible event activity nodes with a status of 'COMPLETED' and continues the thread of execution from each of those nodes.
See: Default_Rule, Default_Rule2, Default_Rule3, and Instance_Default_Rule.
Note: You can also send an event to a workflow process by choosing the custom action option and including send processing in your custom rule function. See: Standard API for an Event Subscription Rule Function.
To send an event to an agent, you must specify either the Out Agent that should send the outbound message, or the To Agent that should receive the inbound message, or both.
If you specify both a To Agent and an Out Agent, Oracle Workflow places the event message on the Out Agent's queue for propagation, addressed to the To Agent.
If you specify a To Agent without an Out Agent, Oracle Workflow selects an outbound agent on the subscribing system whose queue type matches the queue type of the To Agent. The event message is then placed on this outbound agent's queue for propagation, addressed to the To Agent.
If you specify an Out Agent without a To Agent, Oracle Workflow places the event message on the Out Agent's queue without a specified recipient.
You can omit the To Agent if the Out Agent uses a multi-consumer queue with a subscriber list. (The standard Workflow queue handlers work only with multi-consumer queues.) In this case the queue's subscriber list determines which consumers can dequeue the message. If no subscriber list is defined for that queue, however, the event message is placed on the WF_ERROR queue for error handling.
Note: The subscriber list for a multi-consumer queue in Oracle Advanced Queuing is different from event subscriptions in the Oracle Workflow Business Event System. For more information, see: Subscription and Recipient Lists, Oracle Streams Advanced Queuing User's Guide and Reference.
You can also omit the To Agent if the Out Agent uses a single-consumer queue for which you have defined a custom queue handler. For a single-consumer queue, no specified consumer is required.
You can optionally specify the priority with which the recipient should dequeue a message. Messages are dequeued in ascending priority order.
You can also define additional subscription parameters to be used in one of two ways:
If you want to add more parameters to the event message before it is sent, you can enter these parameters for the subscription and choose the Add Subscription Parameters option to set the subscription parameters into the event message parameter list.
If you want to specify additional conditions to control whether or not the subscription is executed, you can enter subscription parameters that describe those conditions and choose the Launch when Parameters Match option. In this case the Event Manager sends the event to the specified agent only if the event message includes parameters whose names and values match all the parameters defined for the subscription. Ensure that you include the required parameters in the parameter list within the event message, either by providing them when the event is raised or by adding them during prior subscription processing.
If you want an event message to become available to the recipient at a future date, rather than being available immediately as soon as it is propagated, you can set the SEND_DATE attribute within the event message to the date you want. You should set the send date during prior subscription processing before the event is sent. The event message is propagated to the To Agent but does not become available for dequeuing until the specified date.
See: Default_Rule, Default_Rule2, and Default_Rule3.
Note: You can also send an event to an agent by choosing the custom action option and including send processing in your custom rule function. See: Standard API for an Event Subscription Rule Function.
If the only processing you need to perform when an event occurs is sending a notification, you can define a subscription that simply performs that action. In this case you do not need to define and run a complete workflow process to send the notification.
However, you must specify a message template for the notification you want to send. The message template must be a message defined within an item type in the Workflow Builder and stored in your database. You can either select a standard message provided by Oracle 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.
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 and GetValueForParameter.
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.
See: SendNotification.
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.
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.
If you want to invoke a BPEL process, identify the triggering business event, and define the BPEL process to accept the event data payload. Then identify the Web Services Description Language (WSDL) description URL and other Web service properties for the BPEL process, and define a subscription to your event specifying those properties. When the event occurs, the Business Event System executes the subscription and invokes the BPEL process. For more information about BPEL processes and setting up security for BPEL process Web services, see: Oracle BPEL Process Manager Developer's Guide and Oracle Web Services Manager Administrator's Guide.
To invoke any other Web service, identify the triggering business event, identify the WSDL description URL and other properties for the Web 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 Web service.
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.
The message transformation parameters let you specify XSL files to transform the XML input message and response message during pre-invocation or post-invocation processing. First, upload the XSL files to Oracle E-Business Suite using the oracle.apps.ecx.loader.LoadXSLTToClob loader in Oracle XML Gateway. Then specify the following parameters for the event or subscription:
WFBES_IN_XSL_FILENAME - The XSL file used to transform the XML input message during pre-invocation processing.
WFBES_OUT_XSL_FILENAME - The XSL file used to transform the XML response message during post-invocation processing.
Set each parameter value to the XSL file name, owning application short name, and version number, separated by colons, in the following format:
<filename>:<application_short_name>:<version>
The security parameters let you provide a user name and password in a UsernameToken element in the WS-Security header to authenticate the user invoking the Web service. If you want to provide these security parameters at the event level, first store the password in the database under the appropriate module name and key, using the $FND_TOP/sql/fndvltput.sql script. Then specify the following parameters for the event:
WFBES_SOAP_USERNAME - The user name for the Web service.
WFBES_SOAP_PASSWORD_MOD - The module name used to retrieve the password for the user.
WFBES_SOAP_PASSWORD_KEY - The key used to retrieve the password for the user.
For more information about using the $FND_TOP/sql/fndvltput.sql script, see the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
If you want to provide these security parameters at the subscription level, enter the user name and password in the subscription action details.
Additionally, you can specify the WFBES_SOAP_EXPIRY_DURATION parameter for the event or subscription to determine how long the WS-Security header remains valid before it expires. The expiration time for the header helps protect it from being reused during a replay attack. By default, the header is set to expire 60 seconds after it is created. You can optionally specify a different expiration time in the WFBES_SOAP_EXPIRY_DURATION parameter. Specify the value for this parameter in seconds.
The callback parameters let you raise or enqueue a callback event to continue processing based on the response message received from the Web service.
WFBES_CALLBACK_EVENT - Specify an event in whose event data Oracle Workflow should store the XML response message from the Web service.
WFBES_CALLBACK_AGENT - Specify an inbound Business Event System agent onto which Oracle Workflow should enqueue the callback event. If you do not specify a callback agent, then Oracle Workflow raises the callback event to the Business Event System locally.
You can then define subscriptions that define the processing to perform on the callback event. The callback event is assigned the same event key as the event originally used to invoke the Web service in order to identify it. For example, if the Web service was originally invoked through a raise event activity in a workflow process, you can send the callback event to continue the waiting process. If you set the event key of the original invoking event to the item key of the workflow process, Oracle Workflow can use the same event key in the callback event to identify the process to which the callback event should be sent.
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.
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.
Additionally, you can include custom processing by extending the oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription class and overriding the following methods.
preInvokeService - Override this method to add processing before the Web service is invoked. For example, you can transform the event data within the event message and create the Web service request. The default implementation performs XSL transformation using the XSL file specified in the WFBES_IN_XSL_FILENAME parameter.
setInputParts - Override this method to add parts to the XML input message, such as the header, body, and so on, according to the input message definition for the selected operation. For example, you can set specific input parts that you require, or extend this method to set values for RPC-style Web service invocation.
Note: Currently Oracle E-Business Suite Integrated SOA Gateway supports only document-style Web services by default.
The default implementation adds the event data payload as the body of the input message. It also adds any other parts provided as event parameters in the triggering event with parameter names in the following format:
WFBES_INPUT_<PartName>
addWSSecurityHeader - Override this method to add any WS-Security header to the SOAP request, or to specify custom logic for retrieving the user name and password used to build the UsernameToken element. The default implementation adds the UsernameToken element to the WS-Security header based on the WFBES_SOAP_USERNAME, WFBES_SOAP_PASSWORD_MOD, and WFBES_SOAP_PASSWORD_KEY parameters, and sets the expiration time for the header in the Timestamp element based on the WFBES_SOAP_EXPIRY_DURATION parameter.
addCustomSOAPHeaders - Override this method to add any custom SOAP headers to the SOAP request. Use this method to add any required SOAP headers that are not defined in the input message for the selected operation.
postInvokeService - Override this method to add processing after the Web service is successfully invoked. For example, you can process and validate the response, if one is expected, and update the application state. The default implementation performs XSL transformation using the XSL file specified in the WFBES_OUT_XSL_FILENAME parameter and raises or enqueues the callback event based on the WFBES_CALLBACK_EVENT and WFBES_CALLBACK_AGENT parameters.
See: Standard API for an Event Subscription Rule Function and WebServiceInvokerSubscription.
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).
You can extend your subscription processing by creating custom rule functions. A subscription can have either a PL/SQL rule function for processing in the database or a Java rule function for processing in the middle tier.
Custom rule functions must be defined according to a standard PL/SQL or Java API. See: Standard API for an Event Subscription Rule Function.
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.
You can use a rule function for many different purposes, including:
Performing validation
Processing inbound messages as a receive message handler for an application
Making modifications to an outbound message, such as adding a correlation ID that associates this message with other messages
Note: You can call WF_EVENT_FUNCTIONS_PKG.AddCorrelation() within a custom rule function to add a correlation ID during your custom processing. See: AddCorrelation.
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.
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.
You can associate a subscription with the program or application to which it belongs by setting the program name and brief identifier as the owner name and owner tag for the subscription. The program can then use this identifying information to locate the subscriptions that it owns. The subscription owner may be the same program as the owner of the triggering event, or a different program.
If you do not want subscriptions for an event to be executed immediately when the event occurs, you can defer the subscriptions. In this way you can return control more quickly to the calling application and let the Event Manager execute any costly subscription processing at a later time.
You can defer subscription processing by three different methods:
Raise the event with a future date in the SEND_DATE attribute. Use this method when you want to defer all subscription processing for a locally raised event until a particular effective date.
Define subscriptions to the event with phase numbers of 100 or higher. Use this method when you want to defer processing of particular subscriptions for either local or external events.
Set the dispatch mode of the Event Manager to deferred processing before raising the event from PL/SQL code. This method can be used to defer all subscription processing for a locally raised event. This method is not recommended, however, and should only be used in exceptional circumstances.
Note: Additionally, if an event is raised by PL/SQL code or received by a PL/SQL agent listener, the Event Manager always defers processing of any Java subscriptions to the event, regardless of their phase numbers.
When subscription processing for an event is deferred by any of these methods, the event message is placed on a standard deferred agent. If the subscription at which processing is deferred is a PL/SQL subscription, the event is placed on the standard WF_DEFERRED agent. If the subscription at which processing is deferred is a Java subscription, the event is placed on the standard WF_JAVA_DEFERRED agent. You must ensure that agent listeners are running to monitor the WF_DEFERRED and WF_JAVA_DEFERRED agents. See: Scheduling Listeners for Local Inbound Agents.
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.
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.
You can also use the phase number for a subscription to control whether the subscription is executed immediately or is deferred. The Event Manager treats subscriptions with a phase number of 100 or higher as deferred subscriptions. Both Local and External subscriptions can be deferred in this way.
Note: For this deferral method to take effect when an event is raised locally, the event must not be raised with a future send date, and the Event Manager must be in the normal synchronous mode for subscription processing. Otherwise, the event message will immediately be placed on the deferred queue, and the Event Manager will not execute any subscriptions until the event is dequeued from there.
When a triggering event is raised or received, the Event Manager executes subscriptions to that event in phase order until it encounters a subscription with a phase number of 100 or higher. The Event Manager sets that subscription into the ERROR_SUBSCRIPTION attribute within the event message, as well as setting the priority specified in the subscription properties into the PRIORITY attribute. Then the event message is placed on the appropriate deferred queue.
Note: Additionally, if an event is raised by PL/SQL code or received by a PL/SQL agent listener, and the Event Manager encounters a Java subscription to the event, it always defers the remaining subscription processing beginning with that subscription, regardless of the subscription phase number.
The amount of time by which subscription processing is deferred depends on the schedule defined for the agent listener monitoring the WF_DEFERRED or WF_JAVA_DEFERRED agent. When the listener dequeues an event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If a subscription ID is present, meaning that subscription processing was deferred from that subscription onwards, the Event Manager begins by executing that subscription, and then continues executing any other subscriptions to the event with the same or a higher phase number.
Note: The Event Manager resumes subscription processing at the phase number of the subscription set into the event message. It does not necessarily begin with the phase number 100, if there were no subscriptions with that phase number when the event was originally processed.
If you raise an event from a local application in PL/SQL code, you can also choose to defer all subscription processing for that event every single time the application raises it. To do so, call the SetDispatchMode() API with the mode 'ASYNC', indicating deferred (asynchronous) processing, just before calling the Raise() API. See: SetDispatchMode.
This method is not recommended, however, and should only be used in exceptional circumstances, since it requires hard-coding the deferral in your application. To retain the flexibility to modify subscription processing without intrusion into the application, you can simply raise the event with a future send date or mark some or all of the individual subscriptions for deferral using the subscription phase numbers.
When an event is raised after the dispatch mode is set to deferred processing, the Event Manager immediately places the event message on the WF_DEFERRED queue, without executing any of the subscriptions for the event. All subscriptions to the event are deferred, regardless of their phase number.
The amount of time by which subscription processing is deferred depends on the schedule defined for the agent listener monitoring the WF_DEFERRED agent. When the listener dequeues the event message, the Event Manager checks for a subscription ID in the ERROR_SUBSCRIPTION attribute. If the event message does not contain a subscription ID, meaning that all subscription processing for the event was deferred immediately after the event was raised, then the Event Manager proceeds to execute all subscriptions to the event, in ascending phase order.
Note: If an event was deferred when it was raised, the Event Manager executes all eligible subscriptions to the event when the event is dequeued from the WF_DEFERRED queue, regardless of the subscription phase numbers. Subscriptions will not be deferred a second time, even if they have a phase number of 100 or higher.
If an event is raised locally from PL/SQL code, or received on an agent and processed by a PL/SQL agent listener, the Event Manager performs subscription processing in the database tier. It begins processing the subscriptions to the event in phase order and executes PL/SQL subscriptions synchronously, within the same database session, as long as the subscriptions are not deferred.
If the Event Manager encounters a PL/SQL subscription that is deferred, it stops processing and places the event message on the WF_DEFERRED agent. Subscription processing for the event resumes when the Workflow Deferred Agent Listener or another agent listener runs on that agent.
If the Event Manager encounters any Java subscription, or if the event has a Java generate function, the Event Manager stops processing and places the event message on the WF_JAVA_DEFERRED agent, regardless of the subscription phase number. Subscription processing for the event resumes when the Workflow Java Deferred Agent Listener or another agent listener runs on that agent.
If an event is raised locally from Java code, or received on an agent and processed by a Java agent listener, the Event Manager performs subscription processing in the middle tier. It begins processing the subscriptions to the event in phase order, executing Java subscriptions in Java and PL/SQL subscriptions using Java Database Connectivity (JDBC), as long as the subscriptions are not deferred.
If the Event Manager encounters a Java subscription that is deferred, it stops processing and places the event message on the WF_JAVA_DEFERRED agent. Subscription processing for the event resumes when the Workflow Java Deferred Agent Listener or another agent listener runs on that agent.
If the Event Manager encounters a PL/SQL subscription that is deferred, it stops processing and places the event message on the WF_DEFERRED agent. Subscription processing for the event resumes when the Workflow Deferred Agent Listener or another agent listener runs on that agent.