Itential Automation Platform

On this page:


This guide explains how to upgrade your software for the Itential Automation Platform (IAP).


  • Please review all Breaking Changes in the Product Notices section before upgrading IAP.
  • Itential currently supports the use of MongoDB 4.2.x on all released IAP versions. If you are using an earlier version it is recommended that you upgrade.

Job Management Before a Major or Minor Upgrade

Major Version Upgrade

Before any major version upgrade, all jobs should be canceled or completed before starting the upgrade process.

Minor Version Upgrade

Before a minor version upgrade, make sure all jobs are paused, canceled, or completed before beginning the upgrade process.

Please use your Itential Product Support account if you need support when performing an upgrade.

Steps to Upgrade IAP Software

To upgrade the core IAP software from 2018.3 or 2019.1:

  1. Verify the latest version of IAP has been copied to the server. You can acquire the link for this build from the portal.

  2. The upgrade will capture your latest /opt/pronghorn/current/properties.json file and use it for your upgraded installation.

  3. Shutdown IAP.

  4. Refer to the Installing Dependencies section in the IAP Installation Guide to ensure that all dependency requirements have been met prior to continuing.

  5. Change, cd, to the directory where the latest IAP install build .bin file is stored.

  6. Run the following command to upgrade IAP (add -v for verbose output).

    bash pronghorn-<build-id>.linux.x86_64.bin -p
  7. Change, cd, to the migration script directory.

  8. Run the migration script.

    node migratePropertiesToDatabase.js

    Important Notes

    • Running node migratePropertiesToDatabase.js unattended will automatically respond yes to all prompts, requiring no user input.

    • During an upgrade, a database backup will be triggered via installer script. For instances where IAP is connected via SSL to a mongo database and mongo is configured with the requireSSL property, the backup may fail with the following message:

      Failed: error connecting to db server: no reachable servers.
    • A mongo database backup can be created using a mongodump command like this:

      sudo mongodump --ssl --db pronghorn --host $hostname --port 27017 --username $mongoUsername --password $MONGOPASS --sslCAFile $pathToCert
  9. Respond to the migration script prompts to match the deployment environment.

    Retrieving properties.json file...
    Found properties.
    Connecting to Database...
    Are you sure you want to delete the following databases:
    (y)es (n)o y
    No service_configs collection detected, skipping.
    No iap_profiles collection detected, skipping.
    RabbitMQ hostname and port are currently set to "localhost:5671". Do you wish to keep these?
    (y)es (n)o y
    Retaining localhost:5671
    Would you like to run WITHOUT SSL?
    (y)es (n)o y
    RabbitMQ credentials currently set to
    username: guest
    password: guest
    Do you wish to keep these?
    (y)es (n)o y
    Retaining guest credentials
    RabbitMQ properties:
    "protocol": "amqp",
    "hostname": "localhost",
    "port": 5672,
    "username": "guest",
    "password": "$ENC84ff82395069f15bdb8e014991d32417818a228dad",
    "locale": "en_US",
    "frameMax": 0,
    "heartbeat": 0,
    "vhost": "/",
    "certPath": "",
    "keyPath": "",
    "passphrase": "guest",
    "caPath": ""
    Backing up properties.json to /opt/pronghorn/itential-1568912783776/properties_9c95343d-51df-41a7-9073-d21f34c840f8.json
    Loading services...
    (node:7345) Warning: Use Cipheriv for counter mode of aes-256-ctr
    Services loaded 8
    Generating init file data...
    Config data generated.
    Generating DB data...
    DB data generated.
    Connection established.
    Creating databases...
    Creating service_configs
    Creating iap_profiles
    Database creation complete.
    Creating IAP database config...
    Collection iap_profiles created!
    IAP database config created.
    Creating service configs entries...
    Collection service_configs created!
    Service configs entries created.
    Cleaning up properties.json...
    Migration complete!

    Note: The migration script output above assumes that RabbitMQ is running on the same node as IAP, using default RabbitMQ credentials, and has SSL disabled. For security reasons this RabbitMQ configuration is not recommended for a production environment.

  10. The migration script will migrate much of the /opt/pronghorn/current/properties.json content to the Mongo database. A backup of the original properties.json file is generated during migration and will appear similar to /opt/pronghorn/current/properties_4d37a26d-e5e1-4796-845d-220f09681d65.json.

  11. Note any adapter schema errors in startup logs. Errors for adapter schema issues should be fixed in the properties.json file, or using the System > Adapters view.

Restart IAP & Login

  1. Restart IAP.

  2. Login to verify the service is up.

  3. In the event you are unable to find old automations, tags, etc., run the migration script for the respective application and refresh IAP.

  4. For example, if you are not finding tags created on a previous version of IAP:

    • Locate the migration script for tags.

    • Run the script.

      node migrateTagRefs.js
    • Refresh IAP.

  5. If you are still experiencing issues after running the migration script, please log a ticket with the Itential Service Desk. Be sure to provide all necessary information to reproduce the problem and the Itential Service Desk will help to address your issue.