The quick introduction to the Integration Cloud Service (Oracle PaaS – ICS)

Integration is the term we employ for ‘what ties systems together into end-to-end interaction flows’. Integration describes what we have to do to make applications in one domain talk to those in another, or systems in one enterprise talk to those in another. And to systems running in one cloud interact with those running in another cloud or those running on premises. Integration is ideally approached based on standard based service interfaces and encapsulated implementations. With generic integration facilities handling most of the protocol, format, and technology specific details, and translating interactions as much as possible to standard SOAP and REST exchanges. And with that generic platform handling monitoring, security, system errors and state when asynchronous exchanges are required.

The Oracle Integration Cloud Service (ICS from now on) provides the cloud based integration platform that can run and manage these integration flows. ICS exposes a browser based user interface through which the integration is first designed, then activated and managed. ICS provides adapters to easily interact with a number of popular SaaS applications (Salesforce, Oracle HCM Cloud, Oracle ERP Cloud, Oracle SalesCloud, Service Cloud | Right Now, Eloqua, CPQ, Gmail & Google Task, Evernote, …) and Platform Services and technologies (Oracle Database, Oracle Messaging Cloud Service, FTP, SOAP and REST services) as well as a collection of Social Networks (Twitter, Linked In, Facebook). With ICS it is straightforward to connect to any of these as a target and expose an tailor made, easy to use interface to ICS consumers. Some of these can also be a source for interactions: events in SaaS applications  – such as creation or update of a business object – can trigger ICS to perform an integration flow – pushing data derived from the event to some target.

In this article I will introduce some of the core terminology for ICS and demonstrate my first steps. I will create a SOAP service that exposes a simple operation to convert distances in meters to their equivalent in yards. This service is the based on an existing conversion service offered by a third party. ICS is used to virtualize this service and map to and from between the business friendly interface that I have devised and the pre-existing service interface.

Overview

You will see how I have to first create two connections. Connection is the ICS term for an external link – either outbound from ICS to target systems  (comparable to business services in Service Bus or a Reference in SCA composites) or inbound into ICS (from external consumers), similar to Proxy Service in Service Bus and Service in SCA composites. One connection is outbound, to the third party service that does distance conversions. The other connection is inbound – it describes the SOAP interface that I want to expose from ICS to my consumers.

These connections are brought together in an Integration – with My External Service Interface connection providing the source for the integration and the connection to the 3rd Party Conversion Service providing the target for the integration.

The integration contains a mapping for both the inbound (or request) flow and the outbound (the response) flow. The mapping connects the elements in the incoming message to the corresponding elements in the outgoing message. The integration can also include enrichment and – a recent feature – content based routing or filtering.

Additionally, we can define tracking fields based on values in the request message. These tracking fields are recorded for each instance of ICS, i.e. each request processed by the integration. This makes monitoring and after the fact analysis of whatever took place much easier.

After the integration is

Creating the Two Connections

The first connection I will create is the outbound connection to the external web service that does distance conversions. This service is offered at http://www.webservicex.net/length.asmx?wsdl . It does not require any authentication. This service offers four bindings – SOAP 1.1, SOAP 1.2, HTTP GET and HTTP POST. We will make use of the first one.

From the dashboard for ICS, click on the tile for Connections:

Then click on Create New Connection and in the popup with integration adapters, select the SOAP adapter:

 

Set a name for the connection in the popup that appears; perhaps provide some description as well.

The click the the Create button.

Click on the button labeled Configure Connectivity. Enter the URL for the WSDL for the external web service, as shown in the next figure.

Then click on OK.

The external web service that this connection links up to does not have any security policies associated with it. Therefore, click the Configure Credentials button. Select No Security Policy from the dropdown list. Then click OK.

When the popup has closed, click the Test icon – to verify the connection details.

Upon success, click Save. Then click Exit Connection.

The first connection is now set up.

 

The second connection is of the inbound kind: we define an entrance into ICS as we want to offer it to our consumers. The steps are by and large the same as we saw before:

Click on Create Connection. Then click the select  button for the SOAP Adapter. Enter a name and a description for the inbound connection:

Then Click Create to create the connection.

Click Configure Connectivity. Since this is an inbound connection, you are not expected to provide an endpoint. What we do need to provide is an abstract WSDL document with a portType, operations and message definitions. In this case instead of referring to such a WSDL document through a URL, I will upload the WSDL itself from my local file system into ICS. Here is a screenshot of a section of this WSDL document:

Uploading is pretty self explanatory:

Finally, for this connection we do not need to enforce any form of authentication on incoming requests. Therefore, click Configure Credentials and set No Security Policy.

Just as before, Test the Connection – you will not be allowed to use the connection if you have not gone through this test step. When the test is successfully done, click Save and click Exit Connection.

 

Both connections, inbound and outbound, are prepared. We now need to set set up an integration to link and map between these to.

 

Adding the Integration with the Two Mappings

Click on the Integrations node in the navigator on the left hand side.

Then click on Create New Integration.

Select the Map My Data integration type:

Enter a name and optionally a description:

Then press Create.

The integration editor is shown. Drag the webservicex connection to the Target area – as it serves as the outbound destination for this integration.

In the popup dialog, provide a name and a description for the ‘outbound endpoint’. Press Next.

Select the appropriate Port from the WSDL at the far end of the connection:

And select – although in this case there is a choice of one – the desired operation to integrate to:

Press Next.

On the Summary Page, press Done.

The outbound part of the integration is now done. Drag the DistanceConversionMetersToYardsProxy conection to the Source area.

Type a name and description for the inbound endpoint:

Press Next.

Confirm the selected Port Type (only one available in the abstract WSDL we uploaded for this connection) and operation:

Press Next.

On the Summary Page, press Done.

On the overview page, click on the first mapping and then click on the plus icon to create the message mapping for the request message from source to target:

The mapping editor appears. Drag the distanceValue element in the source to the LengthValue element in the target. Click on the fromLengthUnit element in the target and enter the string Meters on the mapping builder details page that appears:

Press Close.

Click on toLenghtUnit and type the string Yards on the mapping builder page. After clicking close to return, this is what the overall map looks like:

Press Test to … well, to test the map definition.

In the Test Map dialog, click on Generate Input to create a random message according to the XSD that describes the source message.

Click on Execute to perform the test

and verify that the result is what we need.

Close the test map dialog. Press Save in the main map dialog. Then press Exit Mapper.

Now click on the second map icon, for the response flow from target back to source.

Map the ChangeLengthunitResult element that contains the converted distance value returned by the external web service to the DistanceConversionResult element in the response message from the inbound connection:

You could test this ma. Then save and exit mapper.

Return to the integration editor.

 

Specifying Tracking Fields

Click on the Tracking icon, as shown in the previous screenshot. This allows us to specify the business identifiers to track – record, monitor – when instances of this integration are executed.

In the Business Identifiers for Tracking page, drag the distanceValue source element – from the request message that triggers this integration – to the first row’s Tracking Field:

Provide values for Tracking Name and Help Text:

Press Done.

Press Save, then press Exit for the Integration:

The Integration is now completely configured.

 

Activation of the Integration

The Integration can not yet be executed. It first needs to be activated.

Click on the Activation button to make that happen:

Confirm the activation of the integration – and turn on Detailed Tracing:

After a few seconds, the integration is activated and is now live and accessible to external consumers. We can now find out at which endpoint these external consumers can have their meters converted to yards. Click on the little i icon for the integration

A popup appears that contains the url for the WSDL of the inbound connection exposed by this integration:

Copy this URL to the clipboard.

 

Testing the Service exposed by ICS

Create SoapUI WSDL project for the SOAP Service exposed from ICS – using the URL for the WSDL that was retrieved in the previous step:

Have a test request generated.

When you try to send in this generated request, you will run into an error response – OSB-386200 (tells you something about the underlying implementation of the ICS) General Web Service Security Error.

This one had me thrown for a moment, since we specifically specified that no security policy should be applied to this connection. However, I guess because the connection is exposed from the ICS identity domain and accessed over an HTTPS connection, we still need to provide authentication. In SoapUI this is done fairly easily.

Set the username and password properties as shown in the next screenshot – using the ICS account credentials. Then right click the test request and select Add WSS Username Token. Accept the Password Text option.

Right click again and select Add WSS Timestamp.

When both headers have been added to the Test Request, execute the test again.

This time, the service response should contain the converted Yards value. Who would have guessed that 1000 meters corresponds with 1094 yards?!

Monitoring ICS

When we made the call to our new ICS integration, the field tracking was dutifully performed – and we can check on it.

Return to ICS and click on the Monitoring button.

Open the Activity Stream tab – and find messages relating to the service call we just performed from SoapUI:

Click on the Tracking icon.

The instance of the integration that was created when we made the call from SoapUI is shown – along with the tracking field: distance in meters.

We can drill down on this instance, and inspect the exact flow trace for it.

Even though in this case it does not add a lot of insight – you can probably see how this could be useful when integrations fail at some point in the end to end flow.

 

Resources

Documentation for ICS

Various blog articles on ICS by my colleague Robert van Mölken

The home page for ICS on the Oracle Public Cloud Website