AddCorrelation (Oracle Workflow API Reference)

Oracle Workflow API Reference
Release 2.6.3
Part Number B10286-02


	Previous	Next		Contents	Index	Glossary

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. The function must be specified in the Parameters field for the subscription in the following format:

 ITEMKEY=<package_name.function_name>

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)

p_subscription_ guid	The globally unique identifier of the subscription.
p_event	The event message.


	Previous	Next		Contents	Index	Glossary