Upgrade to the latest version of Platform 6

Upgrade your Itential Platform installation to the latest version. This guide covers upgrades within Platform 6 and migrations from earlier platform versions (2022.1, 2023.1, 2023.2) to the latest version of Platform 6.

Before you begin

Review these resources before upgrading:

Platform 6 deprecations

Features and APIs removed in Platform 6

Platform 6 breaking changes

Changes that may impact your installation

Feature release announcements

New features in Platform 6 releases

Maintenance release notes

Bug fixes and improvements

Need help? Contact your Itential Account Manager for assistance establishing an upgrade plan.

Choose your upgrade path

Current version	Target version	Upgrade path
Platform 6.x.x	Latest Platform 6	Upgrade within Platform 6
Platform 2022.1, 2023.1, or 2023.2	Platform 6	Migrate to Platform 6

Upgrade within Platform 6

Upgrade from an earlier Platform 6 version to the latest Platform 6 release.

Prerequisites

Repository access — Access to the Itential repository (contact your Itential Account Manager if needed).
Server access — Root or sudo access to your server.
Release review — Review release notes and dependency changes for the target version.
Backup — Back up your MongoDB database and configuration files.

Prepare for upgrade

Stop running jobs

Choose one of these options:

Option 1: Verify no jobs are running

Check Operations Manager for active jobs.
Wait for all jobs to complete.

Option 2: Disable new jobs

Disable task and job workers in Admin Essentials.
Wait several minutes for running tasks to complete.

Verify custom code location

Confirm your custom code location:

Default location: /opt/itential/platform/services
Custom location: Check your configuration.

The upgrade updates only the server folder and continues to serve adapters and apps from the services directory.

Back up the database

$ mongodump --db=itential --out=/backup/mongodb/$(date +%Y%m%d)

Back up configuration

$ sudo cp /etc/itential/platform.properties /backup/platform.properties.$(date +%Y%m%d)

Download the installation package

Access the repository

Download directly from your organization’s Itential repository portal. If you need credentials, contact your Itential Account Manager.

Download the RPM

Download the RPM file named itential-platform-6.x.x.rpm, where 6.x.x is the target version number.

Copy to the server

Copy the RPM to your server. Use /tmp as it is accessible to all users:

$ cp itential-platform-6.x.x.rpm /tmp/

Verify file permissions

Ensure the file is readable by the service user:

$ ls -la /tmp/itential-platform-6.x.x.rpm

Find the service user

The installation package must be readable by the user that runs the itential-platform service.

Option 1: Check the service file

$ sudo systemctl status itential-platform

The output shows the service file location, typically /etc/systemd/system/itential-platform.service. Open the file to view the User parameter.

Option 2: Check the server directory

$ ls -la /opt/itential/platform/server

The owner shown is typically the service user.

Run the upgrade

Stop the Platform service

$ sudo systemctl stop itential-platform

Install the new version

$ rpm -Uh /tmp/itential-platform-6.x.x.rpm

The output shows progress:

Preparing...                          ################################# [100%]
Updating / installing...
   1:itential-platform-6.x.x          ################################# [100%]

Start the Platform service

$ sudo systemctl start itential-platform

Verify the upgrade

Check that the service started successfully:

$ sudo systemctl status itential-platform

A successful result shows the service as active:

itential-platform.service - Itential Platform Service
     Loaded: loaded (/etc/systemd/system/itential-platform.service; enabled; vendor preset: disabled)
     Active: active (running) since Fri 2025-10-10 14:23:15 UTC; 5s ago
   Main PID: 12345 (node)
      Tasks: 23 (limit: 23449)
     Memory: 256.8M
     CGroup: /system.slice/itential-platform.service
             └─12345 node server.js

Verify in the UI

Platform is accessible.
Version number is correct (check Admin Essentials).
Workflows and automations function properly.

Troubleshoot upgrade issues

If the upgrade fails or the service does not start:

Check service logs

$ sudo journalctl -u itential-platform -n 100

Check platform logs

$ tail -f /var/log/itential/app.log

Verify file permissions

$ ls -la /opt/itential/platform

Check the database connection

$ sudo systemctl status mongod

Restore from backup if needed

If the upgrade cannot be resolved, restore from backup and contact Itential Support.

Migrate to Platform 6

Migrate from Platform 2022.1, 2023.1, or 2023.2 to Platform 6.

Platform 6 organizes files differently than earlier versions. To avoid conflicts, Itential recommends installing Platform 6 on a new or clean system and migrating your data, rather than upgrading your current installation directly.

Migration overview

The migration process involves:

Installing Platform 6 on a new or clean system.
Migrating encrypted secrets from your existing database.
Migrating custom apps and adapters.
Migrating configuration settings.

Install Platform 6

Platform 6 installation guide

Follow the complete Platform 6 installation instructions

After installation, proceed with data migration.

Migrate encrypted secrets

Platform 6 requires an encryption key for operation. Use the key migration utility to migrate encrypted secrets from your existing database.

Before you migrate

Critical prerequisites:

Back up your MongoDB database — the utility modifies the database directly.
Back up your properties.json file — the utility modifies encrypted values in place.
Prepare to migrate all collections at once — the utility cannot be run multiple times on a single database.

If migration is interrupted, restore from backup and run the utility again.

Run the key migration utility

Navigate to the server directory

$ cd /opt/itential/platform/server

Choose a configuration method

Select the method that matches your setup:

Method 1: Using platform.properties file

$ npm run key:migrate -- \
>   --config-file /etc/itential/platform.properties \
>   --encryption-key "$KEY"

Method 2: Using legacy properties.json file

$ npm run key:migrate -- \
>   --properties-json ./properties.json \
>   --encryption-key "$KEY"

Method 3: Using environment variables

$ ITENTIAL_MONGO_URL=mongodb://127.0.0.1:27017 \
> ITENTIAL_MONGO_DB_NAME=itential \
> npm run key:migrate -- \
>   --config-file /etc/itential/platform.properties \
>   --encryption-key "$KEY"

Replace $KEY with your encryption key.

Migrate custom collections (optional)

If you have custom collections with encrypted values:

$ npm run key:migrate -- \
>   --encryption-key "$KEY" \
>   --properties-json ./properties.json \
>   --extra-collections custom-collection-1 \
>   --extra-collections custom-collection-2

Review the output

Verify the migration completed successfully by checking the output.

Migrated collections

The utility migrates these collections by default:

service_configs — Service configuration data
oauth_clients — OAuth client credentials
accounts — User account information
iap_profiles — Platform profiles

Understand migration output

The migration utility reports progress as it runs.

Example output:

> @itential/iap@6.0.0 key:migrate
> node utils/keyMigrate.js --encryption-key [KEY] --properties-json ./properties.json
Collection service_configs migrated document 1 with _id 67c07c608998f13133c9ba97 pointer /properties/properties/database/url
Collection service_configs: Successfully replaced 1 of 1 documents
Collection accounts migrated document 1 with _id 67c07c8da129bb3309dddbb3 pointer /gitTokens/GitHub
Collection accounts: Successfully replaced 1 of 1 documents
Decryption recheck validated -- key migration successful!

Success indicators:

Each collection shows “Successfully replaced X of X documents.”
Final message: “Decryption recheck validated — key migration successful!”

After successful migration, connect Platform 6 to your existing database.

Migrate apps and adapters

Platform 6 stores custom applications and adapters in a different location than earlier versions.

Platform 6 default location:

/opt/itential/platform/services

Earlier versions location:

/opt/itential/current/node_modules/@itentialopensource

Configure a custom location (optional)

Option 1: Configuration file

Set the service_directory property in /etc/itential/platform.properties:

1 service_directory=/custom/path/to/services

Option 2: Environment variable

$ export ITENTIAL_SERVICE_DIRECTORY=/custom/path/to/services

Option 3: Admin Essentials

Edit the serviceDirectory field in your active profile through Admin Essentials.

Copy custom code

Locate custom code

Find your custom apps and adapters:

Open-source adapters: /opt/itential/current/node_modules/@itentialopensource
Organization-managed code: Consult your system administrator.

Copy to Platform 6

$ cp -r /path/to/custom/apps/* /opt/itential/platform/services/

Set file ownership

$ sudo chown -R <service-user>:<service-group> /opt/itential/platform/services

Verify the migration

Restart Platform and verify custom apps and adapters load correctly:

$ sudo systemctl restart itential-platform

Migrate configuration

Platform 6 deprecates the properties.json configuration file and introduces new configuration methods.

Configuration options in Platform 6

Method	File location	Recommended	Notes
platform.properties file	`/etc/itential/platform.properties`	Yes	Preferred method for Platform 6
Environment variables	System environment	Yes	Override file-based configuration
Database profiles	MongoDB	Legacy	Supported for backward compatibility
properties.json file	`/opt/itential/platform/server`	No	Deprecated, not recommended

Platform 6 continues to support database profiles and the legacy properties.json file, but Itential recommends transitioning to environment variables or the platform.properties file.

Create the platform.properties file

Copy the template

$ sudo cp /opt/itential/platform/server/utils/template.properties /etc/itential/platform.properties

Edit the configuration

$ sudo vi /etc/itential/platform.properties

Set the database connection

1 mongo.url=mongodb://127.0.0.1:27017
2 mongo.db_name=itential

Set the encryption key

1 encryption.key=your-encryption-key-here

Configure a custom service directory (optional)

1 service_directory=/custom/path/to/services

Set file permissions

$ sudo chown <service-user>:<service-group> /etc/itential/platform.properties
$ sudo chmod 600 /etc/itential/platform.properties

Continue using properties.json (not recommended)

If you must continue using properties.json, place it in the Platform 6 server directory:

$ cp properties.json /opt/itential/platform/server/

The properties.json file is deprecated. Migrate to platform.properties or environment variables for better security and maintainability.

Verify the migration

Start Platform

$ sudo systemctl start itential-platform

Check service status

$ sudo systemctl status itential-platform

Access the UI

Platform is accessible.
Version shows Platform 6.x.x.
All expected apps and adapters are loaded.

Test workflows

Execute existing workflows.
Test adapter connections.
Verify data access.

Review logs

$ tail -f /var/log/itential/app.log

Troubleshoot migration issues

Database connection fails

Verify MongoDB is running

$ sudo systemctl status mongod

Verify the connection string

Check the MongoDB URL in your configuration.

Test the connection

$ mongo mongodb://127.0.0.1:27017/itential

Check the firewall

If using a remote database, ensure the firewall allows MongoDB connections.

Custom apps or adapters not loading

Verify file location

$ ls -la /opt/itential/platform/services

Check file permissions

$ sudo chown -R <service-user>:<service-group> /opt/itential/platform/services

Review logs

$ grep -i error /var/log/itential/app.log

Verify compatibility

Ensure custom code is compatible with Platform 6.

Encryption errors

Verify key migration completed successfully

Confirm the key migration utility ran without errors.

Check the encryption key

Verify the encryption key in your configuration matches the key used for migration.

Review migration output

Check the migration utility output for errors or skipped collections.

Re-run the migration

If needed, restore the database backup and re-run the migration utility.

Post-upgrade tasks

Update documentation

Record the new platform version.
Update system documentation.
Document any configuration changes.
Note any custom code modifications required.

Test functionality

Run existing workflows.
Test adapter connections.
Verify integrations.
Check custom apps and automations.
Review scheduled jobs.
Test user access and permissions.

Monitor performance

Check resource utilization (CPU, memory, disk).
Review log files for errors or warnings.
Monitor database performance.
Verify workflow execution times.
Check adapter response times.

Clean up

Delete temporary RPM files.
Archive old backups.
Clean up migration utility output.
Remove deprecated configuration files after verification.

Best practices

Before upgrading:

Always back up your database and configuration.
Review release notes and breaking changes.
Test the upgrade in a non-production environment first.
Schedule upgrades during maintenance windows.
Stop active jobs to prevent data loss.

During the upgrade:

Follow the appropriate upgrade path for your version.
Verify each step completes successfully before proceeding.
Monitor logs for errors or warnings.
Keep backup accessible for quick rollback if needed.

After the upgrade:

Thoroughly test all functionality.
Monitor performance and logs.
Update documentation.
Communicate upgrade completion to stakeholders.
Plan for cleanup of old files and backups.

For migrations to Platform 6:

Use a clean system when possible.
Migrate encrypted secrets before connecting to the database.
Verify custom code compatibility.
Transition to platform.properties or environment variables.
Test thoroughly before decommissioning the old system.

Next steps

Platform 6 documentation

Learn about Platform 6 features and capabilities

Configure platform settings

Configure Platform 6 for your environment

Admin Essentials

Manage platform settings and profiles

Archive and purge data

Implement data retention policies