This chapter describes the APIs for the Oracle Workflow Business Event System. The APIs include datatypes and PL/SQL functions and procedures that you can use to access the Business Event System.
This chapter covers the following topics:
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
Sending a notification to a role
Receiving an Oracle XML Gateway message from a trading partner (Oracle E-Business Suite only)
Sending an Oracle XML Gateway message to a trading partner (Oracle E-Business Suite only)
Executing custom code on the event information
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.
Related Topics
Business Event System Datatypes
Event Subscription Rule Function APIs
Business Event System Replication APIs
Business Event System Cleanup APIs
Managing Business Events, Oracle Workflow Developer's Guide
Event Activities, Oracle Workflow Developer's Guide
Oracle Workflow uses a number of abstract datatypes (ADTs) to model the structure and behavior of Business Event System data. These datatypes include the following:
The Business Event System datatypes are created by a script called wftypes.sql, which is located in the $FND_TOP/sql directory.
See: User-Defined Datatypes, Oracle Concepts.
Related Topics
Example for Using Abstract Datatypes
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.
| 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.
Related Topics
Agents, Oracle Workflow Developer's Guide
MEMBER FUNCTION getName return varchar2
Returns the value of the NAME attribute in a WF_AGENT_T object.
MEMBER FUNCTION getSystem return varchar2
Returns the value of the SYSTEM attribute in a WF_AGENT_T object.
MEMBER PROCEDURE setName (pName in varchar2)
Sets the value of the NAME attribute in a WF_AGENT_T object.
| Variable | Description |
|---|---|
| pName | The value for the NAME attribute. |
MEMBER PROCEDURE setSystem
(pSystem in varchar2)
Sets the value of the SYSTEM attribute in a WF_AGENT_T object.
| Variable | Description |
|---|---|
| pSystem | The value for the SYSTEM attribute. |
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.
| 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.
MEMBER FUNCTION getName return varchar2
Returns the value of the NAME attribute in a WF_PARAMETER_T object.
MEMBER FUNCTION getValue return varchar2
Returns the value of the VALUE attribute in a WF_PARAMETER_T object.
MEMBER PROCEDURE setName (pName in varchar2)
Sets the value of the NAME attribute in a WF_PARAMETER_T object.
| Variable | Description |
|---|---|
| pName | The value for the NAME attribute. |
MEMBER PROCEDURE setValue (pValue in varchar2)
Sets the value of the VALUE attribute in a WF_PARAMETER_T object.
| Variable | Description |
|---|---|
| pValue | The value for the VALUE attribute. |
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
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.
| 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.
Related Topics
Example for Using Abstract Datatypes
Mapping Between WF_EVENT_T and SYS.AQ$_JMS_TEXT_MESSAGE
STATIC PROCEDURE initialize (new_wf_event_t in out wf_event_t)
Initializes a new WF_EVENT_T object by setting the PRIORITY attribute to 0, initializing the EVENT_DATA attribute to EMPTY using the Empty_CLOB() function, and setting all other attributes to NULL.
Important: You must call the Initialize method before you can perform any further manipulation on a new WF_EVENT_T object.
| Variable | Description |
|---|---|
| new_wf_event_t | The WF_EVENT_T object to initialize. |
MEMBER FUNCTION getPriority return number
Returns the value of the PRIORITY attribute in a WF_EVENT_T object.
MEMBER FUNCTION getSendDate return date
Returns the value of the SEND_DATE attribute in a WF_EVENT_T object.
MEMBER FUNCTION getReceiveDate return date
Returns the value of the RECEIVE_DATE attribute in a WF_EVENT_T object.
MEMBER FUNCTION getCorrelationID return varchar2
Returns the value of the CORRELATION_ID attribute in a WF_EVENT_T object.
MEMBER FUNCTION getParameterList return wf_parameter_list_t
Returns the value of the PARAMETER_LIST attribute in a WF_EVENT_T object.
MEMBER FUNCTION getEventName return varchar2
Returns the value of the EVENT_NAME attribute in a WF_EVENT_T object.
MEMBER FUNCTION getEventKey return varchar2
Returns the value of the EVENT_KEY attribute in a WF_EVENT_T object.
MEMBER FUNCTION getEventData return clob
Returns the value of the EVENT_DATA attribute in a WF_EVENT_T object.
MEMBER FUNCTION getFromAgent return wf_agent_t
Returns the value of the FROM_AGENT attribute in a WF_EVENT_T object.
MEMBER FUNCTION getToAgent return wf_agent_t
Returns the value of the TO_AGENT attribute in a WF_EVENT_T object.
MEMBER FUNCTION getErrorSubscription return raw
Returns the value of the ERROR_SUBSCRIPTION attribute in a WF_EVENT_T object.
MEMBER FUNCTION getErrorMessage return varchar2
Returns the value of the ERROR_MESSAGE attribute in a WF_EVENT_T object.
MEMBER FUNCTION getErrorStack return varchar2
Returns the value of the ERROR_STACK attribute in a WF_EVENT_T object.
MEMBER PROCEDURE setPriority (pPriority in number)
Sets the value of the PRIORITY attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pPriority | The value for the PRIORITY attribute. |
MEMBER PROCEDURE setSendDate (pSendDate in date default sysdate)
Sets the value of the SEND_DATE attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pSendDate | The value for the SEND_DATE attribute. |
MEMBER PROCEDURE setReceiveDate (pReceiveDate in date default sysdate)
Sets the value of the RECEIVE_DATE attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pReceiveDate | The value for the RECEIVE_DATE attribute. |
MEMBER PROCEDURE setCorrelationID
(pCorrelationID in varchar2)
Sets the value of the CORRELATION_ID attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pCorrelationID | The value for the CORRELATION_ID attribute. |
MEMBER PROCEDURE setParameterList (pParameterList in wf_parameter_list_t)
Sets the value of the PARAMETER_LIST attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pParameterList | The value for the PARAMETER_LIST attribute. |
MEMBER PROCEDURE setEventName (pEventName in varchar2)
Sets the value of the EVENT_NAME attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pEventName | The value for the EVENT_NAME attribute. |
MEMBER PROCEDURE setEventKey (pEventKey in varchar2)
Sets the value of the EVENT_KEY attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pEventKey | The value for the EVENT_KEY attribute. |
MEMBER PROCEDURE setEventData (pEventData in clob)
Sets the value of the EVENT_DATA attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pEventData | The value for the EVENT_DATA attribute. |
MEMBER PROCEDURE setFromAgent (pFromAgent in wf_agent_t)
Sets the value of the FROM_AGENT attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pFromAgent | The value for the FROM_AGENT attribute. |
MEMBER PROCEDURE setToAgent (pToAgent in wf_agent_t)
Sets the value of the TO_AGENT attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pToAgent | The value for the TO_AGENT attribute. |
MEMBER PROCEDURE setErrorSubscription (pErrorSubscription in raw)
Sets the value of the ERROR_SUBSCRIPTION attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pErrorSubscription | The value for the ERROR_SUBSCRIPTION attribute. |
MEMBER PROCEDURE setErrorMessage (pErrorMessage in varchar2)
Sets the value of the ERROR_MESSAGE attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pErrorMessage | The value for the ERROR_MESSAGE attribute. |
MEMBER PROCEDURE setErrorStack (pErrorStack in varchar2)
Sets the value of the ERROR_STACK attribute in a WF_EVENT_T object.
| Variable | Description |
|---|---|
| pErrorStack | The value for the ERROR_STACK attribute. |
MEMBER PROCEDURE Content (pName in varchar2, pKey in varchar2, pData in clob)
Sets the values of all the event content attributes in a WF_EVENT_T object, including EVENT_NAME, EVENT_KEY, and EVENT_DATA.
| 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. |
MEMBER PROCEDURE Address (pOutAgent in wf_agent_t, pToAgent in wf_agent_t, pPriority in number, pSendDate in date)
Sets the values of the all address attributes in a WF_EVENT_T object, including FROM_AGENT, TO_AGENT, PRIORITY, and SEND_DATE.
| 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. |
MEMBER PROCEDURE AddParameterToList (pName in varchar2, pValue in varchar2)
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.
| Variable | Description |
|---|---|
| pName | The parameter name. |
| pValue | The parameter value. |
MEMBER FUNCTION GetValueForParameter (pName in varchar2) return varchar2
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.
| Variable | Description |
|---|---|
| pName | The parameter name. |
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.
declare
l_overrideagent varchar2(30) := '&overrideagent';
l_overridesystem varchar2(30) := '&overridesystem';
l_fromagent varchar2(30) := '&fromagent';
l_fromsystem varchar2(30) := '&fromsystem';
l_toagent varchar2(30) := '&toagent';
l_tosystem varchar2(30) := '&tosystem';
l_eventname varchar2(100) := '&eventname';
l_eventkey varchar2(100) := '&eventkey';
l_msg varchar2(200) := '&message';
l_clob clob;
l_overrideagent_t wf_agent_t;
l_toagent_t wf_agent_t;
l_fromagent_t wf_agent_t;
l_event_t wf_event_t;
begin
/*You must call wf_event_t.initialize before you can manipulate
a new wf_event_t object.*/
wf_event_t.initialize(l_event_t);
l_overrideagent_t := wf_agent_t(l_overrideagent, l_overridesystem);
l_toagent_t := wf_agent_t(l_toagent, l_tosystem);
l_fromagent_t := wf_agent_t(l_fromagent, l_fromsystem);
if l_msg is null then
l_event_t.Content(l_eventname, l_eventkey, null);
else
dbms_lob.createtemporary(l_clob, FALSE, DBMS_LOB.CALL);
dbms_lob.write(l_clob, length(l_msg), 1, l_msg);
l_event_t.Content(l_eventname, l_eventkey, l_clob);
end if;
l_event_t.Address(l_fromagent_t, l_toagent_t, 50, sysdate);
wf_event.enqueue(l_event_t, l_overrideagent_t);
end;
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
GROUPSEQ - The sequence number of the message within the group
PROPERTIES - Additional message properties in the SYS.AQ$_JMS_USERPROPARRAY datatype
The SYS.AQ$_JMS_USERPROPARRAY datatype is a named varying array with a maximum size of 100. The datatype of its elements is another ADT named SYS.AQ$_JMS_USERPROPERTY.
The following table shows how the attributes of the WF_EVENT_T message structure are mapped to the attributes within the SYS.AQ$_JMS_TEXT_MESSAGE structure.
| WF_EVENT_T | SYS.AQ$_JMS_TEXT_MESSAGE |
|---|---|
| WF_EVENT_T.PRIORITY | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.SEND_DATE | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.RECEIVE_DATE | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.CORRELATION_ID | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.EVENT_NAME | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.EVENT_KEY | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.EVENT_DATA | TEXT_VC or TEXT_LOB |
| WF_EVENT_T.PARAMETER_LIST | SYS.AQ$_JMS_HEADER.REPLYTO |
| WF_EVENT_T.PARAMETER_LIST | SYS.AQ$_JMS_HEADER.TYPE |
| WF_EVENT_T.PARAMETER_LIST | SYS.AQ$_JMS_HEADER.USERID |
| WF_EVENT_T.PARAMETER_LIST | SYS.AQ$_JMS_HEADER.APPID |
| WF_EVENT_T.PARAMETER_LIST | SYS.AQ$_JMS_HEADER.GROUPID |
| WF_EVENT_T.PARAMETER_LIST | SYS.AQ$_JMS_HEADER.GROUPSEQ |
| WF_EVENT_T.PARAMETER_LIST (any parameters other than JMS header properties) | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.FROM_AGENT | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.TO_AGENT | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.ERROR_SUBSCRIPTION | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.ERROR_MESSAGE | SYS.AQ$_JMS_USERPROPARRAY |
| WF_EVENT_T.ERROR_STACK | SYS.AQ$_JMS_USERPROPARRAY |
See: Using Oracle Java Message Service (OJMS) to Access Oracle Streams AQ, Oracle Streams Advanced Queuing User's Guide and Reference and Package oracle.jms, Oracle Supplied Java Packages Reference.
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.
procedure Raise (p_event_name in varchar2, p_event_key in varchar2, p_event_data in clob default NULL, p_parameters in wf_parameter_list_t default NULL, p_send_date in date default NULL);
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.
| 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. |
declare
l_xmldocument varchar2(32000);
l_eventdata clob;
l_parameter_list wf_parameter_list_t;
l_message varchar2(10);
begin
/*
** If the complete event data is easily available, we can
** optionally test if any subscriptions to this event
** require it (rule data = Message).
*/
l_message := wf_event.test('<EVENT_NAME>');
/*
** If we do require a message, and we have the message now,
** set it; else we can just rely on the Event Generate
** Function callback code. Then raise the event with the
** required parameters.
*/
if l_message = 'MESSAGE' then
if l_xmldocument is not null then
dbms_lob.createtemporary(l_eventdata, FALSE, DBMS_LOB.CALL);
dbms_lob.write(l_eventdata, length(l_xmldocument), 1 ,
l_xmldocument);
-- Raise the Event with the message
wf_event.raise( p_event_name => '<EVENT_NAME>',
p_event_key => '<EVENT_KEY>',
p_event_data => l_eventdata,
p_parameters => l_parameter_list);
else
-- Raise the Event without the message
wf_event.raise( p_event_name => '<EVENT_NAME>',
p_event_key => '<EVENT_KEY>',
p_parameters => l_parameter_list);
end if;
elsif
l_message = 'KEY' then
-- Raise the Event
wf_event.raise( p_event_name => <EVENT_NAME>,
p_event_key => <EVENT_KEY>,
p_parameters => l_parameter_list);
end if;
/*
** Up to your own custom code to commit the transaction
*/
commit;
/*
** Up to your own custom code to handle any major exceptions
*/
exception
when others then
null;
end;
Related Topics
Any Event, Oracle Workflow Developer's Guide
Unexpected Event, Oracle Workflow Developer's Guide
procedure Raise3 (p_event_name in varchar2, p_event_key in varchar2, p_event_data in clob default NULL, p_parameter_list in out nocopy wf_parameter_list_t, p_send_date in date default NULL);
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.
| 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. |
procedure Send (p_event in out wf_event_t);
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.
| Variable | Description |
|---|---|
| p_event | The event message. |
function NewAgent (p_agent_guid in raw) return wf_agent_t;
Creates a WF_AGENT_T structure for the specified agent and sets the agent's system and name into the structure. See: Agent Structure.
| Variable | Description |
|---|---|
| p_agent_guid | The globally unique identifier of the agent. |
function Test (p_event_name in varchar2) return varchar2;
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.
| Variable | Description |
|---|---|
| p_event_name | The internal name of the event. |
procedure Enqueue (p_event in wf_event_t, p_out_agent_override in wf_agent_t default null);
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.
| Variable | Description |
|---|---|
| p_event | The event message. |
| p_out_agent_override | The outbound agent on whose queue the event message should be enqueued. |
procedure Listen (p_agent_name in varchar2, p_wait in binary_integer default dbms_aq.no_wait, p_correlation in varchar2 default null, p_deq_condition in varchar2 default null); procedure Listen (p_agent_name in varchar2, p_wait in binary_integer default dbms_aq.no_wait, p_correlation in varchar2 default null, p_deq_condition in varchar2 default null, p_message_count in out nocopy number, p_max_error_count in out nocopy number);
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.
| 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
procedure SetErrorInfo (p_event in out wf_event_t, p_type in varchar2);
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.
| Variable | Description |
|---|---|
| p_event | The event message. |
| p_type | The error type, either 'ERROR' or 'WARNING'. |
procedure SetDispatchMode (p_mode in varchar2);
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.
| Variable | Description |
|---|---|
| p_mode | The dispatch mode: either 'ASYNC' for deferred (asynchronous) subscription processing, or 'SYNC' for synchronous subscription processing. |
Related Topics
Deferred Subscription Processing, Oracle Workflow Developer's Guide
procedure AddParameterToList (p_name in varchar2, p_value in varchar2, p_parameterlist in out wf_parameter_list_t);
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.
| Variable | Description |
|---|---|
| p_name | The parameter name. |
| p_value | The parameter value. |
| p_parameterlist | The parameter list. |
procedure AddParameterToListPos (p_name in varchar2, p_value in varchar2, p_position out integer, p_parameterlist in out wf_parameter_list_t);
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.
| Variable | Description |
|---|---|
| p_name | The parameter name. |
| p_value | The parameter value. |
| p_parameterlist | The parameter list. |
function GetValueForParameter (p_name in varchar2, p_parameterlist in wf_parameter_list_t) return varchar2;
Retrieves the value of the specified parameter from the specified parameter list varray. GetValueForParameter() begins at the end of the parameter list and searches backwards through the list.
| Variable | Description |
|---|---|
| p_name | The parameter name. |
| p_parameterlist | The parameter list. |
function GetValueForParameterPos (p_position in integer, p_parameterlist in wf_parameter_list_t) return varchar2;
Retrieves the value of the parameter stored at the specified position in the specified parameter list varray.
| Variable | Description |
|---|---|
| p_position | The index representing the position of the parameter within the parameter list. |
| p_parameterlist | The parameter list. |
procedure SetMaxNestedRaise (maxcount in number default 100);
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.
| Variable | Description |
|---|---|
| max_count | The maximum number of nested raises to allow. |
function GetMaxNestedRaise return number;
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.
function GetParamListFromString (p_parameters in varchar2) return wf_parameter_list_t;
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>
| Variable | Description |
|---|---|
| p_parameters | A text string containing parameter name and value pairs, separated by spaces. |
procedure setNavigationParams (p_agentName in varchar2 default null, p_navigationThreshold in number default 0);
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.
| 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. |
procedure resetNavigationParams;
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.
function getQueueNavigation return BINARY_INTEGER;
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.
For more information about dequeuing messages, see: Oracle Streams Advanced Queuing User’s Guide. For more information about the NAVIGATION_RESET_THRESHOLD parameter, see: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide.
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.
Additionally, Oracle Workflow provides a standard Java rule function called oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription that you can assign to an event subscription to invoke a Web service.
Related Topics
Event Subscriptions, Oracle Workflow Developer's Guide
Standard API for an Event Subscription Rule Function, Oracle Workflow Developer's Guide
function Default_Rule (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
Performs default subscription processing for an event subscription. The default processing includes:
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
function Log (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
function Error (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
function Warning (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
function Success (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
function Workflow_Protocol (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
Workflow_Protocol() is used as the rule function in several predefined subscriptions to Workflow Send Protocol events. See: Workflow Send Protocol, Oracle Workflow Developer's Guide.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
function Error_Rule (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| 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
function SetParametersIntoParameterList (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
Related Topics
function Default_Rule2 (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
Related Topics
function Default_Rule3 (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
Related Topics
SetParametersIntoParameterList
function SendNotification (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| 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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
Related Topics
function Instance_Default_Rule (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
Related Topics
SetParametersIntoParameterList
function Default_Rule_Or (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
Related Topics
function Default_Generate (p_event_name in varchar2, p_event_key in varchar2, p_parameter_list in wf_parameter_list_t) return clob;
Generates a simple set of event data from the specified event name, event key, and parameter list. You can assign this standard generate function to events for demonstration and testing purposes.
Default_Generate() generates the event data as an XML document in the following structure:
<BUSINESSEVENT event-name="" key="">
<GENERATETIME mask="">
<PARAMETERS count="">
<PARAMETER parameter-name="">
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.
Sample Event Data XML Document
<BUSINESSEVENT event-name="oracle.my.event" key="123">
<GENERATETIME mask="mm-dd-rr hh:mi:ss">04-24-06 09:05:23</GENERATETIME>
<PARAMETERS count="1">
<PARAMETER parameter-name="NOTE"><![CDATA[This is a sample note]]>
</PARAMETER>
</PARAMETERS>
</BUSINESSEVENT>
| 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_parameter_list | A list of additional parameter name and value pairs for the event. |
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.
You can add custom processing if necessary by extending this class and overriding the preInvokeService. invokeService, addWSSecurityHeader, and postInvokeService methods.
See: Invoking a Web Service, Oracle Workflow Developer's Guide and the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
The WebServiceInvokerSubscription class defines the onBusinessEvent method from the SubscriptionInterface Java interface to invoke a Web service.
public void onBusinessEvent (Subscription eo, BusinessEvent event, WorkflowContext context) throws BusinessEventException
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.
| 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. |
The WebServiceInvokerSubscription class always calls the preInvokeService method before invoking the Web service.
protected String preInvokeService (Subscription eo, BusinessEvent event, WorkflowContext context) throws BusinessEventException
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.
| 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. |
The WebServiceInvokerSubscription class calls the invokeService method after performing any pre-invocation processing in the preInvokeService method.
protected String invokeService (String wsdlLocation, String serviceName, String invokePort, String portTypeName, String operationName, String eventData) throws Exception
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.
| 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. |
The setInputParts method is called during the invocation processing.
protected void setInputParts (WSIFMessage inputMessage, Input input, String eventData) throws Exception
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.
Note: Currently Oracle E-Business Suite Integrated SOA Gateway supports only document-style Web services by default.
If the input message processing does not succeed, this method throws an Exception.
| Variable | Description |
|---|---|
| inputMessage | The XML input message to which the parts should be added. |
| input | The input message definition for the selected operation. |
| eventData | The event data payload that should be set as the body of the XML input message. |
The addWSSecurityHeader method is called during the invocation processing.
protected void addWSSecurityHeader (ArrayList headersList) throws Exception
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.
| Variable | Description |
|---|---|
| headersList | The ArrayList object containing the list of headers to which the WS-Security compliant header should be added. |
The WebServiceInvokerSubscription class calls the postInvokeService method after successfully invoking the Web service.
protected void postInvokeService (Subscription eo, BusinessEvent event, WorkflowContext context, String requestData, String responseData) throws BusinessEventException
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.
| 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. |
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.
Java syntax: public String getService()
getPortType - Returns the port type as specified in the SERVICE_PORTTYPE internal subscription parameter.
Java syntax: public String getPortType()
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.
Java syntax: public String getBindingStyle()
See: Invoking a Web Service, Oracle Workflow Developer's Guide and the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
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.
function Parameters (p_string in varchar2, p_numvalues in number, p_separator in varchar2) return t_parameters;
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:
| 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.
| Variable | Description |
|---|---|
| p_string | A text string containing concatenated parameters. |
| p_numvalues | The number of parameters contained in the string. |
| p_separator | The separator used to delimit the parameters in the string. |
set serveroutput on
declare
l_parameters wf_event_functions_pkg.t_parameters;
begin
-- Initialize the datatype
l_parameters := wf_event_functions_pkg.t_parameters(1,2);
l_parameters := wf_event_functions_pkg.parameters('1111/2222',2,'/');
dbms_output.put_line('Value 1:'||l_parameters(1));
dbms_output.put_line('Value 2:'||l_parameters(2));
end;
/
function SubscriptionParameters (p_string in varchar2, p_key in varchar2) return varchar2;
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.
| 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. |
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');
...
function AddCorrelation (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
If AddCorrelation() encounters an exception, the function returns the status code ERROR. Otherwise, AddCorrelation() returns the status code SUCCESS.
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
function Generate (p_event_name in varchar2, p_event_key in varchar2) return clob;
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.
| 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. |
Related Topics
WF_EVENT_SUBSCRIPTIONS_PKG.Generate
Predefined Workflow Events, Oracle Workflow Developer's Guide
function Receive (p_subscription_guid in raw, p_event in out wf_event_t) return varchar2;
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.
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription. |
| p_event | The event message. |
Related Topics
WF_EVENT_SUBSCRIPTIONS_PKG.Receive
Predefined Workflow Events, Oracle Workflow Developer's Guide
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.
WF_EVENTS_PKG
WF_EVENT_GROUPS_PKG
WF_SYSTEMS_PKG
WF_AGENTS_PKG
WF_AGENT_GROUPS_PKG
WF_EVENT_SUBSCRIPTIONS_PKG
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.
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_TABLE_DATA> <- masterTagName
<WF_TABLE_NAME> <- m_table_name
<VERSION></VERSION> <- m_package_version
<COL1></COL1>
<COL2></COL2>
</WF_TABLE_NAME>
</WF_TABLE_DATA>
The Business Event System replication APIs use the following DTDs:
The following document type definition (DTD) describes the required structure for an XML message that contains the complete information for an event definition in the WF_EVENTS table.
<WF_TABLE_DATA>
<WF_EVENTS>
<VERSION></VERSION>
<GUID></GUID>
<NAME></NAME>
<TYPE></TYPE>
<STATUS></STATUS>
<GENERATE_FUNCTION></GENERATE_FUNCTION>
<OWNER_NAME></OWNER_NAME>
<OWNER_TAG></OWNER_TAG>
<CUSTOMIZATION_LEVEL></CUSTOMIZATION_LEVEL>
<LICENSED_FLAG></LICENSED_FLAG>
<JAVA_GENERATE_FUNC></JAVA_GENERATE_FUNC>
<DISPLAY_NAME></DISPLAY_NAME>
<DESCRIPTION></DESCRIPTION>
</WF_EVENTS>
</WF_TABLE_DATA>
function Generate (x_guid in raw) return varchar2;
Generates an XML message containing the complete information from the WF_EVENTS table for the specified event definition.
| Variable | Description |
|---|---|
| x_guid | The globally unique identifier of the event. |
procedure Receive (x_message in varchar2);
Receives an XML message containing the complete information for an event definition and loads the information into the WF_EVENTS table.
| Variable | Description |
|---|---|
| x_message | An XML message containing the complete information for an event 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_TABLE_DATA>
<WF_EVENT_GROUPS>
<VERSION></VERSION>
<GROUP_NAME></GROUP_NAME>
<MEMBER_NAME></MEMBER_NAME>
</WF_EVENT_GROUPS>
</WF_TABLE_DATA>
Note: The Workflow XML Loader also still supports uploading event group member definitions that are structured according to the previous version of the DTD:
<WF_TABLE_DATA>
<WF_EVENT_GROUPS>
<VERSION></VERSION>
<GROUP_GUID></GROUP_GUID>
<MEMBER_GUID></MEMBER_GUID>
</WF_EVENT_GROUPS>
</WF_TABLE_DATA>
function Generate (x_group_guid in raw, x_member_guid in raw) return varchar2;
Generates an XML message containing the complete information from the WF_EVENT_GROUPS table for the specified event group member definition.
| Variable | Description |
|---|---|
| x_group_guid | The globally unique identifier of the event group. |
| x_member_guid | The globally unique identifier of the individual member event. |
procedure Receive (x_message in varchar2);
Receives an XML message containing the complete information for an event group member definition and loads the information into the WF_EVENT_GROUPS table.
| Variable | Description |
|---|---|
| x_message | An XML message containing the complete information for an event group member definition. |
The following document type definition (DTD) describes the required structure for an XML message that contains the complete information for a system definition in the WF_SYSTEMS table.
<WF_TABLE_DATA>
<WF_SYSTEMS>
<VERSION></VERSION>
<GUID></GUID>
<NAME></NAME>
<MASTER_GUID></MASTER_GUID>
<DISPLAY_NAME></DISPLAY_NAME>
<DESCRIPTION></DESCRIPTION>
</WF_SYSTEMS>
</WF_TABLE_DATA>
function Generate (x_guid in raw) return varchar2;
Generates an XML message containing the complete information from the WF_SYSTEMS table for the specified system definition.
| Variable | Description |
|---|---|
| x_guid | The globally unique identifier of the system. |
procedure Receive (x_message in varchar2);
Receives an XML message containing the complete information for a system definition and loads the information into the WF_SYSTEMS table.
| Variable | Description |
|---|---|
| x_message | An XML message containing the complete information for a system definition. |
The following document type definition (DTD) describes the required structure for an XML message that contains the complete information for an agent definition in the WF_AGENTS table.
<WF_TABLE_DATA>
<WF_AGENTS>
<VERSION></VERSION>
<GUID></GUID>
<NAME></NAME>
<SYSTEM_GUID></SYSTEM_GUID>
<PROTOCOL></PROTOCOL>
<ADDRESS></ADDRESS>
<QUEUE_HANDLER></QUEUE_HANDLER>
<QUEUE_NAME></QUEUE_NAME>
<DIRECTION></DIRECTION>
<STATUS></STATUS>
<DISPLAY_NAME></DISPLAY_NAME>
<DESCRIPTION></DESCRIPTION>
<TYPE></TYPE>
</WF_AGENTS>
</WF_TABLE_DATA>
function Generate (x_guid in raw) return varchar2;
Generates an XML message containing the complete information from the WF_AGENTS table for the specified agent definition.
| Variable | Description |
|---|---|
| x_guid | The globally unique identifier of the agent. |
procedure Receive (x_message in varchar2);
Receives an XML message containing the complete information for an agent definition and loads the information into the WF_AGENTS table.
| Variable | Description |
|---|---|
| x_message | An XML message containing the complete information for an agent 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_TABLE_DATA>
<WF_AGENT_GROUPS>
<VERSION></VERSION>
<GROUP_GUID></GROUP_GUID>
<MEMBER_GUID></MEMBER_GUID>
</WF_AGENT_GROUPS>
</WF_TABLE_DATA>
function Generate (x_group_guid in raw, x_member_guid in raw) return varchar2;
Generates an XML message containing the complete information from the WF_AGENT_GROUPS table for the specified agent group member definition.
| 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. |
procedure Receive (x_message in varchar2);
Receives an XML message containing the complete information for an agent group member definition and loads the information into the WF_AGENT_GROUPS table.
| Variable | Description |
|---|---|
| x_message | An XML message containing the complete information for an agent group member 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_TABLE_DATA>
<WF_EVENT_SUBSCRIPTIONS>
<VERSION></VERSION>
<GUID></GUID>
<SYSTEM_GUID></SYSTEM_GUID>
<SOURCE_TYPE></SOURCE_TYPE>
<SOURCE_AGENT_GUID></SOURCE_AGENT_GUID>
<EVENT_FILTER_GUID></EVENT_FILTER_GUID>
<PHASE></PHASE>
<STATUS></STATUS>
<RULE_DATA></RULE_DATA>
<OUT_AGENT_GUID></OUT_AGENT_GUID>
<TO_AGENT_GUID></TO_AGENT_GUID>
<PRIORITY></PRIORITY>
<RULE_FUNCTION></RULE_FUNCTION>
<JAVA_RULE_FUNC></JAVA_RULE_FUNC>
<STANDARD_TYPE></STANDARD_TYPE>
<STANDARD_CODE></STANDARD_CODE>
<ON_ERROR_CODE></ON_ERROR_CODE>
<ACTION_CODE></ACTION_CODE>
<WF_PROCESS_TYPE></WF_PROCESS_TYPE>
<WF_PROCESS_NAME></WF_PROCESS_NAME>
<PARAMETERS></PARAMETERS>
<OWNER_NAME></OWNER_NAME>
<OWNER_TAG></OWNER_TAG>
<CUSTOMIZATION_LEVEL></CUSTOMIZATION_LEVEL>
<LICENSED_FLAG></LICENSED_FLAG>
<DESCRIPTION></DESCRIPTION>
<EXPRESSION></EXPRESSION>
</WF_EVENT_SUBSCRIPTIONS>
</WF_TABLE_DATA>
function Generate (x_guid in raw) return varchar2;
Generates an XML message containing the complete information from the WF_EVENT_SUBSCRIPTIONS table for the specified event subscription definition.
| Variable | Description |
|---|---|
| x_guid | The globally unique identifier of the event subscription. |
procedure Receive (x_message in varchar2);
Receives an XML message containing the complete information for an event subscription definition and loads the information into the WF_EVENT_SUBSCRIPTIONS table.
| Variable | Description |
|---|---|
| x_message | An XML message containing the complete information for an event subscription definition. |
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.
procedure Cleanup_Subscribers (errbuf out varchar2, retcode out varchar2);
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