KB-2254 How to use the isSuitableForUpgrade script

Purpose

In order to safely upgrade an Appian environment, the engines in the source environment must be shut down using the stop script. Ungraceful shutdowns can introduce data inconsistencies and can lead to a failed upgrade.

The isSuitableForUpgrade.sh script can be used to detect if engines are not shutdown gracefully before the upgrade is performed. This helps validate the state of the engine data and confirms whether the data is in a state in which it can be safely be upgraded to a higher Appian version.

This script currently only works with single node and highly available(HA) topologies where the service_manager.log is in a central location. This script currently does not work with distributed topologies where the service_manager.log can be present on multiple servers.

Instructions

How to execute the script:

1. After shutting down all Appian components, download the script to the server that hosts the Appian engines.
   1. If the environment is HA, place the script in <APPIAN_HOME>/shared-logs.
   2. If the environment is on a single server, place the script in <APPIAN_HOME>/logs.
2. Make the script executable by running chmod +x isSuitableForUpgrade.sh. 
3. Run ./isSuitableForUpgrade.sh -p <your_service_manager_password>
4. The script will detect if the engines are suitable for upgrade and output the result to the console.
   1. If all engines are suitable for upgrade, it is safe to proceed with the next steps of the upgrade procedure. Sample output:
      

      Date of evaluation: * 
      
      The below results refer to the shutdown performed at * 
      If the timestamp is incorrect, please start and stop your engines then try again.
      
      15 engines are suitable for upgrade
      15 total engines detected 
      
      All engines are suitable for upgrade
      It is safe to proceed with the upgrade

   2. If one or more engines are unsuitable for upgrade, run the following steps. Sample output:
      

      Date of evaluation: * 
      
      The below results refer to the shutdown performed at * 
      If the timestamp is incorrect, please start and stop your engines then try again.
      
      12 engines are suitable for upgrade
      15 total engines detected
      
      One or more engines is unsuitable for upgrade
      Please perform a full start-up of all engines, gracefully shut down all engines, then try again

      1. Start all engines.
      2. Verify that all engines are running.
      3. Shut down all engines.
      4. Repeat steps 3-4 until all engines are suitable for upgrade. 

Note: If you are consistently unable to show that all engines are suitable for upgrade, please create a case with Appian Support.

Affected Versions

This article applies to self-managed versions of Appian 19.4 and later hosted on Linux

Last Reviewed: August 2023