Connections define our integration points
It all starts with creating connections. A connection defines the application you want to integrate with. If an application has a public API then ICS can integrate with it. For example, a well-known or lesser-known SaaS application, a public SOAP or REST API for weather or flight information, a custom application using the Messaging Service, or an on-premises Enterprise Resource Planning (ERP) application.
Oracle Integration Cloud Service comes with a large set of out-of-the-box Cloud adapters, to provide easy access to these applications. The amount of available adapters is constantly growing. Most of these adapters are built by Oracle, but through the marketplace it is also possible for customers and partners to build their own adapters.
Each connection can be used for inbound and outbound communication. The majority of available adapters support both ways. A connection commonly describes the type of application, the location of the API definition or endpoint, and the credentials needed to connect securely with the application.
Connections can be divided into four categories: SaaS adapters, Technology adapters, Social adapters, and on-premises adapters:
SaaS adapters
Oracle Integration Cloud Service offers a large collection of adapters to connect to SaaS applications natively. Software as a Service (SaaS), also called on-demand software, is software that is offered as a hosted service. SaaS applications are typically accessed by users using a browser, but most offer API's to access and modify the data or to send events to the SaaS application to perform a task. For the most popular SaaS vendors, Oracle supplies Cloud adapters that can be used by Integration Cloud Service. New adapters are released on monthly cycles. The SaaS adapters can also be developed by customers, partners, and even you.
Most SaaS applications that Oracle offers as the vendor have their own adapter in Integration Cloud Service, such as the ERP, HCM, and the Sales Cloud:
Besides that, ICS supports solutions such as Salesforce, Eloqua, and NetSuite out-of-the-box.
What's the difference with native APIs?
Because the SaaS application offers their API, you might wonder why a special adapter is necessary. The adapters offer a much more simplified experience through a powerful wizard. For example, the Oracle RightNow and Salesforce adapters support the automatic provisioning of Business Objects in the wizard. These adapters also handle security and provide standard error handling capabilities.
In Chapter 4, Integrations between SaaS Applications, we will integrate applications with some of these SaaS applications.
Technology adapters
Not all applications we see on a daily basis are SaaS applications with prebuilt adapters. Industry standards such as SOAP and REST are used by the majority of APIs. SOAP is mostly used for system-to-system integrations, whereas the lightweight REST protocol is used to provide access to mobile applications. For both protocols Oracle Integration Cloud Service provides an adapter.
SOAP adapter
Originally an acronym for Simple Object Access Protocol, SOAP is an industry standard protocol originated around 2000. This specification is used in the implementation of web services and describes exchanging structured information. The SOAP protocol uses XML as the markup language for its message format. SOAP itself is not a transport protocol, but relies on application layer protocols, such as HTTP and JMS.
Web services that are built to communicate using the SOAP protocol use the Web Service Description Language (WSDL). This is an XML-based interface and describes the functionality a web service offers. The acronym WSDL also describes the physical definition file. There are two versions of the WSDL, 1.1 and 2.0, but version 1.1 is still the most commonly used.
The WSDL structure consists of five building blocks; types, messages, porttypes, bindings, and services:
The first three describe the abstract definition and are separated from the latter two that describe the concrete use, allowing the reuse in multiple transports. Where concrete means that a specific instance of a service is referenced (meaning that you have a URI).
Types are nothing more than placeholders that describe the data. An embedded or external referenced XML Schema definition is used to describe the message structure.
Messages are an abstraction of the request and/or response messages used by an operation. The information needed to perform the operation is described by the message. It typically refers to an element in the embedded or referenced XML Schema definition.
PortTypes or Interfaces define a web service, with a set of operations it can perform and direct which messages are used to perform the operation. An operation can only have a request message (one-way), a response message (call-back), or both request and response message (synchronous).
Bindings describe the first part of a concrete WSDL. It specifies the interface with its operations and binds a porttype to a specific protocol (typically SOAP over HTTP).
Services expose a set of bindings to the web-based protocols. The port or endpoint typically represent where consumers can reach the web service:
SOAP itself, also defines a small XML Envelope, which allows XML messages to be carried from one place to another without any system having to inspect the content. Compare it to sending a parcel with a courier-the courier only needs to see the information written on the box, not what is in it!
In Oracle Integration Cloud Service you can create connections based on these WSDLs. When the SOAP adapter is used in ICS you get a wizard that lets you pick one of the available operations (or select it for you if you only have one).
REST adapter
Originally an acronym for Representational State Transfer, REST is a software architectural style also introduced in 2000. It consists of a coordinated set of architectural constraints within distributed systems. The REST architectural style introduces certain architectural properties such as performance, scalability, simplicity, addressability, portability, and reliability. Because it is a style, there are some variations going around.
Web services or APIs that apply REST are called RESTful APIs. They are simply a collection of URIs, HTTP-based calls that use JavaScript Object Notation (JSON) or XML to transmit data objects, many of which will contain relational links. JSON is a human-readable text format consisting of attribute/value pairs.
RESTful APIs are usually defined with the following aspects:
- The principal of addressability is covered by the URIs, which has a base URI, such as
http://www.example.com/restfulapi/, for all its resources. - Each resource has its own address, also known as an URI. A resource exposes a unique piece of information that the server can provide.
- For sending the data objects, an Internet media type, often JSON, is used.
- The API uses standard HTTP methods, for example,
GET,PUT,POST, orDELETE. - Reference stat and reference-related resources use hypertext links.
RESTful APIs use common resource naming. When deciding which resources are available within your system, name the resources as nouns as opposed to verbs or actions. They should refer to a thing instead of an action. The name and structure convey meaning to those consuming the API.
Resource examples
In this example, we use our Flight API hosted on Apiary (https://apiary.io/).
The base URI for this API is: http://icsflightapi.apiary-mock.com/
To insert (create) an airline in our flight system, we can use:
POST http://icsflightapi.apiary-mock.com/airlines
To retrieve the details of the Airline with ICAO Identifier KLM, we can use the following:
GET http://icsflightapi.apiary-mock.com/airlines/KL
The same URI would be used for PUT and DELETE, to update and delete, respectively.
What about creating a new destination an airline travels to? One option is to POST to the resource URI http://icsflightapi.apiary-mock.com/destinations, but it's arguably outside the context of an airline.
Because you want to create a destination for a flight schedule, the context should be on the schedule. It can be argued that the option to POST a message to the URI http://icsflightapi.apiary-mock.com/airlines/KL/destinations better clarifies the resource. Now you know that the destination is added to the airline.
With this in mind, there is no limit on the depth of the URIs hierarchy as long as it is in the context of the parent resource.
In Oracle Integration Cloud Service you can create connections based on the base URI. When the REST adapter is used in ICS you get a wizard that lets you create the resource that you want to expose. Only one resource can be implemented per integration.
In Chapter 2, Integrating Our First Two Applications, both SOAP(inbound) and REST(outbound) adapters are used for our first integration.
FTP adapter
Besides web service standards of SOAP and REST, there is also a technology adapter for FTP. Originally an acronym for File Transfer Protocol, FTP is a protocol used to rapidly transfer files across servers originated around 1985. The FTP adapter enables you to transfer files from a source or to a target FTP server in an integration in ICS.
With this adapter you can transfer (write) files to any server that is publicly accessible through the Internet. Files can be written in either binary or ASCII format. The adapter enables you to create integrations, which will read a file from a source FTP and write it to a target FTP server. In this scenario, the integration also supports scheduling, which enables you to define the time and frequency the transfer occurs.
The adapter supports some welcome features, such as the possibility to natively translate file content and to encrypt and decrypt outbound files using Pretty Good Privacy (PGP) cryptography. With the first feature you can translate a file with comma-separated values to XML.
The adapter not only supports plain FTP, but also FTP over SSL and secure FTP (SFTP). FTP over SSL requires the upload of a Certificate store. SFTP requires an optional host key to ensure that you connect to the correct SFTP server and secures that your connection is not compromised.
We will use the FTP adapter when managing file transfers in Chapter 9, Managed File Transfers with Scheduling.
On-premises adapters
Of course, not all of our applications run in the cloud, for most of us it is still rather new. Most of our mission critical systems run on-premises. Oracle Integration Cloud Service provides adapters and supporting software to create a Hybrid Cloud solution.
A Hybrid Cloud is a cloud computing environment, which is a combination of on-premises, private (third-party), and public cloud services. Between the platforms we usually find an Orchestration layer. For example, an enterprise has an on-premises finance system to host critical and sensitive workloads, but want to expose this system for third-party users.
Integration Cloud Service provides adapters and the supporting software to simplify integration between cloud and on-premises applications in a secure and scalable way.
The supported adapters include technology adapters, for example, Database, File, and JMS, an adapter for Oracle E-Business Suite, Oracle Siebel and SAP, and so on.
For example, with the database adapter you can call a stored procedure in your on-premises database or execute a pure SQL statement.
The File Adapter enables file transfers between two servers that cannot talk directly with each other. Java Message Service (JMS) enables integrations with existing JEE applications.
Adapters do not indicate if it is for on-premises use only, or if it can be used with an on-premises endpoint. When creating a new connection based on the adapter it will ask for an agent to assign to the connection.
ICS includes two agents; the Connectivity and the Execution agent. An agent is a piece of software running on-premises and puts a secure bridge between the Oracle Cloud and on-premises. We will shortly describe both agents, but have dedicated Chapter 11, Calling an On-Premises API to explain them in more detail.
What is the Connectivity Agent?
The Agent is basically a gateway between cloud and on-premises, and it eliminates common security and complexity issues previously associated with integrating on-premises applications from outside the firewall. The agent can connect with on-premises applications, such as the database or ERP application, using the existing JCA adapter framework. To understand this concept we first look at the agent's architecture.
Architecture Guidelines
The Agent is developed with a few architectural guidelines in mind. The most important guideline is that it shouldn't be required to open inbound ports to communicate with on-premises applications. This means that there isn't a need to create firewall rules to provide access. Because of this no open ports can be abused.
The second guideline describes that it is not required to expose a private SOAP-based web service using a (reverse) proxy, for example, API Gateway or Oracle HTTP Server (OHS). The third describes that no on-premises assets have to be installed in the DeMilitarized Zone (DMZ). The agent is installed in the local network where the backend systems are accessible.
The fourth guideline describes that it is not required to have an existing J2EE container to deploy the agent on. The fifth and last guideline describes that it is not required to have IT personnel monitor the on-premises component. With this agent the monitoring of the component is part of monitoring UI within ICS.
Architecture
The Agent consists of two components, a Cloud Agent installed on ICS and a Client Agent installed at on-premises. The Messaging Cloud is used by the Agent for its message exchange and only allows connections established from the Oracle Cloud.
It disallows explicit inbound connections for other parties. The agent uses the existing JCA adapter framework to invoke on-premises endpoints, for example, Database, file, and ERP (Siebel/SAP):
Oracle Integration Cloud Service supports multiple agents for load distribution and high availability. For example, it is possible to group multiple agents, but place each agent on a different local host/machine. Agents can be grouped on a functional, process, or organization level.
The Connectivity Agent can be downloaded from ICS and installed on demand on-premises. What you get at the end is a fully installed WebLogic server with a domain and managed server running the necessary Agent clients and JCA adapters.
Message Exchange Patterns
A Message Exchange Pattern (MEP) describes the pattern of messages required by a communication protocol for the exchange of messages between nodes. A MEP defines the sequence of messages, specifying the order, direction, and cardinality of those messages in a service call or service operation.
Two main MEPs are synchronous (request-response) and asynchronous (fire and forget).
The agent conforms to a few message exchange patterns when communicating with on-premises applications from the cloud:
- Synchronous request from cloud to on-premise to retrieve data (for example, getting the status of an order from EBS in real time)
- Cloud events triggers Async message exchange with on-premises (for example, creation of an incident in RightNow causes creation of service requests in EBS)
- On-Premises events triggers Async message exchange with the cloud (for example, service request updates event result in Async synchronization with RightNow)
- Synchronized data extracts between on-premises and Cloud applications (for example, EBS-based customer data synchronized with CRM)
What is the Execution Agent?
This Agent is a fully fledged Integration Cloud Service that you can install on-premises. When you subscribe to ICS, you also have the option to install an on-premises version in your local environment (that is, DMZ). This enables you to use ICS as a proxy server that sits between your mission critical systems protected by a firewall and the cloud version. More on this agent in Chapter 11, Calling an On-Premises API.
Noticeable differences
After installing the on-premises version of ICS you can create users and assign roles to these users. This is done in the provided Users page of the on-premises ICS. This page is not available in the Cloud version.
You also have access to the WebLogic Console, Service Console, and Fusion Middleware Control. This means that you can take a peak in the deployed applications, the Service Bus resources, and in the log files. When something goes wrong you can debug the problem without the help of Oracle Support. This is not possible in the Cloud version.
Restrictions between connectivity and execution agent
Another difference or even a restriction between the Cloud and the on-premises version is that you aren't able to configure Connectivity Agents. With this restriction in place, the adapters for connecting to the Oracle Database, MySQL Database, and Oracle SAP are not supported.
There is a default Agent group available in the Cloud version of ICS. All installed Execution Agents will be registered under this group, which restricts assigning connections to a specific Execution Agent:
We will explore both the Connectivity and Execution Agent in Chapter 11, Calling an On-Premises API.
Social and productivity adapters
Oracle Integration Cloud Service comes with a dozen of other kinds of adapters. These applications can also be categorized as SaaS applications; they're not in a traditional sense that is, enterprise applications, but offer Internet services. I'm talking about services where people can be social or collaborate with each other.
Integration Cloud Service supports social apps such as Facebook, LinkedIn, and Twitter, to post a status update. The supported productivity apps include Google, Microsoft Calendar and Mail, Google Task, MailChimp, and SurveyMonkey; and this list is updated on a monthly cycle:
If you're looking for a full reference of all the supported adapters, please take a look at the documentation which can be found at: https://docs.oracle.com/cloud/latest/intcs_gs/ICSUG/GUID-8BE53B5C-6436-4F81-AD20-78ECE5589BA9.htm.
