Previous	Next		Contents	Index	Glossary

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:

See: Default_Rule, Oracle Workflow API Reference.

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

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, Oracle Workflow API Reference.

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.

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:

The function must return one of the following status codes:

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, Oracle Workflow API Reference.

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, Oracle Workflow API Reference.

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

Event Message Structure, Oracle Workflow API Reference

Workflow Core APIs, Oracle Workflow API Reference

Event Subscription Rule APIs, Oracle Workflow API Reference

Event(), Oracle Workflow API Reference

Send(), Oracle Workflow API Reference

Default_Rule, Oracle Workflow API Reference

SetErrorInfo(), Oracle Workflow API Reference

Copyright © 2003 Oracle Corporation.
All rights reserved.