Integration with Oracle E-Business Suite

Introduction

Integrated SOA Gateway (ISG) in Oracle EBusiness Suite 12.1 provides Service Invocation Framework (SIF) to natively consume and invoke web services. SIF uses Oracle Workflow Business Event System to provide necessary infrastructure to consume an abstract Web Service and dynamically invoke the Web Service without requiring any design-time code generation. In this blog post we will see a specific use case of how to invoke web services from an Oracle Workflow process that is designed using Oracle Workflow Builder and executed in the database by the Oracle Workflow Engine.

SIF setup

Please refer to 12.1 ISG Developer Guider topic "Defining Web Service Invocation Metadata" under chapter "Working With Oracle Workflow Business Event System to Invoke Web Services" for detailed information on creating Business Event System meta-data. A summary of the steps are given below.

1. Create an Invoker Business Event.
2. Create a Local Subscription of Action Type "Invoke Web Services" to the invoker event.
3. Create an Error subscription to the invoker event to handle any errors during invocation is also required.

Once the above Business Event System meta-data is created, raise the invoker Business Event to invoke the web service consumed within the Local event subscription. A Business Event can be raised either using a PLSQL API or a Java API. Hence, it can be assumed that SIF can be used to invoke web services from PLSQL or Java.

The PLSQL API is WF_EVENT.Raise and the Java API is oracle.apps.fnd.wf.bes.BusinessEvent.raise. SIF run-time code executes only on Java tier (OACORE or Concurrent Tier). Raising the invoker event using Java API that already runs on middle tier causes the web service to be invoked synchronously and the response available to the caller immediately. Whereas if the invoker event is raised in PLSQL, the web service is invoked asynchronously by Workflow Java Deferred Agent Listener in Concurrent Tier. To receive the web service response back in the database in asynchronous mode following set up is required.

1. Create a callback business event and set it as part of the "Invoke Web Services" Local subscription.
2. Specify a callback agent such as WF_JMS_IN to which the callback event can be enqueued. You can create and use any workflow agent to receive the response.
3. Create an External subscription to the callback event to handle the web service response from WF_JMS_IN.

After successful invocation of the web service, the Java Deferred Agent Listener sets the response to callback event's payload and enqueues to the callback agent. Running event listener on the callback agent executes the External subscription to perform the specified action. With above setup we are now ready to invoke a web service by raising the invoker business event. The invocation can be tested using business event test page.

Invoking from Workflow Process

Workflow processes include standard event activities such as Raise event and Receive event. Since Workflow processes execute within the database we will use the PLSQL message pattern discussed above to invoke the web service from workflow processes. Following steps are required to successfully invoke web service from workflow process using SIF.

Create Raise Event activity

Use Raise Event activity to raise the invoker event. A function activity can be used to create input message required for the web service and set to the invoker event payload.

Create a Receive Event activity

Use a Receive Event activity to receive the callback event in the workflow process. Callback event is raised after successful invocation of web service by Java Deferred Agent Listener.

Create an External Subscription to the callback event

Create an External subscription to the callback event with Workflow Type and Workflow Process set to the workflow process waiting to receive the web service response. The External subscription can also be used to simply execute a rule function to process the web service response.

Code Sample

Above use case is explained using a sample Workflow Process with required Business Event System meta-data. You may download the sample code for testing.

Files Uploaded

1. WFINVTSTE.wfx - Invoker Event and Callback (Receive) Event
2. WFINVTSTS.wfx - Local "Invoke Web Service" Subscription to Invoker Event, Error Subscription to Invoker Event, External Subscription to Callback Event
3. WFINVTST.wft - The Workflow process that raises the Invoker Event and Receives the Callback Event
4. WFINVTSTS.pls - PLSQL spec for function activities used in above Workflow Process
5. WFINVTSTB.pls - PLSQL body for function activities used in above Workflow Process

Instructions to use sample

1. Upload *.wfx files using Workflow Business Event System loader program oracle.apps.fnd.wf.WFXLoad
2. Upload *.wft file using Workflow Definitions Loader $FND_TOP/bin/WFLOAD
3. Compile *.pls files to APPS schema
4. Verify Workflow Java Deferred Agent Listener is up and running
5. Launch Workflow using LAUNCH.sql script. The workflow process sends a notification with the web service response to a specified recipient after successful invocation of web service.
6. Wait until Workflow Java Deferred Agent Listener completes execution of the "Invoke Web Service" subscription and enqueues response to WF_JMS_IN agent.
7. Configure an Agent Listener to run against WF_JMS_IN or another appropriate Callback Agent that you want to use to listen to callback events. An easy way to run listener is exececute PLSQL API WF_EVENT.Listen from sqlplus connected to APPS schema.

You may also launch the Workflow Process from Developer Studio and monitor the Workflow Process from Status Monitor functions available from Workflow Administrator Web Applications responsibility.

Oracle Workflow provides Business Event System implementation within the database and in the middle tier. 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, following subscription processing can be achieved.

1. Execute PLSQL rule function synchronously or asynchronously. Oracle Workflow provides a bunch of default rule functions in WF_RULE package for your use
2. Execute Java rule function synchronously or asynchronously. Oracle Workflow provides a default rule function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription to invoke web services.
3. Launch workflow process
4. Send event to an agent (AQ)

Workflow Business Events can be raised using one of two following ways.

1. PLSQL API WF_EVENT.Raise
2. Java method oracle.apps.fnd.wf.BusinessEvent.raise

As long as the call to these APIs does not throw an error, the event is raised successfully. There is a wrong notion among developers and administrators that all the events raised are enqueued to an agent (AQ) such as WF_DEFERRED or WF_JAVA_DEFERRED. No, it is not enqueued to an agent always, but it is driven based on how the subscription is defined. Now how are the event subscriptions dispatched and how to check the status of a subscription execution?

Subscriptions are either synchronous (phase < 100) or asynchronous (phase >= 100) with respect to the layer it is raised such as either PLSQL or Java and that layer's ability to dispatch the subscriptions. Following table gives an idea about how different subscriptions are dispatched.