Update Guide


The following steps are required to update an on-premises installation of Appian 17.2 or higher to the current release. If you are not on Appian 17.2 or higher, you must first update to 17.2 before updating to the current release. Appian Cloud customers do not need to follow the instructions on this page when updating 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

Important File location Changes

In previous versions, a separate application server had to be configured. Starting with 18.3, Appian no longer uses a separate application server. As a result, the directories under <APPIAN_HOME> have changed.

If you have created any scripts or shortcuts that reference any of the locations below, you will need to modify your tools so that they can continue to work with Appian 18.3 and above.

Previous Location New Location
<APPIAN_HOME>/ear/ <APPIAN_HOME>/deployment/
appian_log4j.properties <APPIAN_HOME>/deployment/web.war/WEB-INF/resources/appian_log4j.properties
Application Server specific directory for server log <APPIAN_HOME>/logs/tomcat-stdOut.log
Application Server specific directory for RDBMS driver(s) <APPIAN_HOME>/tomcat/apache-tomcat/lib/
Application Server specific files for Data Source configurations <REPO_HOME>/tomcat/tomcatResources.xml
Application Server specific file to configure JVM heap settings Configure JVM heap settings in <REPO_HOME>/conf/custom.properties.<ENVIRONMENT>with conf.appserver.minHeapSize or conf.appserver.maxHeapSize

Review New System Requirements and Behavior Changes

Review the release notes and system requirements.

Starting in Appian 18.3 there are new configurations that specify additional URLs used to securely serve new types of web content in addition to the URL used for the Appian web interface. Depending on your existing network configuration this may require new domains and server certificates. These new configurations will not block upgrades but are necessary to avoid errors with new Appian features.

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 update 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 update legacy customizations knowledge base article for instructions.

1. Disable Scheduled Appian Administrative Scripts

Halt any scheduling for the following scripts to prevent system changes while updating 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 update 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 update 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 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 updated.
  • 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. If updating from a version prior to 18.3, back up the application server directory (previously referred to as <JBOSS_HOME> or <WEBLOGIC_HOME> in older versions of the documentation). This directory does not exist in version 18.3 or above and so does not need to be backed up.
  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 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

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 (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.
  • In version 18.3, Appian no longer requires an external application server (JBoss or WebLogic) to be provided. You may uninstall them when upgrading to version 18.3 or above.
  • Starting in Appian 18.3 there are new configurations that specify additional URLs used to securely serve new types of web content in addition to the URL used for the Appian web interface. Depending on your existing network configuration this may require new domains and server certificates. These new configurations will not block upgrades but are necessary to avoid errors with new Appian features.

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/search/
  • <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/collaboration/gw1/
  • <APPIAN_HOME>/server/forums/gw1/
  • <APPIAN_HOME>/server/msg/
  • <APPIAN_HOME>/server/notifications/gw1/
  • <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/

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.

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

Appian Data Source Configuration

In versions of Appian prior to 18.3 the method of configuring the Appian data source changed and it must be re-configured when updating to version 18.3 or higher. Previously, the Appian data source was configured through the Application server (JBoss or WebLogic) that was used to run Appian. In 18.3 and higher, the Appian data source must be configured in <REPO_HOME>/tomcat/tomcatResources.xml.<ENVIRONMENT>.

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

See also: Configuring Relational Databases

Insecure Cookies Configuration

If you had previously modified web.xml to allow insecure cookies, do not carry this change forward when updating versions of Appian.

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 set in custom.properties.

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 updating to the latest version of Appian.

Email Polling Configurations

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

Application Portal Access

In Appian 18.4, access to the Application Portal was removed. If you are still using the Application Portal, configure access by setting conf.security.IS_APPS_PORTAL_VISIBLE=true in custom.properties.

8. Recreate Search Indices

To account for changes in the format of the search server indices since the last release, delete the <APPIAN_HOME>/_admin/search-local/ directory from every server.

After following these steps, the search indices will be recreated during application server startup.

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

See also:

9. 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 update 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.

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

11. 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).