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

6

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.

imageThe 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.

image

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.

image

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:

image

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

image 

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

image

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.

image

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.

image

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

image

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:

image

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:

image

Uploading is pretty self explanatory:

image

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.

image

 

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.

image

Then click on Create New Integration.

Select the Map My Data integration type:

image

Enter a name and optionally a description:

image

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.

image

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

image

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

image

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

image

Press Next.

On the Summary Page, press Done.

image

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

image

Type a name and description for the inbound endpoint:

image

Press Next.

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

image

Press Next.

On the Summary Page, press Done.

image

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:

image

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:

image

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:

image

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.

image

Click on Execute to perform the test

image

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.

image

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

image

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:

image

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

Return to the integration editor.

image

 

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:

image

Provide values for Tracking Name and Help Text:

image

Press Done.

Press Save, then press Exit for the Integration:

image

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:

image

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

image

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

image

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

image

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:

SNAGHTML9ec13c2

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.

image

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.

SNAGHTML9eede41

Right click again and select Add WSS Timestamp.

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

image

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.

image

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

image

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.

image

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

image

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

About Author

Lucas Jellema, active in IT (and with Oracle) since 1994. Oracle ACE Director and Oracle Developer Champion. Solution architect and developer on diverse areas including SQL, JavaScript, Kubernetes & Docker, Machine Learning, Java, SOA and microservices, events in various shapes and forms and many other things. Author of the Oracle Press book Oracle SOA Suite 12c Handbook. Frequent presenter on user groups and community events and conferences such as JavaOne, Oracle Code, CodeOne, NLJUG JFall and Oracle OpenWorld.

6 Comments

  1. Wonderful article Lucas. I was searching for similar article with example and this helps a lot. Thanks a lot for sharing detailed steps with screen shots. Will keep reading your articles. Appreciate if you can share WSDL for inbound integration as I am facing some issues while replicating this.

  2. Can you upload the WSDL file ? I’m getting Error while creating SOAP to ICS messaging service integration. I created SOAP Trigger point as mentioned in this Blog.

    Error:The application has encountered an unexpected error. Please check the applications connection details, credentials and retry your request.

    • Hi Athavan,
      I am facing similar issue, was you able to get wsdl file for inbound connection. Lucas it will be great if you can help us out or add WSDL file in blog.

      Thanks,
      Kunal

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.