Oracle Process Cloud Service Connectors (Part 2 of 2): REST Service Connector

by Antonis Antoniou

In the previous post we saw how you can use the Web Service Connector in Oracle Process Cloud Service to exchange data with an external application using the SOAP protocol.

Oracle Process Cloud Service also supports the REST architecture to retrieve, create, update and delete data using REST services and this is what we will look into in detail.

To create a REST service connection in Oracle Process Cloud Service, you need the following information:

REST Service definition (for example, WADL, RAML, YAML, etc.)
Resource URLs
Access to the resource URLs to retrieve JSON sample
List of operations to use on each resource
List of parameters for each operation
In case of a secured REST service, the credentials (username and password) to access the service

Without losing any time, let’s see how you can create a REST Service Connector in Oracle Process Cloud Service using a very simple scenario.

I will be using one of the many publicly available web services to retrieve the states and territories of a country. The service url is “http://services.groupkt.com/state/get/{countryCode}/all” and the service requires you to supply a country code in the form of a 3 character ISO code and will return a list of states in JSON format.

In a nutshell, what we will develop is a process that will invoke the REST service described above. The process will start with a form pattern, where the user will type in the 3 character ISO country code. The process will then invoke the REST service, passing it the country code entered by the user and using a second human task, we will display the first state of that country.

First thing that we will do is to create a new application in Oracle Process Cloud Service (I’ve named it “Rest Service Connector Demo App” under a new space called “aantoniou”).

Next we will create a process to hold the two human tasks and the service call. So from the “Create a Process” screen, select the “Start with a form” pattern, give your process a name and click on “Create”.

Edit the “Start” component and open it’s implementation details and enter a title for the start component (for example, “Retrieve Country States”).

Under the “Web Form” section click on the blue add button to create a new web form and give your web form a name. Ensure you selected “Open Immediately” to open the web form for editing.

In the web form designer, drag and drop on the form canvas a dropdown and a text field. Name the dropdown component “Country Code” and the text field “State” and ensure the “State” text field is disabled (by unchecking the “Enabled” property).

Go to the “Country Code” dropdown properties and add a few options in the form of a “display=key” value-pair. Your “Country Code” dropdown should like as below.

We can now move on and create the Rest Service Connector. From the “Application Home” tab, go to “Connectors”, click on the plus icon and select “New Rest Connector” to create a new connection. Give your rest connector a name and supply the base URL of your REST service.

In the “Rest Connector Editor” click on the “Add” button to create a new resource. Give your resource a name and update the base url path to reflect your resource location.

Once we have defined a resource we can now go on and create an operation (or more if we want) on that specific resource. We will create a “Get” operation, so from the “Add” button select the “Get operation” and click on the newly created operation to open its properties. In the path property we will enter the full path of the operation. This is “get/{countryCode}/all“. Please notice how Oracle Process Cloud Service automatically identified the parameter in the operation path and created it for you under the parameters section.

Because of the “semi-structured” nature of REST servicesN (and their JSON response), we need to instruct our REST service connector what the response will look like. Therefore from the “Response” tab click on the plus icon to create a business object to store the REST service response. Supply a name for your business object and enter the JSON response of your service (Oracle Process Cloud Service will inspect the JSON response and construct appropriate XML elements).

Click “Apply” to apply your changes and dismiss the operation window and save your work.

Our REST Service Connector is ready for use. Go back to your process and drag and drop from the component palette a “Service” component between the “Start” and “End” components.

Rename the “Service” component to “States Service” and go to its implementation details to define its implementation type. From the “Type” drop down select “Service Call” and click on the pencil icon to configure the “Service Call”.

From the “Configure” window select the “Rest” service type and using the connector browser select the REST Service Connector you above (if you followed my exact steps this will be “DemoRestConnector”). The “Resource” and “Operation” drop down lists should be automatically populated with the appropriate resource and operation you created on the REST service.

Next we need to pass to the service call the Country Code that will be entered by the user in the process start form and pass back to the process response from the REST service (the first state).

So with the service component selected, click on the “Data Association” button and assign your form’s Country Code element to the countryCode. You should get an exception saying that you cannot assign CountryCodeType to a string. That’s because country code is an enumeration of elements. To fix this error just surround your assignment with string() function to convert it to a string.

Next we need to assign the response of the service to the form’s state element. So from the “Output” tab, click on the function button (fx) to open the expression editor. Expand the “body” element, “restResponse” and “result” and select the “name” element and click on “Insert Into Expression”.

Please note that the response is an array of states, therefore we need to instruct PCS to retrieve a specific array element. We will be displaying just the first state, so update your expression as follows:
“body.restResponse.result[1].name”

Click “OK” to dismiss the “Expression Builder” window and “Apply” to apply your configurations.

Drag a “Submit” component (Human Task) next to your service component, rename the “Submit” component to “View Service Result” and from its implementation details ensure you selected the same web form you created for the “Start” component.

We are now ready to test our application. And for testing we will be using the Application Player feature of Oracle PCS which basically deploys a version of your application to runtime using a special runtime partition and allows you to inspect inline execution of your process.

Click on the “Play Process” button just above your process and then click on the play button that is shown just above the “Start” button. This will bring up the “Play” window which allows you to select the user to perform this task. I will use the default one and click on the “Run” button.

This will bring up your web form. From the “Country Code” select a country and click on the submit button.

You should see your process execution path with the token being now at the “View Service Result” human task. Click on the “Play”button which now appears just above the “Submit” task and from the “Play” window click on the “Run” button and select “Launch Form” to open your web form.

You should now see the “State” field being populated with the REST Service’s result.

Oracle Process Cloud Service Connectors (Part 2 of 2): REST Service Connector

by Antonis Antoniou

Related posts