Skip Headers

Oracle Workflow API Reference
Release 12.1
Part Number E12904-04
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Business Event System APIs

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:

Overview of the Oracle Workflow Business Event System

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

Subscriptions can include the following types of processing:

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 APIs

Event Subscription Rule Function APIs

Event 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

Business Event System Datatypes

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

Agent Structure

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

WF_AGENT_T Attributes
Attribute Name Datatype Description
NAME VARCHAR2(30) The name of the agent.
SYSTEM VARCHAR2(30) The system where the agent is located.

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

Related Topics

Agents, Oracle Workflow Developer's Guide

getName

PL/SQL Syntax

MEMBER FUNCTION getName 
  return varchar2

Description

Returns the value of the NAME attribute in a WF_AGENT_T object.

getSystem

PL/SQL Syntax

MEMBER FUNCTION getSystem  
  return varchar2

Description

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

setName

PL/SQL Syntax

MEMBER PROCEDURE setName 
  (pName in varchar2)

Description

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

Arguments (input)

Variable Description
pName The value for the NAME attribute.

setSystem

PL/SQL Syntax

MEMBER PROCEDURE setSystem 
    (pSystem in varchar2)

Description

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

Arguments (input)

Variable Description
pSystem The value for the SYSTEM attribute.

Parameter Structure

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

WF_PARAMETER_T Attributes
Attribute Name Datatype Description
NAME VARCHAR2(30) The parameter name.
VALUE VARCHAR2(2000) The parameter value.

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

getName

PL/SQL Syntax

MEMBER FUNCTION getName  
  return varchar2

Description

Returns the value of the NAME attribute in a WF_PARAMETER_T object.

getValue

PL/SQL Syntax

MEMBER FUNCTION getValue  
  return varchar2

Description

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

setName

PL/SQL Syntax

MEMBER PROCEDURE setName  
  (pName in varchar2)

Description

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

Arguments (input)

Variable Description
pName The value for the NAME attribute.

setValue

PL/SQL Syntax

MEMBER PROCEDURE setValue  
   (pValue in varchar2)

Description

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

Arguments (input)

Variable Description
pValue The value for the VALUE attribute.

Parameter List Structure

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

WF_PARAMETER_LIST_T

Event Message Structure

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

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

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

The following table lists the attributes of the WF_EVENT_T datatype.

WF_EVENT_T Attributes
Attribute Name Datatype Description
PRIORITY NUMBER The priority with which the message recipient should dequeue the message. A smaller number indicates a higher priority. For example, 1 represents a high priority, 50 represents a normal priority, and 99 represents a low priority.
SEND_DATE DATE The date and time when the message is available for dequeuing. The send date can be set to the system date to indicate that the message is immediately available for dequeuing, or to a future date to indicate future availability.
If the send date is set to a future date when an event is raised, the event message is placed on the WF_DEFERRED queue, and subscription processing does not begin until the specified date. If the send date is set to a future date when an event is sent to an agent, the event message is propagated to that agent's queue, but does not become available for the consumer to dequeue until the specified date.
RECEIVE_DATE DATE The date and time when the message is dequeued by an agent listener.
CORRELATION_ID VARCHAR2(240) A correlation identifier that associates this message with other messages. This attribute is initially blank but can be set by a function. If a value is set for the correlation ID, then that value is used as the item key if the event is sent to a workflow process. Note that the item key for a process instance can only contain single-byte characters. It cannot contain a multibyte value.
PARAMETER_LIST WF_PARAMETER_LIST_T A list of additional parameter name and value pairs.
EVENT_NAME VARCHAR2(240) The internal name of the event.
EVENT_KEY VARCHAR2(240) The string that uniquely identifies the instance of the event.
EVENT_DATA CLOB A set of additional details describing what occurred in the event. The event data can be structured as an XML document.
FROM_AGENT WF_AGENT_T The agent from which the event is sent. For locally raised events, this attribute is initially null.
TO_AGENT WF_AGENT_T The agent to which the event should be sent (the message recipient).
ERROR_SUBSCRIPTION RAW(16) If an error occurs while processing this event, this is the subscription that was being executed when the error was encountered.
ERROR_MESSAGE VARCHAR2(4000) An error message that the Event Manager generates if an error occurs while processing this event.
ERROR_STACK VARCHAR2(4000) An error stack of arguments that the Event Manager generates if an error occurs while processing this event. The error stack provides context information to help you locate the source of an error.

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

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

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

Related Topics

Example for Using Abstract Datatypes

Mapping Between WF_EVENT_T and SYS.AQ$_JMS_TEXT_MESSAGE

Initialize

PL/SQL Syntax

STATIC PROCEDURE initialize   
  (new_wf_event_t in out wf_event_t)

Description

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.

Arguments (input)

Variable Description
new_wf_event_t The WF_EVENT_T object to initialize.

getPriority

PL/SQL Syntax

MEMBER FUNCTION getPriority  
  return number

Description

Returns the value of the PRIORITY attribute in a WF_EVENT_T object.

getSendDate

PL/SQL Syntax

MEMBER FUNCTION getSendDate  
  return date

Description

Returns the value of the SEND_DATE attribute in a WF_EVENT_T object.

getReceiveDate

PL/SQL Syntax

MEMBER FUNCTION getReceiveDate  
  return date

Description

Returns the value of the RECEIVE_DATE attribute in a WF_EVENT_T object.

getCorrelationID

PL/SQL Syntax

MEMBER FUNCTION getCorrelationID  
  return varchar2

Description

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

getParameterList

PL/SQL Syntax

MEMBER FUNCTION getParameterList  
  return wf_parameter_list_t

Description

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

getEventName

PL/SQL Syntax

MEMBER FUNCTION getEventName  
  return varchar2

Description

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

getEventKey

PL/SQL Syntax

MEMBER FUNCTION getEventKey 
  return varchar2

Description

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

getEventData

PL/SQL Syntax

MEMBER FUNCTION getEventData   
  return clob

Description

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

getFromAgent

PL/SQL Syntax

MEMBER FUNCTION getFromAgent  
  return wf_agent_t

Description

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

getToAgent

PL/SQL Syntax

MEMBER FUNCTION getToAgent  
  return wf_agent_t

Description

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

getErrorSubscription

PL/SQL Syntax

MEMBER FUNCTION getErrorSubscription  
  return raw

Description

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

getErrorMessage

PL/SQL Syntax

MEMBER FUNCTION getErrorMessage  
  return varchar2

Description

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

getErrorStack

PL/SQL Syntax

MEMBER FUNCTION getErrorStack  
  return varchar2

Description

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

setPriority

PL/SQL Syntax

MEMBER PROCEDURE setPriority  
  (pPriority in number)

Description

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

Arguments (input)

Variable Description
pPriority The value for the PRIORITY attribute.

setSendDate

PL/SQL Syntax

MEMBER PROCEDURE setSendDate  
  (pSendDate in date default sysdate)

Description

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

Arguments (input)

Variable Description
pSendDate The value for the SEND_DATE attribute.

setReceiveDate

PL/SQL Syntax

MEMBER PROCEDURE setReceiveDate  
  (pReceiveDate in date default sysdate)

Description

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

Arguments (input)

Variable Description
pReceiveDate The value for the RECEIVE_DATE attribute.

setCorrelationID

PL/SQL Syntax

MEMBER PROCEDURE setCorrelationID  
    (pCorrelationID in varchar2)

Description

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

Arguments (input)

Variable Description
pCorrelationID The value for the CORRELATION_ID attribute.

setParameterList

PL/SQL Syntax

MEMBER PROCEDURE setParameterList  
  (pParameterList in wf_parameter_list_t)

Description

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

Arguments (input)

Variable Description
pParameterList The value for the PARAMETER_LIST attribute.

setEventName

PL/SQL Syntax

MEMBER PROCEDURE setEventName  
  (pEventName in varchar2)

Description

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

Arguments (input)

Variable Description
pEventName The value for the EVENT_NAME attribute.

setEventKey

PL/SQL Syntax

MEMBER PROCEDURE setEventKey  
  (pEventKey in varchar2)

Description

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

Arguments (input)

Variable Description
pEventKey The value for the EVENT_KEY attribute.

setEventData

PL/SQL Syntax

MEMBER PROCEDURE setEventData  
   (pEventData in clob)

Description

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

Arguments (input)

Variable Description
pEventData The value for the EVENT_DATA attribute.

setFromAgent

PL/SQL Syntax

MEMBER PROCEDURE setFromAgent  
  (pFromAgent in wf_agent_t)

Description

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

Arguments (input)

Variable Description
pFromAgent The value for the FROM_AGENT attribute.

setToAgent

PL/SQL Syntax

MEMBER PROCEDURE setToAgent  
  (pToAgent in wf_agent_t)

Description

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

Arguments (input)

Variable Description
pToAgent The value for the TO_AGENT attribute.

setErrorSubscription

PL/SQL Syntax

MEMBER PROCEDURE setErrorSubscription  
  (pErrorSubscription in raw)

Description

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

Arguments (input)

Variable Description
pErrorSubscription The value for the ERROR_SUBSCRIPTION attribute.

setErrorMessage

PL/SQL Syntax

MEMBER PROCEDURE setErrorMessage  
  (pErrorMessage in varchar2)

Description

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

Arguments (input)

Variable Description
pErrorMessage The value for the ERROR_MESSAGE attribute.

setErrorStack

PL/SQL Syntax

MEMBER PROCEDURE setErrorStack  
   (pErrorStack in varchar2)

Description

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

Arguments (input)

Variable Description
pErrorStack The value for the ERROR_STACK attribute.

Content

PL/SQL Syntax

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

Description

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

Arguments (input)

Variable Description
pName The value for the EVENT_NAME attribute.
pKey The value for the EVENT_KEY attribute.
pData The value for the EVENT_DATA attribute.

Address

PL/SQL Syntax

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

Description

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

Arguments (input)

Variable Description
pOutAgent The value for the FROM_AGENT attribute.
pToAgent The value for the TO_AGENT attribute.
pPriority The value for the PRIORITY attribute.
pSendDate The value for the SEND_DATE attribute.

AddParameterToList

PL/SQL Syntax

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

Description

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

Arguments (input)

Variable Description
pName The parameter name.
pValue The parameter value.

GetValueForParameter

PL/SQL Syntax

MEMBER FUNCTION GetValueForParameter  
  (pName in varchar2) return varchar2

Description

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

Arguments (input)

Variable Description
pName The parameter name.

Example for Using Abstract Datatypes

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

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;

Mapping Between WF_EVENT_T and SYS.AQ$_JMS_TEXT_MESSAGE

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

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

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

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

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

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.

Mapping WF_EVENT_T Attributes to SYS.AQ$_JMS_TEXT_MESSAGE Attributes
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.

Event APIs

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

Raise

PL/SQL Syntax

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);

Description

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

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

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

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

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

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

The Event Manager checks each subscription before executing it to determine whether the subscription requires the event data. If the event data is required but is not already provided, the Event Manager calls the generate function for the event to produce the event data. If the event data is required but no generate function is defined for the event, Oracle Workflow creates a default set of event data using the event name and event key.

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

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

Arguments (input)

Variable Description
p_event_name The internal name of the event.
p_event_key A string generated when the event occurs within a program or application. The event key uniquely identifies a specific instance of the event.
p_event_data An optional set of information about the event that describes what occurred. The Event Manager checks each subscription before executing it to determine whether the subscription requires the event data. If the event data is required but is not already provided, the Event Manager calls the generate function for the event to produce the event data. See: Events, Oracle Workflow Developer's Guide and Standard API for an Event Data Generate Function, Oracle Workflow Developer's Guide.
p_parameters An optional list of additional parameter name and value pairs.
p_send_date An optional date to indicate when the event should become available for subscription processing.

Sample Code

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

Raise3

PL/SQL Syntax

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);

Description

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

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

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

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

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

Arguments (input)

Variable Description
p_event_name The internal name of the event.
p_event_key A string generated when the event occurs within a program or application. The event key uniquely identifies a specific instance of the event.
p_event_data An optional set of information about the event that describes what occurred. The Event Manager checks each subscription before executing it to determine whether the subscription requires the event data. If the event data is required but is not already provided, the Event Manager calls the generate function for the event to produce the event data. See: Events, Oracle Workflow Developer's Guide and Standard API for an Event Data Generate Function, Oracle Workflow Developer's Guide.
p_parameter_list A list of additional parameter name and value pairs.
p_send_date An optional date to indicate when the event should become available for subscription processing.

Send

PL/SQL Syntax

procedure Send 
   (p_event in out wf_event_t);

Description

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

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

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

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

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

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

Arguments (input)

Variable Description
p_event The event message.

NewAgent

PL/SQL Syntax

function NewAgent 
  (p_agent_guid in raw) return wf_agent_t;

Description

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

Arguments (input)

Variable Description
p_agent_guid The globally unique identifier of the agent.

Test

PL/SQL Syntax

function Test 
  (p_event_name in varchar2) return varchar2;

Description

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

Arguments (input)

Variable Description
p_event_name The internal name of the event.

Enqueue

PL/SQL Syntax

procedure Enqueue  
  (p_event in wf_event_t,
   p_out_agent_override in wf_agent_t default null);

Description

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

Arguments (input)

Variable Description
p_event The event message.
p_out_agent_override The outbound agent on whose queue the event message should be enqueued.

Listen

PL/SQL Syntax

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);

Description

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

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

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

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

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

Arguments (input)

Variable Description
p_agent_name The name of the inbound agent.
p_wait An optional wait period, in seconds, during which you want the agent listener to block on the agent's queue to wait for messages. By default an agent listener does not wait but exits if all messages on the queue have been dequeued.
p_correlation Optionally specify an AQ correlation ID to identify the event messages that you want the agent listener to process. The AQ correlation ID for an event message in the Business Event System is usually specified as an event name, or as a partial event name followed by a percent sign (%) as a wildcard character. Consequently, by specifying an AQ correlation ID in this parameter, you can dedicate the agent listener to listen only for messages that are instances of the specified event or events. For example, you can specify oracle.apps.wf.notification% to listen for all events related to notifications whose names begin with that value. The default value for this correlation ID is null, which allows the agent listener to process messages that are instances of any event.
If a dequeue condition is specified in the next parameter, this parameter must be null.
See: Dequeue Methods, Oracle Streams Advanced Queuing User's Guide and Reference.

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

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

Related Topics

Any Event, Oracle Workflow Developer's Guide

Unexpected Event, Oracle Workflow Developer's Guide

Wfagtlst.sql, Oracle Workflow Administrator's Guide

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

SetErrorInfo

PL/SQL Syntax

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

Description

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

Arguments (input)

Variable Description
p_event The event message.
p_type The error type, either 'ERROR' or 'WARNING'.

SetDispatchMode

PL/SQL Syntax

procedure SetDispatchMode 
  (p_mode in varchar2);

Description

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

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

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

Arguments (input)

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

Related Topics

Deferred Subscription Processing, Oracle Workflow Developer's Guide

Raise

AddParameterToList

PL/SQL Syntax

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

Description

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

Arguments (input)

Variable Description
p_name The parameter name.
p_value The parameter value.
p_parameterlist The parameter list.

AddParameterToListPos

PL/SQL Syntax

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

Description

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

Arguments (input)

Variable Description
p_name The parameter name.
p_value The parameter value.
p_parameterlist The parameter list.

GetValueForParameter

PL/SQL Syntax

function GetValueForParameter  
  (p_name in varchar2,
   p_parameterlist in wf_parameter_list_t) 
  return varchar2;

Description

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.

Arguments (input)

Variable Description
p_name The parameter name.
p_parameterlist The parameter list.

GetValueForParameterPos

PL/SQL Syntax

function GetValueForParameterPos   
  (p_position in integer,
   p_parameterlist in wf_parameter_list_t) 
  return varchar2;

Description

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

Arguments (input)

Variable Description
p_position The index representing the position of the parameter within the parameter list.
p_parameterlist The parameter list.

SetMaxNestedRaise

PL/SQL Syntax

procedure SetMaxNestedRaise 
  (maxcount in number default 100);

Description

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

Arguments (input)

Variable Description
max_count The maximum number of nested raises to allow.

GetMaxNestedRaise

PL/SQL Syntax

function GetMaxNestedRaise 
  return number;

Description

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

GetParamListFromString

PL/SQL Syntax

function GetParamListFromString
  (p_parameters in varchar2) return wf_parameter_list_t;

Description

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

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

Arguments (input)

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

setNavigationParams

PL/SQL Syntax

procedure setNavigationParams
  (p_agentName in varchar2 default null,
   p_navigationThreshold in number default 0);

Description

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

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

Arguments (input)

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

resetNavigationParams

PL/SQL Syntax

procedure resetNavigationParams;

Description

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

getQueueNavigation

PL/SQL Syntax

function getQueueNavigation return BINARY_INTEGER;

Description

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

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

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.

Event Subscription Rule Function APIs

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

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

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

Default_Rule

PL/SQL Syntax

function Default_Rule  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

Performs default subscription processing for an event subscription. The default processing includes:

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:

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

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

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

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

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

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Log

PL/SQL Syntax

function Log  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

set serveroutput on size 100000

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

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

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Error

PL/SQL Syntax

function Error  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

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

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

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Warning

PL/SQL Syntax

function Warning  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

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

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

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Success

PL/SQL Syntax

function Success  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Workflow_Protocol

PL/SQL Syntax

function Workflow_Protocol  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

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

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

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.

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Error_Rule

PL/SQL Syntax

function Error_Rule  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

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

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Related Topics

Unexpected Event, Oracle Workflow Developer's Guide

Any Event, Oracle Workflow Developer's Guide

SetParametersIntoParameterList

PL/SQL Syntax

function SetParametersIntoParameterList  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

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

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Related Topics

Event Message Structure

Default_Rule2

PL/SQL Syntax

function Default_Rule2  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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.

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Related Topics

Default_Rule

Default_Rule3

PL/SQL Syntax

function Default_Rule3  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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.

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Related Topics

SetParametersIntoParameterList

Default_Rule

SendNotification

PL/SQL Syntax

function SendNotification  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

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

Parameters for Sending a Notification
Parameter Name Parameter Value
RECIPIENT_ROLE The role name assigned to receive the notification.
MESSAGE_TYPE The item type associated with the message.
MESSAGE_NAME The message internal name.
CALLBACK The callback function name used for communication of SEND and RESPOND source message attributes.
CONTEXT Context information passed to the callback function.
SEND_COMMENT A comment presented with the message.
PRIORITY The priority of the message. If this value is null, the Notification System uses the default priority of the message.
DUE_DATE The date that a response is required. This optional due date is only for the recipient's information; it has no effect on processing.

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

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Related Topics

Send

Event Message Structure

Raise3

GetValueForParameter

GetAttribute

Instance_Default_Rule

PL/SQL Syntax

function Instance_Default_Rule  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

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

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.

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Related Topics

SetParametersIntoParameterList

Default_Rule

Default_Rule_Or

PL/SQL Syntax

function Default_Rule_Or  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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.

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Related Topics

Default_Rule

Default_Generate

PL/SQL Syntax

function Default_Generate
  (p_event_name in varchar2, 
   p_event_key in varchar2,
   p_parameter_list in wf_parameter_list_t) return clob;

Description

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="">

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>

Arguments (input)

Variable Description
p_event_name The internal name of the event.
p_event_key A string generated when the event occurs within a program or application. The event key uniquely identifies a specific instance of the event.
p_parameter_list A list of additional parameter name and value pairs for the event.

WebServiceInvokerSubscription

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

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

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

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.

onBusinessEvent

The WebServiceInvokerSubscription class defines the onBusinessEvent method from the SubscriptionInterface Java interface to invoke a Web service.

Java Syntax

public void onBusinessEvent
  (Subscription eo, 
   BusinessEvent event, 
   WorkflowContext context) throws BusinessEventException

Description

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

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

Arguments (input)

Variable Description
eo The Subscription object, which provides information about the subscription such as the phase number and parameters.
event The BusinessEvent object, which provides information about the business event that occurred, including the event name, event key, event data, and payload object.
context Workflow context information, including the database connection and the Log object which can be used for logging.

preInvokeService

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

Java Syntax

protected String preInvokeService
  (Subscription eo, 
   BusinessEvent event, 
   WorkflowContext context) throws BusinessEventException

Description

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

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

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

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

Arguments (input)

Variable Description
eo The Subscription object, which provides information about the subscription such as the phase number and parameters.
event The BusinessEvent object, which provides information about the business event that occurred, including the event name, event key, event data, and payload object.
context Workflow context information, including the database connection and the Log object which can be used for logging.

invokeService

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

Java Syntax

protected String invokeService
  (String wsdlLocation, 
   String serviceName, 
   String invokePort, 
   String portTypeName, 
   String operationName, 
   String eventData) throws Exception 

Description

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

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

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

Arguments (input)

Variable Description
wsdlLocation The URL where the Web Services Description Language (WSDL) description for the Web service is located.
serviceName The name of the Web service.
invokePort The port, which is the single communication endpoint defined by a combination of a network address and a binding. The binding specifies concrete protocol and data format specifications for the operations and messages defined by the port type.
portTypeName The port type, or set of abstract operations, that includes the operation to invoke.
operationName The operation to invoke.
eventData The string returned by the preInvokeService method, usually in XML format, that will be used as the Web service request.

setInputParts

The setInputParts method is called during the invocation processing.

Java Syntax

protected void setInputParts
  (WSIFMessage inputMessage, 
   Input input, 
   String eventData) throws Exception

Description

Adds parts to the XML input message, such as the header, body, and so on, according to the input message definition for the selected operation. The default implementation adds the event data payload as the body of the input message. It also adds any other parts provided as event parameters in the triggering event. The event parameters that contain input message parts must be identified by parameter names in the following format:

WFBES_INPUT_<PartName>

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

WFBES_INPUT_header

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

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.

Arguments (input)

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.

addWSSecurityHeader

The addWSSecurityHeader method is called during the invocation processing.

Java Syntax

protected void addWSSecurityHeader
  (ArrayList headersList) throws Exception 

Description

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

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

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

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

Arguments (input)

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

postInvokeService

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

Java Syntax

protected void postInvokeService
  (Subscription eo, 
   BusinessEvent event, 
   WorkflowContext context, 
   String requestData, 
   String responseData) throws BusinessEventException 

Description

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

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

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

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

Arguments (input)

Variable Description
eo The Subscription object, which provides information about the subscription such as the phase number and parameters.
event The BusinessEvent object, which provides information about the business event that occurred, including the event name, event key, event data, and payload object.
context Workflow context information, including the database connection and the Log object which can be used for logging.
requestData The string that was sent as the Web service request.
responseData The string that was received as the response from the Web service, if any.

get Parameter Methods

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

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

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.

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

See: Invoking a Web Service, Oracle Workflow Developer's Guide and the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

Event Function APIs

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

Parameters

PL/SQL Syntax

function Parameters  
  (p_string in varchar2, 
   p_numvalues in number,
   p_separator in varchar2) return t_parameters;

Description

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

T_PARAMETERS Datatype
Datatype Name Element Datatype Definition
T_PARAMETERS VARCHAR2(240)

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

Arguments (input)

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.

Sample Code

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;
/  

SubscriptionParameters

PL/SQL Syntax

function SubscriptionParameters  
  (p_string in varchar2, 
   p_key in varchar2) return varchar2;

Description

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

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

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

Arguments (input)

Variable Description
p_string A text string containing the parameters defined for an event subscription.
p_key The name of the parameter whose value should be returned.

Sample Code

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

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

AddCorrelation

PL/SQL Syntax

function AddCorrelation  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

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

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

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:

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

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

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

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Generate

PL/SQL Syntax

function Generate  
  (p_event_name in varchar2, 
   p_event_key in varchar2) return clob;

Description

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

The Seed event group includes the following events:

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

Arguments (input)

Variable Description
p_event_name The internal name of the event.
p_event_key A string generated when the event occurs within a program or application. The event key uniquely identifies a specific instance of the event.

Related Topics

WF_EVENTS_PKG.Generate

WF_EVENT_GROUPS_PKG.Generate

WF_SYSTEMS_PKG.Generate

WF_AGENTS_PKG.Generate

WF_AGENT_GROUPS_PKG.Generate

WF_EVENT_SUBSCRIPTIONS_PKG.Generate

Predefined Workflow Events, Oracle Workflow Developer's Guide

Receive

PL/SQL Syntax

function Receive  
  (p_subscription_guid in raw, 
   p_event in out wf_event_t) return varchar2;

Description

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

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

The Seed event group includes the following events:

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.

Arguments (input)

Variable Description
p_subscription_guid The globally unique identifier of the subscription.
p_event The event message.

Related Topics

WF_EVENTS_PKG.Receive

WF_EVENT_GROUPS_PKG.Receive

WF_SYSTEMS_PKG.Receive

WF_AGENTS_PKG.Receive

WF_AGENT_GROUPS_PKG.Receive

WF_EVENT_SUBSCRIPTIONS_PKG.Receive

Predefined Workflow Events, Oracle Workflow Developer's Guide

Business Event System Replication APIs

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

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

Document Type Definitions

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

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

WF_EVENTS Document Type Definition

The following document type definition (DTD) describes the required structure for an XML message that contains the complete information for an event 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> 

WF_EVENTS_PKG.Generate

PL/SQL Syntax

function Generate 
  (x_guid in raw)
  return varchar2;

Description

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

Arguments (input)

Variable Description
x_guid The globally unique identifier of the event.

WF_EVENTS_PKG.Receive

PL/SQL Syntax

procedure Receive 
  (x_message in varchar2);

Description

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

Arguments (input)

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

WF_EVENT_GROUPS Document Type Definition

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

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

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

WF_EVENT_GROUPS_PKG.Generate

PL/SQL Syntax

function Generate 
  (x_group_guid in raw,
   x_member_guid in raw)
  return varchar2;

Description

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

Arguments (input)

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.

WF_EVENT_GROUPS_PKG.Receive

PL/SQL Syntax

procedure Receive 
  (x_message in varchar2);

Description

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

Arguments (input)

Variable Description
x_message An XML message containing the complete information for an event group member definition.

WF_SYSTEMS Document Type 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> 

WF_SYSTEMS_PKG.Generate

PL/SQL Syntax

function Generate 
  (x_guid in raw)
  return varchar2;

Description

Generates an XML message containing the complete information from the WF_SYSTEMS table for the specified system definition.

Arguments (input)

Variable Description
x_guid The globally unique identifier of the system.

WF_SYSTEMS_PKG.Receive

PL/SQL Syntax

procedure Receive 
  (x_message in varchar2);

Description

Receives an XML message containing the complete information for a system definition and loads the information into the WF_SYSTEMS table.

Arguments (input)

Variable Description
x_message An XML message containing the complete information for a system definition.

WF_AGENTS Document Type Definition

The following document type definition (DTD) describes the required structure for an XML message that contains the complete information for an agent 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>

WF_AGENTS_PKG.Generate

PL/SQL Syntax

function Generate 
  (x_guid in raw)
  return varchar2;

Description

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

Arguments (input)

Variable Description
x_guid The globally unique identifier of the agent.

WF_AGENTS_PKG.Receive

PL/SQL Syntax

procedure Receive 
  (x_message in varchar2);

Description

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

Arguments (input)

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

WF_AGENT_GROUPS Document Type Definition

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

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

<WF_TABLE_DATA> 
  <WF_AGENT_GROUPS> 
    <VERSION></VERSION> 
    <GROUP_GUID></GROUP_GUID> 
    <MEMBER_GUID></MEMBER_GUID> 
  </WF_AGENT_GROUPS> 
</WF_TABLE_DATA> 

WF_AGENT_GROUPS_PKG.Generate

PL/SQL Syntax

function Generate 
  (x_group_guid in raw,
   x_member_guid in raw)
  return varchar2;

Description

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

Arguments (input)

Variable Description
x_group_guid The globally unique identifier of the agent group.
x_member_guid The globally unique identifier of the individual member agent.

WF_AGENT_GROUPS_PKG.Receive

PL/SQL Syntax

procedure Receive 
  (x_message in varchar2);

Description

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

Arguments (input)

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

WF_EVENT_SUBSCRIPTIONS Document Type Definition

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

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

WF_EVENT_SUBSCRIPTIONS_PKG.Generate

PL/SQL Syntax

function Generate 
  (x_guid in raw)
  return varchar2;

Description

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

Arguments (input)

Variable Description
x_guid The globally unique identifier of the event subscription.

WF_EVENT_SUBSCRIPTIONS_PKG.Receive

PL/SQL Syntax

procedure Receive 
  (x_message in varchar2);

Description

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

Arguments (input)

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

Business Event System Cleanup API

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

Cleanup_Subscribers

PL/SQL Syntax

procedure Cleanup_Subscribers  
  (errbuf out varchar2,
   retcode out varchar2);

Description

Performs cleanup for the standard WF_CONTROL queue.

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

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

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

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

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

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

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

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