Overview of the Oracle Workflow Business Event System

The Oracle Workflow Business Event System leverages the Oracle Advanced Queuing infrastructure to communicate business events between systems. When a significant business event occurs in an internet or intranet application on a system, it triggers event subscriptions that specify the processing to execute for that event.

Subscriptions can include the following types of processing:

Sending event information to a workflow process

Sending event information to named communication points called agents on the local system or external systems

The event information communicated by the Business Event System is called an event message. The event message includes header properties to identify the event as well as event data describing what occurred.

You define events, systems, agents, and subscriptions in the Event Manager. You can also define event activities in the Workflow Builder to include business events in your workflow processes.

Agent Structure

Oracle Workflow uses the object type WF_AGENT_T to store information about an agent in a form that can be referenced by an event message. The following table lists the attributes of the WF_AGENT_T datatype.

WF_AGENT_T Attributes

Attribute Name

Datatype

Description

NAME

VARCHAR2(30)

The name of the agent.

SYSTEM

VARCHAR2(30)

The system where the agent is located.

The WF_AGENT_T object type also includes the following methods, which you can use to retrieve and set the values of its attributes.

Arguments (input)

setSystem

PL/SQL Syntax

Description

Sets the value of the SYSTEM attribute in a WF_AGENT_T object.

Arguments (input)

Variable

Description

pSystem

The value for the SYSTEM attribute.

Parameter Structure

Oracle Workflow uses the object type WF_PARAMETER_T to store a parameter name and value pair in a form that can be included in an event message parameter list. WF_PARAMETER_T allows custom values to be added to the WF_EVENT_T event message object. The following table lists the attributes of the WF_PARAMETER_T datatype.

WF_PARAMETER_T Attributes

Attribute Name

Datatype

Description

NAME

VARCHAR2(30)

The parameter name.

VALUE

VARCHAR2(2000)

The parameter value.

The WF_PARAMETER_T object type also includes the following methods, which you can use to retrieve and set the values of its attributes.

Arguments (input)

setValue

PL/SQL Syntax

Description

Sets the value of the VALUE attribute in a WF_PARAMETER_T object.

Arguments (input)

Variable

Description

pValue

The value for the VALUE attribute.

Parameter List Structure

Oracle Workflow uses the named varying array (varray) WF_PARAMETER_LIST_T to store a list of parameters in a form that can be included in an event message. WF_PARAMETER_LIST_T allows custom values to be added to the WF_EVENT_T event message object. The WF_PARAMETER_LIST_T datatype can include up to 100 parameter name and value pairs. A description of this datatype is as follows:

WF_PARAMETER_LIST_T

Maximum size: 100

Element datatype: WF_PARAMETER_T

Event Message Structure

Oracle Workflow uses the object type WF_EVENT_T to store event messages. This datatype contains all the header properties of an event message as well as the event data payload, in a serialized form that is suitable for transmission outside the system.

WF_EVENT_T defines the event message structure that the Business Event System and the Workflow Engine use to represent a business event. Internally, the Business Event System and the Workflow Engine can only communicate events in this format. Many of the standard queues that Oracle Workflow provides for the Business Event System use WF_EVENT_T as their payload type.

Note: If you want to use queues with a custom payload type, including any existing queues you already have defined on your system, you must create a queue handler to translate between the standard Workflow WF_EVENT_T structure and your custom payload type. See: Setting Up Queues, Oracle Workflow Administrator's Guide and Standard APIs for a Queue Handler, Oracle Workflow Developer's Guide.

The following table lists the attributes of the WF_EVENT_T datatype.

WF_EVENT_T Attributes

Attribute Name

Datatype

Description

PRIORITY

NUMBER

The priority with which the message recipient should dequeue the message. A smaller number indicates a higher priority. For example, 1 represents a high priority, 50 represents a normal priority, and 99 represents a low priority.

SEND_DATE

DATE

The date and time when the message is available for dequeuing. The send date can be set to the system date to indicate that the message is immediately available for dequeuing, or to a future date to indicate future availability. If the send date is set to a future date when an event is raised, the event message is placed on the WF_DEFERRED queue, and subscription processing does not begin until the specified date. If the send date is set to a future date when an event is sent to an agent, the event message is propagated to that agent's queue, but does not become available for the consumer to dequeue until the specified date.

RECEIVE_DATE

DATE

The date and time when the message is dequeued by an agent listener.

CORRELATION_ID

VARCHAR2(240)

A correlation identifier that associates this message with other messages. This attribute is initially blank but can be set by a function. If a value is set for the correlation ID, then that value is used as the item key if the event is sent to a workflow process. Note that the item key for a process instance can only contain single-byte characters. It cannot contain a multibyte value.

PARAMETER_LIST

WF_PARAMETER_LIST_T

A list of additional parameter name and value pairs.

EVENT_NAME

VARCHAR2(240)

The internal name of the event.

EVENT_KEY

VARCHAR2(240)

The string that uniquely identifies the instance of the event.

EVENT_DATA

CLOB

A set of additional details describing what occurred in the event. The event data can be structured as an XML document.

FROM_AGENT

WF_AGENT_T

The agent from which the event is sent. For locally raised events, this attribute is initially null.

TO_AGENT

WF_AGENT_T

The agent to which the event should be sent (the message recipient).

ERROR_SUBSCRIPTION

RAW(16)

If an error occurs while processing this event, this is the subscription that was being executed when the error was encountered.

ERROR_MESSAGE

VARCHAR2(4000)

An error message that the Event Manager generates if an error occurs while processing this event.

ERROR_STACK

VARCHAR2(4000)

An error stack of arguments that the Event Manager generates if an error occurs while processing this event. The error stack provides context information to help you locate the source of an error.

The WF_EVENT_T object type also includes the following methods, which you can use to retrieve and set the values of its attributes.

Note: You can set the values of the EVENT_NAME, EVENT_KEY, and EVENT_DATA attributes individually using the setEventName, setEventKey, and setEventData methods, or you can use the Content method to set all three event content attributes at once. See: Content.

Similarly, you can set the values of the FROM_AGENT, TO_AGENT, PRIORITY, and SEND_DATE attributes individually using the setFromAgent, setToAgent, setPriority, and setSendDate methods, or you can use the Address method to set all four address attributes at once. See: Address.

Arguments (input)

setCorrelationID

PL/SQL Syntax

Description

Sets the value of the CORRELATION_ID attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pCorrelationID

The value for the CORRELATION_ID attribute.

setParameterList

PL/SQL Syntax

MEMBER PROCEDURE setParameterList
(pParameterList in wf_parameter_list_t)

Description

Sets the value of the PARAMETER_LIST attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pParameterList

The value for the PARAMETER_LIST attribute.

setEventName

PL/SQL Syntax

MEMBER PROCEDURE setEventName
(pEventName in varchar2)

Description

Sets the value of the EVENT_NAME attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pEventName

The value for the EVENT_NAME attribute.

setEventKey

PL/SQL Syntax

MEMBER PROCEDURE setEventKey
(pEventKey in varchar2)

Description

Sets the value of the EVENT_KEY attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pEventKey

The value for the EVENT_KEY attribute.

setEventData

PL/SQL Syntax

MEMBER PROCEDURE setEventData
(pEventData in clob)

Description

Sets the value of the EVENT_DATA attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pEventData

The value for the EVENT_DATA attribute.

setFromAgent

PL/SQL Syntax

MEMBER PROCEDURE setFromAgent
(pFromAgent in wf_agent_t)

Description

Sets the value of the FROM_AGENT attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pFromAgent

The value for the FROM_AGENT attribute.

setToAgent

PL/SQL Syntax

MEMBER PROCEDURE setToAgent
(pToAgent in wf_agent_t)

Description

Sets the value of the TO_AGENT attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pToAgent

The value for the TO_AGENT attribute.

setErrorSubscription

PL/SQL Syntax

MEMBER PROCEDURE setErrorSubscription
(pErrorSubscription in raw)

Description

Sets the value of the ERROR_SUBSCRIPTION attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pErrorSubscription

The value for the ERROR_SUBSCRIPTION attribute.

setErrorMessage

PL/SQL Syntax

MEMBER PROCEDURE setErrorMessage
(pErrorMessage in varchar2)

Description

Sets the value of the ERROR_MESSAGE attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pErrorMessage

The value for the ERROR_MESSAGE attribute.

setErrorStack

PL/SQL Syntax

MEMBER PROCEDURE setErrorStack
(pErrorStack in varchar2)

Description

Sets the value of the ERROR_STACK attribute in a WF_EVENT_T object.

Arguments (input)

Variable

Description

pErrorStack

The value for the ERROR_STACK attribute.

Content

PL/SQL Syntax

MEMBER PROCEDURE Content
(pName in varchar2,
pKey in varchar2,
pData in clob)

Description

Sets the values of all the event content attributes in a WF_EVENT_T object, including EVENT_NAME, EVENT_KEY, and EVENT_DATA.

Arguments (input)

Variable

Description

pName

The value for the EVENT_NAME attribute.

pKey

The value for the EVENT_KEY attribute.

pData

The value for the EVENT_DATA attribute.

Address

PL/SQL Syntax

MEMBER PROCEDURE Address
(pOutAgent in wf_agent_t,
pToAgent in wf_agent_t,
pPriority in number,
pSendDate in date)

Description

Sets the values of the all address attributes in a WF_EVENT_T object, including FROM_AGENT, TO_AGENT, PRIORITY, and SEND_DATE.

Arguments (input)

Variable

Description

pOutAgent

The value for the FROM_AGENT attribute.

pToAgent

The value for the TO_AGENT attribute.

pPriority

The value for the PRIORITY attribute.

pSendDate

The value for the SEND_DATE attribute.

AddParameterToList

PL/SQL Syntax

MEMBER PROCEDURE AddParameterToList
(pName in varchar2,
pValue in varchar2)

Description

Adds a new parameter name and value pair to the list stored in the PARAMETER_LIST attribute of a WF_EVENT_T object. If a parameter with the specified name already exists in the parameter list, then the previous value of that parameter is overwritten with the specified value.

Arguments (input)

Variable

Description

pName

The parameter name.

pValue

The parameter value.

GetValueForParameter

PL/SQL Syntax

Description

Returns the value of the specified parameter from the list stored in the PARAMETER_LIST attribute of a WF_EVENT_T object. This method begins at the end of the parameter list and searches backwards through the list. If no parameter with the specified name is found in the parameter list, then the method returns NULL.

Arguments (input)

Variable

Description

pName

The parameter name.

Example for Using Abstract Datatypes

The following example shows some ways to use abstract datatype methods in a SQL script, including:

Initializing a new event message structure with the Initialize method

Important: You must call the Initialize method before you can perform any further manipulation on a new WF_EVENT_T object.

Initializing a CLOB locator

Writing a text variable into a CLOB variable

Setting the content attributes of the event message structure with the Content method

Setting the address attributes of the event message structure with the Address method

The example code is from the script wfevtenq.sql, which enqueues an event message on a queue using an override agent. See: Wfevtenq.sql, Oracle Workflow Administrator's Guide.

Mapping Between WF_EVENT_T and SYS.AQ$_JMS_TEXT_MESSAGE

Java Message Service (JMS) is a messaging standard defined by Sun Microsystems, Oracle, IBM, and other vendors. JMS is a set of interfaces and associated semantics that define how a JMS client accesses the facilities of an enterprise messaging product.

Oracle Java Message Service provides a Java API for Oracle Advanced Queuing (AQ) based on the JMS standard. Oracle JMS supports the standard JMS interfaces and has extensions to support the AQ administrative operations and other AQ features that are not a part of the standard. The abstract datatype used to store a JMS Text message in an AQ queue is called SYS.AQ$_JMS_TEXT_MESSAGE.

Oracle Workflow supports communication of JMS Text messages through the Business Event System by providing a queue handler called WF_EVENT_OJMSTEXT_QH. This queue handler translates between the standard Workflow WF_EVENT_T message structure and SYS.AQ$_JMS_TEXT_MESSAGE. Oracle Workflow also provides standard inbound and outbound queues that you can use for JMS Text messages, These queues are called WF_JMS_IN and WF_JMS_OUT, respectively, and use the WF_EVENT_OJMSTEXT_QH queue handler. See: Agents, Oracle Workflow Developer's Guide.

The SYS.AQ$_JMS_TEXT_MESSAGE datatype contains the following attributes.

HEADER - Header properties in the SYS.AQ$_JMS_HEADER datatype

TEXT_LEN - The size of the message payload, set automatically

TEXT_VC - The message payload in VARCHAR2 format, if the payload is equal to or less than 4000 bytes

TEXT_LOB - The message payload in CLOB format, if the payload is greater than 4000 bytes

The SYS.AQ$_JMS_HEADER datatype contains the following attributes.

REPLYTO - A Destination supplied by a client when a message is sent

TYPE - The type of the message

USERID - The identity of the user sending the message

APPID - The identity of the application sending the message

GROUPID - The identity of the message group of which this message is a part; set by the client

Event APIs

The Event APIs can be called by an application program or a workflow process in the runtime phase to communicate with the Business Event System and manage events. These APIs are defined in a PL/SQL package called WF_EVENT.

Raise

PL/SQL Syntax

Description

Raises a local event to the Event Manager. Raise() creates a WF_EVENT_T structure for this event instance and sets the specified event name, event key, event data, parameter list, and send date into the structure.

The event data can be passed to the Event Manager within the call to the Raise() API, or the Event Manager can obtain the event data itself by calling the generate function for the event, after first checking whether the event data is required by a subscription. If the event data is not already available in your application, you can improve performance by allowing the Event Manager to run the generate function and generate the event data only when subscriptions exist that require that data, rather than always generating the event data from your application at runtime. See: Events, Oracle Workflow Developer's Guide and Standard API for an Event Data Generate Function, Oracle Workflow Developer's Guide.

The send date can optionally be set to indicate when the event should become available for subscription processing. If the send date is null, Raise() sets the send date to the current system date. You can defer an event by setting the send date to a date later than the system date. In this case, the Event Manager places the event message on the standard WF_DEFERRED queue, where it remains in a WAIT state until the send date. When the send date arrives, the event message becomes available for dequeuing and will be dequeued the next time an agent listener runs on the WF_DEFERRED queue.

Note: If an event is deferred when it is raised, the event retains its original Local source type when it is dequeued from the WF_DEFERRED queue.

When an event is raised and is not deferred, or when an event that was deferred is dequeued from the WF_DEFERRED queue, the Event Manager begins subscription processing for the event. The Event Manager searches for and executes any enabled subscriptions by the local system to that event with a source type of Local, and also any enabled subscriptions by the local system to the Any event with a source type of Local. If no enabled subscriptions exist for the event that was raised (apart from subscriptions to the Any event), then Oracle Workflow executes any enabled subscriptions by the local system to the Unexpected event with a source type of Local.

Note: The Event Manager does not raise an error if the event is not defined.

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: For subscriptions with Stop and Rollback error handling, any exceptions raised during subscription processing are not trapped, but instead are exposed to the code that called the Raise() procedure. This behavior enables you to use subscriptions and their rule functions to perform validation, with the same results as if the validation logic were coded inline.

For subscriptions with Skip to Next error handling, no exceptions are exposed to the calling application. This behavior lets you continue processing without waiting in cases where the calling application does not depend on the successful completion of those subscriptions.

Arguments (input)

Variable

Description

p_event_name

The internal name of the event.

p_event_key

A string generated when the event occurs within a program or application. The event key uniquely identifies a specific instance of the event.

p_event_data

An optional set of information about the event that describes what occurred. 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. See: Events, Oracle Workflow Developer's Guide and Standard API for an Event Data Generate Function, Oracle Workflow Developer's Guide.

p_parameters

An optional list of additional parameter name and value pairs.

p_send_date

An optional date to indicate when the event should become available for subscription processing.

PL/SQL Syntax

Description

Raises a local event to the Event Manager and returns the parameter list for the event. Raise3() performs the same processing as the Raise() procedure, except that Raise3() passes the event parameter list back to the calling application after completing the event subsription processing. See: Raise.

Raise3() creates a WF_EVENT_T structure for this event instance and sets the specified event name, event key, event data, parameter list, and send date into the structure. Then, if the event is not deferred, the Event Manager begins subscription processing for the event. The Event Manager searches for and executes any enabled subscriptions by the local system to that event with a source type of Local, and also any enabled subscriptions by the local system to the Any event with a source type of Local. If no enabled subscriptions exist for the event that was raised (apart from subscriptions to the Any event), then Oracle Workflow executes any enabled subscriptions by the local system to the Unexpected event with a source type of Local.

After completing subscription processing for the event, Raise3() returns the parameter list for the event, including any modifications made to the parameters by the rule functions of the subscriptions. In this way, event subscriptions can communicate parameters back to the application that raised the event.

Note: For subscriptions with Stop and Rollback error handling, any exceptions raised during subscription processing are not trapped, but instead are exposed to the code that called the Raise3() procedure. This behavior enables you to use subscriptions and their rule functions to perform validation, with the same results as if the validation logic were coded inline.

For subscriptions with Skip to Next error handling, no exceptions are exposed to the calling application. This behavior lets you continue processing without waiting in cases where the calling application does not depend on the successful completion of those subscriptions.

Arguments (input)

Variable

Description

p_event_name

The internal name of the event.

p_event_key

A string generated when the event occurs within a program or application. The event key uniquely identifies a specific instance of the event.

p_event_data

An optional set of information about the event that describes what occurred. 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. See: Events, Oracle Workflow Developer's Guide and Standard API for an Event Data Generate Function, Oracle Workflow Developer's Guide.

p_parameter_list

A list of additional parameter name and value pairs.

p_send_date

An optional date to indicate when the event should become available for subscription processing.

Send

PL/SQL Syntax

procedure Send
(p_event in out wf_event_t);

Description

Sends an event message from one agent to another. If the event message contains both a From Agent and a To Agent, the message is placed on the outbound queue of the From Agent and then asynchronously delivered to the To Agent by AQ propagation, or whichever type of propagation is implemented for the agents' protocol.

If the event message contains a To Agent but no specified From Agent, the message is sent from the default outbound agent that matches the queue type of the To Agent.

If the event message contains a From Agent but no specified To Agent, the event message is placed on the From Agent's queue without a specified recipient.

You can omit the To Agent if the From 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. See: Subscription and Recipient Lists, Oracle Streams Advanced Queuing User's Guide and Reference.

You can also omit the To Agent if the From 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.

The send date within the event message indicates when the message should become available for the consumer to dequeue. If the send date is blank, the Send() procedure resets the value to the current system date, meaning the message is immediately available for dequeuing as soon as it is propagated. If the send date is a future date, the message is marked with a delay time corresponding to that date and does not become available for dequeuing until the delay time has passed. For more information, see: Time Specification: Delay, Oracle Streams Advanced Queuing User's Guide and Reference.

Note: If you want to use the send date to determine when a message becomes available for dequeuing on the To Agent, you should set the send date during subscription processing before Send() is called.

Send() returns the final event message that was sent, including any properties set by the procedure.

Arguments (input)

Variable

Description

p_event

The event message.

NewAgent

PL/SQL Syntax

function NewAgent
(p_agent_guid in raw) return wf_agent_t;

Description

Creates a WF_AGENT_T structure for the specified agent and sets the agent's system and name into the structure. See: Agent Structure.

Arguments (input)

Variable

Description

p_agent_guid

The globally unique identifier of the agent.

Test

PL/SQL Syntax

function Test
(p_event_name in varchar2) return varchar2;

Description

Tests whether the specified event is enabled and whether there are any enabled subscriptions by the local system referencing the event, or referencing an enabled event group that contains the event. Test() returns the most costly data requirement among these subscriptions, using the following result codes:

NONE - No enabled local subscriptions reference the event, or the event does not exist.

KEY - At least one enabled local subscription references the event, but all such subscriptions require only the event key.

MESSAGE - At least one enabled local subscription on the event requires the complete event data.

Arguments (input)

Variable

Description

p_event_name

The internal name of the event.

Enqueue

PL/SQL Syntax

Description

Enqueues an event message onto a queue associated with an outbound agent. You can optionally specify an override agent where you want to enqueue the event message. Otherwise, the event message is enqueued on the From Agent specified within the message. The message recipient is set to the To Agent specified in the event message. Enqueue() uses the queue handler for the outbound agent to place the message on the queue.

Arguments (input)

Variable

Description

p_event

The event message.

p_out_agent_override

The outbound agent on whose queue the event message should be enqueued.

Description

There are two implementations of Listen(). Both implementations monitor an agent for inbound event messages and dequeue messages using the agent's queue handler, in the database tier.

The standard WF_EVENT_QH queue handler sets the date and time when an event message is dequeued into the RECEIVE_DATE attribute of the event message. Custom queue handlers can also set the RECEIVE_DATE value if this functionality is included in the Dequeue API.

When an event is dequeued, the Event Manager searches for and executes any enabled subscriptions by the local system to that event with a source type of External, and also any enabled subscriptions by the local system to the Any event with a source type of External. If no enabled subscriptions exist for the event that was received (apart from subscriptions to the Any event), then Oracle Workflow executes any enabled subscriptions by the local system to the Unexpected event with a source type of External.

The first implementation of the Listen() procedure exits after it has dequeued all event messages on the agent's queue, unless you specify a wait period to block on the queue waiting for additional messages.

The second implementation of the Listen() procedure exits after it has dequeued the specified maximum number of event messages. However, if errors occur during processing, the Listen() procedure exits after it encounters the specified maximum number of errors. If there are fewer than the maximum number of event messages on the queue, and fewer than the maximum number of errors occur, then the procedure exits after it has dequeued all the event messages on the queue, unless you specify a wait period to block on the queue waiting for additional messages.

You must not call Listen() from within application code. If you want to call this procedure directly, you can run it from SQL*Plus. Otherwise, you can schedule PL/SQL agent listeners for your inbound agents from Oracle Applications Manager. See: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide.

You can optionally restrict the event messages that the Listen() procedure will process by specifying an AQ correlation ID consisting of an event name, or a partial event name followed by a percent sign (%) as a wildcard character. You can also optionally restrict the event messages that the Listen() procedure will process by specifying a dequeue condition that references the properties or content of the message. However, you cannot specify both of these parameters at the same time. If you specify one, you must leave the other null.

Arguments (input)

Variable

Description

p_agent_name

The name of the inbound agent.

p_wait

An optional wait period, in seconds, during which you want the agent listener to block on the agent's queue to wait for messages. By default an agent listener does not wait but exits if all messages on the queue have been dequeued.

p_correlation

Optionally specify an AQ correlation ID to identify the event messages that you want the agent listener to process. The AQ correlation ID for an event message in the Business Event System is usually specified as an event name, or as a partial event name followed by a percent sign (%) as a wildcard character. Consequently, by specifying an AQ correlation ID in this parameter, you can dedicate the agent listener to listen only for messages that are instances of the specified event or events. For example, you can specify oracle.apps.wf.notification% to listen for all events related to notifications whose names begin with that value. The default value for this correlation ID is null, which allows the agent listener to process messages that are instances of any event. If a dequeue condition is specified in the next parameter, this parameter must be null. See: Dequeue Methods, Oracle Streams Advanced Queuing User's Guide and Reference.

Note: The AQ correlation ID is different than the correlation ID contained within the WF_EVENT_T event message structure.

p_deq_condition

Optionally specify a dequeue condition to identify the event messages that you want the agent listener to process. A dequeue condition is an expression that is similar in syntax to the WHERE clause of a SQL query. Dequeue conditions are expressed in terms of the attributes that represent message properties or message content. The messages in the queue are evaluated against the condition, so you can restrict the agent listener to listen only for messages that satisfy this condition. The default value is null, which does not place any restriction on the messages the agent listener can process. If an AQ correlation ID is specified in the previous parameter, this parameter must be null. See: Dequeue Methods, Oracle Streams Advanced Queuing User's Guide and Reference.

p_message_count

The maximum number of event messages the agent listener can process in one batch. Increasing the value of this parameter can help improve performance if you need to process large volumes of event messages.

p_max_error_count

The maximum number of errors the agent listener can encounter before it exits.

Related Topics

Any Event, Oracle Workflow Developer's Guide

Unexpected Event, Oracle Workflow Developer's Guide

Wfagtlst.sql, Oracle Workflow Administrator's Guide

Standard APIs for a Queue Handler, Oracle Workflow Developer's Guide

SetErrorInfo

PL/SQL Syntax

procedure SetErrorInfo
(p_event in out wf_event_t,
p_type in varchar2);

Description

Retrieves error information from the error stack and sets it into the event message. The error message and error stack are set into the corresponding attributes of the event message. The error name and error type are added to the PARAMETER_LIST attribute of the event message.

Arguments (input)

Variable

Description

p_event

The event message.

p_type

The error type, either 'ERROR' or 'WARNING'.

SetDispatchMode

PL/SQL Syntax

procedure SetDispatchMode
(p_mode in varchar2);

Description

Sets the dispatch mode of the Event Manager to either deferred or synchronous subscription processing. Call SetDispatchMode() with the mode 'ASYNC' just before calling Raise() to defer all subscription processing forever for the event that you will raise. In this case, the Event Manager places the event on the WF_DEFERRED queue before executing any subscriptions for that event. The subscriptions are not executed until an agent listener runs to dequeue the event from the WF_DEFERRED queue.

You can call SetDispatchMode() with the mode 'SYNC' to set the dispatch mode back to normal synchronous subscription processing. In this mode, the phase number for each subscription determines whether the subscription is executed immediately or deferred.

Note: This method of deferring subscription processing is not recommended 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 mark some or all of the individual subscriptions for deferral using the subscription phase numbers.

Arguments (input)

Variable

Description

p_mode

The dispatch mode: either 'ASYNC' for deferred (asynchronous) subscription processing, or 'SYNC' for synchronous subscription processing.

AddParameterToList

PL/SQL Syntax

procedure AddParameterToList
(p_name in varchar2,
p_value in varchar2,
p_parameterlist in out wf_parameter_list_t);

Description

Adds the specified parameter name and value pair to the end of the specified parameter list varray. If the varray is null, AddParameterToList() initializes it with the new parameter.

Arguments (input)

Variable

Description

p_name

The parameter name.

p_value

The parameter value.

p_parameterlist

The parameter list.

AddParameterToListPos

PL/SQL Syntax

procedure AddParameterToListPos
(p_name in varchar2,
p_value in varchar2,
p_position out integer,
p_parameterlist in out wf_parameter_list_t);

Description

Adds the specified parameter name and value pair to the end of the specified parameter list varray. If the varray is null, AddParameterToListPos() initializes it with the new parameter. The procedure also returns the index for the position at which the parameter is stored within the varray.

GetValueForParameterPos

PL/SQL Syntax

Description

Retrieves the value of the parameter stored at the specified position in the specified parameter list varray.

Arguments (input)

Variable

Description

p_position

The index representing the position of the parameter within the parameter list.

p_parameterlist

The parameter list.

SetMaxNestedRaise

PL/SQL Syntax

procedure SetMaxNestedRaise
(maxcount in number default 100);

Description

Sets the maximum number of nested raises that can be performed to the specified value. A nested raise occurs when one event is raised and a Local subscription to that event is executed and raises another event. The default maximum is 100.

Arguments (input)

Variable

Description

max_count

The maximum number of nested raises to allow.

GetMaxNestedRaise

PL/SQL Syntax

function GetMaxNestedRaise
return number;

Description

Returns the maximum number of nested raises that can currently be performed. A nested raise occurs when one event is raised and a Local subscription to that event is executed and raises another event.

GetParamListFromString

PL/SQL Syntax

Description

Parses a string of text containing parameters and returns the parsed parameters in a varray using the WF_PARAMETER_LIST_T abstract datatype. The parameter name and value pairs in the text string should be separated by spaces and should appear in the following format:

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

Arguments (input)

Variable

Description

p_parameters

A text string containing parameter name and value pairs, separated by spaces.

setNavigationParams

PL/SQL Syntax

Description

Sets the navigation parameters for dequeuing messages from an agent's queue, including the agent name and navigation threshold. The navigation threshold is the maximum number of messages the agent listener should dequeue before resetting its navigation to the FIRST_MESSAGE option.

setNavigationParams() is typically used in a queue handler before a loop that dequeues several messages from an agent's queue. For example, you can call this procedure before calling WF_EVENT.Listen(). For more information about dequeuing messages, see: Oracle Streams Advanced Queuing User’s Guide.

Arguments (input)

Variable

Description

p_agentName

The internal name of the agent.

p_navigationThreshold

The maximum number of messages the agent listener should dequeue before resetting its navigation to the FIRST_MESSAGE option. This parameter does not apply for queues that are enabled for transactional grouping.

resetNavigationParams

PL/SQL Syntax

procedure resetNavigationParams;

Description

Resets the navigation message counter, so that next navigation option to use is FIRST_MESSAGE or NEXT_TRANSACTION. This procedure is typically used in a queue handler when catching a dequeue exception. For more information about dequeuing messages, see: Oracle Streams Advanced Queuing User’s Guide.

getQueueNavigation

PL/SQL Syntax

function getQueueNavigation return BINARY_INTEGER;

Description

Returns the next dequeue navigation option that should be used, such as FIRST_MESSAGE, NEXT_MESSAGE, and so on. This function is typically used in a queue handler to obtain the appropriate navigation option just before dequeuing.

To ensure that the agent listener parameter NAVIGATION_RESET_THRESHOLD takes effect when you use a custom queue handler, you should call setNavigationParams() to set the dequeue navigation parameters before starting a loop to dequeue messages from a queue, and then call WF_EVENT.getQueueNavigation() before dequeuing to ensure that you use the appropriate navigation option.

Event Subscription Rule Function APIs

The event subscription rule function APIs provide standard rule functions that you can assign to event subscriptions. A rule function specifies the processing that Oracle Workflow performs when the subscription's triggering event occurs.

Oracle Workflow provides a standard Default_Rule function to perform basic subscription processing. The default rule function includes the following actions:

Sending the event message to a workflow process, if specified in the subscription definition

Sending the event message to an agent, if specified in the subscription definition

Oracle Workflow also provides some other standard rule functions that you can use. The Log, Error, Warning, and Success functions can be used for testing and debugging your application. Other standard rule functions provide specialized processing used in predefined Oracle Workflow event subscriptions or in special options you can choose to refine your subscription processing.

These rule function APIs are defined in a PL/SQL package called WF_RULE.

The WF_RULE package also provides a standard generate function that you can assign to events for demonstration and testing purposes. A generate function produces the complete event data from the event name, event key, and parameter list.

Description

Sending the event message to a workflow process, if specified in the subscription definition

Sending the event message to an agent, if specified in the subscription definition

If either of these operations raises an exception, Default_Rule() traps the exception, stores the error information in the event message, and returns the status code ERROR. Otherwise, Default_Rule() returns the status code SUCCESS.

Note: If the subscription is sending the event message to an error process in the System: Error (WFERROR) item type, then Default_Rule() generates a new correlation ID to use as the item key for the process in order to ensure that the item key is unique.

If you want to run a custom rule function on the event message before it is sent, you can define one subscription with a low phase number that uses the custom rule function, and then define another subscription with a higher phase number that uses the default rule function to send the event.

For example, follow these steps:

Define a subscription to the relevant event with your custom rule function and a phase of 10.

Define another subscription to the event with the rule function WF_EVENT.Default_Rule and a phase of 20, and specify the workflow or agent to which you want to send the event.

Raise the event to trigger the subscriptions. The subscription with the lower phase number will be executed first and will run your custom rule function on the event message. When the event is passed to the second subscription, the modified event message will be sent to the workflow or agent you specified.

You can also call Default_Rule() to add the default send processing within a custom rule function. If you enter a rule function other than Default_Rule() for a subscription, Oracle Workflow does not automatically send the event message to the workflow and agent specified in the subscription. Instead, if you want to send the message from the same subscription, you must explicitly include the send processing in your custom rule function, which you can optionally accomplish by calling Default_Rule(). See: Standard API for an Event Subscription Rule Function, Oracle Workflow Developer's Guide.

Note: You may find it advantageous to define multiple subscriptions to an event with simple rule functions that you can reuse, rather than creating complex specialized rule functions that cannot be reused.

Arguments (input)

Variable

Description

p_subscription_guid

The globally unique identifier of the subscription.

p_event

The event message.

Log

PL/SQL Syntax

Description

Logs the contents of the specified event message using DBMS_OUTPUT.put_line and returns the status code SUCCESS. Use this function to output the contents of an event message to a SQL*Plus session for testing and debugging purposes.

For example, if you want to test a custom rule function that modifies the event message, you can use Log() to show the event message both before and after your custom rule function is run. Define three subscriptions to the relevant event as follows:

Define the first subscription with a phase of 10 and the rule function WF_RULE.Log.

Define the second subscription with a phase of 20 and your custom rule function.

Define the third subscription with a phase of 30 and the rule function WF_RULE.Log.

Next, connect to SQL*Plus. Execute the following command:

set serveroutput on size 100000

Then raise the event using WF_EVENT.Raise. As the Event Manager executes your subscriptions to the event in phase order, you should see the contents of the event message both before and after your custom rule function is run.

Note: You should not assign Log() as the rule function for any enabled subscriptions in a production instance of Oracle Workflow. This function should be used for debugging only.

Arguments (input)

Variable

Description

p_subscription_guid

The globally unique identifier of the subscription.

p_event

The event message.

Error

PL/SQL Syntax

Description

Returns the status code ERROR. Additionally, when you assign this function as the rule function for a subscription, you must define a subscription parameter with the name ERROR_MESSAGE and a value set to the internal name of an Oracle Workflow error message. When the subscription is executed, Error() will set that error message into the event message using setErrorMessage(). See: setErrorMessage.

Enter the parameter name ERROR_MESSAGE in the Name field and the parameter value in the Value field in the Subscription Parameters region of the Create Event Subscription page. The parameter value must be a valid name of an Oracle Workflow error message. The names of the error messages provided by Oracle Workflow are stored in the NAME column of the WF_RESOURCES table for messages with a type of WFERR.

You can use Error() as a subscription rule function if you want to send the system administrator an error notification with one of the predefined Workflow error messages whenever a particular event is raised.

For example, define a subscription to the relevant event with the rule function WF_RULE.Error and define a subscription parameter with the name ERROR_MESSAGE and the value WFSQL_ARGS. Then raise the event to trigger the subscription. Because Error() returns the status code ERROR, the Event Manager places the event message on the WF_ERROR queue. When the listener runs on the WF_ERROR queue, an error notification will be sent to the system administrator with the message "Invalid value(s) passed for arguments", which is the display name of the WFSQL_ARGS error message.

Note: Error() does not raise any exception to the calling application when it completes normally.

Arguments (input)

Variable

Description

p_subscription_guid

The globally unique identifier of the subscription.

p_event

The event message.

Warning

PL/SQL Syntax

Description

Returns the status code WARNING. Additionally, when you assign this function as the rule function for a subscription, you must define a subscription parameter with the name ERROR_MESSAGE and a value set to the internal name of an Oracle Workflow error message. When the subscription is executed, Warning() will set that error message into the event message using setErrorMessage(). See: setErrorMessage.

Enter the parameter name ERROR_MESSAGE in the Name field and the parameter value in the Value field in the Subscription Parameters region of the Create Event Subscription page. The parameter value must be a valid name of an Oracle Workflow error message. The names of the error messages provided by Oracle Workflow are stored in the NAME column of the WF_RESOURCES table for messages with a type of WFERR.

You can use Warning() as a subscription rule function if you want to send the system administrator a warning notification with one of the predefined Workflow error messages whenever a particular event is raised.

For example, define a subscription to the relevant event with the rule function WF_RULE.Warning and define a subscription parameter with the name ERROR_MESSAGE and the value WFSQL_ARGS. Then raise the event to trigger the subscription. Because Warning() returns the status code WARNING, the Event Manager places the event message on the WF_ERROR queue, but subscription processing for the event still continues. When the listener runs on the WF_ERROR queue, a warning notification will be sent to the system administrator with the message "Invalid value(s) passed for arguments", which is the display name of the WFSQL_ARGS error message.

Note: Warning() does not raise any exception to the calling application when it completes normally.

Success

PL/SQL Syntax

Description

Returns the status code SUCCESS. This function removes the event message from the queue but executes no other code except returning the SUCCESS status code to the calling subscription.

You can use Success for testing and debugging purposes while developing code for use with the Business Event System. For example, if you are trying to debug multiple subscriptions to the same event, you can modify one of the subscriptions by replacing its rule function with WF_RULE.Success, leaving all other details for the subscription intact. When the subscription is executed, it will return SUCCESS but not perform any other subscription processing. This strategy can help you isolate a problem subscription.

Success() is analogous to the WF_STANDARD.Noop procedure used in the standard Noop activity.

Workflow_Protocol

PL/SQL Syntax

Description

Sends the event message to the workflow process specified in the subscription, which will in turn send the event message to the inbound agent specified in the subscription.

Note: Workflow_Protocol() does not itself send the event message to the inbound agent. This function only sends the event message to the workflow process, where you can model the processing that you want to send the event message on to the specified agent.

If the subscription also specifies an outbound agent, the workflow process places the event message on that agent's queue for propagation to the inbound agent. Otherwise, a default outbound agent will be selected.

If the subscription parameters include the parameter name and value pair ACKREQ=Y, then the workflow process waits to receive an acknowledgement after sending the event message.

If the workflow process raises an exception, Workflow_Protocol() stores the error information in the event message and returns the status code ERROR. Otherwise, Workflow_Protocol() returns the status code SUCCESS.

Error_Rule

PL/SQL Syntax

Description

Performs the same subscription processing as Default_Rule(), including:

Sending the event message to a workflow process, if specified in the subscription definition

Sending the event message to an agent, if specified in the subscription definition

However, if either of these operations encounters an exception, Error_Rule() reraises the exception so that the event is not placed back onto the WF_ERROR queue. Otherwise, Error_Rule() returns the status code SUCCESS.

Error_Rule() is used as the rule function for the predefined subscriptions to the Unexpected event and to the Any event with the Error source type. The predefined subscriptions specify that the event should be sent to the Default Event Error process in the System: Error item type.

You can also use this rule function with your own error subscriptions. Enter WF_RULE.Error_Rule as the rule function for your error subscription and specify the workflow item type and process that you want the subscription to launch.

Arguments (input)

Variable

Description

p_subscription_guid

The globally unique identifier of the subscription.

p_event

The event message.

Related Topics

Unexpected Event, Oracle Workflow Developer's Guide

Any Event, Oracle Workflow Developer's Guide

SetParametersIntoParameterList

PL/SQL Syntax

Description

Sets the parameter name and value pairs from the subscription parameters into the PARAMETER_LIST attribute of the event message, except for any parameter named ITEMKEY or CORRELATION_ID. For a parameter with one of these names, the function sets the CORRELATION_ID attribute of the event message to the parameter value.

If these operations raise an exception, SetParametersIntoParameterList() stores the error information in the event message and returns the status code ERROR. Otherwise, SetParametersIntoParameterList()returns the status code SUCCESS.

You can use SetParametersIntoParameterList()as the rule function for a subscription with a lower phase number, to add predefined parameters from the subscription into the event message. Then subsequent subscriptions with higher phase numbers can access those parameters within the event message.

Note: If the event message will later be sent to a workflow process, then the value for any ITEMKEY or CORRELATION_ID parameter can only contain single-byte characters, because the CORRELATION_ID attribute of the event message will be used as the item key for the process. The item key for a process instance can only contain single-byte characters. It cannot contain a multibyte value.

Default_Rule2

PL/SQL Syntax

Description

Performs the default subscription processing only if the PARAMETER_LIST attribute of the event message includes parameters whose names and values match all the parameters defined for the subscription. If the event includes the required parameters, then the rule function calls Default_Rule() to perform the following processing:

Sending the event message to a workflow process, if specified in the subscription definition

Sending the event message to an agent, if specified in the subscription definition

If either of these operations raises an exception, Default_Rule2() traps the exception, stores the error information in the event message, and returns the status code ERROR. Otherwise, Default_Rule2() returns the status code SUCCESS.

Default_Rule3

PL/SQL Syntax

Description

Sets the parameter name and value pairs from the subscription parameters into the PARAMETER_LIST attribute of the event message, and then performs the default subscription processing with the modified event message. This rule function first calls SetParametersIntoParameterList() to set the parameters and then calls Default_Rule() to perform the following processing:

Sending the event message to a workflow process, if specified in the subscription definition

Sending the event message to an agent, if specified in the subscription definition

If either of these operations raises an exception, Default_Rule3() traps the exception, stores the error information in the event message, and returns the status code ERROR. Otherwise, Default_Rule3() returns the status code SUCCESS.

SendNotification

PL/SQL Syntax

Description

Sends a notification as specified by the parameters in the PARAMETER_LIST attribute of the event message. Use this rule function to send notifications outside of a workflow process.

After sending the notification, this function 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 Oracle Workflow completes subscription processing for the event. You can then call WF_EVENT.GetValueForParameter() to obtain the value of the #NID parameter.

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.

SendNotification() calls the WF_NOTIFICATION.Send() API to send the notification, using the event parameters as the input arguments for WF_NOTIFICATION.Send(). The following table shows the names of the parameters you should include in the event parameter list to specify the notification you want to send, and the information you should provide in each parameter's value.

Parameters for Sending a Notification

Parameter Name

Parameter Value

RECIPIENT_ROLE

The role name assigned to receive the notification.

MESSAGE_TYPE

The item type associated with the message.

MESSAGE_NAME

The message internal name.

CALLBACK

The callback function name used for communication of SEND and RESPOND source message attributes.

CONTEXT

Context information passed to the callback function.

SEND_COMMENT

A comment presented with the message.

PRIORITY

The priority of the message. If this value is null, the Notification System uses the default priority of the message.

DUE_DATE

The date that a response is required. This optional due date is only for the recipient's information; it has no effect on processing.

Note: Although you can send a notification using the SendNotification() rule function without defining or running a workflow process, you do need to define the message you want to send within a workflow item type.

Instance_Default_Rule

PL/SQL Syntax

Description

Sends the event to all existing workflow process instances that have eligible receive event activities waiting to receive it. This rule function lets you use a business key attribute to identify one or more workflow processes that should receive the event, instead of sending the event to one particular process based on a specific item type, process name, and item key, as with Default_Rule().

Note: Instance_Default_Rule() only sends the event to continue existing workflow processes. If you want to send the event to launch a new process instance, use Default_Rule() instead.

First, Instance_Default_Rule() calls SetParametersIntoParameterList() to set any parameter name and value pairs from the subscription parameters into the PARAMETER_LIST attribute of the event message.

Next, the function searches for existing workflow processes that are eligible to receive this event. To be eligible, a workflow process must meet the following requirements:

The process includes a receive event activity with an activity status of NOTIFIED, meaning the process has transitioned to that activity and is waiting to receive the event.

The event filter for the receive event activity is set to one of the following values:

This individual event

An event group of which this event is a member

NULL, meaning the activity can receive any event

The receive event activity has an activity attribute named #BUSINESS_KEY whose default value is an item type attribute.

The current value of that item type attribute matches the event key.

After sending the event to all eligible workflow processes, Instance_Default_Rule() also sends the event message to an agent, if specified in the subscription definition.

If any operations raise an exception, Instance_Default_Rule() traps the exception, stores the error information in the event message, and returns the status code ERROR. Otherwise, Instance_Default_Rule() returns the status code SUCCESS.

Note: 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 use Instance_Default_Rule() as the rule function for a subscription, 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.

Default_Rule_Or

PL/SQL Syntax

Description

Performs the default subscription processing only if the PARAMETER_LIST attribute of the event message includes at least one parameter whose name and value match a parameter defined for the subscription. If the event includes a matching parameter, then the rule function calls Default_Rule() to perform the following processing:

Sending the event message to a workflow process, if specified in the subscription definition

Sending the event message to an agent, if specified in the subscription definition

If either of these operations raises an exception, Default_Rule_Or() traps the exception, stores the error information in the event message, and returns the status code ERROR. Otherwise, Default_Rule_Or() returns the status code SUCCESS.

The BUSINESSEVENT tag is the opening tag for the XML structure. The event-name attribute stores the event name, and the key attribute stores the event key.

The GENERATETIME tag stores the date and time when the XML document was generated. The mask attribute defines the date format mask. The XML documents generated by this API always use the date format mask "mm-dd-rr hh:mi:ss".

The PARAMETERS tag stores the parameter list for the event. The count attribute defines the number of parameters in the list. The PARAMETERS tag is included in the XML document only if the number of parameters is greater than zero.

The PARAMETER tag stores a parameter value for the event. The parameter-name attribute defines the parameter name. The data for the parameter value is included in a CDATA structure to avoid issues with reserved XML characters.

Arguments (input)

A string generated when the event occurs within a program or application. The event key uniquely identifies a specific instance of the event.

p_parameter_list

A list of additional parameter name and value pairs for the event.

WebServiceInvokerSubscription

The WebServiceInvokerSubscription class is a standard Java rule function that implements the SubscriptionInterface Java interface. This class invokes a business process execution language (BPEL) process or other Web service using the Web Services Invocation Framework (WSIF) from Oracle Application Server.

The WebServiceInvokerSubscription class is stored in the oracle.apps.fnd.wf.bes Java package. The following list shows the APIs in this class.

Important: Java is case-sensitive and all Java method names begin with a lower case letter to follow Java naming conventions.

Java Syntax

Description

Performs the subscription processing to invoke a Web service when the triggering event occurs by calling the preInvokeService, invokeService, and postInvokeService methods. The subscription parameters must provide the Web Services Description Language (WSDL) description URL, service name, port type, operation, and port for the Web service.

If the execution of the subscription processing does not succeed, this method throws a BusinessEventException to pass the error details to the Event Manager.

Arguments (input)

Variable

Description

eo

The Subscription object, which provides information about the subscription such as the phase number and parameters.

event

The BusinessEvent object, which provides information about the business event that occurred, including the event name, event key, event data, and payload object.

context

Workflow context information, including the database connection and the Log object which can be used for logging.

preInvokeService

The WebServiceInvokerSubscription class always calls the preInvokeService method before invoking the Web service.

Java Syntax

Description

Returns the string, usually in XML format, that will be used as the Web service request. The default implementation of this method checks whether an XSL file is specified in the WFBES_IN_XSL_FILENAME parameter for the subscription or the triggering event, and if so uses that XSL file to transform the event data to the format required for the Web service. Otherwise, the method simply returns the event data stored within the event message.

Note: If both the event and the subscription include the WFBES_IN_XSL_FILENAME parameter, then the event parameter value overrides the subscription parameter value.

If you extend the WebServiceInvokerSubscription class, you can override this method to add further processing before the Web service is invoked.

If the pre-invocation processing does not succeed, this method throws a BusinessEventException.

Arguments (input)

Variable

Description

eo

The Subscription object, which provides information about the subscription such as the phase number and parameters.

event

The BusinessEvent object, which provides information about the business event that occurred, including the event name, event key, event data, and payload object.

context

Workflow context information, including the database connection and the Log object which can be used for logging.

invokeService

The WebServiceInvokerSubscription class calls the invokeService method after performing any pre-invocation processing in the preInvokeService method.

Java Syntax

Description

Invokes the Web service according to the specified parameters and returns the response received from the Web service, if the operation resulted in a response. This method uses the string returned by the preInvokeService method as the Web service request.

The default implementation uses the Web Services Invocation Framework (WSIF) APIs to invoke the Web service. If you extend the WebServiceInvokerSubscription class, you can override this method to invoke the Web service through another implementation. For more information about WSIF, see: Using Web Services Invocation Framework, Oracle Application Server Advanced Web Services Developer's Guide.

If the invocation does not succeed, this method throws an Exception.

Arguments (input)

Variable

Description

wsdlLocation

The URL where the Web Services Description Language (WSDL) description for the Web service is located.

serviceName

The name of the Web service.

invokePort

The port, which is the 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.

portTypeName

The port type, or set of abstract operations, that includes the operation to invoke.

operationName

The operation to invoke.

eventData

The string returned by the preInvokeService method, usually in XML format, that will be used as the Web service request.

setInputParts

The setInputParts method is called during the invocation processing.

Java Syntax

Description

Adds parts to the XML input message, such as the header, body, and so on, according to the input message definition for the selected operation. 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. 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

If you extend the WebServiceInvokerSubscription class, you can override this method to add parts to the XML input message through custom logic. For example, you can set specific input parts that you require, or extend this method to set values for RPC-style Web service invocation.

addWSSecurityHeader

Java Syntax

Description

Adds a WS-Security compliant header to the ArrayList object containing the headers that will be added to the Web service request. The default implementation adds the UsernameToken element to the ArrayList based on the WFBES_SOAP_USERNAME, WFBES_SOAP_PASSWORD_MOD, and WFBES_SOAP_PASSWORD_KEY parameters for the subscription or the triggering event.

Note: If both the event and the subscription include the WFBES_SOAP_USERNAME, WFBES_SOAP_PASSWORD_MOD, and WFBES_SOAP_PASSWORD_KEY parameters, then the event parameter values override the subscription parameter values.

If you extend the WebServiceInvokerSubscription class, you can override this method to add any WS-Security header, or to specify custom logic for retrieving the user name and password used to build the UsernameToken element.

If the header processing does not succeed, this method throws an Exception.

Arguments (input)

Variable

Description

headersList

The ArrayList object containing the list of headers to which the WS-Security compliant header should be added.

postInvokeService

The WebServiceInvokerSubscription class calls the postInvokeService method after successfully invoking the Web service.

Java Syntax

Description

Allows processing to be performed on the response received from the Web service, if the operation resulted in a response. The default implementation of this method checks whether an XSL file is specified in the WFBES_OUT_XSL_FILENAME parameter for the subscription or the triggering event, and if so uses that XSL file to transform the XML response. The method also checks whether a callback event and callback agent are specified in the WFBES_CALLBACK_EVENT and WFBES_CALLBACK_AGENT parameters for the subscription or the triggering event. If a callback event is specified, postInvokeService stores the XML response in the event data of that event. If a callback agent is specified, postInvokeService enqueues the callback event onto that agent. Otherwise postInvokeService raises the callback event to the Business Event System locally.

Note: If both the event and the subscription include the WFBES_OUT_XSL_FILENAME, WFBES_CALLBACK_EVENT, and WFBES_CALLBACK_AGENT parameters, then the event parameter values override the subscription parameter values.

If you extend the WebServiceInvokerSubscription class, you can override this method to add further processing after the Web service is invoked. For example, you can process and validate the response and update the application state.

If the post-invocation processing does not succeed, this method throws a BusinessEventException.

Arguments (input)

Variable

Description

eo

The Subscription object, which provides information about the subscription such as the phase number and parameters.

event

The BusinessEvent object, which provides information about the business event that occurred, including the event name, event key, event data, and payload object.

context

Workflow context information, including the database connection and the Log object which can be used for logging.

requestData

The string that was sent as the Web service request.

responseData

The string that was received as the response from the Web service, if any.

get Parameter Methods

The WebServiceInvokerSubscription class includes several methods that return the values of the parameters used during the pre-invocation, invocation, and post-invocation processing.

The following methods return the values of parameters specified in the subscription definition that identify the Web service to invoke.

getWsdlLocation - Returns the URL where the Web Services Description Language (WSDL) description for the Web service is located, as specified in the SERVICE_WSDL_URL subscription parameter.

Java syntax: public String getWsdlLocation()

getService - Returns the service name as specified in the SERVICE_NAME subscription parameter.

getPort - Returns the port as specified in the SERVICE_PORT subscription parameter.

Java syntax: public String getPort()

getOperation - Returns the operation as specified in the SERVICE_OPERATION subscription parameter.

Java syntax: public String getOperation()

The following methods return the values of parameters that define further pre-invocation and post-invocation processing. These parameters can appear 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.

getOutXslFile - Returns the XSL file used to transform the XML response message during post-invocation processing, as specified in the WFBES_OUT_XSL_FILENAME parameter.

Java syntax: public String getOutXslFile()

getInXslFile - Returns the XSL file used to transform the XML input message during pre-invocation processing, as specified in the WFBES_IN_XSL_FILENAME parameter.

Java syntax: public String getInXslFile()

getCallbackEvent - Returns the event in whose event data Oracle Workflow should store the XML response message from the Web service, as specified in the WFBES_CALLBACK_EVENT parameter.

Java syntax: public String getCallbackEvent()

getCallbackAgent - Returns the inbound Business Event System agent onto which Oracle Workflow should enqueue the callback event, as specified in the WFBES_CALLBACK_AGENT parameter.

Java syntax: public String getCallbackAgent()

getUsername - Returns the user name for the Web service authentication, as specified in the WFBES_SOAP_USERNAME parameter.

Java syntax: public String getUsername()

getPasswordModule - Returns the module name used to retrieve the password for the user, as specified in the WFBES_SOAP_PASSWORD_MOD parameter.

Java syntax: public String getPasswordModule()

getPasswordKey - Returns the key used to retrieve the password for the user, as specified in the WFBES_SOAP_PASSWORD_KEY parameter.

Java syntax: public String getPasswordKey()

The following methods return the values of other parameters used in processing the Web service subscription.

getBusinessEvent - Returns the business event that triggered the subscription.

Java syntax: public BusinessEvent getBusinessEvent()

getBindingStyle - Returns the binding style of the current operation being invoked. The value of the binding style can be either document or rpc. Currently Oracle E-Business Suite Integrated SOA Gateway supports document-style Web services.

Event Function APIs

The Event Function APIs provide utility functions that can be called by an application program, the Event Manager, or a workflow process in the runtime phase to communicate with the Business Event System and manage events. These APIs are defined in a PL/SQL package called WF_EVENT_FUNCTIONS_PKG.

Parameters

PL/SQL Syntax

Description

Parses a string of text that contains the specified number of parameters delimited by the specified separator. Parameters() returns the parsed parameters in a varray using the T_PARAMETERS composite datatype, which is defined in the WF_EVENT_FUNCTIONS_PKG package. The following table describes the T_PARAMETERS datatype:

T_PARAMETERS Datatype

Datatype Name

Element Datatype Definition

T_PARAMETERS

VARCHAR2(240)

Parameters() is a generic utility that you can call in generate functions when the event key is a concatenation of values separated by a known character. Use this function to separate the event key into its component values.

SubscriptionParameters

PL/SQL Syntax

Description

Returns the value for the specified parameter from a text string containing the parameters defined for an event subscription. The parameter name and value pairs in the text string should be separated by spaces and should appear in the following format:

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

SubscriptionParameters() searches the text string for the specified parameter name and returns the value assigned to that name. For instance, you can call this function in a subscription rule function to retrieve the value of a subscription parameter, and then code different behavior for the rule function based on that value.

Arguments (input)

Variable

Description

p_string

A text string containing the parameters defined for an event subscription.

p_key

The name of the parameter whose value should be returned.

Sample Code

In the following example, SubscriptionParameters() is used to assign the value of the ITEMKEY subscription parameter to the l_function program variable. The example code is from the AddCorrelation function, which adds a correlation ID to an event message during subscription processing. See: AddCorrelation.

...
--
-- This is where we will do some logic to determine
-- if there is a parameter
--
l_function := wf_event_functions_pkg.SubscriptionParameters
(l_parameters,'ITEMKEY');
...

AddCorrelation

PL/SQL Syntax

Description

Adds a correlation ID to an event message during subscription processing. AddCorrelation() searches the subscription parameters for a parameter named ITEMKEY that specifies a custom function to generate a correlation ID for the event message. When you define the subscription parameter, enter ITEMKEY as the parameter name and <package_name.function_name> as the parameter value.

AddCorrelation() uses SubscriptionParameters() to search for and retrieve the value of the ITEMKEY parameter. See: SubscriptionParameters.

If a custom correlation ID function is specified with the ITEMKEY parameter, then AddCorrelation() runs that function and sets the correlation ID to the value returned by the function. Otherwise, AddCorrelation() sets the correlation ID to the system date. If the event message is then sent to a workflow process, the Workflow Engine uses that correlation ID as the item key to identify the process instance.

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

AddCorrelation() is defined according the standard API for an event subscription rule function. You can use AddCorrelation() as the rule function for a subscription with a low phase number to add a correlation ID to an event, and then use a subscription with a higher phase number to perform any further processing.

For example, follow these steps:

Define a subscription to the relevant event with the rule function WF_EVENT_FUNCTIONS_PKG.AddCorrelation and a phase of 10. Enter the parameter name and value pair ITEMKEY=<package_name.function_name> in the Parameters field for the subscription, replacing <package_name.function_name> with the package and function that will generate the correlation ID.

Define another subscription to the event with a phase of 20, and specify the processing you want to perform by entering a custom rule function or a workflow item type and process, or both.

Raise the event to trigger the subscriptions. The subscription with the lower phase number will be executed first and will add a correlation ID to the event message. When the event is passed to the second subscription, that correlation ID will be used as the item key.

You can also call AddCorrelation() within a custom rule function to add a correlation ID during your custom processing. See: Standard API for an Event Subscription Rule Function, Oracle Workflow Developer's Guide.

Note: You may find it advantageous to define multiple subscriptions to an event with simple rule functions that you can reuse, rather than creating complex specialized rule functions that cannot be reused.

Generate

PL/SQL Syntax

Description

Generates the event data for events in the Seed event group. This event data contains Business Event System object definitions which can be used to replicate the objects from one system to another.

The Seed event group includes the following events:

oracle.apps.wf.event.event.create

oracle.apps.wf.event.event.update

oracle.apps.wf.event.event.delete

oracle.apps.wf.event.group.create

oracle.apps.wf.event.group.update

oracle.apps.wf.event.group.delete

oracle.apps.wf.event.system.create

oracle.apps.wf.event.system.update

oracle.apps.wf.event.system.delete

oracle.apps.wf.event.agent.create

oracle.apps.wf.event.agent.update

oracle.apps.wf.event.agent.delete

oracle.apps.wf.agent.group.create

oracle.apps.wf.agent.group.update

oracle.apps.wf.agent.group.delete

oracle.apps.wf.event.subscription.create

oracle.apps.wf.event.subscription.update

oracle.apps.wf.event.subscription.delete

oracle.apps.wf.event.all.sync

For the event, event group, system, agent, agent group member, and subscription definition events, WF_EVENT_FUNCTIONS_PKG.Generate() calls the Generate APIs associated with the corresponding tables to produce the event data XML document. For the Synchronize Event Systems event, WF_EVENT_FUNCTIONS_PKG.Generate() produces an XML document containing all the event, event group, system, agent, agent group member, and subscription definitions from the Event Manager on the local system.

Arguments (input)

Variable

Description

p_event_name

The internal name of the event.

p_event_key

A string generated when the event occurs within a program or application. The event key uniquely identifies a specific instance of the event.

Receive

PL/SQL Syntax

Description

Receives Business Event System object definitions during subscription processing and loads the definitions into the appropriate Business Event System tables. This function completes the replication of the objects from one system to another.

WF_EVENT_FUNCTIONS_PKG.Receive() is defined according the the standard API for an event subscription rule function. Oracle Workflow uses WF_EVENT_FUNCTIONS_PKG.Receive() as the rule function for two predefined subscriptions, one that is triggered when the System Signup event is raised locally, and one that is triggered when any of the events in the Seed event group is received from an external source.

The Seed event group includes the following events:

oracle.apps.wf.event.event.create

oracle.apps.wf.event.event.update

oracle.apps.wf.event.event.delete

oracle.apps.wf.event.group.create

oracle.apps.wf.event.group.update

oracle.apps.wf.event.group.delete

oracle.apps.wf.event.system.create

oracle.apps.wf.event.system.update

oracle.apps.wf.event.system.delete

oracle.apps.wf.event.agent.create

oracle.apps.wf.event.agent.update

oracle.apps.wf.event.agent.delete

oracle.apps.wf.agent.group.create

oracle.apps.wf.agent.group.update

oracle.apps.wf.agent.group.delete

oracle.apps.wf.event.subscription.create

oracle.apps.wf.event.subscription.update

oracle.apps.wf.event.subscription.delete

oracle.apps.wf.event.all.sync

WF_EVENT_FUNCTIONS_PKG.Receive() parses the event data XML document from the event message that was received and then loads the Business Event System object definitions into the appropriate tables.

Note: For the event, event group, system, agent, agent group, and subscription definition events, WF_EVENT_FUNCTIONS_PKG.Receive() calls the Receive APIs associated with the corresponding tables to parse the XML document and load the definition into the table.

Business Event System Replication APIs

You can call the following APIs to replicate Business Event System data across your systems. The replication APIs are stored in the following PL/SQL packages, each of which corresponds to a Business Event System table. Oracle Workflow provides both a generate function and a receive function for each table.

Each generate API produces an XML message containing the complete information from the appropriate table for the specified Business Event System object definition. The corresponding receive API parses the XML message and loads the row into the appropriate table.

Oracle Workflow uses these APIs during the automated replication of Business Event System data. The generate APIs are called by WF_EVENT_FUNCTIONS_PKG.Generate(), while the receive APIs are called by WF_EVENT_FUNCTIONS_PKG.Receive(). See: Generate and Receive.

Document Type Definitions

The document type definitions (DTDs) for the Workflow table XML messages are defined under the master tag WF_TABLE_DATA. Beneath the master tag, each DTD has a tag identifying the Workflow table name to which it applies, and beneath that, a version tag as well as tags for each column in the table. The following example shows how the DTDs are structured:

WF_EVENTS_PKG.Generate

PL/SQL Syntax

Description

Generates an XML message containing the complete information from the WF_EVENTS table for the specified event definition.

Arguments (input)

Variable

Description

x_guid

The globally unique identifier of the event.

WF_EVENTS_PKG.Receive

PL/SQL Syntax

procedure Receive
(x_message in varchar2);

Description

Receives an XML message containing the complete information for an event definition and loads the information into the WF_EVENTS table.

Arguments (input)

Variable

Description

x_message

An XML message containing the complete information for an event definition.

WF_EVENT_GROUPS Document Type Definition

The following document type definition (DTD) describes the required structure for an XML message that contains the complete information for an event group member definition in the WF_EVENT_GROUPS table.

Note: Event group header information is defined in the WF_EVENTS table, similarly to an individual event. Only the event group member definitions are stored in the WF_EVENT_GROUPS table.

WF_AGENTS_PKG.Generate

PL/SQL Syntax

Description

Generates an XML message containing the complete information from the WF_AGENTS table for the specified agent definition.

Arguments (input)

Variable

Description

x_guid

The globally unique identifier of the agent.

WF_AGENTS_PKG.Receive

PL/SQL Syntax

procedure Receive
(x_message in varchar2);

Description

Receives an XML message containing the complete information for an agent definition and loads the information into the WF_AGENTS table.

Arguments (input)

Variable

Description

x_message

An XML message containing the complete information for an agent definition.

WF_AGENT_GROUPS Document Type Definition

The following document type definition (DTD) describes the required structure for an XML message that contains the complete information for an agent group member definition in the WF_AGENT_GROUPS table.

Note: Agent group header information is defined in the WF_AGENTS table, similarly to an individual agent. Only the agent group member definitions are stored in the WF_AGENT_GROUPS table.

WF_AGENT_GROUPS_PKG.Generate

PL/SQL Syntax

Description

Generates an XML message containing the complete information from the WF_AGENT_GROUPS table for the specified agent group member definition.

Arguments (input)

Variable

Description

x_group_guid

The globally unique identifier of the agent group.

x_member_guid

The globally unique identifier of the individual member agent.

WF_AGENT_GROUPS_PKG.Receive

PL/SQL Syntax

procedure Receive
(x_message in varchar2);

Description

Receives an XML message containing the complete information for an agent group member definition and loads the information into the WF_AGENT_GROUPS table.

Arguments (input)

Variable

Description

x_message

An XML message containing the complete information for an agent group member definition.

WF_EVENT_SUBSCRIPTIONS Document Type Definition

The following document type definition (DTD) describes the required structure for an XML message that contains the complete information for an event subscription definition in the WF_EVENT_SUBSCRIPTIONS table.

WF_EVENT_SUBSCRIPTIONS_PKG.Generate

PL/SQL Syntax

Description

Generates an XML message containing the complete information from the WF_EVENT_SUBSCRIPTIONS table for the specified event subscription definition.

Arguments (input)

Variable

Description

x_guid

The globally unique identifier of the event subscription.

WF_EVENT_SUBSCRIPTIONS_PKG.Receive

PL/SQL Syntax

procedure Receive
(x_message in varchar2);

Description

Receives an XML message containing the complete information for an event subscription definition and loads the information into the WF_EVENT_SUBSCRIPTIONS table.

Arguments (input)

Variable

Description

x_message

An XML message containing the complete information for an event subscription definition.

Business Event System Cleanup API

The Workflow Business Event System cleanup API can be used to clean up the standard WF_CONTROL queue in the Business Event System by removing inactive subscribers from the queue. This API is defined in a PL/SQL package called WF_BES_CLEANUP.

Cleanup_Subscribers

PL/SQL Syntax

Description

Performs cleanup for the standard WF_CONTROL queue.

When a middle tier process for Oracle E-Business Suite starts up, it creates a JMS subscriber to the WF_CONTROL queue. Then, when an event message is placed on the queue, a copy of the event message is created for each subscriber to the queue. If a middle tier process dies, however, the corresponding subscriber remains in the database. For more efficient processing, you should ensure that WF_CONTROL is periodically cleaned up by running Cleanup_Subscribers() to remove the subscribers for any middle tier processes that are no longer active.

The Cleanup_Subscribers() procedure sends an event named oracle.apps.wf.bes.control.ping to check the status of each subscriber to the WF_CONTROL queue. If the corresponding middle tier process is still alive, it sends back a response.

The next time the cleanup procedure runs, it checks whether responses have been received for each ping event sent during the previous run. If no response was received from a particular subscriber, that subscriber is removed.

Finally, after removing any subscribers that are no longer active, the procedure sends a new ping event to the remaining subscribers.

The recommended frequency for performing cleanup is every twelve hours. In order to allow enough time for subscribers to respond to the ping event, the minimum wait time between two cleanup runs is thirty minutes. If you run the procedure again less than thirty minutes after the last run, it will not perform any processing.

The maximum retention time for information about ping events sent to subscribers is thirty days. Cleanup_Subscribers() deletes information for previously sent pings that are more than thirty days old.

The procedure returns an error buffer that contains an error message if any inactive subscriber could not be removed during the cleanup. It also returns one of the following codes to indicate the status of the cleanup.

0 - Success

1 - Warning

2 - Error

Related Topics

Cleaning Up the Workflow Control Queue, Oracle Workflow Administrator's Guide

Standard Agents, Oracle Workflow Developer's Guide

Business Event System Control Events, Oracle Workflow Developer's Guide