Upgrade to Oracle Integration 3: Phase 2

Enable Process with Oracle Integration 3

To use Process with Oracle Integration, an administrator needs to enable it from an Oracle Integration service instance in the Oracle Cloud Infrastructure (OCI) Console.

When enabled, a Process instance gets automatically provisioned with the Oracle Integration instance. In such a case, the two services become associated with each other and gets listed in each other's Associated services page in the Oracle Cloud Infrastructure Console.

Key points about enabling Process with Oracle Integration:

You can enable Process only with Oracle Integration 3 Enterprise Edition.
You must ensure that the user who enables Process with Oracle Integration must exist in the identity domain of the Oracle Integration instance and must have MANAGE permissions on Process.
You must ensure that you've set up the correct IAM policies to manage access to the Process instance. See Set Up IAM Policies to Manage Process Automation Instance in Administering Oracle Cloud Infrastructure Process Automation.
A Process instance provisioned with Oracle Integration cannot be deleted independently. Such an instance is deleted whenever the Oracle Integration instance with which it is associated is deleted.
A Process instance provisioned with Oracle Integration must be in the same tenancy, region, and compartment as the Oracle Integration instance. You cannot move the instance to a different compartment.

Set Up IAM Policies to Manage Process Instance

To enable Process with Oracle Integration, you need to create Oracle Cloud Infrastructure Identity and Access Management (IAM) policies that allow Oracle Integration administrators belonging to a specified IAM group to manage the Process instance.

Set up the following IAM policies for Process:

Syntax: allow group <group_name> to manage process-automation-instances in compartment <compartment_name>

Example: allow group domain_admins to manage process-automation-instances in compartment oicpa_compartment
Syntax: allow group <group_name> to read metrics in compartment <compartment_name>

Example: allow group domain_admins to read metrics in compartment oicpa_compartment

See About IAM Policies for Process Automation and Create an IAM Policy in an Identity Domain in Administering Oracle Cloud Infrastructure Process Automation.

For information on IAM policies for Oracle Integration, see About IAM Policies for Oracle Integration and Create an IAM Policy in an Identity Domain for Oracle Integration.

Enable Process

To enable a Process instance with an Oracle Integration instance:

Open the navigation menu and click Developer Services. Under Application Integration, click Integration.
From the Compartment drop-down list, select the compartment in which you want to provision and enable a Process instance with an Oracle Integration instance. The page is refreshed to show any existing service instances in the selected compartment.
Choose an existing instance or create an Oracle Integration instance and select it. The Integration instance details page opens.
Click the Enable link for Process on the Integration instance information tab.
When prompted, click Enable to confirm that you want to enable Process. Note the following:
- The Oracle Integration icon turns orange and its status changes to Updating.
- It can take several minutes for the enablement to complete.
- Once complete, that is when a Process instance gets enabled and provisioned with the Oracle Integration instance, the Oracle Integration icon changes back to green with an Active status and Process shows as Enabled.
To navigate to the Process instance that just got created, click Associated services under Resources.
Select the Process instance and view its details.

Assign IDCS Application Roles to Manage Access

After you've enabled an Process instance, assign predefined IDCS application roles to users so that they can work with the features of the Process instance.

In Process, there are two predefined IDCS application roles: ServiceDeveloper and ServiceAdministrator. These roles have to be assigned to users or groups in the Process service instance application from the Oracle Identity Cloud Service (IDCS) admin console.

Note:

The user who enables Process with Oracle Integration 3 is automatically granted the ServiceAdministrator role.

ServiceDeveloper: Any user who wants to access and work on Process Designer has to be assigned the ServiceDeveloper role.
ServiceAdministrator: Any user who wants full administrative privileges within Process including administrative tasks in Workspace has to be assigned the ServiceAdministrator role.

As a best practice, it is recommended that you assign these roles to groups, rather than individual users. For example, assign the ServiceDeveloper IDCS application role to a group in both the Oracle Integration and Process service instance applications from the Oracle Identity Cloud Service admin console. In this way it will be easier to manage user access, as any user who is a member of the group can access the Oracle Integration and Process design-time.

For information on how to assign IDCS application roles for Process and Oracle Integration, see:

Assign IDCS Application Roles to Groups in an Identity Domain in Administering Oracle Cloud Infrastructure Process Automation.
Assign Oracle Integration Roles to Groups in an Identity Domain

Now that a Process instance is enabled and provisioned with an Oracle Integration instance, and IDCS application roles assigned, you can:

Open the Process Designer and Workspace user interfaces using the Designer and Workspace URLs displayed on the Details tab of the Process instance details page.
Open Oracle Integration by clicking the Service Console button from the Oracle Integration instance details page. From the navigation menu in the Oracle Integration home page, click the punch out URL for Process. The Process Designer opens in another browser tab and you can start designing your process applications.

Export and Import Process Applications

Export Process applications from Oracle Integration Generation 2 and import them into Process on Oracle Integration 3.

Determine which applications you want to migrate.
You may want to take this opportunity to clean up unnecessary applications. Think about whether you want to migrate only those applications that are in your production environment.

If you're going to migrate individual applications, take note of the applications you want to migrate and any dependencies they have.
Migrate your applications using one of the following methods:
- Migrate all applications in bulk
  1. In the Oracle Cloud Infrastructure Console, create an Object Storage bucket. See Creating an Object Storage Bucket.
    The storage bucket URL you'll need in the next step is in the following format:
    
    https://swiftobjectstorage.region.oraclecloud.com/v1/namespace/bucket
    
    Where:
    - region is the identifier of your Oracle Cloud Infrastructure (OCI) data center.
    - namespace is the tenancy where you created your bucket.
    - bucket is your bucket name.
  2. Make a POST request to your Oracle Integration Generation 2 instance to export your applications:
    curl -X POST https://Generation2_hostname/ic/api/process/v1/exportArtifactsInternal
    
    With the following payload:
```
{
    "jobId": "enter_a_descriptive_ID",
    "storageInfo": {
        "storageUrl": "Swift_storage_bucket_URL",
        "storageUser": "OCI_Console_user",
        "storagePassword": "OCI_Console_user_password"
    }
}
```
    You’ll know the export job is complete when you see the process_status.json file in your bucket. This file contains the status of the job, its completion percentage, and, if failed, the error message. You should also see the following content in your bucket:
    - Process/project folder—contains all your process applications.
    - Process/dmn folder—contains all your decision models.
  3. After the applications have been exported into your bucket, make a POST request to your Oracle Integration 3 instance to migrate your applications:
    curl -X POST https://Integration3_hostname/process/api/v1/oic-migration/jobs/
    
    With your tenant ID:
    
    x-tenant-id: tenant_OCID
    
    And your bucket information:
```
{
    "bucketInfo": {
        "region": "region",
        "namespace": "namespace",
        "bucket": "bucket"
    }
}
```
    See Security, Authentication and Authorization in Developer API for Oracle Cloud Infrastructure Process Automation.
  4. Wait for the migration job to complete. To check the status of the migration job:
    curl http://localhost:8080/process/internal-api/v1/oic-migration/jobs/job_ID
- Migrate individual applications
  1. Export the Oracle Integration Generation 2 process applications.
    In the Oracle Integration Generation 2 instance that includes the applications you want to migrate, export each application you want to migrate. See Export an Application in Using Processes in Oracle Integration Generation 2.
  2. Import the process applications into Oracle Integration 3 Process.
    In Oracle Integration 3 Process, import the Oracle Integration Generation 2 process applications. See Import an Application in Using Oracle Cloud Infrastructure Process Automation.
    
    Oracle Integration 3 Process converts the legacy process applications to the latest product version.
Review the migration report.
When the import and conversion is complete, you'll see a migration report showing what was successfully imported, what needs additional work, and any items that couldn't be migrated. This gives you an idea of migration issues that you'll need to handle.

You can refer back to the original migration report in the main menu. See Import an Application in Using Oracle Cloud Infrastructure Process Automation.

Refactor Process Applications

Refactor Process applications to resolve validation issues. Activate the applications on Oracle Integration 3 Process.

Validate and Activate Imported Process Applications

To validate and activate your process applications, perform the following steps:

Validate each application and fix any errors and warnings.
Validate each application from the Designer by clicking and choosing Validate from the menu.

To resolve validation issues, see How Upgrade Affects Process Features.
Activate the application.
After you've resolved all validation errors, you can activate your application. See Activate Applications in Using Oracle Cloud Infrastructure Process Automation.

Map Users and Groups to New Application Roles

Application Roles have significantly changed in Oracle Integration 3. ProcessOwner, AnalyticsViewer, and ProcessReviewer roles are now explicitly defined for each application, enabling you to control their members and permissions.

The following table shows how the Oracle Integration Generation 2 roles map to the Oracle Integration 3 Process roles.

Oracle Integration Generation 2	Oracle Integration 3 Process
<application-name>.ProcessOwner	Process Owner
<application-name>.AnalyticsViewer	N/A
<application-name>.<swim-lane>	<swim-lane>
<application-name>.ProcessReviewer	Process Reviewer

The new roles are available after the migration, but you need to add members (users and groups) to them. You'll probably need to reference your Oracle Integration Generation 2 environment to see which members should be assigned to each role.

If Oracle Integration 3 Process shares the same identity domain as your existing Oracle Integration Generation 2 instance, existing users and groups should be available for selection.

You can add members either before activation in the Designer or after activation in the Workspace.

For additional information on Oracle Integration 3 Process, see Configure Roles for Process Applications in Using Oracle Cloud Infrastructure Process Automation.

Update Clients that Call Process Applications

Depending on your specific usage, you'll perform different steps to update your clients.

Perform the steps that apply to your implementation:

Integrations Calling Process

Integrations calling processes in Oracle Integration 3 will need to be updated to use the new Process action. To do this, create a new major version of your integration, add the new process action, and reference the process you want to start from Oracle Integration 3. Remove the legacy process action and activate your integration.

Integrations Called by Process

Oracle Integration 3 Process supports REST-based communication only via Service Registration. This means that connectivity to SOAP-based integrations will no longer be possible.

If you have integrations that use a SOAP trigger and these are called by processes in Oracle Integration Generation 2, you will need to take additional steps to present a REST based interface to Oracle Integration 3 Process. This may mean that you need to do one of the following:

Create REST-based wrapper integrations.
or
Change the existing trigger from SOAP to REST.

Review all the integration connections in the migrated process applications. Refresh connection metadata, ensuring that the latest definition is brought into your process application. Update any invalid data mappings and redeploy your process via a new version.

Visual Builder Applications

The developer APIs for Process and Decision application change after the upgrade. As a result, you must update any Visual Builder applications that interact with them, replacing any deprecated integration patterns. See Work with Business Processes in Building Responsive Applications with Visual Builder Studio.

To do this you may need to evaluate current process usage. Look through each of your Visual Builder applications and determine if they're making calls to developer APIs for Process via Action Chains, Direct Calls, or using embeddable process components (also referred to as CCA).

If your applications are calling Process endpoints, perform the following steps:

Connect to Oracle Integration 3 Process.
Create a backend connection to Oracle Integration 3 Process. This backend will be used to establish a connection to the new Oracle Integration 3 Process instance. See Connect to Developer APIs for Process Automation in Building Responsive Applications with Visual Builder Studio.
Create a new version of your applications.
Oracle recommends, creating a new version of your Visual Builder applications to implement required changes. See How to Create Versions of an Application in Developing Applications with Oracle Visual Builder.

Action Chains

If your application is using action chains to start a process or take action on a task, you'll need to replace each of these with a REST-based Service Connection. Repeat these steps for each process action chain task.

Triggering a Process

Replace the Start Process action chain with a Catalog based Service Connection.

Navigate to Oracle Integration Generation 2 and take note of the process you're calling. You can determine this either from the action chain process step or from the processes tab in the application menu on the left.
Create a Catalog-based Service Connection to your process in the new version of your Visual Builder application. See Create a Service Connection from an OCI Process Automation Catalog in Building Responsive Applications with Visual Builder Studio. Ensure that you select the same process you were referencing before.

Note:
Your process should already be activated.
Create a Type based on the endpoint of the above process. See Create a Type from an Endpoint in Developing Applications with Oracle Visual Builder.
Create a Variable based on the above type. See Create Variables in Developing Applications with Oracle Visual Builder.
Navigate to your action chains and perform the following actions:
1. Drag an Assign Variable Action above your current Start Process Action.
2. Map the data fields and input parameters required to invoke your process. For an example, see Integrate Oracle Process Automation with Visual Builder.
3. Drag the Call REST Action above your current Start Process Action.
4. Configure the Call REST Action by selecting the POST/Instances endpoint.
5. Map the above Variable to the request body of the REST Action.
6. Delete the legacy Start Process Acton.
Test the call, and ensure that your process is being called successfully in Oracle Integration 3 Process.

GET Process Instance

Replace the Get Process Instance action chain with a Catalog-based Service Connection.

If you created a Catalog-based Service Connection to your process by following the steps above, you'll notice that Get Process Instance endpoint is now available in your service connection.

Replace the legacy Get Process Instance Process Action with a Call REST Action that is configured with the above endpoint, and re-map the instanceID field.

Note:

The response payload values here have changed.

Other Process Actions

Perform the following steps for all other Process Actions such as Perform Task and Get Task:

Navigate to Oracle Integration Generation 2 and take note of the Process Actions you're using.

Replace these Actions with endpoint-based Service Connections.

The following table maps each of these actions to the corresponding Developer API for Process.

Visual Builder Action	Developer API for Process	Description
Perform Task	POST /process/api/v1/tasks/{id}/complete	Approval actions such as Approve, Reject, and so on.
Perform Task	PUT /process/api/v1/tasks/{id}	Update the Task Priority, Payload, Title, and such.
Perform Task	PUT /process/api/v1/tasks/{id}/payload	Update the Task Payload.
Perform Task	POST /process/api/v1/tasks/{id}/claim	Claim a task.
Perform Task	POST /process/api/v1/tasks/{id}/release	Release a task.
Perform Task	POST /process/api/v1/tasks/{id}/request-for-info	Request for information on a task.
Perform Task	POST /process/api/v1/tasks/{id}/submit-info	Submit the requested information for a task.
Perform Task	POST /process/api/v1/tasks/{id}/reassign	Reassign a task.
Get Task Collection	GET /process/api/v1/tasks
Get Task	GET /process/api/v1/tasks/{id}
Get Deployed Process Collection	GET /process/api/v1/instances
Get Process Instance Collection	POST /process/api/v1/instances

Direct Calls
The developer APIs for Process and Decision application change after the upgrade. As a result, you must update any direct service connections. See Developer API for Oracle Cloud Infrastructure Process Automation.

CCA Components

If you're using Oracle Integration Generation 2 Process CCA components, you must replace them with their equivalent Oracle Integration 3Process component.

Component Name	Oracle Integration Generation 2 CCA	Oracle Integration 3 Process Equivalent
Task List	oj-pcs-task-list	oj-opac-task-list
Task Detail	oj-pcs-task-detail	oj-opac-task-detail
App List	oj-pcs-app-list	oj-opac-applist
Start Form	oj-pcs-start-form	oj-opac-start-form
DP List	oj-pcs-dplist	oj-opac-instance-list (Displays both Structured Process and Dynamic process)
Visualization	oj-pcs-visualization	oj-opac-analytics (Cannot save visualizations)

Note:

If you have created and deployed a new version of your process, ensure that an alias has been defined for Visual Builder to call the new process.

Non-Oracle-Integration Clients

If you're calling process applications from outside Oracle Integration (for example, your own custom application), you need to update the REST endpoints and authorization policies used to call the newly configured Oracle Integration 3 Process instance. For more information on the new API endpoints and supported authorization policies, see Developer API for Oracle Cloud Infrastructure Process Automation.

Verification

Perform a System Integration Test to validate your work.

Test the connectivity to the new process environment. This test should focus on validating the following interaction patterns based on your usage:

Oracle Integration 3 Process - Oracle Integration 3 - Integrations
Oracle Integration 3 - Integrations to Oracle Integration 3 - Processes
Visual Builder - Applications to Oracle Integration 3 Process - Processes

Promote Process Applications to Production

Move the Oracle Integration 3 assets to user acceptance and production instances.

You need to deploy the new version of all the Oracle Integration 3 assets such as Process applications, Visual Builder applications, and integrations to the higher environment for validation.

Perform Switchover to Oracle Integration 3 Process

Perform the following steps:

Activate and deploy client changes to ensure that all new system-driven requests are sent to Oracle Integration 3 Process as previously described.
Communicate the new Oracle Integration 3 Process Workspace URL with users and ensure that users:
- Bookmark the Oracle Integration 3 Process workspace.
- Create new processes only in Oracle Integration 3 Process.
- Complete their new tasks in Oracle Integration 3 Process.
Retire the Oracle Integration Generation 2 applications so that no new processes can be created but the existing ones are allowed to complete. See Manage Active Applications in Using Processes in Oracle Integration 2.

Important:

From this point onwards, Oracle Integration 3 Process should handle all new requests.

Coexistence Period

When Oracle Integration 3 Process starts serving new transactions in production, you'll likely enter what is known as a coexistence period.

During this time:

New process instances will be served by Oracle Integration 3 Process.
Existing process instances will continue to run on Oracle Integration Generation 2 Process until they complete.

Note:

During the coexistence period, users must perform tasks assigned to them in both Oracle Integration 3 Process and Oracle Integration Generation 2.

During this period, Process users should:

Work primarily from the Oracle Integration 3 Process Workspace.
Occasionally check the Oracle Integration Generation 2 My Tasks List.
Rely on email-based approvals as much as possible, as the links in the emails will take them to the right place to perform the task.

The coexistence period lasts until all transactions created on Oracle Integration Generation 2 are complete. You should actively seek to shorten the duration of this period as much as possible. Here are some guidelines:

Prevent the creation of new transactions on Oracle Integration Generation 2 by using the Retire functionality. This is applicable to all structured processes that don't contain receive activities. The retire functionality prevents the creation of new instances but also allows existing transactions to complete. See Manage Active Applications in Using Processes in Oracle Integration 2.
Aim to actively expedite the completion of Oracle Integration Generation 2 instances as much as possible by following up with users to take action that sees them through to completion. You can see the number of open transactions per process and the assignee for associated tasks using a new report that is available if you navigate to Process, Administration, and then Migration Report.
For very long-running process, instances that can't be completed in several months, explore the following options:
- Recreate the instance in Oracle Integration 3 Process and use the Alter Flow functionality to update the payload and move the process instance to the current action (where it is currently in Oracle Integration Generation 2 Process). After this is done, the existing Oracle Integration Generation 2 instance can be terminated. See Alter the Flow of a Process in Using Oracle Cloud Infrastructure Process Automation.
- Modify the migrated application so that it can be initiated using the latest state of the existing Oracle Integration Generation 2 process instance.

You can track the remaining Oracle Integration Generation 2 process transactions by clicking My Tasks, then choosing Processes in your Oracle Integration Generation 2 instance. You must sign in with a user who has the Service Administrator Role.

Exit Oracle Integration Generation 2 Process

To avoid service disruption, you must plan to exit Oracle Integration Generation 2 Process by December 31, 2026. Process in Oracle Integration Generation 2 will be decommissioned on December 31, 2026.

You can move your Process applications to Oracle Integration 3 before December 31, 2026 by enabling Process in Oracle Integration 3. See Enable Process with Oracle Integration 3. For information on exporting or importing Process application design-time artifacts, see Migrate All Applications REST Endpoints.

Save runtime data from Oracle Integration Generation 2 Process. This step is important to ensure that you don't lose the history of completed transactions. You must do this before upgrade. See Archiving and Purging Process Automation Data in Oracle Integration.

As part of these steps, you'll configure the Oracle Storage Service and schedule instances for archive and purge. Be aware of the following points:

The archived information will be available in the configured Object Storage bucket.
Attachments aren't included in the archive files. You must export these manually. See Retrieve a Process Attachment as a Stream in REST API for Oracle Integration 2.