Previous	Next		Contents	Index	Glossary

procedure Event

    (itemtype in varchar2,

     itemkey in varchar2,

     process_name in varchar2 default null,

     event_message in wf_event_t);

Description

Receives an event from the Business Event System into a workflow process.

If the specified item key already exists, the event is received into that item. If the item key does not already exist, but the specified process includes an eligible Receive event activity marked as a Start activity, the Workflow Engine creates a new item running that process.

Within the workflow process that receives the event, the procedure searches for eligible Receive event activities. For an activity to be eligible to receive an event, its event filter must either be set to that particular event, set to an event group of which that event is a member, or left blank to accept any event. Additionally, the activity must either be marked as a Start activity, or it must have an activity status of NOTIFIED, meaning the process has transitioned to that activity and is waiting to receive the event.

For each eligible Receive event activity, Event() stores the event name, event key, and event message in the item type attributes specified in the event activity node, if they have been defined. Additionally, the procedure sets any parameters in the event message parameter list as item type attributes for the process, creating new item type attributes if a corresponding attribute does not already exist for any parameter. It also sets the subscription's globally unique identifier (GUID) as a dynamic item attribute so that the workflow process can reference other information in the subscription definition. Then the Workflow Engine begins a thread of execution from the event activity.

If no eligible Receive event activity exists for a received event, the procedure returns an exception and an error message.

Note: If an event arrives at a Start activity to launch a new process instance, the Workflow Engine also searches for all other receive event activities that are marked as Start activities and that do not have any incoming transitions, regardless of their event filter. For these activities, the Workflow Engine sets the activity status to 'NOTIFIED' so that they will be ready to receive an event if any more events are sent to this process. This feature lets you design a workflow process that requires multiple events to be received when you do not know in advance the order in which the events will arrive.

Note: If the event received by a Receive event activity was originally raised by a Raise event activity in another workflow process, the item type and item key for that process are included in the parameter list within the event message. In this case, the Workflow Engine automatically sets the specified process as the parent for the process that receives the event, overriding any existing parent setting. See: SetItemParent.

Arguments (input)

itemtype	A valid item type.
itemkey	A string that uniquely identifies the item within an item type. The item type and key together identify the process.

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

process_name

An optional argument that allows the selection of a particular subprocess for that item type. Provide the process activity's label name. If the process activity label name does not uniquely identify the subprocess you can precede the label name with the internal name of its parent process. For example, <parent_process_internal_name>:<label_name>. If this argument is null, the top level process for the item is started. This argument defaults to null.

event_message

The event message containing the details of the event.