For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Open sourceSupportFAQsDocs Home
DocumentationAPI referenceRelease notes
DocumentationAPI referenceRelease notes
  • Platform On-Prem
    • Overview
    • Navigate
      • Archiving and purging
      • Start, stop, restart
      • Best practices
      • Testing policy
        • Upgrade to latest version
        • Common upgrade errors
    • Search resources
  • Apps
    • FlowAI
    • Itential Automation Gateway
  • Resources
    • Itential Academy
    • Version lifecycle
    • Itential MCP
    • Accessibility conformance
    • Get support
    • FAQs
LogoLogo
Open sourceSupportFAQsDocs Home
On this page
  • Before you begin
  • Choose your upgrade path
  • Upgrade within Platform 6
  • Prerequisites
  • Prepare for upgrade
  • Download the installation package
  • Find the service user
  • Run the upgrade
  • Troubleshoot upgrade issues
  • Migrate to Platform 6
  • Migration overview
  • Install Platform 6
  • Migrate encrypted secrets
  • Before you migrate
  • Run the key migration utility
  • Migrated collections
  • Understand migration output
  • Migrate apps and adapters
  • Configure a custom location (optional)
  • Copy custom code
  • Migrate configuration
  • Configuration options in Platform 6
  • Create the platform.properties file
  • Continue using properties.json (not recommended)
  • Verify the migration
  • Troubleshoot migration issues
  • Database connection fails
  • Custom apps or adapters not loading
  • Encryption errors
  • Post-upgrade tasks
  • Update documentation
  • Test functionality
  • Monitor performance
  • Clean up
  • Best practices
  • Next steps
Platform On-PremMaintainUpgrade

Upgrade to the latest version of Platform 6

Was this page helpful?
Previous

Common upgrade errors

Next
Built with

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 versionTarget versionUpgrade path
Platform 6.x.xLatest Platform 6Upgrade within Platform 6
Platform 2022.1, 2023.1, or 2023.2Platform 6Migrate 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

1

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.
2

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.

3

Back up the database

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

Back up configuration

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

Download the installation package

1

Access the repository

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

2

Download the RPM

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

3

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/
4

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

1

Stop the Platform service

$sudo systemctl stop itential-platform
2

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%]
3

Start the Platform service

$sudo systemctl start itential-platform
4

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
5

Verify in the UI

Log in to the Platform UI and verify:

  • 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:

1

Check service logs

$sudo journalctl -u itential-platform -n 100
2

Check platform logs

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

Verify file permissions

$ls -la /opt/itential/platform
4

Check the database connection

$sudo systemctl status mongod
5

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:

  1. Installing Platform 6 on a new or clean system.
  2. Migrating encrypted secrets from your existing database.
  3. Migrating custom apps and adapters.
  4. 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

1

Navigate to the server directory

$cd /opt/itential/platform/server
2

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.

3

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
4

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:

1service_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

1

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.
2

Copy to Platform 6

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

Set file ownership

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

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

MethodFile locationRecommendedNotes
platform.properties file/etc/itential/platform.propertiesYesPreferred method for Platform 6
Environment variablesSystem environmentYesOverride file-based configuration
Database profilesMongoDBLegacySupported for backward compatibility
properties.json file/opt/itential/platform/serverNoDeprecated, 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

1

Copy the template

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

Edit the configuration

$sudo vi /etc/itential/platform.properties
3

Set the database connection

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

Set the encryption key

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

Configure a custom service directory (optional)

1service_directory=/custom/path/to/services
6

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

1

Start Platform

$sudo systemctl start itential-platform
2

Check service status

$sudo systemctl status itential-platform
3

Access the UI

Log in to the Platform UI and verify:

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

Test workflows

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

Review logs

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

Troubleshoot migration issues

Database connection fails

1

Verify MongoDB is running

$sudo systemctl status mongod
2

Verify the connection string

Check the MongoDB URL in your configuration.

3

Test the connection

$mongo mongodb://127.0.0.1:27017/itential
4

Check the firewall

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

Custom apps or adapters not loading

1

Verify file location

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

Check file permissions

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

Review logs

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

Verify compatibility

Ensure custom code is compatible with Platform 6.

Encryption errors

1

Verify key migration completed successfully

Confirm the key migration utility ran without errors.

2

Check the encryption key

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

3

Review migration output

Check the migration utility output for errors or skipped collections.

4

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