An Example of Using the Oracle E-Business Suite Adapter as an Invoke (Target) in an Integration

Overview

To better understand how to use Oracle E-Business Suite services in Oracle Integration Cloud Service, this chapter describes an integration example through the use of Oracle E-Business Suite Adapter as an invoke (target) connection.

Sample Business Scenario

Take a PL/SQL API called Sales Order Services (OE_INBOUND_INT) as an example to explain the integration between the Oracle E-Business Suite Adapter and a trigger (source) connection in Oracle Integration Cloud Service.

In this example, the Oracle E-Business Suite Adapter is used as an invoke (target) connection for service invocation, and the REST Adapter is used as a trigger (source) connection to provide a REST request. When the Oracle E-Business Suite Adapter receives the request message with input payload for order creation from the trigger (source) connection, the OE_INBOUND_INT REST service in Oracle E-Business Suite is invoked to create the order.

Note: Any application adapters can be used as trigger (source) connections to create integrations for your business needs. In this example, the REST Adapter is used as a trigger (source) connection.

Once the integration is successfully executed at runtime, a sales order will be created in Oracle E-Business Suite.

Using Oracle E-Business Suite REST Services for Integrations in Oracle Integration Cloud Service

Based on the integration scenario, the following tasks are included in this section:

  1. Establishing the Connections for Oracle E-Business Suite and REST Services

  2. Creating an Integration

  3. Adding the Oracle E-Business Suite Adapter as an Invoke (Target) Connection

  4. Adding the REST Adapter as a Trigger (Source) Connection

  5. Creating Mappings

  6. Assigning Business Identifier for Tracking

  7. Activating and Testing the Integration

Establishing the Connections for Oracle E-Business Suite and REST Services

Before creating an integration, you need to create the following two connections:

Creating an Oracle E-Businss Suite Connection with Oracle E-Business Suite Adapter

Perform the following steps to establish the connection for Oracle E-Businss Suite in Oracle Integration Cloud Service:

  1. Log in to Oracle Integration Cloud Service.

    In the Integration Cloud Service toolbar, click Connections.

  2. Click Create New Connection.

    In the Create Connection - Select Adapter dialog appears. Scroll down and select "Oracle E-Business Suite" from the dialog. You can optionally use the search feature to enter a full or partial name to locate the Oracle E-Business Suite Adapter from the dialog. Click the Select button for "Oracle E-Business Suite" to create a connection through the Oracle E-Business Suite Adapter.

  3. In the New Connection - Information dialog, enter the following information for your connection:

    • Connection Name: Enter "EBS1225".

    • Identifier: Accept the default populated identifier, such as "EBS1225".

    • Connection Role: Select "Trigger and Invoke" role for this connection.

    • Description: Enter "Use the Oracle E-Business Suite Adapter connection in an integration" as the description.

    Creating the Oracle E-Business Suite Connection

    the picture is described in the document text

    Click Create to create the connection.

  4. Click Configure Connectivity to open the Connection Properties dialog where you enter a URL (http://<ebs host name>:<port>) to connect to an Oracle E-Busiess Suite instance.

    Click OK to save your work.

  5. Click Configure Security to open the Credentials dialog.

    Ensure that the Basic Authentication is selected as the security policy.

    Enter operations as the username and its associated password in the Credentials dialog to access the Oracle E-Business Suite instance you specified earlier in the Connection Properties dialog.

    Click OK to save your work.

  6. Click Configure Agents to display the Select an Agent group dialog. A list of available agent groups is automatically populated for your selection.

    Select a desired agent group, such as "EBS", and click Use to enable the selection.

    Selecting an Agent Group

    the picture is described in the document text

  7. After you specify the connection information for "EBS1225", the connection details page is displayed.

  8. Click Test to test the connection you just specified for Oracle E-Business Suite.

  9. Click Save to save your connection.

    Click Exit Connection.

The Oracle E-Business Suite connection "EBS1225" now appears in the Connections page.

Creating an Connection for REST Services

Perform the following steps to create an connection for REST APIs:

  1. In Oracle Integration Cloud Service, click Create New Connection.

    The Create Connection - Select Adapter dialog appears.

  2. Scroll down and select "REST" from the dialog. You can optionally use the search feature to enter a full or partial name to locate the REST Adapter from the dialog.

    Click the Select button for "REST" to create an connection through the REST Adapter.

  3. The New Connection - Information dialog appears.

    Enter "GenericREST" as the Connection Name. The identifier value, GENERICREST, is automatically populated.

    Select "Trigger and Invoke" as the Connection Role. Enter a meaningful description for this connection, such as "The sample source REST endpoint".

  4. Click Create to create the connection.

  5. Click Configure Connectivity to open the Connection Properties dialog where you select "REST API Base URL" as the Connection Type and enter a connection URL (http://<ebs host name>:<port>/webservices/rest/orderMgmt) to connect to an instance for REST services.

    Entering the Connection Properties through the REST Adapter

    the picture is described in the document text

    Click OK to save your work.

  6. Click Configure Security to open the Credentials dialog.

    Enter operations as the username and its associated password in the Credentials dialog to access the instance for REST services you specified earlier in the Connection Properties dialog.

    Click OK to save your work.

  7. Click Test to test the connection you just specified for REST services.

  8. Click Save to save your connection.

    Click Exit Connection.

The "GenericREST" connection for REST services appears in the Connections page, along with the Oracle E-Business Suite connection "EBS1225" that you created earlier.

Creating an Integration

Perform the following steps to create an integration between REST services and Oracle E-Business Suite:

  1. In the Integration Cloud Service toolbar, click Designer.

  2. In the Designer Portal, click Integrations.

  3. In the Integrations page, click New Integration.

    The Create Integration - Select a Style/Pattern dialog appears.

  4. Click Select for the "Map My Data" integration pattern to create an integration with a blank source and target.

    Selecting the "Map My Data" as the Integration Pattern

    the picture is described in the document text

  5. The New Integration - Information dialog appears. Enter the following information:

    Entering the "Create Order" Integration Information

    the picture is described in the document text

    • What do you want to call your integration? Enter "Create Order" as the name.

    • Identifier: Accept the default identifier value such as "CREATE ORDER".

    • Version: Accept the default version number.

    • What does this integration do? Enter description information for your integration, such as "Create a sales order in Oracle E-Business Suite".

  6. Click Create and Save.

To complete the integration, you need to add the following tasks that are described in the next few sections:

Adding the Oracle E-Business Suite Adapter as an Invoke (Target) Connection

Once the integration is created, add the Oracle E-Business Suite connection "EBS1225" that you created earlier as an invoke (target) connection in your integration.

Perform the following steps to add the Oracle E-Business Suite Adapter as an invoke (target) connection:

  1. In the Create Order integration page, search the "EBS1225" connection that you created earlier from the Connections panel.

    Selecting "EBS1225" from the Connections Panel

    the picture is described in the document text

  2. In the Integration Designer, drag EBS1225 from the Connections panel on the right to the Target area on the canvas.

    The Configure Oracle E-Business Suite Adapter Endpoint wizard appears.

  3. In the Basic Info page, enter the following information for your endpoint:

    • What do you want to call your endpoint? - Enter "EBS_Reference".

    • What does this endpoint do? - Enter "Create a Sales Order in Oracle E-Business Suite".

    Entering the Basic Information for the Target Endpoint

    the picture is described in the document text

    Click Next.

  4. In the Web Services page, specify the following information for your target connection:

    • Product Family: Select "Order Management Suite" from the drop-down list.

    • Product: Select "Order Management".

    Selecting a Product Family and Product for a Web Service

    the picture is described in the document text

    After you select a desired product family and a product, a list of PL/SQL APIs including Oracle seeded APIs and custom ones contained in the selected product "Order Management" is populated for further selection.

    Select a desired API name, such as "Sales Order Services". The corresponding API internal name (OE_INBOUND_INT) and description are automatically populated.

    Selecting the "Sales Order Services" API from the Populated List

    the picture is described in the document text

    Click Next.

  5. The selected API internal name OE_INBOUND_INT appears in the Operations page.

    Select a desired method name contained in the selected OE_INBOUND_INT API for this invoke (target) connection. For example, select "PROCESS_ORDER".

    Selecting the "PROCESS_ORDER" Method in the Operations Page

    the picture is described in the document text

    Click Next.

  6. The Summary page displays all the selected interface details. This information includes the selected "PROCESS_ORDER" operation (with "Ready to Use" status) contained in the "OE_INBOUND_INT" web service from the Order Management Suite product family and Order Management product. This page also displays the default interaction pattern "Synchronize" and security policy "Username Token" for the selected service.

    Viewing the Selected Target Endpoint Details in the Summary Page

    the picture is described in the document text

    The Oracle E-Business Suite Adapter Target Endpoint configuration is successfully created.

    Click Done.

  7. Click Save to save your work.

The connection for Oracle E-Businses Suite now appears in the Invoke (Target) area on the canvas.

Showing the Oracle E-Businses Suite Connection in the Invoke Area

the picture is described in the document text

Adding the REST Adapter as a Trigger (Source) Connection

After adding the Oracle E-Business Suite invoke (target) connection, you need to add a trigger (source) connection in the integration. The trigger (source) connection can be any application adapters suitable for your integrations. In this example, the REST Adapter is used for the integration.

Perform the following steps to add the REST Adapter as a trigger (source) connection:

  1. In the Create Order integration page, locate the "GenericREST" connection that you created earlier by entering "GenericREST" in the Connections field.

    Selecting "GenericREST" from the Connections Panel

    the picture is described in the document text

  2. Drag GenericREST from the Connections panel on the right to the Trigger (Source) area on the canvas.

    The Configure Oracle REST Endpoint wizard appears.

  3. Enter the following information:

    • What do you want to call your endpoint? - Enter the name of this endpoint, such as "Source".

    • What does this endpoint do? - Enter the usage of this endpoint, such as "Provide REST endpoint with input payload for sales order creation".

    • What is the endpoint's relative resource URI? - Enter /process_order.

    • What action does the endpoint perform? - Select "POST" from the drop-down list.

    Ensure that you select the following two check boxes for this trigger (source) connection:

    • Configure a request payload for this endpoint

    • Configure this endpoint to receive the response

    Entering the REST Adapter Endpoint Details in the Basic Info Page

    the picture is described in the document text

    Click Next.

  4. In the Request page, perform the following tasks:

    • In the "Select the request payload file" section, select the JSON schema button.

      Please note that the request payload file type can be either XML schema or JSON format.

    • Click Browse to select a desired request payload file, such as "request.json". Click Open to attach the selected file.

      For the sample request payload, see Sample JSON Payloads for the Oracle E-Business Suite Adapter as an Invoke Example.

    • In the "Select the type of payload with which you want the endpoint to receive" section, select the JSON button as the payload type.

    Specifying the Request Payload Details in the Request Page

    the picture is described in the document text

    Click Next.

  5. In the Response page, select the JSON Sample button for this example.

    Similar to the request, the response payload type can be either XML schema or JSON format.

    Specifying the Response Payload Details in the Response Page

    the picture is described in the document text

    Click Browse to select a desired request payload file, such as "response.json". Click Open to attach the selected file.

    For the sample response payload, see Sample JSON Payloads for the Oracle E-Business Suite Adapter as an Invoke Example.

    In the "Select the type of payload with which you want the endpoint to reply" section, select the JSON button as the payload type.

  6. Click Next.

    This displays the Summary page with the following REST service information that you specified earlier:

    • REST Service URI: /process_order/

    • Method: POST

    • Request Media Type: application/json

    • Response Media Type: application/json

    Viewing the REST Endpoint Summary Information

    the picture is described in the document text

    Click Done.

    Click Save to save your work. The GenericREST connection now appears in the Trigger (Source) area on the canvas, along with the "EBS1225" displayed in the Invoke (Target) area.

Creating Mappings

This step is to create mappings between the source and target data structures in the integration. It includes the following three mappings:

Creating the first mapping for the request:

  1. In the middle of the integration, click the Mapper icon for the request.

    Click Create (the + icon) to display the Mapper page.

    Creating the Mapping for the Request Message

    the picture is described in the document text

  2. In the Mapper page, create the mappings between the source and target elements:

    • In the Source section, expand the execute node, then the request-wrapper node, then the PROCESS_ORDER_Input node, and then the InputParameters node.

      Select the P_API_VERSION_NUMBER element.

    • In the Target section, expand the PROCESS_ORDER_Input node, and then the InputParameters node.

      Select the P_API_VERSION_NUMBER element.

    Drag the P_API_VERSION_NUMBER element from the Source section to the P_API_VERSION_NUMBER element in the Target section to map the data.

    Once you complete this step, the mapped source value and the corresponding target element are connected by a green line.

    Displaying a Green Line for Mapped Source and Target Fields

    the picture is described in the document text

    Similarly, use the same approach to complete the mappings for the elements listed in the following table.

    Source Path Source Element Target Path Target Element
    execute/equest-wrapper/ PROCESS_ORDER_Input/RESTHeader Responsibility PROCESS_ORDER_Input/RESTHeader Responsibility
    execute/equest-wrapper/ PROCESS_ORDER_Input/RESTHeader RespApplication PROCESS_ORDER_Input/RESTHeader RespApplication
    execute/equest-wrapper/ PROCESS_ORDER_Input/RESTHeader SecurityGroup PROCESS_ORDER_Input/RESTSecurityGroupHeader SecurityGroup
    execute/equest-wrapper/ PROCESS_ORDER_Input/RESTHeader NLSLanguage PROCESS_ORDER_Input/RESTHeader NLSLanguage
    execute/equest-wrapper/ PROCESS_ORDER_Input/RESTHeader Org_Id PROCESS_ORDER_Input/RESTHeader Org_Id
    execute/equest-wrapper/ PROCESS_ORDER_Input/InputParameters P_INIT_MSG_LIST PROCESS_ORDER_Input/InputParameters P_INIT_MSG_LIST
    execute/equest-wrapper/ PROCESS_ORDER_Input/InputParameters P_RETURN_VALUES PROCESS_ORDER_Input/InputParameters P_RETURN_VALUES
    execute/equest-wrapper/ PROCESS_ORDER_Input/InputParameters P_ACTION_COMMIT PROCESS_ORDER_Input/InputParameters P_ACTION_COMMIT

    Notice that a green check mark icon appears for the element that has a mapping created. Additionally, the mapped data appears in the Mapping column of the Target section.

  3. Once the mapping is complete, click Save to save your work.

  4. Click Exit Mapper.

Creating the second mapping for the response:

  1. In the middle of the integration, click the Mapper icon for the response.

    Click Create (the + icon) to display the Mapper page.

  2. In the Mapper page, create mappings to map the source and target elements.

    • In the Source section, expand the PROCESS_ORDERResponse node, and then the OutputParameters node.

      Select the X_RETURN_STATUS element.

    • In the Target section, expand the executeResponse node, then the response-wrapper node, and then the Output Parameters node.

      Select the X_RETURN_STATUS element.

    Drag the X_RETURN_STATUS element from the Source section to the X_RETURN_STATUS element in the Target section to map the data.

  3. Use the same approach to complete the mappings for the elements listed in the following table.

    Source Path Source Element Target Path Target Element
    PROCESS_ORDERResponse/OutputParameters/X_MESSAGES/X_MESSAGES_ITEM MESSAGE_TEXT executeResponse/response-wrapper/OutputParameters/X_MESSAGES/X_MESSAGES_ITEM MESSAGE_TEXT
    PROCESS_ORDERResponse/OutputParameters/X_HEADER_REC ORDER_NUMBER executeResponse/response-wrapper/OutputParameters/X_HEADER_REC ORDER_NUMBER

    Displaying Mapped Fields in the Mapping Column

    the picture is described in the document text

    Click Save to save your work.

  4. Click Exit Mapper.

Creating the third mapping for the fault:

  1. In the middle of the integration, click the Mapper icon for the fault.

    The Fault Mappings dialog appears.

  2. Under the Route To, select "APIInvocationError" as the fault type.

  3. Under Map, click the Mapper (+) icon to create mapping.

  4. Create the mapping between the source and target elements:

    • In the Source section, expand the fault node.

      Select the errorCode element.

    • In the Target section, expand the APIInvocationError node.

      Select the errorCode element.

    Drag the errorCode element from the Source section to the errorCode element in the Target section to map the data.

  5. Use the same approach to complete the mappings for the elements listed in the following table.

    Source Path Source Element Target Path Target Element
    fault reason APIInvocationError/errorDetails instance
    fault details APIInvocationError/errorDetails errorPath

    Displaying Mappings for the Fault

    the picture is described in the document text

  6. Click Save to save your work, and then click Exit Mapper.

The mappings for the request, response, and fault are all created successfully.

Click Save to save your work.

Assigning Business Identifier for Tracking

To effectively track payload fields in messages during runtime, you can specify up to three tracking fields to enable runtime tracking on messages.

  1. In the Create Order Integration page, click Tracking.

    The Business Identifiers For Tracking dialog appears.

  2. From the Available Source Fields section, drag the payload field that you want to track to the Tracking Field column.

    For example, drag the INVENTORY_ITEM_ID element from the Available Source Fields section to the Tracking Field column in the table.

    Enter "item" as the Tracking Name for the INVENTORY_ITEM_ID element.

    Displaying the Selected Element for Tracking

    the picture is described in the document text

  3. Click Done.

    Save your work and then click Exit Integration.

Activating and Testing the Integration

Activating the Integration

After you complete the integration with desired source and target connections and mappings, you can activate the "Create Order" integration.

Perform the following steps to activate the integration:

  1. In the Integrations page, click Activate for the "Create Order" integration that you created earlier.

  2. The Confirmation dialog appears. Click Activate.

    Displaying the Integration with ACTIVE Status

    the picture is described in the document text

    Notice that the status of the "Create Order" integration changes to ACTIVE indicating that the integration is ready to use at runtime.

Testing the Integration

To view the activated "Create Order" integration, click the View icon. A pop-up dialog appears with the integration details.

You can copy the Endpoint URL (https://<ebs host name>:<port>/integration/flowapi/rest/CREATE_ORDER/v01/) and open it in any REST client to invoke the REST service for order creation.

For example, an order number 69359 is created successfully after the service invocation and is shown in the Response tab.

Displaying the Service Invocation Response with an Order Number

the picture is described in the document text

Verifying Order Creation in Oracle E-Business Suite

Log in to Oracle E-Business Suite as a user who has the Order Management Super User, Vision Operations (USA) responsibility.

Select Order Returns and then Sales Order from the navigation menu to open the Sales Orders form.

Search for an order by pressing the F11 key. In the Customer PO field, enter the order ID retrieved from the service invocation. For example, enter 69359 and press the CTRL+F11 keys to execute the query. You should be able to find the order created in Oracle E-Business Suite.