In this Definitive Tip, we are going to look at the ability to use Versioning on Integrations to seamlessly deploy update integrations is an important requirement of any enterprise integration platform.

ICS supports the model of semantic versioning, perhaps better recognised as versioning as Major, Minor and patch.  Which is best described at

This post will demo a minor and then a major version change. So we can see how change as the behaviours change between the two. A major change indicates an likely change in definition and minor one reflects logical change.

Seeing Versioning in Action

To demonstrate versioning we need an integration that is currently active. Ideally, you will have some sort of data feed or test framework, such as SoapUI or even a simple cURL script regularly triggering the integration. We need this script running to demonstrate the impact of the cutover.

In our example we’re going to use the service from Definitive Guide #1 (DG1), but given that we are not going to really modify the service itself, this will work with any service you want.

Applying A Minor Change

With everything ready, we can start by cloning or creating a draft of our sample integration. With the clone or draft action we are presented with the Create dialog. In the dialog we can modify the version number at the major or minor levels, for example 1.00.0000 to 1.10.0000. We can complete this step using the Create button.

Version Number changed

With a new integration with same name as an existing integration. With a higher version number we can now make some modifications to the integration. The changes should be easy to spot in the demo, for example adding or changing Tracking ids.

Once the changes have been made, you can save the integration returning to the list of Integrations. The original integration is unimpaired so far, and any active calls are still showing as being handled by the version 1.00.0000 of the integration, as you can see in the next screenshot.

2 Versions of an Integration

Now, we activate the new integration. When the new integration becomes active, the older version will be deactivated. Leaving us with only 1 active integration, and we should see our test harness now triggering the modified (version 1.10) integration without having changed anything.

Major Version change

Unlike minor or patch changes, a major version change usually represents a break in the contract (service interface) and/or a change so radical in the integration it is likely to have sufficient impact on the use of the service to warrant other possible changes.  As you change will most likely demand change from the integration client(s) it becomes necessary to run both services in parrallel for a period to allow a change in usage. As a result you need ICS to support both versions running.

To illustrate the behaviour we can repeat the process of changing the integration that we applied in the minor version number change.  This time taking the version number from 1.10.0000 to 2.0.0000.  With the changes all safely applied, we will see in the integrations view the same integration with version 1.0 inactive, 1.10 active and version 2.0 inactive. Now we should activate version 2.0, rather than 1.10 being deactivated, we will see both active as shown in the next screenshot:

So the question begs, how does the invocation differentiate between the two instances?  If we look at the information for each integration we can see the answer, as we can see below:

V1.10 versioning information

V2 versioning information

As you can see the URL is different, with the URL version number having changed from/v01 to /v02. So if you trigger your test without any change we will see the v1.10 integration execute as before.  Now change the test harnesses URL to reference the v02 rather than v01 and then fire the test call. This time you’ll see your new instance execute.


As you can see we can transition integration changes without creating downtime on the endpoints. We also have a means to parallel run some integration changes.