Using Service Invocation Framework to Invoke REST Services

REST Service Invocation Framework Overview

Similar to the SOAP service invocation framework, the REST service invocation framework also leverages Oracle Workflow Java Business Event System to provide an infrastructure for REST service invocation natively from Oracle E-Business Suite.

With this framework, an developer can directly interact with a REST service through the service endpoint, provided while defining the REST service metadata. The metadata will then be stored as subscription parameters and used later during the actual service invocation at runtime.

This framework supports REST service invocation through the GET or POST HTTP method with XML or JSON payload. It also supports HTTP Basic authentication security, error and exception handling, and test invocation features. Furthermore, it provides advanced configuration option allowing you to extend the HTTP header request with Signature and Digest header options, to add callback configuration, and to include additional REST service invoker parameters if required as part of the metadata for the REST service to be invoked.

In summary, the REST service invocation framework provides the following functionality:

For detailed information about Oracle Workflow, see the Oracle Workflow User's Guide, Oracle Workflow Developer's Guide, and the Oracle Workflow Administrator's Guide.

This section describes the information on how to invoke REST services using the REST service invocation framework. It includes the following topics:

Note: All outbound service invocation messages from Oracle E-Business Suite through service invocation framework are monitored using Service Invocation Monitor. See: Monitoring and Managing Outbound Service Invocation Messages Using Service Invocation Monitor, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Understanding REST Service Message Patterns

The REST service invocation framework supports Synchronous Request - Response message pattern and One - Way (Request Only) message pattern. These message patterns are supported in the same way as they are used in the SOAP service invocation framework.

For information on how these patterns work, see Understanding SOAP Service Message Patterns.

Calling Back to Oracle E-Business Suite with REST Service Response

The REST service invocation framework uses the callback mechanism in Oracle Workflow to communicate the response message back to Oracle E-Business Suite through the Business Event System. This feature is implemented to support synchronous request - response service operation, if a REST service has an output or a response message.

When callback is required for your REST service invocation, you must define the following callback values:

This callback mechanism takes the REST service invoker event's event key to enqueue the callback event to the callback agent you specified here for the response. If a workflow process invokes a REST service using a "Raise" event activity and waits for a REST service response using a "Receive" event activity, then the REST invoker event key should be the same as the invoker and/or waiting workflow process's item key so that when callback is performed, the waiting workflow process is correctly identified by the WF_ENGINE.EVENT API.

With callback event and agent, the REST service invocation can be integrated back with a waiting workflow process or any other module within Oracle E-Business Suite.

Supporting REST Service Security

When creating the event subscription for the REST service to be invoked, the developer needs to specify the user name and password information for the HTTP Basic Authentication REST service security so that the user credentials can be passed in the HTTP Header to authenticate the user before invoking the REST service.

Additionally, this REST service invocation framework supports the Digest HTTP Header and Signature HTTP Header. That is, you can optionally add another layer of security to further define the invocation metadata by extending the HTTP header request with Signature and Digest header options during the event subscription creation.

Note that the REST service security is handled based on the customization level. This is similar to the existing behavior of the SOAP service invocation framework on handling the user name and password.

For more information about the REST service security, see Supporting REST Service Security and Configuring Security with Customization Level, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Understanding REST Service Invocation Metadata

To be able to successfully invoke a REST service through the invocation framework, the developer needs to supply invocation metadata that will be used at runtime when the invocation actually happens. These metadata are provided in the event subscription creation for the triggering event to be occurred. This section explains the concepts and definitions of the invocation metadata in details.

When creating an event subscription in the Create Event Subscription page, the developer needs to first select a triggering event, enter related execution condition, and select "Invoke REST Service" as the action type before proceeding to the following pages to enter REST service invocation details:

Note: Oracle E-Business Suite Adapter with Oracle Integration has leveraged the REST service invocation framework for Business Event capabilities in integrations. For the event subscriptions created automatically from Oracle E-Business Suite Adapter with Oracle Integration, in the Create Event Subscription page you can only update the values of the Status and Phase fields. All other fields in the page are displayed as read-only fields and are not updatable.

For more information about the Oracle E-Business Suite Adapter with Oracle Integration, see Using the Oracle E-Business Suite Adapter with Oracle Integration, available in the Oracle Cloud Library on the Oracle Help Center.

REST Service Details

After specifying general subscription information in the Create Event Subscription page, you are proceed to the Create Event Subscription - Invoke REST Service page where you must provide basic REST service information for the invocation.

Create Event Subscription - Invoke REST Service Page

the picture is described in the document text

Advanced Configuration

The REST service invocation framework allows you to optionally add more configuration parameters for the REST service to be invoked in the Create Event Subscription - Invoke REST Service Advanced Configuration page. These include parameters for HTTP headers, callback configuration, and the REST service invoker.

Create Event Subscription - Invoke REST Service Advanced Configuration Page

the picture is described in the document text

Managing REST Service Invocation Errors

The REST service invocation framework manages the invocation errors through the same error and exception handling mechanism used in the SOAP service invocation framework. That is, you must create an Error subscription with the following values to enable the error processing in the Business Event System:

If there is an error or exception, HTTP Return Status Code should be captured and available to the consuming program. The SYSADMIN user will receive an notification about the REST service definition and error details. For more information on error handling during the service invocation, see Managing REST Service Invocation Errors, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Defining REST Service Invocation Metadata

Similar to defining SOAP service invocation metadata, you need to log in to Oracle Workflow Business Event System to create an Invoker event and the Invoker event subscription for the REST service to be invoked at runtime. If it is required to have a response message, then you need to create a receive event and the receive event subscription.

Specifically, this section includes the following topics:

  1. Creating a REST Service Invoker Business Event

    Before creating an event subscription, you must first create an event. This Invoker event serves as a request message (or a REST service input message) for a service that needs to be created.

  2. Creating a Local Subscription to Invoke a REST Service

    This event subscription indicates that when a triggering event occurs, the action item of this subscription is to invoke a REST service that will be defined as part of this subscription.

  3. Creating an Error Subscription to Enable Error Processing for the REST Service

    This error subscription enables error processing in the Business Event System that is used to communicate with the SYSADMIN user of an error condition in subscription processing.

  4. Creating a Receive Event for REST Response (Optional)

    This step is required only if a REST service has an output or a response message to communicate or call back to Oracle E-Business Suite.

    If a REST service does not require a response, neither a receive event nor a receive event subscription should be created.

  5. Creating a Receive Event Subscription for REST Response (Optional)

    Once a receive event is in place, you must create an External subscription to the receive event to pass the REST service response message.

Step 1: Creating a REST Service Invoker Business Event

The first step of defining REST service invocation metadata is to create an invoker event that can be served as a request message (or a REST service input message) in a message pattern to send inquiries to a service.

Note: In this release, the service invocation framework supports the following types of service invocation:

For more information about business events, see Events, Oracle Workflow Developer's Guide.

To create a REST service invoker event:

  1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web responsibility. Select the Business Events link, and choose Events in the horizontal navigation if the Events page is not already displayed.

  2. In the Events page, click Create Event to open the Create Event page.

  3. Enter the following information in the Create Event page:

    • Name: Enter an event name, such as oracle.apps.xxx.user.restservice.invoke

    • Display Name: Enter an event display name, such as oracle.apps.xxx.user.RESTservice.invoke

    • Description: Enter a description for the event

    • Status: Enabled

    • Generate Function: Specify a generate function for the PL/SQL based event if the application where the event occurs will not provide the event data

    • Java Generate Function: Specify a generate function for the Java based event if the application where the event occurs will not provide the event data

    • Owner Name: Specify the program or application name that owns the event (such as Oracle Workflow)

    • Owner Tag: Specify the program or application ID that owns the event (such as 'FND')

  4. Click Apply to save your work.

Step 2: Creating a Local Subscription to Invoke the REST Service

Once an invoker event is created, you need to create a local subscription to the invoker event with Invoke REST Service action type. When a triggering event occurs, the Business Event System processes the subscription through the seeded Java function and invokes the REST service as indicated by the action type.

To create a local event subscription with 'Invoke REST Service' action type:

  1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web responsibility. Select the Business Events link, and choose Subscriptions in the horizontal navigation.

  2. In the Event Subscriptions page, click Create Subscription to open the Create Event Subscription page.

  3. Enter the following information in the Create Event Subscription page:

    • Subscriber: Select the local system

    • Source Type: Local

    • Event Filter: Select the event name that you just created, such as oracle.apps.xxx.user.RESTservice.invoke

    • Phase: 90

      If the event is raised from Java, the phase number determines whether an event will be invoked right away or enqueued to the WF_JAVA_DEFFERED queue.

      Note: If the invoker event is raised from PL/SQL, it is always deferred to the WF_JAVA_DEFERRED queue regardless of the phase because the subscription has a Java rule function that cannot be processed in the database.

      • If the phase is greater than or equal to 100, then the event is enqueued to the WF_JAVA_DEFFERED queue and will be dispatched later.

      • If the phase is less than 100, then the event is dispatched immediately to the Java Business Event System soon after a triggering event occurs.

    • Status: Enabled

    • Rule Data: Message

    • Action Type: Invoke REST Service

    • On Error: Stop and Rollback

  4. Click Next. This opens the Create Event Subscription - Invoke REST Service page.

    1. Enter the following REST service metadata information:

      • Resource Base – Enter the base URI of the resource. For example, http://<host>:<port>/webservices/rest/user

        Note that user is the service alias of a deployed PL/SQL REST service called "User" (FND_USER_PKG). This service contains a service operation called "Test User Name" (testusername).

      • Resource Path – Enter the relative URI path of the resource. For example, /testusername/

      • Service Endpoint – The value of this field is populated automatically based on the resource base and resource path you entered earlier, such as http://<host>:<port>/webservices/rest/user/testusername/.

      • HTTP Method – Select either POST or GET from the drop-down list. By default, POST is selected.

      • Content Type – Select either XML or JSON from the drop-down list. By default, XML is selected.

      • Accept – Select either XML or JSON from the drop-down list. By default, XML is selected.

    2. In the Query Parameters region, enter a desired parameter name and its value. Click '+' if required to add more rows.

    3. In the REST Service Security region, enter information in the Username and Password fields if appropriate.

    4. In the REST Service Invoker region, the default Java Rule Function name oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription is automatically populated.

      Important: If you have extended the functionality of the seeded rule function, manually enter your custom function name here.

    5. In the Documentation region, enter an application name or a program name that owns the subscription (such as 'Oracle Workflow') in the Owner Name field. Enter the program ID (such as 'FND') in the Owner Tag field.

    6. If this is all the information required for your REST service invocation, click Apply to save your work.

    7. If you want to add more configuration and callback information for your REST service invocation, click Advanced Configuration to display the Create Event Subscription - Invoke REST Service Advanced Configuration page.

    8. In the Create Event Subscription - Invoke REST Service Advanced Configuration page, enter the following information in the HTTP Headers region:

      • Digest Algorithm – Select either "SHA-512" or "SHA-256" from the drop-down list.

      • Signing Algorithm – Select either "rsa-sha512", or "rsa-sha256" from the drop-down list.

        Additionally, enter appropriate values for the following fields corresponding to the Signing Algorithm value if it's selected:

        • PKCS #12 Keystore – If the Signing Algorithm value is selected, click Choose File to browse and upload the keystore file in .p12 or .pfx format.

        • Keystore Password – Enter the keystore password twice.

        • Certificate Alias – If the Signing Algorithm value is selected, enter the alias associated with the digital certificate used for signing the headers.

        • KeyID – Provide the KeyID parameter for the Signature header.

        • Headers to be Signed – Provide HTTP Headers that need to be signed for the Signature header. The default value is "content-type accept".

        • HTTP Headers – You can provide a list of HTTP Header name and its value to be added to an HTTP request.

    9. In the Callback Configuration region, enter the following fields:

      • Callback Agent - Select a desired inbound agent from the drop-down list.

      • Callback Event - Select a desired event from the drop-down list.

    10. In the REST Service Invoker Parameters region, enter desired parameter names and their associated values in the table.

    11. Click Apply to save your work.

For more information, see Defining Event Subscriptions, Oracle Workflow Developer's Guide.

Step 3: Creating an Error Subscription to Enable Error Processing for the REST Service

To create an error subscription, you must subscribe to the REST invoker event with the 'Launch Workflow' action type.

When a triggering event occurs, this subscription enables error processing in the Business Event System and communicates with the SYSADMIN user by sending a workflow notification with the REST service definition, event details, and error details.

Similar to the error processing used in the SOAP service invocation framework, this notification allows the SYSADMIN user to quickly identify and respond to the error. Additionally, the SYSADMIN user can invoke the REST service again once the underlying issue is resolved, abort the errored event if needed, or reassign an errored notification to another user if appropriate.

To create an error subscription with 'Launch Workflow' action type:

  1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web responsibility. Select the Business Events link, and choose Subscriptions in the horizontal navigation.

  2. In the Event Subscriptions page, click Create Subscription to open the Create Event Subscription page.

  3. Enter the following information in the Create Event Subscription page:

    • Subscriber: Select the local system

    • Source Type: Error

    • Event Filter: Select the event name that you just created, such as oracle.apps.xxx.user.RESTservice.invoke

    • Phase: This can be any phase number.

    • Status: Enabled

      Note: While updating an event and an event subscription, for seeded events with a customization level of Limit, you can only update the status. For seeded product-specific events with a customization level of Core, you cannot update any properties. You can only view the subscription definition.

      For information on how to use customization level, see Supporting REST Service Security.

    • Rule Data: Key

    • Action Type: Launch Workflow

    • On Error: Stop and Rollback

  4. Click Next to open the Create Event Subscription - Launch Workflow page.

  5. Enter the following information in the Action region:

    • Workflow Type: WFERROR

    • Workflow Process: DEFAULT_EVENT_ERROR2

    • Priority: Normal

  6. In the Documentation region, enter an application or a program name that owns the event subscription (such as Oracle Workflow) in the Owner Name field and application or program ID (such as 'FND') in the Owner Tag field.

  7. Click Apply.

Step 4: Creating a Receive Event for REST Response (Optional)

Similar to the SOAP service invocation framework, if a REST service has an output or a response message to communicate or call back to Oracle E-Business Suite, and the Invoker event is raised from Java code with the subscription phase greater than or equal to 100 or if the event is raised from PL/SQL, then you should create a Receive event for callback to complete the invocation process. Additionally, create an external subscription to the Receive event to pass the REST service response.

Note: If it is raised from Java with subscription phase less than 100, then the REST service is invoked immediately and response is available to the calling program using BusinessEvent.getResponseData() method after calling BusinessEvent.raise(). In this case, the response may not have to be communicated back to Oracle E-Business Suite using a callback event. Hence, you may not need to create a receive event.

If a REST service does not require a response, then there is no need to create a receive event.

To create a receive event for a REST service:

  1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web responsibility. Select the Business Events link, and choose Events in the horizontal navigation.

  2. In the Events page, click Create Event to open another Create Event page.

  3. Enter the following information in the Create Event page:

    • Name: Enter an event name, such as oracle.apps.xxx.user.RESTservice.receive

    • Display Name: Enter an event display name, such as oracle.apps.xxx.user.RESTservice.receive

    • Description: Enter a description for the event

    • Status: Enabled

    • Owner Name: Enter an application or program name that owns the event (such as 'Oracle Workflow')

    • Owner Tag: Enter the application or program ID that owns the event (such as 'FND')

  4. Click Apply to create a receive event.

Step 5: Creating a Receive Event Subscription for REST Response (Optional)

If a Receive event is created, you must create an external event subscription to pass the REST service response that is enqueued to the inbound workflow agent you selected for the callback configuration while defining the REST service metadata.

The subscription to the Receive event does not have to be with the "Launch Workflow" action type. It can be created with any action type if appropriate.

To create a receive event subscription for a REST service:

  1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility. Select the Business Events link, and choose Subscriptions in the horizontal navigation.

  2. In the Event Subscriptions page, click Create Subscription to open the Create Event Subscription page.

  3. Enter the following information in the Create Event Subscription page:

    • Subscriber: Select the local system

    • Source Type: External

    • Event Filter: Select the receive event name that you just created, such as oracle.apps.xxx.user.RESTservice.receive

    • Phase: any phase number

    • Status: Enabled

    • Rule Data: Key

    • Action Type: any action type

    • On Error: Stop and Rollback

  4. Click Next to open the Create Event Subscription - Launch Workflow page.

    Note that the type of the Create Event Subscription page to be shown depends on the value selected in the Action Type field. If "Launch Workflow" is selected, you will see the Create Event Subscription - Launch Workflow page. If any other action type is selected, then a different type of the create event subscription page is displayed. By entering an appropriate action type through the subscription page, you can launch a workflow process or invoke a custom rule function for the event defined as part of this subscription.

  5. Enter the following information in the Action region:

    • Workflow Type: Enter a workflow type that is waiting for the response

    • Workflow Process: Enter a workflow process that is waiting for the response

    • Priority: Normal

  6. In the Documentation region, enter an application or a program name in the Owner Name field (such as 'Oracle Workflow'). Enter an application or a program ID in the Owner Tag field (such as 'FND').

  7. Click Apply.

Invoking REST Services

REST service invocation from Oracle E-Business Suite can be from a PL/SQL or Java layer:

Service Invocation from PL/SQL

  1. An application raises a business event using PL/SQL API WF_EVENT.Raise.

    The event data can be passed to the Event Manger within the call to the WF_EVENT.Raise API, or the Event Manger can obtain the event data or message payload by calling the Generate Function for the event if the data or payload is required for a subscription.

    Note: See the Oracle Workflow API Reference for information about WF_EVENT.Raise API.

  2. Oracle Workflow Business Event System (BES) identifies that the event has a subscription with Java Rule Function oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription.

  3. The Business Event System enqueues the event message to the WF_JAVA_DEFERRED queue. The Java Deferred Agent Listener then dequeues and processes the subscription whose Java rule function invokes the REST service.

  4. If callback event and agent parameters are mentioned, the REST service response is communicated back to Oracle E-Business Suite using the callback information. The Java Deferred Agent Listener process that runs on the Concurrent Manager (CM) tier invokes the REST service.

Service Invocation from Java

  1. A Java application raises a business event using Java method oracle.apps.fnd.wf.bes.BusinessEvent.raise either from an OA Framework page controller/AMImpl or Java code running on the Concurrent Manager tier.

  2. Since the event is raised from Java where the subscription's seeded Java Rule Function oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription is accessible, whether the rule function is processed inline or deferred is determined by the phase of the subscription.

    • If the invoker subscription is created with the Phase value greater than or equal to 100, the event is enqueued to the WF_JAVA_DEFERRED queue.

    • If the invoker subscription is created with the Phase value less than 100, the event is dispatched inline.

      If the event is raised from an OA Framework page, the dispatch logic runs within OACORE WebLogic Server.

    Note: If the REST service invoker event is raised from Java on the application tier, and the invoker subscription is synchronous with the subscription phase value less than 100, then the REST service is invoked as soon as the event is raised. If the invocation is successful, the response can be read by the calling application and is available immediately by using method BusinessEvent.getResponseData().

    oracle.apps.fnd.wf.bes.BusinessEvent.raise throws oracle.apps.fnd.wf.bes.BusinessEventException if there are any issues while invoking a REST service inline. BusinessEventException object internally stores the underlying root cause exception within a linkedException object. In order to see the complete exception details, print the exception stack trace from BusinessEventException.getLinkedException();.

    If the event is raised from Java with the subscription phase value greater than or equal to 100 or if the event is raised from PL/SQL, the event message will be enqueued to the WF_JAVA_DEFERRED queue. If the REST service has an output or a response message, a callback event with callback agent is required to receive the output message into Oracle E-Business Suite.

Testing REST Service Invocation

The Oracle Workflow Test Business Event page used for testing SOAP service invocation is also used for testing REST service invocation by raising a test event from either a Java or PL/SQL layer and by processing synchronous or asynchronous subscriptions to that event. You can easily validate whether a REST service can be successfully invoked from the concurrent manager tier and OACORE WebLogic Server.

Use the Test Business Event page to test an event by raising it from a PL/SQL API or Java.

Testing REST Service Invocations

To access the Test Business Event page, log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web responsibility, and select Business Events from the navigation menu. After a search to locate the event that you want to raise for testing the REST service invocation, click the Test icon. This displays the Test Business Event page where you can raise the event with a unique event key.

Enter event parameters for the invoker event subscription and a valid XML message that complies with input message schema. The Test Business Event page will also display the XML/JSON response message if appropriate.

To test an event invocation:

  1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web responsibility and select Business Events.

  2. Search on a business event that you want to run the test, such as oracle.apps.xxx.user.RESTservice.invoke and click Go.

  3. Select the business event that you want to raise from the result table and click the Test icon to open the Test Business Event page.

  4. Enter a unique event key in the Event Key field and leave the Sand Date field blank.

  5. Enter appropriate parameters in the Enter Parameters region.

  6. In the Event Data region, enter the following information:

    • Upload Option: Write XML/JSON

    • XML/JSON Content: Enter appropriate XML or JSON information as an input message. For example, you can enter the following content in JSON format:

      {
  "TESTUSERNAME_Input": {
    "RESTHeader": {
      "Responsibility": "SYSTEM_ADMINISTRATOR",
      "RespApplication": "SYSADMIN",
      "SecurityGroup": "STANDARD",
      "NLSLanguage": "AMERICAN",
      "Org_Id": "202"
    },
    "InputParameters": {
      "X_USER_NAME": "operations"
    }
  }
}

  7. Click Raise in Java to raise an event from the OACORE WebLogic Server.

    If the REST service is successfully invoked, a confirmation message appears on top of the Test Business Event page indicating that the event (oracle.apps.xxx.user.RESTservice.invoke) has been successfully raised.

    This test page reloads and displays the XML/JSON Response region right after the XML/JSON Content field.

  8. Click Raise in PLSQL to raise an event from the concurrent manager tier.

  9. If errors occur, the Event Error Details region appears letting you view the error details.

Viewing Error Details in the Test Business Event Page

If any errors occur while testing the service invocation, an error message appears indicating that errors occurred while dispatching the event and detailed information is shown in the Event Error Details region.

The Event Error Details region lets you quickly view error information through the same page for easier debugging.

Optionally, to see detailed log messages that capture each occurrence in sequential order for service invocation, before testing the invocation, you can enable the diagnostics and logging feature to directly display on-screen logs in the test page. For instructions about how to turn on this logging feature, see Troubleshooting SOAP Service Invocation Failure on OACORE WebLogic Server.

For more information about testing business events, see To Raise a Test Event, Oracle Workflow Developer's Guide.

An Example of Invoking a REST Service from a Java API

Invocation Scenario Using the REST Service Invocation Framework

Take a PL/SQL API called "User" (FND_USER_PKG) that contains a service operation "Test User Name" (testusername) as an example to explain a REST service invocation through the REST service invocation framework.

In this example, this "User" API is deployed as a REST service with alias "user". We will invoke the deployed testusername service operation from a Java class using the REST service invocation framework. The invoker business event will be raised from this Java class. Based on the FND_USER_PKG.TESTUSERNAME REST service metadata defined in the invoker event subscription, it will be invoked. The corresponding response message is also received at the same session of the invocation.

For information on deploying a REST service, see Deploying REST Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Steps to Invoke REST Service

Based on the invocation scenario, the invocation through the REST service invocation framework includes the following steps:

  1. Create an invoker business event to invoke a REST service.

    See: Creating an Invoker Business Event.

  2. Create an invoker business event subscription to invoke a REST service.

    See: Creating an Invoker Business Event Subscription.

  3. Create a Java class to raise the invoker business event.

    See: Creating a Java Class to Raise the Invoker Business Event.

  4. Compile and run the Java class to obtain the response.

    See: Compiling and Running the Java Class.

Creating an Invoker Business Event

To invoke a deployed REST service FND_USER_PKG using the REST service invocation framework, the first step is to create an invoker event. This invoker event serves as a request message for the FND_USER_PKG REST service to be created during the event subscription.

For detailed step-by-step instructions on creating an invoker event, see Creating a REST Service Invoker Business Event.

Creating an Invoker Business Event Subscription

This event subscription indicates that when a triggering event from a Java class occurs, the action item of this subscription is to invoke the deployed FND_USER_PKG REST service that is defined in this step as part of the subscription.

Perform the following steps to create an invoker event subscription:

  1. Enter event subscription information with the following key values in the Create Event Subscription page for this example:

    • Action Type: Invoke REST Service

    • Phase: 10

  2. In the Create Event Subscription - Invoke REST Service page, enter the following service metadata information in the REST Service Details region:

    • Resource Base – Enter the base URI of the resource, such as http://<host>:<port>/webservices/rest/user in this example.

      Note that user is the service alias of the deployed FND_USER_PKG REST service.

    • Resource Path – Enter the relative URI path of the resource. For example, /testusername/

      Note that testusername is the service operation contained in the deployed FND_USER_PKG REST service.

    • Service Endpoint – The value of this field is populated automatically based on the resource base and resource path you entered earlier, such as http://<host>:<port>/webservices/rest/user/testusername/.

    • HTTP Method – Leave the default POST unchanged.

    • Content Type – Leave the default XML unchanged.

    • Accept – Leave the XML unchanged.

  3. Leave the Query Parameters region blank, and enter security information in the REST Service Security region.

  4. In the Rest Service Invoker region, leave the default Java Rule Function value unchanged, and enter appropriate values in the Documentation region.

For more information on creating an invoker event subscription, see Creating a Local Subscription to Invoke a REST Service.

Creating a Java Class to Raise the Invoker Business Event

The following sample Java code raises a business event that invokes a REST service and reads the response in the same session:

package oracle.apps.fnd.wf.bes;

import java.sql.Connection;
import oracle.apps.fnd.common.AppsLog;
import oracle.apps.fnd.common.Log;
import oracle.apps.fnd.wf.bes.InvokerConstants;
import oracle.apps.fnd.wf.common.WorkflowContext;

public class InvokeRESTService { 
    static Log mLog;
    static WorkflowContext mCtx;

    public InvokeRESTService() {  } 

    public static Connection getConnection(String dbcFile) {  
        Connection conn = null;
        System.setProperty("dbcfile", dbcFile);
        WorkflowContext mCtx = new WorkflowContext();
        mLog = mCtx.getLog();
        mLog.setLevel(Log.STATEMENT);
        ((AppsLog)mLog).reInitialize();
        mLog.setModule("%");

        return mCtx.getJDBCConnection();
    } 

    public static void main(String[] args)  {  
        BusinessEvent event;
        Connection conn;
        conn = getConnection(args[0]);

        try {    
            // Proxy host and port, if required    
            //System.setProperty("http.proxyHost", args[1]);
            //System.setProperty("http.proxyPort", args[2]);

            //Replace business event and event key
            event = new BusinessEvent (<business event>,<event key>);

            // Input XML or JSON message for REST Web Service    
            String input = null;
            input ="{  \"TESTUSERNAME_Input\": {    \"RESTHeader\": {      \"Responsibility\": \"SYSTEM_ADMINISTRATOR\",      \"RespApplication\": \"SYSADMIN\",      \"SecurityGroup\": \"STANDARD\",      \"NLSLanguage\": \"AMERICAN\",      \"Org_Id\": \"202\"    },    \"InputParameters\": {      \"X_USER_NAME\": \"operations\"    }  }}";

            event.setData(input);

            event.raise(conn);
            conn.commit();

            Object resp = event.getResponseData();
            if (resp != null) {
                String respStr = resp.toString();
                // Process REST web service response here
                // Response could be XML or JSON message    
               
            }     
            else {     
                // Either REST web service invocation failed and no exception was thrown               
                // or the web service is one-way or asynchronous and did not return     
                // a valid response         
                System.out.println("No response received");
            }  
        } 
        catch (BusinessEventException e) {   
            // Use appropriate logging mechanism as per your coding standards   
            // instead of System.out.println      
            System.out.println("Exception occured " + e.getLinkedException().getMessage());
            // Print the complete exception stack to log file for troubleshooting  
            // Most importantly, if an exception occurred, do not proceed to process the  
            // response
            e.getLinkedException().printStackTrace();
        } catch (Exception e) {   
            // Use appropriate logging mechanism as per your coding standards   
            // instead of System.out.println   
            System.out.println("Exception occured " + e.getMessage());
            // Print the complete exception stack to log file for troubleshooting  
            // Most importantly, if an exception occurred, do not proceed to process the  
            // response
            e.printStackTrace();
        }
    }
}

Important: When invoking a REST service using the REST service invocation framework, the invoker business event is raised using the oracle.apps.fnd.wf.bes.BusinessEvent.raise(Connection) method that requires a JDBC connection to be passed.

To get the JDBC connection, always use the current application context object available for your scenario. For example, if a REST service invocation is from an OA Framework page, then get the JDBC connection from the OAPageContext object. If it is from a concurrent program, get the JDBC connection from the CpContext object. You should not create a WorkflowContext in these situations. Otherwise, a duplicate application context will be unnecessarily created. A new WorkflowContext should be created only if JDBC connection is not already available through other means.

Compiling and Running the Java Class

In this step, you need to compile and run the process to obtain the response of the REST service invocation using standard javac and java commands from the command line.

Troubleshooting REST Service Invocation Failure

Similar to the SOAP service invocations, REST services can also be invoked through one of the following tiers:

As the REST service to be invoked resides outside the firewall and the running host does not have direct access to the REST service endpoint to send the request, to successfully invoke the REST service from Oracle E-Business Suite, you need to set up and configure the proxy parameters for each tier that the service invocation may occur. See: Setup Tasks, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

At runtime, if a REST service invocation fails, an exception is thrown and the invoker event is enqueued to the WF_ERROR queue. Since the service can be invoked from any of the three tiers, the troubleshooting is based on the three tiers where the REST service invocation may occur. For troubleshooting details, refer to the troubleshooting information described earlier for the SOAP service invocation framework at Troubleshooting SOAP Service Invocation Failure.

Note that when troubleshooting the invocation failure from OACORE WebLogic Server, you can review the on-screen log message if the on-screen logging feature is enabled.

For example, the following log indicates that the service invocation is completed with callback response message enqueued to the WF_WS_JMS_IN inbound queue if the callback event is set to "receive event" and the callback agent value is set to 'WF_WS_JMS_IN'.

WebServiceInvokerSubscription Logs

the picture is described in the document text

For information on enabling the on-screen logging feature and viewing the on-screen logs, see: Troubleshooting SOAP Service Invocation Failure on OACORE WebLogic Server.

Extending Seeded Java Rule Function for REST Services

The REST service invocation framework allows you to extend the seeded rule function oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription for REST services using Java coding standards for more specialized processing.

Specifically, you can extend the seeded rule function to override the following methods:

For detailed information about these methods, see Oracle Workflow API Reference.

Use the following steps to extend the seeded rule function:

  1. Extend the methods using oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription.

  2. Upload the compiled custom class file at $JAVA_TOP/oracle/apps/fnd/wf/bes/.

  3. Bounce the oacore and oafm servers.

  4. Use the custom rule function oracle.apps.fnd.wf.bes.xxxx while creating the subscription.

    Note that xxxx is the name of extended custom class. For example, oracle.apps.fnd.wf.bes.CustomWebServiceInvoker.

preInvokeService

This method is used for preprocessing before invoking a REST service.

     protected String preInvokeService(Subscription eo, 
                                       BusinessEvent event,
                                       WorkflowContext context) 
throws BusinessEventException;

The service input message or request message is available by calling event.getData(). This is the business event payload passed when raising the invoker event or generated by the business event Generate function.

postInvokeService

This method performs the post-processing after invoking a REST service.

     protected void postInvokeService(Subscription eo, 
                                      BusinessEvent event,
                                      WorkflowContext context, 
                                      String requestData, 
                                      String responseData) 
throws BusinessEventException;

If the operation is synchronous request - response, the response is available in parameter responseData.

This method performs an additional processing on the response and updates application state if required. The default implementation through the REST service seeded Java rule function performs the callback feature to the Workflow Business Event System based on the values provided for the Callback Event and Callback Agent.