Standard API for an Event Subscription Rule Function

When you define an event subscription, you choose a function called a rule function to run on the event message. Oracle Workflow provides a standard default rule function named WF_RULE.Default_Rule to perform basic subscription processing. The default rule function includes the following actions:

See: Default_Rule.

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:

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

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.

Related Topics

Standard API for a PL/SQL Subscription Rule Function

The standard API for a PL/SQL rule function is as follows. This section is numbered with the notation (1) for easy referencing. The numbers 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:

(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 unhandled exception in a rule function, the Event Manager's treatment of the unhandled exception depends on the type of error handling specified for the subscription.

Note: If you use custom PL/SQL rule functions, you can optionally enable Oracle Workflow to call your custom functions statically to enhance performance. See: Enabling Static Function Calls for Custom PL/SQL Functions.

Standard API for a Java Subscription Rule Function

You can optionally provide a Java subscription rule function to be executed in the middle tier, instead of a PL/SQL rule function. A Java rule function must be a Java class using the following Java interface:

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. Depending on the error handling specified for the subscription, the Event Manager can either halt subscription processing for this event and roll back any subscriptions already executed for the event, or roll back only the errored subscription and continue processing the next subscription for the event.

Ensure that your rule function Java class is part of the JAVA_TOP that is included in the AF_CLASSPATH on the concurrent processing tier for your Oracle E-Business Suite installation.

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.