Upgrade Guide


This page applies to self-managed installations only. Appian Cloud customers do not need to follow these instructions when upgrading to newer versions of Appian.

This guide assumes you are on Appian version 20.1 or higher. If you are on a lower version of Appian, upgrade to 20.1 first before upgrading to the current release.

To view your current Appian version, log into your Appian environment as a designer or system administrator and click the navigation menu > About 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

Check the KDB+ license

Appian requires K4 version 4.0. Before upgrading to the latest Appian version, you will need to ensure that you have a valid K4 license installed on your Windows or Linux system.

To find your current K4 license details:

  1. Open <OLD_APPIAN_HOME>/logs/data-server/k4_license.info. For example:
    $ cat $APPIAN_PATH/logs/data-server/k4_license.info
    #System auto-generated log on 2021-08-20T09:24:11Z
    BANNER_TEXT=example.com #123456
  2. Review the following dates: EXPIRY_DATE and UPDATE_DATE.

If either of these two dates is after your planned Appian upgrade date, or if the k4_license.info file is not present on your installation, please open a support case for assistance obtaining a valid K4 version 4.0 license before continuing with the Appian upgrade process.

Review New System Requirements and Behavior Changes

Review the release notes and system requirements for more details.

Ensure the JDK and TLS are on the correct version

If you are using Oracle JDK 8, it must be on update 291 or later. If you're using the bundled OpenJDK 8, no action is required.

By default, Transport Layer Security (TLS) 1.2 is required for all connected external sources. If you need to connect to systems using TLS 1.0 or 1.1, follow the steps in the Post-Install Configuration page to enable TLS 1.0 and above.

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 20.4 and later, port 9200 needs to be open for the search server. This port must be accessible from the application server. No changes are required to the search server section of the Appian topology file during Appian upgrade to 20.4, as long as the port 9200 is open. Please refer to the search server configuration page for more details.

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.

Virtual Memory for Search Server

The following is applicable if you are upgrading from 20.3 or earlier to 20.4 or later on Linux operating system:

Appian 20.4 and later uses standalone deployment of Elasticsearch for the search server. This provides increased security and reliability for the search server. Elasticsearch uses a mmapfs directory by default to store its indices. The default operating system limits on mmap counts could be low and result in out of memory exceptions.

On Linux, increase the limits by running the following command as root:

sysctl -w vm.max_map_count=262144

Minimum value of 262144 is required. To set this value permanently, update the vm.max_map_count setting in /etc/sysctl.conf. To verify after rebooting, run sysctl vm.max_map_count.

1. Disable 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. NOTE: Starting in Appian 20.2, old engine checkpoint files will be deleted automatically, so you do not need to reschedule this job once you have completed the upgrade process.
  • status.sh (.bat) - Reports the status of Appian Engines and is used for monitoring purposes.

For all versions 20.3 and later, all engines in a highly-available configuration will restart automatically during checkpointing (given it is safe to restart). If you have previously scheduled the engineRestart script to run periodically it should also be disabled. You will not need to re-enable the script in the steps below.

2. Shut Down Appian

Refer to Starting and Stopping Appian for the version of Appian that you are upgrading from for instructions on how to shut down Appian.

  • Note: Do not kill any Appian processes. Wait for the normal shutdown to complete. An improperly shut down instance cannot be upgraded.
  • 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 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 current Appian instance, first rename your current Appian installation directory to keep from losing the existing data (you will need to copy this data over after installing the new version in the next step). For example, you might change the current directory name of APPIAN_HOME to OLD_APPIAN_HOME. This will allow you to install the new version into APPIAN_HOME.

5. Install New Version of Appian

Refer to the Appian Installation Guides specific to your environment and new version. Follow the steps in Part 1 of the guide to install the new version of Appian and then configure the installation as detailed in Part 2. You should not start Appian until you have completed all instructions prior to step 9 in this document.

Keep the following in mind:

  • If you use the same installation directory (name and path) as was used during the original Appian installation (which was renamed in step 4), 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.
  • If necessary, update the JDK version to match the supported versions listed in the System Requirements.
  • 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. Ensure that you use the same version of the installer on every server in the environment. 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 servers in the environment.

6. Copy Your Data

Copy the following files and folders from the old Appian directory into the same location in your new Appian installation. Some of these directories might not exist in the legacy Appian directory, depending on what version it is.

  • <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/shared/
  • <APPIAN_HOME>/data-server/data/
  • <APPIAN_HOME>/logs/
  • <APPIAN_HOME>/server/archived-process/
  • <APPIAN_HOME>/server/channels/gw1/
  • <APPIAN_HOME>/server/collaboration/gw1/
  • <APPIAN_HOME>/server/forums/gw1/
  • <APPIAN_HOME>/server/msg/
  • <APPIAN_HOME>/server/notifications/gw1/
  • <APPIAN_HOME>/server/personalization/gw1/
  • <APPIAN_HOME>/server/portal/gw1/
  • <APPIAN_HOME>/server/process/analytics/*/gw1/
  • <APPIAN_HOME>/server/process/design/gw1/
  • <APPIAN_HOME>/server/process/exec/*/gw1/
  • <APPIAN_HOME>/services/data/kafka-logs/
  • <APPIAN_HOME>/services/data/zookeeper/

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.

Note that copying the corresponding files from the old Appian installation into <APPIAN_HOME>/services/data/kafka-logs/ in the new installation is mandatory since this directory contains essential data required for proper start up. The target directory must be empty before copying the data from the previous installation.

Double check each directory to ensure that your old files were successfully copied over.

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.

7. Update Your Configuration Files

Copy the custom.properties file located at <OLD_APPIAN_HOME>/conf/ to the <APPIAN_HOME>/conf/ directory.

When upgrading from 20.4 to 21.1 (and later versions), this step can overwrite the key in <APPIAN_HOME>/search-server/conf/, resulting in a 401 Unauthorized Error in tomcat-stdOut.log when Search Server is started. See the below section Search Server Configuration for steps on how to resolve this issue.

  • If upgrading from 20.2 or earlier to 20.3 or later, add the following configurations to the end of the custom.properties file:

These properties are new in 20.3 with the introduction of opaque URLs for tasks and documents. The configurations above provide backwards compatibility for some applications developed in 20.2 or earlier that constructed custom links using a numeric ID. After upgrade, developers can follow the opaque URL guidance to modify their applications to support opaque URLs in custom links. Once applications have been updated to use only opaque URLs, these configurations can be removed from custom.properties.

Appian Topology

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.

Customers upgrading to version 20.3 or later should update the appian-topology.xml file to configure the data server to run with two real-time store components. In previous releases, it was recommmended to run the data server with just one real-time store component. Though this configuration is still technically supported, it is now recommmended to run the data server with two real-time store components in order to load-balance queries to the data server. Currently, it is not supported to run more than two real-time store components. When changing the topology, make sure that the required ports have been opened as well.

Data Server Configuration

Copy over the Data Server security token from <OLD_APPIAN_HOME> to the corresponding directories in <APPIAN_HOME>:

  • conf/data-server-sec.properties
  • data-server/conf/data-server-sec.properties

For more information about the security token, including regeneration, please refer to Data Server Connection Restrictions.

Search Server Configuration

The following is applicable if you are upgrading from 20.3 or earlier:

In 20.3 or earlier versions of Appian, start.conf file in <APPIAN_HOME>/search-server/bin directory was used to modify the defaults for minimum and maximum heap memory usage by the search server. If you have created a start.conf file for your Appian installment in the past and modified the default memory values for the search server, you need to ensure that the corresponding values are set using custom.options file in Appian 20.4 and later. Please refer to starting search server page for more details.

The following is applicable if you are upgrading from 20.4 or earlier:

If you use the configure script to register and install the new version of Appian and you copy the configurations from the older Appian version into the repository for the new Appian version, you might have a mismatch between conf.data.search-server.restclient.apiKey value in REPO/conf/custom.properties.ENV file and conf.search-server.http.auth.apiKey value in REPO/conf/search-server/custom.properties.ENV file. This mismatch will cause configure script validation to fail. This occurs because conf.data.search-server.restclient.apiKey does not exist in Appian version 20.4 and older. To avoid issues, before you validate or deploy the configurations in the new repository, copy the value of conf.search-server.http.auth.apiKey in REPO/conf/search-server/custom.properties.ENV to conf.data.search-server.restclient.apiKey value in REPO/conf/custom.properties.ENV. This will ensure that the conf.search-server.http.auth.apiKey and conf.data.search-server.restclient.apiKey values are the same, which is a requirement for the search server to start.

If you do not use the configure script to deploy configurations and instead manually copy files directly into home, then you might also encounter a similar apiKey mismatch and resulting error. In order to resolve this issue, copy the value of conf.search-server.http.auth.apiKey in <APPIAN_HOME>/conf/ to conf.data.search-server.restclient.apiKey in <APPIAN_HOME>/search-server/conf/. This additional step will ensure that the apiKey values are the same.

Data Cleanup

Starting in Appian 20.2, the system will automatically delete older .kdb files from the <APPIAN_HOME>/services/data/archived/ directory, so the cleanupArchives.sh (.bat) script no longer needs to be scheduled to run. By default, two .kdb files will be kept for every engine. The number of .kdb files that are kept can be configured using the property serviceManager.checkpoint.archives.keep in custom.properties. If you were previously running the cleanupArchives.sh (.bat) with a --keep parameter greater than the recommended value of 2, add the serviceManager.checkpoint.archives.keep property with that value (example: serviceManager.checkpoint.archives.keep=4).

Appian Data Source Configuration

The Appian data source must reuse the same database before and after upgrading 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. These elevated rights may be removed after upgrading, if desired.

See also: Configuring Relational Databases

Custom Spring Security Configurations

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>/deployment/web.war/WEB-INF/conf/security/ directory when upgrading to the latest version of Appian.

8. Start Appian

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

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.

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.

9. Reschedule Appian Administrative Scripts

Reschedule the administrative script(s) you disabled in the first step, except for cleanupArchives.sh (.bat), which does not need to be scheduled to run starting in Appian 20.2.

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

10. 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).
Open in Github Built: Wed, Aug 16, 2023 (04:37:39 PM)

On This Page