Check Upgrade Readiness and Correct Precheck Issues

Oracle periodically performs some prechecks to determine your upgrade readiness so that your upgrade runs smoothly. If the prechecks don't pass, you may need to perform tasks to correct the issues.

After you correct any precheck issues, configure your upgrade settings.

View Your Precheck Status

To see your precheck status or to run the check again, perform the following steps:

  1. In the navigation pane, click Settings, then Upgrade.

    The readiness check table shows the status of the precheck items. The precheck items are described below.

    You can see when the last precheck completed above the readiness check table.

  2. If there are prechecks that didn't pass, perform the associated tasks to correct the issues as described below.
  3. To rerun the precheck, click Check again.

    It takes about an hour for the precheck to complete.

Readiness Check Table

The readiness check table shows the following information about the status of the precheck items.

Column Description
Eligibility Condition The condition that must be met to be ready for upgrade. Some conditions include links to associated documentation.
Owner Who is responsible for managing the condition.
Due Date The date by which the condition should be met.
Eligibility Status The status of the condition, including explanations for conditions that haven't been met. Expand the More details... to see additional information about the condition failure.

Connectivity Agent Prechecks

Eligibility condition Typical owner Blocks upgrade Tasks to Complete

Agent Java Version

Development Operations team No Make sure that your connectivity agents use JDK 17 and PKCS12 KeyStore. Expand More details to see the connectivity agents that need review, or view the Connectivity Agent Status section to see the status of all the connectivity agents in your instance.
  1. For any connectivity agent that isn't already using JDK 17, install JDK 17 on the server that hosts the agent.
  2. For any agent that is still using the JKS KeyStore, convert the KeyStore to PKCS12 KeyStore. You can do the conversion in one of two ways:
    • Automatically, during upgrade: Your JKS KeyStore will automatically be converted to the PKCS12 KeyStore during upgrade.
    • Manually, before upgrade: You can convert the JKS KeyStore to the PKCS12 KeyStore manually, before upgrade, by following the steps below.
    Note

    Converting the JKS KeyStore to the PKCS12 KeyStore doesn't impact your Oracle Integration Generation 2 connectivity agent, and only takes effect after you have upgraded to Oracle Integration 3.

    If you want to manually convert your JKS KeyStore to the PKCS12 KeyStore, complete the following steps before upgrade. These tasks require you to briefly stop and then restart the connectivity agent, so choose a time when the connectivity agent isn't being used.

    1. On the server that hosts the connectivity agent, create a backup of the keystore.jks file, which is located in the following folder:

      Agent_Install_Location/agenthome/agent/cert

    2. Move the backup file to a different folder.
    3. Convert the JKS KeyStore to the PKCS12 KeyStore by running the following command from the command line:

      keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12 -srcstoretype JKS -deststoretype PKCS12 -deststorepass changeit -srcstorepass changeit

    4. Stop the connectivity agent.
    5. Delete the keystore.jks file in the following location:

      Agent_Install_Location/agenthome/agent/cert

    6. Start the connectivity agent.

Agent Connectivity for Oracle Integration 3 - Connectivity agent must be running

Development Operations team No Make sure the connectivity agent is up and running before the upgrade begins. Expand More details to see the connectivity agents that need review, or view the Agent Status column in the Connectivity Agent Status section to see the status of all the connectivity agents in your instance, indicating whether each agent is offline (unavailable).

Agents that are offline during upgrade or don't meet upgrade requirements won't be upgraded, in which case you'll need to perform post-upgrade steps to regain connectivity.

Agent Connectivity for Oracle Integration 3 - Update your allowlist settings

Development Operations team No Before upgrade, you must update your allowlist settings for your connectivity agents. Expand More details to see the connectivity agents that need review, or view the Allowlist status column in the Connectivity Agent Status section to see the status of all the connectivity agents in your instance, indicating whether the allowlist has been updated appropriately.

As your upgrade window approaches, perform the following pre-upgrade tasks:

  • Add the IP address for Oracle Identity Cloud Service (IDCS) to the allowlist.
  • Add the design-time and runtime IP addresses for Oracle Integration to the allowlist.
  • Set the proxy server's Cache property for the Oracle Integration URLs to refresh as frequently as possible.

Agents that are offline during upgrade or don't meet upgrade requirements won't be upgraded, in which case you'll need to perform post-upgrade steps to regain connectivity.

Unsupported AgentGroup Identifier

Development Operations team No If any of your agent groups have a space in their identifiers, they won't be migrated to Oracle Integration 3. If you still need the agent groups, you'll need to recreate them after upgrade.

Instance Prechecks

Eligibility condition Typical owner Blocks upgrade Tasks to Complete

Custom Endpoint URL

Administrator Yes

If you use a custom endpoint, you'll see no difference in runtime access to your integrations after upgrade. For all other access points—design-time, Visual Builder, Process Automation—you still access the custom endpoint, but the custom endpoint then redirects to the appropriate URL.

If you use a custom endpoint for your instance and your instance is failing this precheck, expand More details to see what is causing the failure:

  • Using SSL: Set up a load balancer as a front end for your Oracle Integration Generation 2 instance, and remove the SSL certificate from your Oracle Integration Generation 2 instance. See Configure a Custom Endpoint for an Instance.
  • VBCS is enabled: Oracle Integration 3 currently doesn't support Visual Builder with a custom endpoint. Wait until Oracle starts upgrades for this feature, or, if you want to move forward with upgrade now, delete the custom endpoint from your Oracle Integration Generation 2 instance.
  • Alternate Custom Endpoint used: Oracle Integration 3 currently doesn't support alternate custom endpoints. Wait until Oracle starts upgrades for this feature, or, if you want to move forward with upgrade now, delete the alternate custom endpoint from your Oracle Integration Generation 2 instance.

Instance ID Action

Administrator No The system-generated instance ID that is displayed on the Instances page and in the activity stream for an integration instance has changed from a numeric value to an alphanumeric value in Oracle Integration 3. The value's data type is unchanged; it remains a string data type. The change to an alphanumeric value may affect any systems that you use that rely on the instance ID being a numeric value. For example, if you parse the instance ID from a REST API and store the instance ID in a database as a number field, you'll need to update the database field.

If you have integrations that use instance IDs, the precheck shows a warning. Expand More details to see the integrations that need review. Then update your systems and processes as required. See Adapting to Instance ID Change when upgrading to Oracle Integration 3.

Daily Email Limit

Administrator No Oracle Integration 3 can send a limit of 10,000 emails in a rolling 24-hour window, as described in Service Limits. If your deployment needs to send more than that, you can instead use your customer tenancy. See Configure Notification Emails.

Custom scopes in IDCS

Administrator Yes Oracle Integration 3 adds a default scope (/ic/api/ , urn:opc:resource:consumer::all) to Oracle Identity Cloud Service (IDCS) when the instance is created. It doesn't support any other custom scopes added to IDCS. If you have created custom scopes in IDCS, you must remove them.

Other Failures

Varies Yes If there are any other issues that will block upgrade that don't have specific prechecks, they'll be included under other failures. Expand More details to see the issues that need action.

B2B for Oracle Integration Prechecks

Eligibility condition Typical owner Blocks upgrade Tasks to Complete

B2B Retention Period

Administrator No Although you don't need to do anything to correct this precheck status, be aware that Oracle Integration 3 Standard and Enterprise editions support 32 days of data retention by default. During upgrade only the most recent 32 days of retained data will be migrated. Expand More details to see how many days of retained data you currently have.

Integrations Prechecks

Eligibility condition Typical owner Blocks upgrade Tasks to Complete

Delayed (Asynchronous) Response

Development team Yes The delayed (asynchronous) response pattern was previously supported in the following adapters:
  • Oracle CX Sales and B2B Service Adapter
  • Oracle ERP Cloud Adapter
  • Oracle HCM Cloud Adapter
  • Oracle Field Service Cloud Adapter
  • Salesforce Adapter
  • ServiceNow Adapter
If you have integrations using delayed (asynchronous) response with one of these adapters, rework them by creating two invoke connections to achieve similar functionality:
  1. Create a simple invoke for success callbacks.
  2. Create an additional invoke for failure callbacks under the fault handler to catch the correct fault.

Expand More details to see which integrations need review.

Identity Certificates

Development team No Identity certificates establish client identity during two-way SSL communication. Connections that are based on the AS2 Adapter and the REST Adapter can use identity certificates.

Expand More details to see the names of the identity certificates and the connections that use them.

If you have identity certificates, after the upgrade, you'll need to upload new identity certificates as described in Ensure Connectivity:

Basic Routing Duplicate App Name

Development team Yes If your instance contains basic routing integrations that have the same source and target endpoint names, perform the following steps:
  1. Edit your basic routing integration, deleting the target endpoint, and adding it again with a different name.
  2. Save your integration.

Expand More details to see the integrations that need review.

Number of Active Integrations

Development team Yes An instance can have a maximum of 700 active integrations, as specified in the Service Limits.

If you have more than 700 active integrations, reduce the number by deactivating or remodeling integrations.

Multiple Read File

Development team Yes The Read Multiple File operation was deprecated in Oracle Integration Generation 2.

If you have integrations that include an operation to read multiple files, rework the integrations so that they don't use this pattern. For example, use a listFile operation to list the files, and use a for-each action to read each file individually. Expand More details to see the integrations that need review.

Publish/Subscribe Integrations

Development team Yes

If your instance includes integrations that publish messages or subscribe to messages from Oracle Integration, be aware that publish/subscribe (or pub/sub) integrations need to be converted to event-driven orchestrations. The integrations will be handled differently depending on their configuration:

  • Pub/sub integrations that use a REST adapter trigger with JSON or XML payloads are automatically converted during upgrade.
  • Pub/sub integrations that use a template parameter or a query parameter are automatically converted during upgrade. However, the parameters are removed during conversion. After upgrade, you must reimplement these parameters in the event's custom header. See Define Header-Based Subscription Filtering in Using Integrations in Oracle Integration 3.
  • Pub/sub integrations that use multipart/form-data, multipart/mixed, or binary payloads can't be automatically converted at this time. If you want to proceed with upgrade, remove these integrations, and then, after upgrade recreate them, defining custom headers for the events. If the integration uses an attachment, you can push the attachment into the FTP server or Object Storage in your tenancy and pass the reference to the subscriber flow. See Define Header-Based Subscription Filtering in Using Integrations in Oracle Integration 3.
  • Pub/sub integrations that use an adapter other than a REST adapter can't be automatically converted at this time. If you want to proceed with upgrade, remove these integrations, and then, after upgrade, recreate them. See Create Integrations to Publish and Subscribe to Events in Using Integrations in Oracle Integration 3.
  • If you see the error Only Subscribers are present, no Publishers, you have orphan subscribers that must be deleted before upgrade.

Expand More details to see the integrations that can't be automatically converted.

Note: You might want to take this opportunity to delete any draft Publish flows.

DT API Basic Auth to OAuth action

Development team No If your instance includes integrations that access DT (design-time) built-in APIs using a REST connection with basic authentication, you must change them to use OAuth.

In Oracle Integration Generation 2, you could use Basic Authentication to use the Oracle Integration REST API and File Server REST API. In Oracle Integration 3, you must use OAuth. You need to update any clients, scripts, integrations, and commands that use the Oracle Integration REST API or the File Server REST API to connect using OAuth. For more information on authentication method support, see When is Basic Auth Supported in Oracle Integration 3. For details on using OAuth with the Oracle Integration REST API, see Security, Authentication, and Authorization, or with the File Server REST API, see Security, Authentication, and Authorization.

XSLT function definition

Development team Yes Custom XSLT function definitions that were added manually in the mapper aren't supported at this time. You can wait for Oracle to add support for this functionality, or, if you want to proceed with upgrade now, rework or remove the integration.

Expand More details to see the integrations that include custom XSLT function definitions.

Adapters Prechecks

Eligibility condition Typical owner Blocks upgrade Tasks to Complete

Custom Adapters

Development team Yes If your instance includes integrations that use a custom adapter, the instance can't be upgraded yet. Wait until Oracle starts upgrades for this feature. Expand More details to see the custom adapters you're using.

Oracle Utilities Adapter

Development team No Swagger 2.0 is no longer supported in the Oracle Utilities Adapter. If there is any existing integration using the Swagger 2.0 REST catalog, runtime won't be impacted. However, if you try to edit the design-time connection, retest the connection, refresh the metadata, refresh the artifacts, or reactivate, the integration fails. You must update the catalog to use the OpenAPI 3.x definition. Expand More details to see the integrations that need review. See Using Swagger 2.0 REST catalog with Oracle Utilities Adapter version 24.04.0 or higher.

Unsupported Adapters

Development team Yes If your instance includes an integration that uses one of the following adapters, which aren't supported in Oracle Integration 3, replace the adapters with the REST adapter:
  • Automation Anywhere Adapter
  • Evernote Adapter
  • Oracle Messaging Cloud Service Adapter
  • Oracle Monetization Cloud Adapter
  • Oracle Taleo Business Edition (TBE) Adapter
  • UiPath Robotic Process Automation Adapter

Expand More details to see which unsupported adapters you're using.

Note that robotic process automation (RPA) capabilities are available in Oracle Integration 3. See Learn About Robots and Build a Robot in Using Robots in Oracle Integration 3.

Unsupported REST Types

Development team No The following connection types are deprecated and not supported in a REST Adapter connection. Replace these connection types with different connection types. See Configure Connection Properties for Invoke Connections in Using the REST Adapter with Oracle Integration 3.
  • Metadata Catalog URL
  • Swagger Definition URL
  • RAML Definition URL

Expand More details to see which unsupported REST types you're using.

Developers with a REST API that is described using RAML or the Oracle metadata catalog must take the following action:
  1. Consult your REST service provider and ask for a Swagger definition (if available). Oracle Fusion Applications should have a Swagger option available. This is a guideline for all Oracle Fusion Applications.
  2. If an alternative spec is not available, use the basic template in the REST Adapter by selecting REST API Base URL as the connection URL and defining the target API request using the Adapter Endpoint Configuration Wizard.

Another option is to convert RAML into an OpenAPI specification to use with the REST Adapter connection.

To provide more robust and complete support for the Swagger/OpenAPI specifications, the REST Adapter includes a unified option to specify all OpenAPI specifications in a single field. This option also replaces the option to provide a Swagger definition URL, which is no longer available.

Visual Builder Prechecks

Eligibility condition Typical owner Blocks upgrade Tasks to Complete

VBCS

Administrator Yes If you use Visual Builder with your own Oracle database instance (BYODB), Autonomous Transaction Processing (ATP) must be up and running during upgrade.

Make sure to complete the additional Visual Builder Pre-Upgrade Tasks.

VBCS-PWA

Administrator Yes Oracle Integration 3 doesn't yet support Progressive Web Apps (PWAs) created with Visual Builder. To see which apps are blocking upgrade, expand More details.
If you want to proceed with upgrade:
  1. Delete those apps.
  2. Rerun the precheck.
  3. After upgrade, recreate the apps.
  4. Make sure that any devices running the apps uninstall the old apps and install the new ones.

Process Automation Prechecks

Eligibility condition Typical owner Blocks upgrade Tasks to Complete

Process Automation

Administrator Yes

There are several differences between Process in Oracle Integration Generation 2 and Process Automation in Oracle Integration 3. See Process FAQs.

Depending on how you're using Process in Oracle Integration Generation 2, you'll use a different option to upgrade or migrate. See Process Upgrade Options.

Process Action

Administrator Yes

If you're using the Process action in any integrations, you'll need to replace or remove the Process action prior to upgrade. Use the method described in the Process upgrade option that applies to your situation.

Correct an Instance with Failed Readiness Checks

If your upgrade was scheduled and your instance is no longer ready for upgrade, address the findings so that your upgrade completes successfully.

  1. In Oracle Integration, open the Upgrade page using one of the following steps:
    • In the navigation pane, click Settings, then Upgrade.
    • Click Announcements Announcements icon, and then click the link in the notification.
    The Upgrade page appears.

    The screenshot shows the Upgrade page with a message indicating that the readiness check failed, followed by a list of eligibility conditions and their status. There is a Check again button to re-run the readiness check.

  2. Review the conditions that didn't pass, and take the appropriate action. See Check Upgrade Readiness and Correct Precheck Issues for steps to take.
  3. After addressing all issues, check the instance again.
    1. Click Check again.
      It takes about an hour for the check to complete. You can see when the last check completed above the readiness check table.
    2. Continue making corrections until the check passes.
      If you aren't sure how to correct an issue, enter a service request (SR) on My Oracle Support.