Good development practises such as  configuration management and naming conventions have been a topic of conversation a number of times recently for us when it comes to ICS. In this post we will look at what configuration management means to ICS and the application of naming standards.

Why Configuration Management?

So why do we need configuration management with a tool such as ICS? The question depends on what stage of the software lifecycle you are, but a few reasons:

  • As a developer there have been occasions where we have tried to optimise something and then decided to reverted back to the last secured state in configuration control.
  • Deleted something and then regretted it, whilst desktops have the concept of paper basket to recover from, not so in ICS.
  • If your providing packages of ICS functionality you may have different released versions – so need to keep master copies of every version available to refer to.
  • Sometimes we get ‘configuration drift’ – and therefore need to have a reference point to compare to. This allows us to determine the drift and if it is appropriate to reset an environment. Whilst this may sound less significant, it is enough of a problem for tools like Puppet to incorporate the ability.
  • Tracking what versions of integrations are running in a development vs production environment.

The following diagram shows the development lifecycle and where these scenarios fit.

Configuration management life cycle

Whilst it is possible to achieve a configuration control by managing assets through the use  of just a filing system; using a repository allows you to track who applied the changes, when and create tags to label significant versions. Not to mention that not many file systems are easy to  share or handle change conflict. With many of the cloud offerings, Oracle will provide Developer Cloud Service which includes a GIT repository.

Whilst neither GIT or SVN are recommended solutions for binary artefacts (more on this here) it is a solution within the Oracle ecosystem.

Artefacts In and Out of ICS

So how do you get the content of ICS to and from a configuration repository? ICS provides the means to export integrations or packages either manually or through scripting of the REST API. For example to retrieve an integration we can use a CURL command like the following:

curl -X GET -u jstein:welcome1 -H “Content-Type:application/json” -o ./TestProject.iar https://integration.us.oraclecloud.com/icsapis/v1/integrations/TEST/01.00.0000/export

As you can see we call the export operation on the TEST integration with a version of 01.00.000 and direct the output to a file called TestProject.iar.  This file can then be checked into GIT.  As explained in the book, .iar files are a form of zip file, so binary in nature.  Being able to use GIT or SVN to perform differences is not really an option directly.  However their are tools which can be used to compare the contents of ZIP files, for example:

Correspondingly the REST API also allows for imports (load into) ICS with commands like:

curl -X PUT -u jstein:welcome1 -H "Content-Type:application/json" \
-F file=@"TestProject.iar;type=application/octet-stream" \
https://integration.us.oraclecloud.com/icsapis/v1/integrations/import

This time we tell ICS to read the file as an octet stream using cURL (as it is binary) – note that we don’t address a specific integration in the target URL. The other thing to be aware of is whether the import is creating or replacing an integration. This is differentiated by the use of PUT (replace) vs POST (create).

Automating a full snapshot

Whilst the two examples show how you can retrieve (export) and upload (import) specific integrations.  You also need to get hold of all the integrations to automate the snapshot of an environment. Necessary as it is so easy to develop changes and forget to snapshot or baseline the integrations.  so you might want to periodically snapshot the entire set of integrations within your ICS environment.

This can be done coupling the REST API that allows us to retrieve a list of integrations, and then the results can be iterated over.  The following API will retrieve that list:

curl -X GET -u jstein:welcome1 -H "Content-Type:application/json" -o integrationList.json https://integration.us.oraclecloud.com/icsapis/v1/integrations

This will provide a json file called integrationList.json over which we then need to retrieve the self elements as they point to the URL of the integration to export. If you look carefully you can also see the lastupdated stamp in each integration description. This could be used to tune the snapshot to just retrieve those integrations that have changed. But be aware, this information maybe reporting in a different timezone to the timezone your script will be comparing with.

Tracking Between Development and Production

With the ability to import and export integrations. There are several options for tracking the versions of integrations between environments. the simplest, but also the most susceptible to error, is simply compare CRC values on the .iar file with you your GIT version. More elegant would be to actually annotate the contents of the .iar file (we would suggest the Description element in the PROJECT-INF/project.xml file). This does create the issue of opening up the .iar to apply the annotation and dependency .iar file structures not changing.

Coding Standards

Industrialization of development goes beyond configuration management, and should consider things like coding standards? The question may beg, why do we need such things when you do not code? It is true ICS does not involve coding in the traditional sense (although the introduction of JavaScript capabilities will start to change that); but coding standards include simple things like naming conventions – and we certainly name things in ICS.

Let’s step back, why do we have coding standards? We use such standards to drive consistency and ease of understanding across a team and over time, this holds true for ICS equally as much as a traditional development platform and even system configuration.

You’ll note through the book we adopted a camel case approach for readability and post fix in the names to indicate the associated chapter. This point is underlined by several posts on the SOAJavaPoint blog suggesting conventions.  The important thing is to agree with everyone involved the standard and comply to the agreed standard.

If you are creating JSON definitions, XML schemas, and SOAP endpoints for your integrations you should consider your guidelines for naming there as well.  We typically followed XML conventions in the book.

Checking on Naming Compliance

With the ability to export the integrations.  Compliance can be done by unpacking the .iar file and then running some basic parsing on the configuration files. With the .iar file unpacked applying XQuery to locate the relevant elements within a configuration file along with a REGEX path and it would be easy to validate whether people are applying the conventions or not. Within Chapter 13 of the book we actually looked at the breakdown of the .iar file.

Related Posts