Creating an Orchestration to Invoke an External REST Service

Before You Begin

This 40-minute OBE (Oracle By Example) shows you how to create an orchestration that can invoke an external REST service.

For this example, a REST service on the JD Edwards EnterpriseOne Application Interface Services (AIS) Server serves as the “external” REST service. In a real-world scenario, you would call an external service exposed by a third-party provider instead of the AIS Server. But this example show you the general process to follow to invoke an external REST service, without requiring you to register with a third-party to gain access to their services.

You will create an orchestration with a REST connector to call an “external” REST service to retrieve address book information that includes city and state information. You will add a data request to the orchestration that uses the city and state information retrieved from the REST connector to find a record in the F0117 table (Postal Codes) table in EnterpriseOne. Lastly, you will test the orchestration to verify that it returns the requested data.

Optionally, you can continue to the Open API exercises (section 7,8, and 9), to learn how to call a REST service that exposes a Swagger or Open API descriptor.

Background

In the Orchestrator Studio, you can configure a connector to invoke a REST service. The Connector design page in the Orchestrator Studio provides a test feature that enables you to test the connector and view the JSON response of the REST service call.

What Do You Need?

JD Edwards EnterpriseOne test environment with a minimum of EnterpriseOne Tools 9.2.5.0.
An AIS Server running and accessible (based on network configuration) to your Orchestrator Studio.

Creating a Connection to the External AIS Server

A connector requires a connection, which provides access to the external resource, in this case the server where the REST service resides.

For this example, you can configure the connection to access the same AIS Server configured with the Orchestrator Studio or a different AIS Server if you have another one set up.

On the Orchestrator Studio Home page, click the Connections icon.
Alternatively, you can click the Tools menu and select Connections.
Click the New button and select REST.
On Connection Information, complete these fields:

Name = EXTERNALAIS
Description = External AIS Call

On the Service Information tab, in the Endpoint field, enter the URL for accessing the AIS REST services:
https://<youraisserver:port>/jderest/v2
On the Security tab, select Basic Authentication and then complete these fields to enable access to the external service:
- User = Enter an EnterpriseOne user authorized to access the V0101B business view in the EnterpriseOne Data Browser.
- Password = Enter the password for the EnterpriseOne user.

Note: Again, for this example, the external resource is a REST service on the AIS Server, which is used to retrieve data from EnterpriseOne. In the next task, you will create a connector that uses this connection to the REST service to retrieve data from the V0101B business view in EnterpriseOne. Therefore, the connection must include EnterpriseOne user credentials authorized to view the data for the specified business view in the EnterpriseOne Data Browser.

Enter proxy information on the Proxy tab if necessary for your network configuration.
This is more probable if connecting to a real third-party service.

Connection Information
Save the record.

Creating the Connector

In this task, you will create a connector to call a REST service. The specific REST service we will invoke is documented here: Simple View Query v2 (GET) /jderest/v2/dataservice/view/{viewName}

On the Orchestrator Studio Home page, click the Connectors icon.
Click the New button and select REST.
On the Connector page, complete the following fields:

Name= Get Address Book Records
Enter Short Description = Retrieve address book records from the external AIS Server.

Click the Product Code drop-down list and select 55 for a customer product code.
From the REST drop-down list, select the EXTERNALAIS connection, which you created in the previous task.
Leave the HTTP Method as a GET since this API uses the GET method.
Expand the Pathing section and in the Value grid, build the path to the REST service endpoint by entering the following values in consecutive rows:
- dataservice
- view
- V0101B
After entering these values, the service path displayed above the Value grid should look like this:
http://<youraisserver:port>/jderest/v2/dataservice/view/V0101B
In the Parameters section, enter the following key value pair:

$filter F0101.AN8 EQ ${AddressNumber}

This parameter enables you to filter the data, requesting the record with AN8 matching the input variable AddressNumber.

Click here to review the output for this API, which you will refine in the next step.
To limit the output to a few returned values, expand the Response section and the Output section.

Enter the following output values in the JSON table:

Output	Variable Name
fs_DATABROWSE_V0101B.data.gridData.rowset[0].F0101_ALPH	Name
fs_DATABROWSE_V0101B.data.gridData.rowset[0].F0101_AT1	Type
fs_DATABROWSE_V0101B.data.gridData.rowset[0].F0116_CTY1	City
fs_DATABROWSE_V0101B.data.gridData.rowset[0].F0116_ADDS	State

Save the connector.
To test the service call, click the Test button, enter address number 1 and click Execute.
First you will see the response directly from the service. Make sure you receive the expected output of one record for address 1.
Click the Show Output button and verify that you received only the four pathed items you entered.
Close the test window.

Adding the Connector to an Orchestration

In this task, you will create an orchestration, from the connector created in the previous task to the orchestration. The system automatically populates the inputs, transformations, and outputs.

In the connector page you just finished creating, click the Manage menu, and then click Create Orchestration.
On the Orchestration design page, complete these fields:

Orchestration = External REST to AIS
Enter Short Description = Call a REST service to retrieve address book information.

Click the Product Code drop-down list and select 55 for a customer product code.
Verify that the inputs, transformations, and outputs are automatically populated
- Click the Start node and select Inputs and Values, verify that the input value for AddressNumber is already added.
- Click the Connector node and select Transformations, verify that the AddressNumber value is already mapped.
- Click the End node and select Outputs and Assertions, verify that the four output values are already selected.
In the Output column, rename the four outputs with these simple names:
- Name
- Type
- City
- State

Save the Orchestration.

Testing the Orchestration

Double-click the Start node of the orchestration. Alternatively, you can click the Tools menu and select Run Orchestration. The orchestration will already be selected for you.
Enter an address number (example, 1). Use an address number that has data in V0101B.
Click Run.

The output should show results for the address number that you entered.

Change the number and run it again to see different results.

External REST to AIS Orchestration Test
Click X to close the Run Orchestrations window.

Using the REST Connector Output in a Subsequent Orchestration Step

In this task, you will add a new data request to the orchestration. You will use the values that you returned from in the REST connector as the input to this data request. Specifically, the REST connector is configured to return the city and state of a user. The data request will use these values as filters to find and return the zip code of the given user.

In the External REST to AIS orchestration that you just tested in the previous exercise, double-click the line in the diagram after the existing connector step. Select Data Request.

Click New.
On the Data Request design page, complete these fields:

Name = Get Zip Code
Enter Short Description = Retrieve zip code for address book number from F0117.

Click the Product Code drop-down list and select a customer product code, 55-59.
In the Table/View Name field, enter F0117 and click Load.

To configure the data request to filter on City and State, in the Fields grid, click the Filter icon next to these fields.

City	CTY1
ST	ADDS

To specify the field that contains the data you want returned by the data request, in the Fields grid, click the Return icon next to the Postal Code (ADZ1) field.
The system adds the field to the Return Fields and Variable Names section on the right.

Get Zip Code Data Request
Save the data request and click X to close it.
Back in the orchestration, the Get Zip Code data request will be added to the diagram.
Click the data request step and select Transformations.
■ For the City 1 input, click the Available Values drop-down list and select City under Get Address Book Records.
■ For the ST 1 input, click the Available Values drop-down list and select State under Get Address Book Records.

Orchestration with the Get Zip Code Data Request - Transformations
Save the orchestration.
Click the End node and select Outputs and Assertions.
Enable the Select option for the Postal Code. Do not enable Return All Grid Rows as we only want the first postal code that is found. The outputs should look like this: .

Save the orchestration.

Retesting the Orchestration

Double-click the Start node of the orchestration. Alternatively, you can click the Tools menu and select Run Orchestration. The orchestration will already be selected for you.
Enter an address number (for example, 1). Use an address number that has data in V0101B with a city and state that are in F0117.
Click Run.

The output should show the results, including Postal Code, fetched in the second step (data request step) in the orchestration.

Run Orchestrations Window

Creating an Open API Connection to the External AIS Server

For this example, you can configure the connection to access the AIS Server Open API descriptor. You will call the same API, but you will not necessarily need to rely on the documentation because the descriptor will populate the request for you.

On the Orchestrator Studio Home page, click the Connections icon.
Alternatively, you can click the Tools menu and select Connections.
Click the New button and select Open API.
On Connection Information, complete these fields:
- Name = EXTERNALAISOPEN
- Description = External AIS Open API Call
On the Service Information tab, in the Endpoint field, enter the URL for accessing the AIS REST services: https://<youraisserver:port>/jderest/swagger.json
On the Security tab, select Basic Authentication, and then complete these fields to enable access to the external service:
- User = Enter an EnterpriseOne user authorized to access the V0101B business view in the EnterpriseOne Data Browser.
- Password = Enter the password for the EnterpriseOne user.
Note: Again, for this example, the external resource is REST service on the AIS Server, which is used to retrieve data from EnterpriseOne. In the next task, you will create a connector that uses this connection to the REST service to retrieve data from the V0101B business view in EnterpriseOne. Therefore, the connection must include EnterpriseOne user credentials authorized to view the data for the specified business view in the EnterpriseOne Data Browser.
In the Proxy tab, enter the proxy information if necessary for your network configuration. This is more probable if you are connecting to a third-party service.
Save the record.
Verify that the Endpoint drop-down list is populated with the service endpoint (defined in the Open API descriptor). If multiple endpoints are available, you can select the specific one to use for this connector.

Creating the Open API Connector

In this task, you will create a connector to call a REST service.

On the Orchestrator Studio Home page, click the Connectors icon.
Click the New button and select Open API.
On the Connector page, complete the following fields:
- Name = Get Address Book Records Open API
- Enter Short Description = Retrieve address book records from the external AIS Server
Click the Product Code drop-down list and select 55 for the customer product code.
In the Open API drop-down list, select the EXTERNALAISOPEN connection, which you created in the previous task.
Notice that the API drop-down list contains all of the services described in the Open API/Swagger descriptor.
Select /v2/dataservice/view. This is the same service you manually entered in the previous exercises.

Notice that selecting the API you want to use automatically populates the HTTP Method. In this example, the value is GET.
Expand the Pathing section and in the Value grid, verify that the full path is already populated with a variable defined for the view name parameter in the path.
Expand the Parameters section. Delete all parameters except for the $filter parameter. All of them are displayed because they are all possible defined inputs, but you will only be using one in this example.
Change the Value for the $filter parameter:
$filter = F0101.AN8 EQ ${AddressNumber}
This parameter enables you to filter the data, requesting the record with AN8 matching the input variable AddressNumber.
Click here to review the output for this API, which you will refine in the next step.
Expand the Headers section. Delete all but the Accept key here; you don’t need to use these for this request, but they are defined in the descriptor, so you know they are available.
To limit the output to a few returned values, expand the Response section and the Output section.