Skip Headers

Oracle Workflow API Reference Release 2.6.4 Part Number B15855-02

Home Book List Contents Index Master Index Feedback

---

Previous Next

View PDF

Skip Headers

Oracle Workflow API Reference Release 2.6.4 Part Number B15855-02

Contents

Previous

Next

Business Event System APIs

Overview of the Oracle Workflow Business Event System

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

Subscriptions can include the following types of processing:

• Sending event information to a workflow process

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

• Sending a notification to a role

• Receiving an Oracle XML Gateway message from a trading partner (Oracle E-Business Suite only)

• Sending an Oracle XML Gateway message to a trading partner (Oracle E-Business Suite only)

• Executing custom code on the event information

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

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

Related Topics

Business Event System Datatypes

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

• Agent structure: WF_AGENT_T

• Parameter structure: WF_PARAMETER_T

• Parameter list structure: WF_PARAMETER_LIST_T

• Event message structure: WF_EVENT_T

The Business Event System datatypes are created by a script called wftypes.sql, which is located in the ORACLE_HOME/wf/sql directory for the standalone version of Oracle Workflow, or in the $FND_TOP/sql directory for the version of Oracle Workflow embedded in Oracle Applications.

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.

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

• getName

• getSystem

• setName

• setSystem

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)

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)

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.

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

• getValue

• setName

• setValue

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)

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)

Parameter List Structure

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

WF_PARAMETER_LIST_T

• Maximum size: 100

• Element datatype: WF_PARAMETER_T

Event Message Structure

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

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

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

The following table lists the attributes of the WF_EVENT_T datatype.

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

• Initialize

• getPriority

• getSendDate

• getReceiveDate

• getCorrelationID

• getParameterList

• getEventName

• getEventKey

• getEventData

• getFromAgent

• getToAgent

• getErrorSubscription

• getErrorMessage

• getErrorStack

• setPriority

• setSendDate

• setReceiveDate

• setCorrelationID

• setParameterList

• setEventName

• setEventKey

• setEventData

• setFromAgent

• setToAgent

• setErrorSubscription

• setErrorMessage

• setErrorStack

• Content

• Address

• AddParameterToList

• GetValueForParameter

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.

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

Arguments (input)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

Example for Using Abstract Datatypes

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

• Initializing a new event message structure with the Initialize method

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

• Initializing a CLOB locator

• Writing a text variable into a CLOB variable

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

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

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

declare
l_overrideagent varchar2(30) := '&overrideagent';
l_overridesystem varchar2(30) := '&overridesystem';
l_fromagent varchar2(30) := '&fromagent';
l_fromsystem varchar2(30) := '&fromsystem';
l_toagent varchar2(30) := '&toagent';
l_tosystem varchar2(30) := '&tosystem';
l_eventname varchar2(100) := '&eventname';
l_eventkey varchar2(100) := '&eventkey';
l_msg varchar2(200) := '&message';
l_clob clob;
l_overrideagent_t wf_agent_t;
l_toagent_t wf_agent_t;
l_fromagent_t wf_agent_t;
l_event_t wf_event_t;

begin

  /*You must call wf_event_t.initialize before you can manipulate
    a new wf_event_t object.*/
  wf_event_t.initialize(l_event_t);
  l_overrideagent_t := wf_agent_t(l_overrideagent, l_overridesystem);
  l_toagent_t := wf_agent_t(l_toagent, l_tosystem);
  l_fromagent_t := wf_agent_t(l_fromagent, l_fromsystem);

  if l_msg is null then
    l_event_t.Content(l_eventname, l_eventkey, null);
  else
    dbms_lob.createtemporary(l_clob, FALSE, DBMS_LOB.CALL);
    dbms_lob.write(l_clob, length(l_msg), 1, l_msg);
    l_event_t.Content(l_eventname, l_eventkey, l_clob);
  end if;

  l_event_t.Address(l_fromagent_t, l_toagent_t, 50, sysdate);

  wf_event.enqueue(l_event_t, l_overrideagent_t);

end;

Mapping Between WF_EVENT_T and SYS.AQ$_JMS_TEXT_MESSAGE

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

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

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

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

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

• TEXT_LEN - The size of the message payload, set automatically

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

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

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

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

• TYPE - The type of the message

• USERID - The identity of the user sending the message

• APPID - The identity of the application sending the message

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

• GROUPSEQ - The sequence number of the message within the group

• PROPERTIES - Additional message properties in the SYS.AQ$_JMS_USERPROPARRAY datatype

The SYS.AQ$_JMS_USERPROPARRAY datatype is a named varying array with a maximum size of 100. The datatype of its elements is another ADT named SYS.AQ$_JMS_USERPROPERTY.

The following table shows how the attributes of the WF_EVENT_T message structure are mapped to the attributes within the SYS.AQ$_JMS_TEXT_MESSAGE structure.

See: Using Oracle Java Message Service to Access AQ, Oracle Application Developer's Guide - Advanced Queuing or 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

• Raise3

• Send

• NewAgent

• Test

• Enqueue

• Listen

• SetErrorInfo

• SetDispatchMode

• AddParameterToList

• AddParameterToListPos

• GetValueForParameter

• GetValueForParameterPos

• SetMaxNestedRaise

• GetMaxNestedRaise

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: Any exceptions raised during Raise() 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.

Arguments (input)

Example

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: Any exceptions raised during Raise3() 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.

Arguments (input)

Send

PL/SQL Syntax

procedure Send 
   (p_event in out wf_event_t);

Description

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

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

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

• You can omit the To Agent if the From Agent uses a multi-consumer queue with a subscriber list. (The standard Workflow queue handlers work only with multi-consumer queues.) In this case, the queue's subscriber list determines which consumers can dequeue the message. If no subscriber list is defined for that queue, however, the event message is placed on the WF_ERROR queue for error handling.

  Note: The subscriber list for a multi-consumer queue in Oracle Advanced Queuing is different from event subscriptions in the Oracle Workflow Business Event System. For more information, see: Subscription and Recipient Lists, Oracle Application Developer's Guide - Advanced Queuing or Oracle Streams Advanced Queuing User's Guide and Reference.

• You can also omit the To Agent if the From Agent uses a single-consumer queue for which you have defined a custom queue handler. For a single-consumer queue, no specified consumer is required.

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

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)

Test

PL/SQL Syntax

function Test 
  (p_event_name in varchar2) return varchar2;

Description

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

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

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

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

Arguments (input)

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)

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

Description

Monitors an agent for inbound event messages and dequeues messages using the agent's queue handler, in the database tier.

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

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

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

You must not call Listen() from within application code. If you want to call this procedure directly, you can run it from SQL*Plus. Otherwise, you can schedule PL/SQL agent listeners for your inbound agents from Oracle Applications Manager or Oracle Enterprise Manager, depending on your version of Oracle Workflow. 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. Additionally, if your database version is Oracle9i Database or higher, 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)

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)

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)

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)

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)

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)

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)

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)

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.

Event Subscription Rule Function APIs

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

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

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

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

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

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

• Default_Rule

• Log

• Error

• Warning

• Success

• Workflow_Protocol

• Error_Rule

• SetParametersIntoParameterList

• Default_Rule2

• Default_Rule3

• SendNotification

• Instance_Default_Rule

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:

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

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

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

Note: If the event message is being sent to the Default Event Error workflow process by the subscription, 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)

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:

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

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

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

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

set serveroutput on size 100000

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

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

Arguments (input)

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 enter a text string representing the internal name of an error message in the Parameters field for the subscription. When the subscription is executed, Error() will set that error message into the event message using setErrorMessage(). See: setErrorMessage.

The text string you enter in the Parameters field 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 enter WFSQL_ARGS in the Parameters field. 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 and subscription processing for the event is halted. 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)

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 enter a text string representing the internal name of an error message in the Parameters field for the subscription. When the subscription is executed, Warning() will set that error message into the event message using setErrorMessage(). See: setErrorMessage.

The text string you enter in the Parameters field 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 enter WFSQL_ARGS in the Parameters field. 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)

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)

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 and Event System Demonstration events. See: Workflow Send Protocol, Oracle Workflow Developer's Guide and Event System Demonstration, Oracle Workflow Developer's Guide.

Arguments (input)

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:

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

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

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

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

You can also use this rule function with your own error subscriptions. Enter WF_RULE.Error 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)

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)

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:

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

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

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

Arguments (input)

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:

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

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

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

Arguments (input)

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.

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)

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:

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

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

  • This individual event

  • An event group of which this event is a member

  • NULL, meaning the activity can receive any event

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

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

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

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

Arguments (input)

Related Topics

SetParametersIntoParameterList

Default_Rule

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

• SubscriptionParameters

• AddCorrelation

• Generate

• Receive

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:

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)

Example

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)

Example

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. In standalone Oracle Workflow, the function must be specified in the Parameters field for the subscription in the following format:

ITEMKEY=<package_name.function_name> 

In Oracle Applications, 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)

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:

• oracle.apps.wf.event.event.create

• oracle.apps.wf.event.event.update

• oracle.apps.wf.event.event.delete

• oracle.apps.wf.event.group.create

• oracle.apps.wf.event.group.update

• oracle.apps.wf.event.group.delete

• oracle.apps.wf.event.system.create

• oracle.apps.wf.event.system.update

• oracle.apps.wf.event.system.delete

• oracle.apps.wf.event.agent.create

• oracle.apps.wf.event.agent.update

• oracle.apps.wf.event.agent.delete

• oracle.apps.wf.agent.group.create

• oracle.apps.wf.agent.group.update

• oracle.apps.wf.agent.group.delete

• oracle.apps.wf.event.subscription.create

• oracle.apps.wf.event.subscription.update

• oracle.apps.wf.event.subscription.delete

• oracle.apps.wf.event.all.sync

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

Note: Agent groups are currently only available for the version of Oracle Workflow embedded in Oracle Applications.

Arguments (input)

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:

• oracle.apps.wf.event.event.create

• oracle.apps.wf.event.event.update

• oracle.apps.wf.event.event.delete

• oracle.apps.wf.event.group.create

• oracle.apps.wf.event.group.update

• oracle.apps.wf.event.group.delete

• oracle.apps.wf.event.system.create

• oracle.apps.wf.event.system.update

• oracle.apps.wf.event.system.delete

• oracle.apps.wf.event.agent.create

• oracle.apps.wf.event.agent.update

• oracle.apps.wf.event.agent.delete

• oracle.apps.wf.agent.group.create

• oracle.apps.wf.agent.group.update

• oracle.apps.wf.agent.group.delete

• oracle.apps.wf.event.subscription.create

• oracle.apps.wf.event.subscription.update

• oracle.apps.wf.event.subscription.delete

• oracle.apps.wf.event.all.sync

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

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

Agent groups are currently only available for the version of Oracle Workflow embedded in Oracle Applications.

Arguments (input)

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.

• WF_EVENTS_PKG

  • WF_EVENTS_PKG.Generate

  • WF_EVENTS_PKG.Receive

• WF_EVENT_GROUPS_PKG

  • WF_EVENT_GROUPS_PKG.Generate

  • WF_EVENT_GROUPS_PKG.Receive

• WF_SYSTEMS_PKG

  • WF_SYSTEMS_PKG.Generate

  • WF_SYSTEMS_PKG.Receive

• WF_AGENTS_PKG

  • WF_AGENTS_PKG.Generate

  • WF_AGENTS_PKG.Receive

• WF_AGENT_GROUPS_PKG

  • WF_AGENT_GROUPS_PKG.Generate

  • WF_AGENT_GROUPS_PKG.Receive

• WF_EVENT_SUBSCRIPTIONS_PKG

  • WF_EVENT_SUBSCRIPTIONS_PKG.Generate

  • WF_EVENT_SUBSCRIPTIONS_PKG.Receive

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

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

Document Type Definitions

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

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

• WF_EVENT_GROUPS DTD

• WF_SYSTEMS DTD

• WF_AGENTS DTD

• WF_AGENT_GROUPS DTD

  Note: Agent groups are currently only available for the version of Oracle Workflow embedded in Oracle Applications.

• WF_EVENT_SUBSCRIPTIONS DTD

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

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)

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

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)

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)

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)

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)

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)

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.

Agent groups are currently only available for the version of Oracle Workflow embedded in Oracle Applications.

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

Note: Agent groups are currently only available for the version of Oracle Workflow embedded in Oracle Applications.

Arguments (input)

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.

Note: Agent groups are currently only available for the version of Oracle Workflow embedded in Oracle Applications.

Arguments (input)

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

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)

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

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

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

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

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

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

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

• 0 - Success

• 1 - Warning

• 2 - Error

Related Topics

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

Standard Agents, Oracle Workflow Developer's Guide

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

Copyright © 2003, 2005, Oracle. All rights reserved.

---

Previous Next

Home Book List Contents Index Master Index Feedback