Upgrade Guide


The following steps are required to upgrade an on-premises installation of Appian 17.1 or higher to the current release. If you are not on Appian 17.1 or higher, you must first upgrade to 17.1 before upgrading to the current release. Appian Cloud customers do not need to follow the instructions on this page when upgrading versions of Appian.

In this document, the following conventions are used to indicate the locations you have selected on your servers during installation:

  • Location of the previous Appian installation: <OLD_APPIAN_HOME>
  • Location of the new Appian installation: <APPIAN_HOME>

Before Beginning

Review New System Requirements and Behavior Changes

Review the release notes and system requirements.

Open the Required Ports

Appian components communicate with each other over specified network ports. If you are preparing a distributed installation, you must first ensure that the required ports are open between the servers that host the different Appian components.

In Appian 18.1, ports 5400-5405 were added for the Appian Data Server. These ports must be accessible from the application server(s).

Review Plug-ins

Always check the release notes for defect fixes, Java API deprecations and removals, and other changes that may affect plug-ins used by your installation.

Some plug-ins may need to be updated as part of the upgrade in order to continue to provide the desired functionality.

Custom Application Portal Pages

If your application contains custom Application Portal and non-SAIL forms, See the How to upgrade legacy customizations knowledge base article for instructions.

1. Disable any Scheduled Appian Administrative Scripts

Halt any scheduling for the following scripts to prevent system changes while upgrading or unnecessary jobs from continuing.

  • cleanup.sh (.bat) - This required administrative script copies archives, and logs to backup locations and deletes them from production. Be sure to reschedule this job once you have completed the upgrade process.
  • cleanupArchives.sh (.bat) - This required administrative script deletes old engine checkpoint files from production. Be sure to reschedule this job once you have completed the upgrade process.
  • checkengine.sh (.bat) - Reports the status of Appian Engines for versions prior to 17.3. It can be used for monitoring purposes.
  • status.sh (.bat) - Reports the status of Appian Engines for versions 17.3 and later. It can be used for monitoring purposes.

2. Shut Down the Application Server and the Appian Engines

  1. Shut down your application server using the appropriate shutdown script or procedure for your particular server.
  2. Stop the search server. Execute the stop script located at <OLD_APPIAN_HOME>/search-server/bin/stop.sh (.bat).
  3. Stop the data server. Execute the stop script located at <OLD_APPIAN_HOME>/data-server/bin/stop.sh (.bat).
  4. Stop the Appian Engines. Refer to Starting and Stopping Appian for the version of Appian that you are upgrading from for instructions on how to do this.
    • Note: Do not kill any Appian processes. Wait for the normal shutdown to complete.
      An improperly shut down instance cannot be upgraded. Also do not checkpoint and kill the processes.
  5. If Appian is installed as a Windows Service, stop and delete the Appian Windows services.

3. Back up Your Existing Appian Instance

  1. Back up the entire <OLD_APPIAN_HOME> directory.
  2. Back up the application server directory.
  3. Back up the schemas/tables in the RDBMS used by Appian using the RDBMS vendor’s preferred backup method.

4. Rename Your Existing Installation Directory

If you are installing the new version of Appian on the same server as your existing Appian instance, rename your current directory.

  • For example, you might change the directory name to OLD_APPIAN.

This change retains the existing data for future reference and allows you to reuse the prior <APPIAN_HOME> directory.

If you reuse the prior <APPIAN_HOME> directory location, you may avoid having to change some of the file paths that Appian uses for referencing your data after copying the data files over to the new installation.

5. Install New Version of Appian

Follow the steps listed in the Appian Installation Guide specific to your environment and new version, keeping the following in mind:

  • If you use the same installation directory (name and path) as was used during the original Appian installation (now renamed), you will avoid the need to change file paths. Otherwise, you must update the conf.suite.BASE_PATH property in custom.properties file located in the <APPIAN_HOME>/conf/ directory using forward slashes on both UNIX and Windows.
  • When planning an upgrade, ensure each environment is using the same version of the installer. This can be verified after the installation steps by opening the build.info file located in <APPIAN_HOME>/conf/. The contents of this file should match across all environments.

  • If necessary, upgrade the application server and JDK versions to match the supported versions listed in the System Requirements.
  • Be sure to review the application server configuration instructions, as these change from release to release with the upgraded support for new versions of the application servers. It is especially important to review the memory settings recommended for the application server.
  • Be sure to review the web server configuration instructions and copy the new static files to the web server, as these also change from release to release.
  • If you are running a distributed installation, run the installer on every server that will host any Appian component.

Start and Stop Appian Engines

Specific environment starting and stopping procedures can be found on Starting and Stopping Appian. Only engines and services will be started.

  1. Run start.sh (.bat) located at <APPIAN_HOME>/services/bin/. (Use the Services view in the Microsoft Management Console to start Windows Services.)
  2. Run status.sh (.bat) located at <APPIAN_HOME>/services/bin/ to verify that the services are running properly.
    • All engines should display a Running status.
  3. Run the stop script located at <APPIAN_HOME>/services/bin/.
  4. Run the status script located at <APPIAN_HOME>/services/bin/.
    • All engines should display a Down status.

Delete Transaction Logs

To ensure no transactions interfere with KDB migration perform the following:

  1. Delete the <APPIAN_HOME>/services/data/kafka-logs folder
  2. Delete the <APPIAN_HOME>/services/data/zookeeper folder

Since the engines were only started briefly in the previous steps for verification purposes, no relevant data will be present in the kafka-logs and zookeeper folder. These directories and files will be recreated once Appian is started again.

6. Copy Your Engine Data

  1. Delete the following directories in your new Appian installation.
    • <APPIAN_HOME>/server/process/analytics/0000/gw1
    • <APPIAN_HOME>/server/process/analytics/0001/gw1
    • <APPIAN_HOME>/server/process/analytics/0002/gw1
  2. Delete any additional analytics directories that you may have due to added execution engines or gateways.
    • For example, <APPIAN_HOME>/server/process/analytics/00xx/gw1 or <APPIAN_HOME>/server/process/analytics/0000/gw2
  3. Copy the highest-numbered .kdb files from the previous Appian instance to your new Appian installation according to the table below.
    • If you have additional gateways, such as gw2, do not copy data files for them. Reconfigure the additional gateway(s) in your new instance after successfully updating a single-gateway system.

      Appian Engine Name File Name Location (same for both install locations)
      Analytics pa*.kdb Not copied. Analytics engines are automatically recreated using process execution data. New analytics engines are created for each execution engine.
      Channels channels*.kdb <APPIAN_HOME>/server/channels/gw1/
      Content (main) dc*.kdb <APPIAN_HOME>/server/collaboration/gw1/
      Collaboration (statistics) stat*.kdb <APPIAN_HOME>/server/collaboration/gw1/
      Forums af*.kdb <APPIAN_HOME>/server/forums/gw1/
      Notification (email) s*.kdb <APPIAN_HOME>/server/notifications/gw1/
      Notification (main) n*.kdb <APPIAN_HOME>/server/notifications/gw1/
      Personalization ag*.kdb <APPIAN_HOME>/server/personalization/gw1/
      Portal ap*.kdb <APPIAN_HOME>/server/portal/gw1/
      Process-Design pd*.kdb <APPIAN_HOME>/server/process/design/gw1/
      Process-Execution (00) pe*.kdb <APPIAN_HOME>/server/process/exec/00/gw1/
      Process-Execution (01) pe*.kdb <APPIAN_HOME>/server/process/exec/01/gw1/
      Process-Execution (02) pe*.kdb <APPIAN_HOME>/server/process/exec/02/gw1/
      Process-Execution (n) Update all configured execution engines, up to 31. pe*.kdb <APPIAN_HOME>/server/process/exec/n/gw1/

If you have added execution engines, you must add analytics engines to your topology as well.

7. Copy Your Data

  1. Copy the following files and folders from the legacy Appian directory into the same location in your new Appian installation:
    • <APPIAN_HOME>/_admin/accdocs1/
    • <APPIAN_HOME>/_admin/accdocs2/
    • <APPIAN_HOME>/_admin/accdocs3/
    • <APPIAN_HOME>/_admin/mini/
    • <APPIAN_HOME>/_admin/models/
    • <APPIAN_HOME>/_admin/plugins/
    • <APPIAN_HOME>/_admin/process_notes/
    • <APPIAN_HOME>/_admin/search/ (if this folder exists)
    • <APPIAN_HOME>/_admin/shared/
    • <APPIAN_HOME>/data-server/data/
    • <APPIAN_HOME>/server/archived-process/
    • <APPIAN_HOME>/server/msg/
    • <APPIAN_HOME>/services/data/kafka-logs/
  2. Double check each directory to ensure that your existing files are copied properly.

Note: The system may still start successfully with improperly copied or missing resources. However, resulting system errors may still occur later when a process action that relies on a missing resource is attempted.

8. Copy Your Logs

This step is not strictly required for the proper operation of the system, however the logs directory contains valuable information in the perflogs and data-metrics directories which can be used to determine historical performance and usage trends. Therefore, it is recommended that you copy the existing logs when upgrading.

Copy the contents of the <APPIAN_HOME>/logs/ directory from the legacy Appian directory into the same location in your new Appian installation.

9. Update Your Configuration Files

If your existing installation uses a custom.properties configuration file, copy the custom.properties file located at <OLD_APPIAN_HOME>/ear/suite.ear/conf/ or <OLD_APPIAN_HOME>/conf/ to the <APPIAN_HOME>/conf/ directory. For any other custom configuration files, such as appian-topology.xml, merge your customizations with the new default example or template files and place the resulting file in the new installation's directory.

Revert To The Default web.xml File

In versions of Appian prior to 18.2 it was necessary to modify web.xml in order to allow insecure cookies when running Appian without HTTPS. This is no longer necessary as the security flag for cookies is now based on the value of conf.suite.SCHEME. If you had previously modified web.xml, do not carry this change forward when upgrading versions of Appian.

Merge Your Custom Spring Security Files

Support for custom Spring Security configurations has been deprecated since version 7.11 and you should convert your authentication configuration to one of the three out-of-the-box authentication mechanisms at the earliest opportunity.

If you have not yet converted to using the out-of-the-box authentication configurations and you maintain customized or overridden Spring Security xml files, you must merge them with the associated base files in the <APPIAN_HOME>/ear/suite.ear/web.war/WEB-INF/conf/security directory when upgrading to the latest version of Appian.

Upgrade Email Polling Configurations

In Appian 18.2, the configurations for polling an email account changed. Rather than copy the <OLD_APPIAN_HOME>/ear/suite.ear/email-handler.jar/META-INF/ejb-jar.xml file from your old installation to your new installation, follow the instructions for configuring Appian to poll an email account.

10. Configure the Appian Data Source

When upgrading, the Appian data source must reuse the same database in order to preserve the existing data. The schema of that data source will be automatically updated to the latest version during application server startup. Elevated user rights (such as Schema Owner or Database Owner) are required for the Appian Data source during the application server startup portion of the upgrade process.

Note: The configuration for relational databases can change significantly between versions of JBoss. If you upgrade versions of JBoss at the same time you upgrade Appian, you must follow the updated Configuring Relational Databases documentation in order to configure Appian and business data sources.

See also: Configuring Relational Databases

11. Recreate Search Indices

To account for changes in the format of the search server indices since the last release, complete the following:

Note: These steps should be completed before starting the application server. After following these steps, the search indices will be recreated during application server startup.

  1. Remove the <APPIAN_HOME>/_admin/search-local directory.
  2. Repeat this for every application server.

Note: Current User Activity and Historical Performance Trends for interface executions will not be preserved across upgrades. These data metrics are gathered and retained on a sliding time frame and will be started fresh after an upgrade.

See also:

12. Reset Analytics Engines

Run the reset analytics script. On a distributed installation, you must run this script on every server that hosts either an Analytics engine or a Kafka instance.

13. Clear Application Server Cache

If you are running JBoss and did not need to upgrade the JBoss installation, delete the folder <JBOSS_HOME>/standalone/tmp/work/jboss.web/default-host/suite (including all subfolders) to clear the application server's JSP cache.

If you are running WebLogic, delete the following directories to clear the cache when re-deploying the application.


14. Start Appian Engines

This step is necessary to recreate analytics engine data. Only Appian engines and services will be started. Use the Starting and Stopping Appian page for specific environment procedures.

Note: Do not perform an upgrade and add additional execution or analytics engines or additional gateways in the same step. Perform those changes only after successfully upgrading Appian to the new version.

  1. Run the start script located at <APPIAN_HOME>/services/bin/. (Use the Services view in the Microsoft Management Console to start Windows Services.)
    • Wait for all services to be up and running. This step may take seconds, minutes, or even hours, depending on the size of your existing engines, data, and the number of objects in your environment.
  2. Verify that the services have started by using the status script.
    • All engines should display a Running status.
  3. If you copied your data files for the _admin/mini/ directory into a directory that uses a different file path than before, such as //NewRootFolder/_admin/mini/ instead of //OldRootFolder/_admin/mini/, you must run the change-paths.sh (.bat) file located in <APPIAN_HOME>/_admin/_scripts/tools/ to update the mini website content directory location.
  4. Once the engines finish starting up, stop the analytics engines by running the stop script with the -s analytics option.
  5. Delete the following directories in your new Appian installation.
    • <APPIAN_HOME>/server/process/analytics/0000/gw1
    • <APPIAN_HOME>/server/process/analytics/0001/gw1
    • <APPIAN_HOME>/server/process/analytics/0002/gw1
    • Also delete any additional analytics directories that you may have due to additional engines or gateways that you added in the previous installation prior to upgrading. For example, <APPIAN_HOME>/server/process/analytics/00xx/gw1.
  6. Start the analytics engines by running the <APPIAN_HOME>/services/bin/start.sh (.bat) script with the -s analytics` option.
  7. Verify the services have started by using the status.sh (.bat) script.
    • All engines should display a Running status.

15. Start Appian

  1. Bring up Appian fully using the Starting and Stopping Appian page.
  2. Once all engines, services, and server are running, log in.

Note: If you have multiple application servers, start one application server and wait for it to complete startup before starting the rest. The remaining application servers may be started simultaneously.

16. Reschedule Appian Administrative Scripts

Reschedule the administrative script(s) you disabled in the first step.

Make sure to update the script location to the new instance.

In 17.3 a new administrative script, the cleanupArchives script, was added and needs to be scheduled to run periodically to cleanup old .kdb files.

17. Merge Email Templates

If you used customized email templates in the prior version, reapply these changes to the new templates used in your new version of Appian.

  1. In the E-mail Templates folder of the System Knowledge Center, download the updated emailHeader.html and emailFooter.html files.
  2. Merge your prior customizations into these files, as appropriate.
  3. Upload new versions of the merged file(s).

Clearing Browser Cache

It is possible to successfully upgrade Appian, but see a blank page or older login screen while testing the initial login. If this occurs, clear you browser cache, and try navigating to the BASE_PATH.