#1116 OIC Project Deployments

Introduction

OIC Project deployments enable us to move OIC artifacts (integrations etc.) from one environment to another, e.g. from Test to Prod. Take my simple ERP Orders Project - it contains 4 integrations - 

These are simply dummy integrations, with only one, getOrder, actually using the Fusion ERP adapter.

The project has the following and a lookup - 

So these are the artifacts I will be progressing from Test to Production.

This is very easy with project deployments, which can contain all or just some of your automation artifacts.

In this simple demo, I will create an initial deployment that contains all 4 integrations. I will then add a new integration - processForeignOrders - and for this I will create a second deployment. We will then try out a few variations on this theme. Hopefully, you will then be totally au fait with Project Deployments. If not, then feel free to ping me.

  

Initial Project Deployment

I click Create -

Note how all integrations are pre-selected -

Also note the other artifacts that can be included - 

• AI Agents
• RPA Robots
• Human in the Loop
• Decisions
• B2B

Note, connections, lookups, OIC Events, libraries are included if the deployment contains integrations that use such. In my case, the lookup, CountryCodes, is currently not used in any integration.

Note also, the integration selection defaults to the current versions, we will see how this can be leveraged later.

I export the Deployment - 

Note the 2 options - export to CAR file or to repository. You need to configure a Git repository connection to avail of the latter -

I'll stick to CAR file for this post.

I go to my Prod OIC instance and import the CAR -

Open the project -

The 4 Integrations are present - 

The 2 connections are present - 

Note the Fusion ERP connection is in draft state. That's because the export/import does not include the connection configuration data, as you will normally be using different Fusion ERP instances for Test and Prod.

The lookups are empty, as no integration currently uses our CountryCode lookup.

Clicking on the Deploy tab - 

I see the V1 deployment - note the menu options here -

I click Activate - 

This will attempt to activate the 4 integrations - I expect one to fail - getOrders - as the Fusion ERP connection is still in draft mode.

So the pre-check fails for 1 integration, but the other 3 are activated. 

I fix the Fusion ERP connection and retry project activation - 

 

First, I need to deactivate and then activate - 

Now to the menu options - all are self explanatory, except maybe for Delete.

The deployment is deleted, but the project integrations etc. are still present.

I create the deployment again, just for completeness sake.

Update to Project in Test

Here I can include only new and updated integrations in each subsequent project deployment.

The line of business folks tell us we need a new integration to process foreign orders - 

It uses the countryCode lookup.

Now we create a new deployment - 

Deploy and import to Prod -

New integration is now surfaced in the Prod project -

As well as the lookup - 

How do we ensure changes made to integrations in Prod are not overwritten?

Net, net - this is OOTB - no existing combination of integration/version is  overwritten. Let's try this out by adding a new LOG action to the processForeignOrders integration in Prod - 

Back in Test, I make a change to the same integration - I add a Wait action and then create a new deployment for this updated integration.

I export and import - 

The deployment, V3, surfaces in Prod - 

However, the integration has not been updated - 

This may seem somewhat confusing to begin with, but consider we are dealing with 2 separate artifacts here - the deployment and its contents. The deployment, V3, didn't previously exist in the Prod project, so it is imported successfully. However, when importing the contents, we ensure that integrations with the same version nr are not overwritten. in respect of the processForeignOrders integration it is still tagged as version 1.0.0.

I now delete V3 in Prod.

So how do we get the update from Test to Prod? Simply by incrementing the version nr, and then deploying the updated version - 

I import to Prod - 

Note that both version 1.0.0 and version 1.0.1 (minor versions) have the same endpoint - 

/ic/api/integration/v2/flows/rest/project/AA_ERP_ORDERS/PROCESSFOREIGNORDERS/1.0/order

What's the main takeaway here? By deployment (exp/imp of projects), existing versions of integrations are not overwritten.

If I want to push changes from TEST to Prod, for existing integrations, then I need to use integration versioning.

So what's the best practice here?

What should be included in deployments? Is going the route I just described with V1, V2 and V3 the optimal way of doing things? Technically, it's possible to do it as I showed you, however, consider that deployments can be seen as a snapshot of your project, from a deployment perspective. Remember, deployments don't necessarily include all integrations in your project, but you can configure them to do so.

So back to my simple example - if the other 4 integrations in my TEST env haven't changed, why should I include them in project deployments V2 and V3? The reason is then you have a stable version of your project. If there were issues in V3 in Prod, then you could easily revert to V2. 

Let's try this out - but firstly, let's look at our new integration in Prod - 

Back in Test, let's create a new major version - 

Note, I just see the latest versions, per default - 

I could, if required, include the older version of processForeignOrders - 

I export the CAR and import to Prod.

Note the endpoint url format for version 2 of processForeignOrders -

/ic/api/integration/v2/flows/rest/project/AA_ERP_ORDERS/PROCESSFOREIGNORDERS/2.0/order


Naturally I can have versions 1.01 and 2.0.0 of this integration active at the same time. There could be many reasons for doing this e.g. backwards compatibility, different versions for different clients etc.

Lookups Lifecycle

Currently changes to a lookup in the lower environment, e.g. adding more rows, are not pushed to the higher environment.

Here's a simple example - 

I add a couple of more entries to the Country Codes lookup in my lower environment - 

I also add a new integration processLargeForeignOrders, which uses the lookup.

I create a new deployment, cloning V4 and then adding the new integration.

I check processLargeForeignOrders and export to CAR -

Import to Prod - 

Check the Lookup contents - 

As you can see, the lookup has not been updated.

Best practice for keeping lookups in sync will be discussed later, however this is a good time to look at the structure of the CAR export.

CAR export structure

The structure is simple, 1 folder per artifact type.  

The /integrations folder contains the exploded .iars -

The /lookups folder contains the DVM (domain value map) for my Country Codes lookup, as you can see, it contains the new entries - 

Lookups are not versioned in OIC, so there is just the default version, which will not be overwritten, during the CAR import.

Keeping Lookups Synced

We could leverage the OIC factory API -

Here's a simple example - export the CountryCodes lookup -

You may be tempted to then delete the lookup in Prod and then re-import it. This will not work -

{ "status": "HTTP 412 Precondition Failed", "title": "You are trying to delete the lookup 'CountryCodes'

that is used by one or more integrations

(processLargeForeignOrders | 1.0, processForeignOrders | 2.0,

processForeignOrders | 1.0.1, processForeignOrders | 1.0).

First remove the lookup from the integrations.

Then you can delete the lookup.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13" }

So we could try the update api - 

Note it must contain all entries, not just the 3 new rows.

Review the lookup in Prod - 

To be honest, that's a bit cruddy. So here's another approach - 

Save the response from the Export as a .csv file.

Then, in Prod, import - 

Great, but I need to do it in the UI.

Finally, let's try the import with a PUT instead of POST - 

The Verb is PUT and the url is as follows - 

https://design.integration.us-phoenix-1.ocp.oraclecloud.com/ic/api/integration/v1/projects/AA_ERP_ORDERS/lookups/archive?integrationInstance=yourOICInstance

The payload is - 

Let's try it out; I begin by deleting the new rows in the Prod lookup - 

I execute the request in Postman and then re-open the lookup -

Rollbacks in case of issues

The ability to rollback to a previous integration version is sometimes required.

Let's use the updateOrder integration as an example here -

I currently have version 1.0.0 in Prod. A business change is needed, so I create a new minor version in Test.

I add this to a new deployment - V6, which is cloned from V5. I then add updateOrder 1.0.1 to the new deployment -

I export/import the CAR.

The new version of updateOrder has been added to the projects, but, as you can see, it is not activated.

I can do the activation at deployment level - 

this activates version 1.0.1 of updateOrder.

After a while I get a call from the LOB folks telling me there is an issue with the new version. They want a rollback. 

I could do the following - deactivate deployment V6 and then activate deployment V5.

This, naturally, deactivates all integrations -

I then activate V5.

As you can see, updateOrder version 1.0.0 is back online.

Ergo, this "rollback" does work, but it is overkill for what is required here. I only want 1 integration deactivated, but I end up deactivating all.

In the real world the Prod admin would simply deactivate version 1.0.1 of updateOrder and then activate version 1.0.0 of the same.

Deployment via Factory API

First the housekeeping apis - 

Now to the export/import apis - 

First, the export - let's export the deployment V5.

I save the response - 

This I now use in the import - 

Project Deployments != Git

Just to reiterate, project deployments allow one to bundle related OIC automation artifacts such as integrations, connections, and lookups, in order to manage their lifecycle, activation, and movement between environments (e.g., Development to Test/Production) as a single unit.  

As you have seen, we do have push/merge, with the following features - 

• existing integrations with the same version number are NOT overwritten
• existing lookups are not automatically updated 

As opposed to git, there is currently no diffing functionality available in Projects. Net, net, I can easily view the high level contents of the deployment, e.g. V3 - 

It just contains a new minor version of processForeignOrders, however, I do not see the actual deltas compared to version 1.0.0. (e.g. new actions added, actions modified etc.)

 

Summa Summarum

Adopting OIC Projects is the key to all of the exciting new functionality available in OIC. Projects are the basis for creating your business automations going forward. Project deployment is here to make it simple for you to bundle related OIC automation artifacts such as integrations, connections, and lookups, in order to manage their lifecycle, activation, and movement between environments.