| Previous | Next |  | Contents | Index | Glossary

## Standard API for an Event Subscription Rule Function

When you define an event subscription, you can choose to run a PL/SQL function called a rule function on the event message. Oracle Workflow provides a standard default rule function to perform basic subscription processing. This function is executed by default if no other rule function is specified for the subscription. 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

See: Default_Rule.

Oracle Workflow also provides some standard rule functions that you can use for testing and debugging or other purposes. See: Event Subscription Rule APIs.

You can extend your subscription processing by creating custom rule functions. Custom rule functions must be defined according to a standard API.

A rule function may read from or write to the event message or perform any other database action. However, you should never commit within a rule function. The Event Manager never issues a commit as it is the responsibility of the calling application to commit. Additionally, the rule function must not change the connection context in any way, including security and NLS settings.

> Note: If your rule function writes to the event message, any subsequent subscriptions executed on the event will access the changed message.

If the subscription processing that you want to perform for an event includes several successive steps, you may find it advantageous to define multiple subscriptions to the event with simple rule functions that you can reuse, rather than creating complex specialized rule functions that cannot be reused. You can enter phase values for the subscriptions to specify the order in which they should be executed.

By default, the Event Manager uses the event key as the correlation ID for the event message when no other correlation ID is specified. If you want to specify a different correlation ID, you can use WF_EVENT_FUNCTIONS_PKG.AddCorrelation to add a correlation ID to the event message, either by calling this function within your custom rule function or by defining another subscription that uses WF_EVENT_FUNCTIONS_PKG.AddCorrelation as its rule function. See: AddCorrelation.

If you want to send the event message to a workflow process or to an agent after running custom code on the message, you must either include the send processing in your rule function, or define a separate subscription that uses the default rule function to perform the send processing.

- Call WF_ENGINE.Event() to send the event message to a workflow process.

- Call WF_EVENT.Send() to send the event message to an agent.

- Call WF_RULE.Default_Rule() to include the default subscription processing that can send the event message both to a workflow process and to an agent.

> Note: When you define a subscription in the Event Manager, you can define the workflow item type, workflow process name, out agent, to agent, priority, and parameters for your send processing, as well as defining the rule function. Any rule function can access these send attributes, but if you do not use the default rule function, you must explicitly include the send processing in your custom rule function if you want to send the event from the same subscription.

The standard API for a rule function is as follows. This section is numbered with the notation 1-> for easy referencing. The numbers and arrows themselves are not part of the procedure.

1-> | function <function_name> ( | p_subscription_guid | in raw,
|  |  |  | p_event | in out WF_EVENT_T) return varchar2 is
2-> | <local declarations>
3-> | begin |  |
| <your executable statements> |
4-> | <optional code for WARNING> |  |
| WF_CORE.CONTEXT('<package name>', '<function name>', p_event.getEventName( ),
| p_subscription_guid);
| WF_EVENT.setErrorInfo(p_event, 'WARNING');
| return 'WARNING'; |  |
5-> | return 'SUCCESS'; |  |
6-> | exception |  |
| when others then
| WF_CORE.CONTEXT('<package name>', '<function name>', p_event.getEventName( ),
| p_subscription_guid);
| WF_EVENT.setErrorInfo(p_event, 'ERROR');
| return 'ERROR';
7-> | end; |  |

1-> When the Event Manager calls the rule function, it passes two parameters to the function and expects a return code when the function completes. The parameters are defined here:

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

The function must return one of the following status codes:

- `SUCCESS`--The rule function completed successfully.

- `WARNING`--A warning condition occurred. The rule function reports a warning message using the Workflow Core error APIs and sets the warning information into the event message. The Event Manager places a copy of the event message on the WF_ERROR queue, but subscription processing continues.

- `ERROR`--An error occurred. The rule function reports an error message using the Workflow Core error APIs and sets the error information into the event message. The Event Manager halts subscription processing for this event, rolls back any subscriptions already executed for the event, and places the event message on the WF_ERROR queue.

2-> This section declares any local arguments that are used within the function.

3-> The procedure body begins in this section with one or more executable statements that make up your rule function.

4-> This optional section calls WF_CORE.CONTEXT( ) if a warning condition occurs, so that you can include context information in the error stack to help you locate the source of an error. It also sets the warning information into the event message and returns the status code 'WARNING'. See: CONTEXT.

5-> This section returns the status code 'SUCCESS' when the rule function's normal processing completes successfully.

6-> This section calls WF_CORE.CONTEXT( ) if an exception occurs, so that you can include context information in the error stack to help you locate the source of an error. It also sets the error information into the event message and returns the status code 'ERROR'. See: CONTEXT.

> Note: If you raise an exception in the rule function, the Event Manager rolls back all subscription processing for the event and raises the error to the calling application. In this case the event message is not placed on the WF_ERROR queue.

### See Also

To Define an Event Subscription

Event Message Structure

Workflow Core APIs

Event Subscription Rule APIs

Event()

Send()

Default_Rule()

SetErrorInfo()

| Previous | Next |  | Contents | Index | Glossary