Oracle Business Events and step by step process to subscribe to a Business Event

The concept of Business Events in the context of EBS plays a critcal role in enabling event-driven integration with other systems outside the application.

In addition to that, the Business Events in E-Business Suite in particular allow for an exceptionally effective way of decoupling the standard product functionality, available out of the box, from client customizations that seek to adapt the standard product to meet customer-specific business needs. In other words, Oracle Applications developers should consider using Business Events whenever possible when configuring and customizing the standard products.

 What are Business Events

“A business event is an occurrence in an internet or intranet application or program that might be significant to other objects in a system or to external agents.”

For example, the creation of a purchase order is an example of a business event in a purchasing application

 Oracle Business Events =>Architecture

The Oracle Workflow Business Event System is an application service that leverages the Oracle Advanced Queuing (AQ) infrastructure to communicate business events between systems.

The Business Event System consists of the Event Manager and workflow process event activities

• Is available with both standalone and E-Business Suite Workflow
• Provides event driven processing
• Allows Application modules and external systems to raise events
• Facilitates Oracle Application modules and external system to subscribe to these events
• Subscriptions can be synchronous or asynchronous

o you know,

11i10 E-Business Suite is preconfigured with 915 Business Events

Each Business Event represents a ready to use Integration or extension point

915 Outbound Integration/extension points

915 Inbound Integration/extension points

Integration points centered around the major E-Business Suite flows like p2p, o2c etc

dgreybarrowComponent Architecture

Typically Business events Component can be best understood as:

Transactional Diagram of business Events can be best understood as:

Below is Architectural Diagram for Outbound Business Events , typical flow consist of

• Creates deferred subscription to the selected
• Deferred subscription transfers the event to the customer queue (WF_BPEL_Q)
• Unique consumer is created automatically

“A business event is an occurrence in an internet or intranet application or program that might be significant to other objects in a system or to external agents.”

For example, the creation of a purchase order is an example of a business event in a purchasing application

Event Manager for Oracle Applications

The Oracle Workflow Event Manager lets you register interesting business events that may occur in your applications, the systems among which events will be communicated, named communication agents within those systems, and subscriptions indicating that an event is significant to a particular system. The Event Manager also performs subscribtion processing when events occur.

 Subscriptions for Business Events

• Events that trigger custom code
• Events that send information to Workflow
• Events that send information to other queues or systems

 where you can Uses of Business Events

• System integration messaging hubs
• Distributed applications messaging
• Message-based system integration
• Business-event based workflow processes
• Non-invasive customization of packaged applications

 PLSQL vs Java Business Event System

Oracle Workflow provides Business Event System implementation within the database (PLSQL) and in the middle tier (Java).

The implementation is exactly the same in terms of the event subscription processing in both these layers but the only difference is how the Developer wants to leverage Business Event System's capabilities for event processing requirements.

With the availability of Business Event System implementation in PLSQL and Java, different subscription processing scenarios can be achieved.

 How to Proceed if Business events are required to use

• Design your Business Event/s
• Define your event

 Setting Up the Business Event System [Adopted workflow user documentation]

To set up the Business Event System and enable message propagation, perform the following steps:

1. If you want to communicate business events between the local system and external systems, create database links to those external systems.
2. If you want to use custom queues for propagating events, set up your queues.
3. Check the Business Event System setup parameters.
4. Schedule listeners for local inbound agents.
5. Schedule propagation for local outbound agents.
6. If you are using the version of Oracle Workflow embedded in Oracle Applications, synchronize event and subscription license statuses with product license statuses.
7. Ensure that the WF_CONTROL queue is periodically cleaned up to remove inactive subscribers.

---------------------------------------------------------------------------------------

Business Event

Business Event is an occurrence of a business activity which has some significance. For example, the activity of creating a purchase order (PO) is a business event, like wise approving PO, receiving goods against a PO, matching a PO receipt with invoice is a Business Event.

Subscription

Subscription is an activity to be performed on occurrence of a Business Event.
Eg:- If you would like to send an email notification to some set of users when a PO receipt is created then you can subscribe to PO Receipt related Business Event and trigger a workflow notification from the subscription to send email.

How is Business Event Raised?

Usually seeded Business Events are raise by workflows or Forms through a PL/SQL code.

Oracle not only provides an option to create custom subscriptions to seeded Business Event s but also provides a flexibility to create a complete custom Business Event.

Workflow Engine vs Business Event System

Oracle Workflow has two major execution engines.

• Workflow Engine
• Workflow Business Event System

Here is a simple comparison of what they process and their associated background components.

Workflow Engine	Workflow Business Event System
Executes workflow processes created using Windows based Workflow Builder client	Executes subscriptions to business events registered using Event Manager in Workflow Administrator Web Applications Responsibility
Entry point foreground APIs are WF_ENGINE.CreateProcess and WF_ENGINE.StartProcess	Entry point foreground API is WF_EVENT.Raise
Execution deferred to background by enqueuing message to AQ WF_DEFERRED_QUEUE_M	Execution deferred to background by enqueuing message to AQ WF_DEFERRED
Entry point background API is WF_ENGINE.Background	Entry point background API is WF_EVENT.Listen
AQ Payload is SYSTEM.WF_PAYLOAD_T	AQ Payload is WF_EVENT_T
Background processing is done by Concurrent Program - FNDWFBG (Workflow Background Engine)	Background processing is done by GSC Component - Workflow Deferred Agent Listener
Background Engine is submitted as recurring concurrent request from SRS form or Workflow Manager in OAM	Agent Listener is a service component managed through Workflow Manager in OAM

• When troubleshooting issues with Business Event System, users verify that the Workflow Background Engine is running.
• When troubleshooting deferred workflow processes, users verify that the Workflow Deferred Agent Listener is running.

Steps to Subscribe to a Business Event

In this article I will show you how to subscribe to PO Receipt standard business event (oracle.apps.po.rcv.rcvtxn). Our subscription would just insert the seeded business event details into a custom temporary table.

Navigate to “Workflow Administrator Web (New)” responsibility –> Administrator Workflow –> Business Events

Search for a business event oracle.apps.po.rcv.rcvtxn

Click on Subscription icon

and then click on Create Subscription button

In Create Subscription page enter the following details and save the page:
– System: < choose your system name from LOV >
– Phase: 101 (enter some number greater than 100)
– Status: Enabled
– Rule Data: Message
– Action Type: Custom
– On Error: Stop and Rollback
– PL/SQL Rule Function: xx_be_test_pkg.xx_insert (we will create this package and procedure in next step)
– Priority: Normal
– Owner Name: (enter your custom application short name)
– Owner Tag: (enter your custom application short name)

Execution Condition: PHASE

If you want to execute the business event subscription on sync with workflow activity then you need to select phase below 100 OR else enter phase more than 100 if you want to execute business event subscription after completion of workflow business activity i.e, asynchronously.

Package Specification

-- CREATE OR REPLACE PACKAGE xx_be_test_pkg AS FUNCTION xx_insert (p_subscription_guid IN RAW, p_event IN OUT wf_event_t) RETURN VARCHAR2; END xx_be_test_pkg; / --

Package Body

CREATE OR REPLACE PACKAGE BODY xx_be_test_pkg AS FUNCTION xx_insert (p_subscription_guid IN RAW, p_event IN OUT wf_event_t) RETURN VARCHAR2 IS -- l_param_list wf_parameter_list_t; l_param_name VARCHAR2 (240); l_param_value VARCHAR2 (2000); l_event_name VARCHAR2 (2000); l_event_key VARCHAR2 (2000); l_event_data VARCHAR2 (4000); -- BEGIN -- l_param_list := p_event.getparameterlist; l_event_name := p_event.geteventname (); l_event_key := p_event.geteventkey (); l_event_data := p_event.geteventdata ();   -- INSERT INTO xx_be_debug_log_tmp (text ) VALUES ('EVENT NAME: ' || l_event_name ); -- -- INSERT INTO xx_be_debug_log_tmp (text ) VALUES ('EVENT KEY: ' || l_event_key ); -- -- INSERT INTO xx_be_debug_log_tmp (text ) VALUES ('EVENT DATA: ' || l_event_data );   IF l_param_list IS NOT NULL THEN FOR i IN l_param_list.FIRST .. l_param_list.LAST LOOP -- l_param_name := l_param_list (i).getname; l_param_value := l_param_list (i).getvalue;   -- INSERT INTO xx_be_debug_log_tmp (text ) VALUES (l_param_name || ': ' || l_param_value );   COMMIT; -- END LOOP; END IF;   COMMIT; RETURN 'SUCCESS'; -- -- EXCEPTION WHEN OTHERS THEN -- --Provide context information that helps locate the source of an error. -- wf_core.CONTEXT (pkg_name => 'XX_BE_TEST_PKG', proc_name => 'XX_INSERT', arg1 => p_event.geteventname (), arg2 => p_event.geteventkey (), arg3 => p_subscription_guid ); -- --Retrieves error information from the error stack and sets it into the event message. -- wf_event.seterrorinfo (p_event => p_event, p_type => 'ERROR'); -- RETURN 'ERROR'; -- END xx_insert; END xx_be_test_pkg;

Compile the above package and Restart Workflow Agent Listener service as shown in the below screen shot

More about the package

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 with which we can access Event Key, Event Name, Event Data and Parameters. Every seeded business event has some parameters which we can access through p_event parameter.

The function must return one of the three status codes: SUCCESS or WARNING or ERROR.

Create PO Receipt Transaction to raise Business Event

Create a PO Receipt transaction so that the business event oracle.apps.po.rcv.rcvtxn will get raised the custom subscription we created will get executed.

After creating PO Receipt transaction wait for a minute and query for the custom table which we have mentioned in the package.

SELECT * FROM xx_be_debug_log_tmp;

Event Key

A string that uniquely identifies an instance of an event. Together, the event name, event key, and event data fully communicate what occurred in the event.

Event Data

A set of additional details describing an event. The event data can be structured as an XML document. Together, the event name, event key, and event data fully communicate what occurred in the event.

Event Message

A standard Workflow structure for communicating business events, defined by the datatype WF_EVENT_T. The event message contains the event data as well as several header properties, including the event name, event key, addressing attributes, and error information.

Event Activity

A business event modeled as an activity so that it can be included in a workflow process.

To know if the business event is fired or not query for WF_DEFERRED queue table if the subscription is using PL/SQL procedure or else use WF_JAVA_DEFERRED queue table if the subscription is using Java procedure.

SELECT substr(wfd.corrid,1,40) corrid, decode(wfd.state, 0, '0 = Ready', 1, '1 = Delayed', 2, '2 = Retained', 3, '3 = Exception', to_char(substr(wfd.state,1,12))) State, COUNT(*) COUNT FROM applsys.wf_deferred wfd GROUP BY wfd.corrid, wfd.state;

Status	Meaning
Ready	Activity is ready to be processed
Delayed	Activity will be processed later
Retained	Activity was already processed
Exception	Activity had an error

Note: Make sure Workflow Background Process is running in the background.

In this way we can use business events in many ways to solve business requirements.