Previous	Next		Contents	Index	Glossary

• 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 additional standard rule functions that you can use for advanced processing, testing, debugging, or other purposes. Commonly used rule functions including the following:

• Default_Rule2 - Performs the basic subscription processing only if the parameter list within the event message includes parameters whose names and values match all the parameters defined for the subscription. See: Default_Rule2, Oracle Workflow API Reference.

• Default_Rule3 - Sets the parameter name and value pairs from the subscription parameters into the parameter list within the event message before performing the basic subscription processing. See: Default_Rule3, Oracle Workflow API Reference.

• SendNotification - Sends a notification as specified by the parameter list within the event message. This rule function lets you send a notification outside of a workflow process. See: SendNotification, Oracle Workflow API Reference.

• Instance_Default_Rule - Sends the event to all existing workflow processes that have eligible receive event activities waiting to receive it, identified by a business key attribute. See: Instance_Default_Rule, 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 use the phase numbers 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.

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

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.

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.

public interface SubscriptionInterface

{

  void onBusinessEvent(Subscription eo, BusinessEvent event,

                       WorkflowContext ctx)

               throws BusinessEventException;

}

The arguments for the API are as follows:

eo	The Subscription object, which provides information about the subscription such as the phase number and any parameters.
event	The BusinessEvent object, which provides information about the business event that occurred, including the event name, event key, event data, and the optional payload object.
ctx	Workflow context information, including the database connection and the Log object which can be used for logging.

If the execution of the rule function does not succeed, the subscription can pass the error details to the Event Manager by encapsulating the details in a BusinessEventException.

Note: When raising an event from Java, you can also set a serializable object as a payload for the event. The payload is available to all Java subscriptions to the event.

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

Oracle Workflow Javadoc on OracleMetaLink