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

Oracle Process Cloud Service applications can communicate and exchange data with external applications that are exposed as either REST or Web Services.

In this first part of a two part series on connectors we will explore the Web Service Connector in Oracle Process Cloud Service to exchange data with an external application using the SOAP protocol.

To create a Web Service (SOAP) connection in Oracle Process Cloud Service, you need the following information:

• WSDL file (upload from file or remove via URL)
• The WSDL file should include a port type and a callback port type 
• If the service you are trying to invoke is secure, then you will need the username and password required to access the service

So let's see how you can create a Web Service Connector in Oracle Process Cloud Service. The scenario will be quite simple. 

We will have a process that will invoke a publicly available web service, GeoIPService to lookup countries by IP address. The process will start with a form pattern, where the user will type in the IP address. The process will then invoke the GeoIPService, passing it the IP address typed in by the user and using a second human task, it will display the country where that IP address is.

First thing that we will do is to create a new application in Oracle Process Cloud Service. I've named it "Web Service Connector Demo App" and created a new space (aantoniou) to file this new application under.

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, "Resolve IP Address"). 

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 two text fields. Name the first one "IP Address" and the second one "Country" and ensure the "Country" text field is disabled (by unchecking the "Enabled" property).

Now its time to go and create the Web Service Connector. From the "Application Home" tab, go to "Connectors" and click on the "New Web Service" plus icon to create a new connection. 

In the first train stop, you need to select the source for the WSDL. You can use an existing WSDL file (that was uploaded before), you can upload your WSDL from a file or use a URL to point it to an external WSDL.

I will use the latter option to point it to the GeoIPService WSDL URL (which is http://www.webservicex.net/geoipservice.asmx?WSDL)

In the second wizard train stop, give your service a name and select the appropriate "Port Type" and "Callback Port Type" and click "Next".

In the third wizard screen you can configure some advanced properties like the "Read Time Out", "Connection Time Out" and "Security". I will leave the default and click "Create".

Our Web Service Connector is ready for use. So 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 "GeoIPService" 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 Web Service Connector name you created in the previous step and the appropriate operation and click on "OK".

Next we need to associate all required data for the service call, both for the request as well as the response. So with the service component selected, click on the "Associate the data" button and assign your form's IP Address element to the ipAddress request element and assign your service's response countryName element to your form's country element and click "Apply".

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. Instead of deploying to test our application, we will be the Application Player, a very nice feature of Oracle Process Cloud Service where PCS deploys a version of your application to runtime using a special runtime partition.

Click on the "Play Process" button just above your process. 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. Enter your IP address 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 "Country" field being populated with the Web Service's result.