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.

If you’re upgrading to Platform 6.6.0 or later, upgrade your host to Node 22 if you install the RPM (Platform images bundle Node 22), and check any custom apps or adapters against Node 22 before you upgrade. See Node.js runtime upgraded to Node 22.

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. To replace the encryption key on an existing Platform 6 installation, rotate the encryption key instead.

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:

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

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

Set the encryption key

encryption.key=your-encryption-key-here

Configure a custom service directory (optional)

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