ICS has its own API that provides a range of REST services focused on the control and monitoring of ICS. The API provides a range of operations, from being able to deploy connections and integrations, to activating and deleting them, through to getting details of any errors: the monitoring metrics we saw in the previous chapter.
The details of the APIs can be obtained from the Oracle documentation online (https://docs.oracle.com/cloud/latest/intcs_gs/ICSRA/), which is also linked to the ICS tool itself. While the APIs lend themselves to extending your preferred enterprise monitoring tool, it is also very easy to build some basic management scripts through the use of tools such as cURL.
To illustrate this point, we are going to use the API to retrieve some information about an instance of ICS:
- Retrieve the monitoring metrics so you can see the high-level stats regarding your environment. This is the sort of thing that could be your first step to incorporating ICS into the enterprise monitoring capabilities the IT are likely to be operating.
- Retrieve the monitoring log files - having a little script handy to pull these logs down when you need them to help debug integration development saves on having to navigate between the Designer and the Monitoring views. Note, these logs are slightly different to the system level logs.
- Issue a command to deactivate a specific integration.
Before we illustrate these cases, let's first talk a bit about cURL and get it into place, and the general principles that have been applied to the ICS APIs.
cURL is an open source tool that is mostly associated with Linux platforms but, over time, has been adapted and implemented for just about every operating system you can think of. cURL serves as a tool with which you can communicate with web servers using the HTTP/HTTPS syntax. This makes it ideal for formulating REST-based calls from a command line. cURL can go a long way beyond this, but for our purposes, HTTP is sufficient.
You can download the right platform implementation for cURL from the cURL website - https://curl.haxx.se/. You can retrieve the binaries, source files, or installer packs such as MSI or DEB files. Given the variety here, we are not going to describe the installation process; there is plenty of documentation on how to achieve this on the net. Ultimately, you need to invoke the cURL command from a shell (DOS/PowerShell/Bash, and so on). For the purposes of this book, we have downloaded a binary and ensured that it is the system path.
You can confirm that cURL is running fine by issuing the curl -help command, which should result in the help information being displayed, as you can see in the following screenshot:
With this, we know cURL is available and will run. Let's talk a bit about the cURL command structure. The command is defined as a series of parameters that will define the following details:
- User credentials - these are the same credentials that you will use when signing into the web interface
- The HTTP header attributes such as the nature of the payload being sent or wanted back
- A reference to a file as the contents for the body - although we do not need this except when uploading integrations and so on
- The HTTP operation to perform such as
GET,POST, and so on, as we explained in Chapter 1,Introducing the Concepts and Terminology - The complete target URL that will execute the call
ICS is happy with being sent and being asked for, in most cases, with both XML and JSON formatted payloads. The documentation for each service will confirm whether both formats are supported. With that, we can start to look at the construction of the cURL commands, which in most cases will be as follows:
curl -u username:password -H "HTTP header attribute settings in quotes" -X HTTP operation e.g. GET target URL
To bring this to life, our first example would look like this:
curl -u myusername:mypassword -H "Accept:application/XML" - X GET https://integrationtrial12345- deoracleem12345.integration.us2.oraclecloud.com/icsapis/v1/monitoring/integrations
As you can see, we express whether XML or JSON is wanted through the use of -H "Accept:application/XML" (that is, we will accept XML), and what we are providing is formatted as by -H "Content-Type:application/json". For most requests, there is no provided body content, so we can disregard the Content-Type header information, hence it is not in the example.
Let's execute this cURL command. The following screenshot shows the outcome:
As you can see from the screenshot, we do get a stream of XML back, which is not practical from a readability view. So we would recommend that you direct the output to a file and then use a pretty printer app. The output can be done either by piping the log content or using an -o option for example -o integrations.txt. Note that the moment a file is involved, the display showing the execution changes, with stats regarding the download presented instead as follows:
Applying this means we get a result that can contain information like:
<flowId>8d1261af-7c24-4d19-8c24-41532621d9d4</flowId>
<flowName>TweetFlightScheduleChanges_Ch5</flowName>
<flowCode>TWEETFLIGHTSCHED_CH5</flowCode>
<flowVersion>01.00.0000</flowVersion>
<description>This integration will take the ScheduleUpdate request and send out a tweet returning a result or fault as response.</description>
<noOfMsgsReceived>54</noOfMsgsReceived>
<noOfMsgsProcessed>54</noOfMsgsProcessed>
<noOfErrors>21</noOfErrors>
<noOfSuccess>33</noOfSuccess>
<errorsInQueues xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<errorObjects xsi:type="xsd:string">
Unable to reach target.
</errorObjects>
<errorObjects xsi:type="xsd:string">
Unable to reply back.
</errorObjects>
<errorObjects xsi:type="xsd:string">
Unable to send error back.
</errorObjects>
</errorsInQueues>
<successRate>61</successRate>
<avgRespTime>0</avgRespTime>
Taking our second scenario of using the API to retrieve the logs, we need to observe that the output is documented as an octet-stream not XML or JSON. So, if we invoke the service with:
curl -u myusername:mypassword -H "Accept:application/XML" -o log.txt -X GET https://integrationtrial12345-deoracleem12345.integration.us2.oraclecloud.com/icsapis/v1/monitoring/logs/export
then we will see any empty file, as the header (-H) parameter says we want XML, but the service can only supply an octet-stream. So, correcting this to be:
curl -u myusername:mypassword -H "Accept:application/octet-stream" -o log.txt -X GET https://integrationtrial12345-deoracleem12345.integration.us2.oraclecloud.com/icsapis/v1/monitoring/logs/export
will result in a file called log.txt being populated.
Neither of these examples target specific instances of things in the environment such as an integration or a connection, and are also requests rather than commands. The API adopts the proper REST strategy by incorporating the identifiers within the URL. So, let's look at a command, for example, the activation or deactivation of an integration.
The first step is to choose an integration to activate or deactivate (the only difference being the last part of the URL is activate or deactivate). We will need the integration identifier and the version number, so if you navigate into the integration and pop up the details, you will see something like:
We will need the ICS generated identifier and the full version number of the selected integration, as highlighted in the preceding screenshot. Note that in the API documentation, the identifier is often referred to as the code. We need to incorporate these values into the URL, as the following code illustrates:
curl -u myusername:mypassword -H "Content-Type:application/XML" -H "Accept:application/XML" --write-out %{http_code} -X POST https://integrationtrial12345-deoracleem12345.integration.us2.oraclecloud.com/icsapis/v1/integrations/ROUTEDFLIG_CH7/01.00.0000/deactivate
Within the code, you may also observe several differences; the HTTP operation is now a POST rather than GET as we are issuing a command rather than asking for information. We have also added --write-out %{http_code}. This cURL parameter means that we can see the HTTP response code and response message. Without the additional write parameter, we would not get any indication of the command having been successful, or having failed. For example, as a result of using an incorrect integration, we can see the well-known 404 error as follows:
Or, in the case of deactivating the same service twice, the service deactivates correctly (resulting in a 200 code) and then the second time generates an error as the service is now no longer active, as shown in the following screenshot:
