Some ICS API scripts for doing useful things

ICS Rest API

ICS has had a REST API since April, and I have developed some quick and useful scripts that I would like to share.

You can see the REST API documentation here: http://docs.oracle.com/cloud/latest/intcs_gs/ICSRA/

About these scripts

They’re all implemented with Python 3.5 and pycurl. Get python here: https://www.python.org/downloads/release/python-350/ and pycurl here: http://pycurl.io/. Note that on Linux, you’ll probably have both of these readily available in your distribution. Sadly, this post cannot be a technical support post for installing python and pycurl on Windows.

They use python regular expressions: https://docs.python.org/3/library/re.html#regular-expression-syntax. The default regular expression matches NOTHING- this is by design, you can run these scripts to test connectivity and they won’t do anything else by default, except verify you can connect and download the relevant resources (list of integrations or list of connections).

Help

I tried to make them usefully helpful by themselves (--help works), but here’s a brief overview of each script and it’s intentions.

Logging

All output is logged to a log file (output.log is the default, and you can use --logfile=[whereever] to change it), and --log=DEBUG will enable a lot of additional debugging information if something isn’t working or you want to see the details of the json being exchanged between client and server.

Common parameters

• [baseurlforicsserver] is the base url for your ICS server. This is the URL without the /ics/faces/global suffix. For example for the ICS instance https://ateamics-thisissecret.integration.us2.oraclecloud.com/ics/faces/global you would use https://ateamics-thisissecret.integration.us2.oraclecloud.com
• [userwithicsadminpermission] is a user identity in ICS with administrative permissions
• [password] is their password
• [pattern] is a python regular expression, with an optional field prefix: 'name:.*' will apply the regular expression .* to the “name” field of the integration (name is the default field if none is specified); 'lastUpdatedBy:christian.*' would apply the regular expression christian.* to the field “lastUpdatedBy”

Download

The scripts can be downloaded here: http://www.ateam-oracle.com/wp-content/uploads/2016/06/icsapiscripts.zip

Exporting and cleaning up integrations

First up, a script for exporting and cleaning up ICS integrations. ICS can sometimes get a bit cluttered, with people popping up test integrations left and right to try different things. This isn’t necessarily a great state of affairs, so this script is useful – it lets you use a regular expression against a particular field in the ICS JSON to identify integrations you wish to deactivate, export and potentially delete. Export functionality is always enabled – this script will always export the integrations it matches, however, deactivation and deletion are optional toggles that can happen as well. (Deactivation if enabled is done before export, and deletion if enabled is done after export).

./exportintegrations.py [pattern] --exportdir [directorytoexportto] --server [baseurlforicsserver] --user [userwithicsadminpermission] --pass [password]

• [directorytoexportto] is a directory name. If it doesn’t exist it will be created. All matched integrations will be exported to this directory, as IAR files, the same as if they had been exported from the web console

There’s a couple more arguments that toggle various functionality:

• --deactivate will deactivate all the integrations that match
• --delete will also delete all the integrations after exporting them.

Cleaning up connections

Second up, a connections cleanup script. This is much akin to the first script, it is designed to cleanup an environment that’s become full of experiments. However, connections have no export capability so they can’t be backed up for safe keeping (this is as much by design as an oversight – connections encode secrets such as credentials to other systems, and as such, being able to export them would be a significant security risk).

./cleanconnections.py [pattern] --server [baseurlforicsserver] --user [userwithicsadminpermission] --pass [password]

It takes the common arguments and a --delete argument will actually perform the delete operation. Without it it’ll simply log what it would delete based on your pattern matching.

Bouncing integrations

Finally a bounce script. This script will bounce every integration that matches, by issuing a deactivate followed by an activate request. This may be useful on occasion. Again, it takes the common arguments.

./bounceintegrations.py [pattern] --server [baseurlforicsserver] --user [userwithicsadminpermission] --pass [password]

Summary

As you can see, the ICS REST API is already useful for doing some interesting tasks that are painstaking when using the UI. I hope to expand on it in the coming weeks to more useful tasks, like automatically tracking development in ICS using source code control.

All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission