OIC Gen2 to OIC Gen3 migration: a Club Med success story

Since August 2022, the Gen3 version of Oracle Integration Cloud (OIC) has been available, offering new features and performance enhancements. The migration from Oracle Integration Cloud (OIC) Gen2 to Gen3 is a crucial step for companies using this platform.
Encouraged by Oracle, it will soon become mandatory.

This article guides you through the main stages of this migration, the successful experience of Club Med, world leader in all-inclusive vacations, in its transition to OIC Gen3.

Step 0: Define an OIC Gen2 to Gen3 migration policy

Oracle plans to migrate all instances at the same time, both production and non-production.
However, in the case of Club Med, we opted for a customized approach:

• External integrations: All integrations are called up from the outside via a central orchestrator that manages Club Med’s various multi-application flows.

• API Gateway: Need to test the API Gateway, as Gen3 documentation is insufficient.

• Continuity of services in production: Avoid any risk of production interruption lasting more than 24 hours.

• Specific development needs: Rapid transition of development instance to Gen3 to benefit from project-based access segregation.

Context

Club Med has both non-production and production instances. To minimize risk, we decided to :

• Migrate non-production instances first to perform all necessary tests and corrections.
  Maintain a development instance in Gen2 to ensure continuity of delivery (see Focus #3).

• Plan migration over a long period to test as many interfaces as possible and limit production errors

To implement a non-standard migration strategy, as described, you need to contact Oracle support via a service request (SR).

We recommend you to be as clear and explicit as possible in your request, and ask for confirmations to ensure that you are correctly aligned.

Step 1: Meet the migration eligibility criteria

To ensure the success of the Oracle Integration Cloud Gen2 to Gen3 migration, Oracle has provided a list of prerequisites. This list indicates the impact of the migration at different levels (instance, integration, adapter, connectivity agent, etc.) and the actions to be taken in order for the migration to be successful.

Oracle also provides an automated verification page directly on each of your OIC instances (accessible via Settings > Upgrade). Oracle automatically runs tests to verify the eligibility of each of your instances according to the prerequisite domains, and notifies you via a table of blocking alerts.

All these prerequisites and the associated actions to correct them can be found in the Oracle documentation.

We recommend that you review all these prerequisites to get an overview of the changes, even if, according to the automatic check described above, they don’t apply to you.

Here’s an example of the alert you’ll get on this console: the connectivity agents must be up and running during the upgrade. They must also use JDK 17 and PKCS12 KeyStore. A list of unsupported adapters in Gen3 is also provided.

Step 2: Planning and preparation for OIC migration

Once you’ve validated all the required actions and taken note of the operating changes after migration, you can check whether your instance is ready to be migrated from the same “Upgrade” section in OIC’s “Settings”.

Planning your Oracle Integration Cloud migration

Information on your upgrade date will be available on OIC in this same section, as well as via a banner on the home page. This will take the form of a countdown timer. Oracle will also send an e-mail to instance administrators specifying the time slot during which the migration will take place. Please note that the latter method of notification is not the most optimal. We recommend that you follow the information available on the instance.

If, however, you receive contradictory information, quickly create an SR to Oracle Support to clear up any ambiguity. Include a screenshot of your instance and the e-mail you received. They’ll be able to react quickly and correct the misalignment.

The upgrade date defined by Oracle can be modified if it is more than 3 working days away from the current date. Be careful, plan ahead. It can take up to a month to get a new slot.

Platform administration activities

Once you’ve planned your migration, you’ll need to review some of its parameters. For example, if your instance has connections that use identity certificates, you need to check the “Ignore identity certificates during upgrade eligibility check” option. These will have to be reimported after migration.

These parameters can be used to define the procedure to be followed in the event of failure (failure to activate integrations, failure to program integrations, etc.).

In addition, the IP addresses of the instance after migration will also be visible two weeks before the scheduled date, in order to update the authorization lists.

Please note that activity data from integration instances on Oracle Integration Cloud Gen2 is not migrated to Gen3. To preserve them after migration, it is possible to capture the activity flow of integrations from the OIC console or via the monitoring APIs.

As we did with Club Med, we recommend creating a backup of your instance on a pre-created bucket.

Unavailability

It’s also important to note that there will be a period of downtime during the migration. Any call to an integration (asynchronous or synchronous) during this period will be rejected. The console should be considered switched off. Processing of incoming requests will resume once the migration is fully complete. For scheduled integrations, integrations planned in the future will resume their launch as previously set up on Oracle Integration Cloud Gen2 prior to migration.

Communication

Once you have received confirmation of the migration, it is advisable to notify all those affected (users, developers, etc.) and provide them with at least the following information:

• The migration date and time slot during which the instance will be unavailable. Allow some contingency so that you can perform a batch of sanity checks on the typical integrations you have on your instance. The time slot is generally 2 hours, but you should allow at least half a day.

• Limit developments to 2 days before the scheduled date: it’s best to stop creating, modifying and activating integrations before the migration date, to limit the chances of the upgrade being cancelled.

Step 3: OIC Gen2 to Gen3 migration

Limiting the number of modifications is necessary to ensure that all the conditions required for migration are maintained. In fact, new developments can be a source of failure for previously validated prerequisites. Errors on launched instances may prevent migration, but it is possible to specify that migration will continue in this case when programming.

You are also asked to ensure that all running instances are terminated, and to disconnect from the instance before migration begins.

Once the migration is complete, Oracle sends an e-mail to the administrators to inform them.

Step 4: Post-upgrade actions

Once the migration has been successfully completed, a number of checks and actions need to be carried out. First, it’s important to test access to the new OIC Gen3 instance. The Gen2 URL redirects to the new Gen3 instance URL. It is also advisable to ensure that all integrations that need to be activated are actually activated.

If an Oracle Cloud Infrastructure Identity and Access Management (IAM) rule was defined to access the Gen2 instance based on an ID (Oracle Cloud ID (OCID)) that uniquely identifies an instance, it is necessary to update this information. The new OCID is available on the Oracle Cloud Infrastructure console.

When using Visual Builder on Gen2, it is also expected to create a new IAM rule to allow the OIC administrator group to manage the Visual Builder instance.

If you have connections based on identity certificates, as mentioned above, these are not migrated, so you need to provide new certificates.
Once you’ve tested the connections concerned, you need to reactivate any integrations that use them.

In addition, the connection information (IP address and port) to the OIC SFTP server have changed.
You can retrieve them in the following section: Settings > File Server > Settings.

Although the values linked to the Gen2 instance are valid for 4 months after migration, it is recommended to update SFTP clients and OIC SFTP connections.

Once you’ve successfully completed all these steps, you’ll be ready to use the new OIC Gen3 instance!

Points of attention

The switchover to OIC Gen3 brings with it a number of changes that need to be taken into consideration, as they are likely to cause malfunctions.

Our step-by-step methodology has enabled us to highlight and correct these errors more serenely.
Here are a few of them…

The instance ID is no longer a number

On OIC Gen3, the instance ID is no longer a number but a character string. This can lead to conversion errors if the values taken by this meta-data are stored in the database as numbers (type NUMBER). To remedy this, it will be necessary to change the type of the columns storing this value to VARCHAR.

This change is also problematic for developed REST APIs that would return the instance ID as a number in response. Indeed, an integration whose REST trigger is configured with a return as shown in the image on the left will cause an error because the instance ID cannot be parsed correctly.
To solve this problem, simply modify the return sample by enclosing the instance ID value in quotation marks, as shown in the image on the right:

Change of authentication method for calls to Oracle Integration REST APIs

On Oracle Integration Cloud Gen3, it is no longer possible to use any authentication method other than OAuth2 to call Oracle Integration REST APIs. As a result, if your integrations contain nodes that invoke Oracle’s REST APIs, an error will be returned if the connection used to make this call is configured with the Basic Authentication method or a method other than OAuth.

A number of changes need to be made. First of all, on Oracle Identity Cloud Service, you need to register a “Trusted Application” through which it will be possible to call Oracle’s REST APIs. The authentication type to be defined for this application is “Client Credentials”. It will also need to be assigned one or more OIC roles (ServiceAdministrator, ServiceDeveloper etc.). To create and configure this application, you need to be a domain identity administrator or application administrator.

The connections used for these calls must then be modified. In particular, the security policy must be changed to match OAuth (OAuth Client Credentials), and the access token URI, Client ID, Client Secret and scope must be filled in. These information comes from the created application. OIC then independently handles access token requests each time an Oracle REST API is invoked.

Impossible to migrate a modified integration from Gen3 to Gen2

If an integration is modified, i.e. an element is added or changed, or if an integration is created on OIC Gen3, it cannot be imported on an instance of the previous version (OIC Gen2). This feature is important when you are not migrating the production environment at the same time as the “non-production” environments.

What’s more, the development environment is usually migrated before the test environment, so if you have ongoing developments and regular deliveries, this is an important consideration.

However, it is possible to migrate integrations created or modified on the OIC Gen2 instance to OIC Gen3.

To get around this problem, there are two options:

• The addition of a development instance, the old and main one on the OIC Gen3 version and a new one on the OIC Gen2 version.
  The latter would have to be decommissioned after use.
  Please note that if you choose this option, you’ll need to review your delivery processes.

• If you have a second non-production instance used for UATs, for example, you can upgrade this one, then the production one and finally the development one.

By choosing either option, you’ll be able to develop on the OIC Gen2 version and deliver your integrations developed on this version to your UAT (Gen3) and production (Gen3) environments.

Although it can appear complex, this migration can be successfully carried out thanks to rigorous preparation and good communication.

Our experience with Club Med shows that with a personalized approach and the right support, the benefits of OIC Gen3 can be fully exploited.