Update Guide


The following steps are required to update Appian 7.11 or higher to the current release. If you are not on Appian 7.11 or higher, you must first update to 7.11 before updating to the current release.

Before updating, you must review the Appian Release Notes and System Requirements pages.


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>

1. Disable any 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, logs, and engine checkpoint files to backup locations and deletes them from production. Be sure to reschedule this job once you have completed the update process.
  • checkengine.sh (.bat) - Reports the status of Appian Engines. 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.sh (.bat) script located at <OLD_APPIAN_HOME>/search-server/bin/stop.sh (.bat).
  3. Execute the stop-suite.sh (.bat) script located at <OLD_APPIAN_HOME>/server/_scripts/.
    • Note: Do not kill any Appian processes. Wait for the normal shutdown to complete.
      An improperly shut down instance cannot be updated. Also do not checkpoint and kill the processes.
    • See also: Starting and Stopping Appian
  4. 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>/ear/suite.ear/conf/ directory using forward slashes on both UNIX and Windows.
  • If necessary, update 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 updated 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.

Start and Stop Appian Engines

  1. Run start-suite.sh (.bat) located at <APPIAN_HOME>/server/_scripts/. (Use the Services view in the Microsoft Management Console to start Windows Services.)
  2. Run checkengine.sh (.bat) located at <APPIAN_HOME>/server/_scripts/diagnostic/ to verify that the services are running properly.
    • All engines should display an Okay status.
  3. Run stop-suite.sh (.bat) located at <APPIAN_HOME>/server/_scripts/.
  4. Run checkengine.sh (.bat) located at <APPIAN_HOME>/server/_scripts/diagnostic/.
    • All engines should display a FATAL status.

Apply the Hotfix Package

Install the latest hotfix package released for Appian, specific to your new Appian release.

See also: Hotfixes

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 15.
      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>/server/archived-process/
    • <APPIAN_HOME>/server/msg/
  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 updating.

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/ to the <APPIAN_HOME>/ear/suite.ear/conf/ directory. For any other custom configuration files, such as appian-topology.xml, copy the file from its location in the old installation directory to the corresponding location in the new directory.

For customers updating from 7.11 or earlier, the name of the property that was conf.data.primary.datasource was changed to conf.data.APPIAN_DATA_SOURCE in version 16.1. Similarly, the property that was conf.data.primary.datasource.search.index was changed to conf.data.APPIAN_DATA_SOURCE.search.index. You must adjust your version of custom.properties to reflect this.

Merge Your web.xml File

Support for configuring Appian through modification of web.xml was deprecated in Appian 16.3 and will be removed in a future release. When possible, you should remove any custom modifications you have made to web.xml and use the out-of-the-box copy of that file.

If you have modified web.xml, merge it with the base file in <APPIAN_HOME>/ear/suite.ear/web.war/WEB-INF/.

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

10. Configure the Appian Data Source

When updating, 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 update process.

Note: The configuration for relational databases can change significantly between versions of JBoss. If you update versions of JBoss at the same time you update 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 News search and 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 updates. These data metrics are gathered and retained on a sliding time frame and will be started fresh after an update.

See also:

12. Clear Application Server Cache

If you are running JBoss, 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.


13. Start Appian Engines

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

  1. Run start-suite.sh (.bat) located at <APPIAN_HOME>/server/_scripts/. (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 checkengine.sh (.bat) script.
    • All engines should display an Okay 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-gw.sh (.bat) script located at the following file path: <APPIAN_HOME>/server/_scripts/analytics
  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 updating. For example, <APPIAN_HOME>/server/process/analytics/00xx/gw1 or <APPIAN_HOME>/server/process/analytics/0000/gw2
  6. Start the analytics engines by running the start-gw.sh (.bat)script located at the following file path:/server/_scripts/analytics`
  7. Verify the services have started by using the checkengine.sh (.bat) script.
    • All engines should display an Okay status.

14. Restart Appian Engines

This step applies any BASE_PATH changes you made and is required for any Appian engine update procedure.

  1. Stop Appian by running stop-suite.sh (.bat) located at <APPIAN_HOME>/server/_scripts/.
  2. Run start-suite.sh (.bat) located at <APPIAN_HOME>/server/_scripts/. (Use the Services view in the Microsoft Management Console to start Windows Services.)
  3. Verify that the services have started using the checkengine.sh (.bat) script.
    • All engines should display an Okay status.

15. Start the Search Server

  1. Execute <APPIAN_HOME>/search-server/bin/start.sh (.bat), or start the Appian Search service in the Windows service management console.

If running multiple instances of the search server as a cluster, start all of them in any order before moving on to the next step.

16. Start the Application Server

  1. Start the application server.
  2. 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.

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

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

Update Considerations

Take note of the items below when planning your update.

Update Embedded Script Tag

As of Appian 17.1, the format of the script tag used to embed Appian interfaces into an external web site has changed to:

<script src="https://appian.example.com/suite/tempo/ui/sail-client/embeddedBootstrap.nocache.js" id="appianEmbedded"></script>

Update the script tags in all of your web pages that have Appian interfaces embedded to the above format, replacing appian.example.com/suite with your own Appian server address and application context.

Furthermore, custom themes for embedded interfaces must now be specified in the script tag rather than in the HTML element for the individual embedded interface. If you have custom themes applied to any of your embedded interfaces, move those configurations to the script tag. Here is an example of a script tag with a theme specified:

<script src="https://appian.example.com/suite/tempo/ui/sail-client/embeddedBootstrap.nocache.js" id="appianEmbedded" data-themeidentifierr="corporateTheme1"></script>

Update Web Server Cache Configuration

Starting in Appian 17.1, there are new required web server configurations that specify cache policies specific to certain paths. These caching configurations not only provide users with better performance when accessing Appian from a web browser, they are necessary to avoid UI errors upon upgrade.

Export and Import Data Sources and Third-Party Credentials

The steps in this section should only be performed once all of your environments have been updated to Appian 16.2.

Data sources and Third-party credentials created from the Appian Administration Console can now be exported and imported.

In order to take advantage of this for existing data sources and third-party credentials, you'll need to update them. When updating from versions of Appian prior to 16.2, existing data sources and third-party credentials will have a universally unique identifier (UUID) generated for them. This UUID needs to be the same across all environments. In order to propagate that UUID to other environments, follow these steps:

Appian recommends that data sources and third-party credentials are exported from production environments and then re-imported to all lower environments so that updates to these items can be imported into production in the future.

Export Settings

  1. Navigate to the Appian Administration Console.
  2. From the header, click Export to view the Export Settings dialog.
  3. Click Show Filters to expand the available filters.
  4. From Category, select Data Source and Third-Party Credentials to filter the settings grid.
  5. Select the checkbox in the upper-left corner of the grid to select all settings.
  6. Click Export Selected.
  7. Click the Download package and Download import customization file links. The import customization file allows you to set usernames and passwords for data sources, and the credential field values for all third-party credentials.

Create Distinct Import Customization Files for Each Destination Environment

  1. Open the import customization file in a text editor and uncomment the lines for the settings you want to modify.
  2. Log into the administration console on the destination environment.
  3. Navigate to each data source and third party credentials you exported from production and copy their values to the import customization file. If these values are different for each of the destination environments you will be importing to, you will need to make a copy of the import customization file for each environment. You can append the destination environment name for each file name, i.e. Acme_Third-Party_Credentials_DEV.properties.
  4. Once all the information has been copied to the import customization file, delete the data sources and third-party credentials entries in the destination environments. Note: only delete the entries that you are about to import. You may have some additional data sources or third-party credentials on your destination environments that should not be deleted.

Import Settings

  1. From the header, click Import to open the Import Settings dialog.
  2. Upload the exported package into the Admin Console Package file upload field.
  3. Select Include related import customization file to upload the import customization file.
  4. Click Inspect.
  5. If all values were specified properly, and the existing data sources and third-party credentials were deleted, the inspection should be successful. If successful, click Import.
Troubleshooting Inspection Errors

The following table lists common errors that may be encountered when you inspect your package, and provides suggestions on the likely culprit.

Error Description
Could not connect to the specified host and port: CONNECTION_STRING= <specified connection string> Appian could not establish a connection with the database. This may be due to the connection string specified in the datasource's XML or in the import customization file being incorrect or the database you are trying to connect to is currently unavailable. You should also verify that you don't have any extra spaces at the beginning or end of the specified URL string.
<specified database type> is an invalid database type. Valid database types are: DB2, MySQL, Oracle, SQL Server Only the four database types listed in the error message are supported. Ensure you do not have a typo in the import customization file for the dataSource.<database UUID>.TYPE= property.
Incorrect USERNAME or PASSWORD Connection to the database was established but the provided credentials in the import customization file were not valid. You should contact your database administrator to verify the credentials.

Distributed Setup

If your existing installation uses an appian-topology configuration file, complete the following:

  1. Install and update the base application.
  2. Install the required components for each distributed machine.
    • Do not manually update or replicate any distributed engines.
  3. Edit the appian-topology.xml file located at <OLD_APPIAN_HOME>/ear/suite.ear/conf/ to reference any new server hosts, port numbers, or component locations.
  4. Copy the updated appian-topology.xml file to each <APPIAN_HOME>/ear/suite.ear/conf/ directory in your instance.


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.

Verify Engine Security File

The appian.sec can optionally be used to secure access to Appian engines and is located in <AE_HOME>/ear/suite.ear/conf. Versions of Appian before 16.2 could read this file from other directories, but starting in 16.2 it is only read from the correct directory. When updating, make sure the file is in the correct directory (or is absent if not being used). Multi-server installations must have the file in place on every server.

Application Server Logging

In version 17.1, application server logging is now captured in the application server's stdout. Customers who use WebLogic need to enable logging for stdout in their JVM settings. See our WebLogic configuration instructions for instructions.

In version 17.1, the "Forgot your password?" link is visible on the sign-in page by default unless all users authenticate through SAML or LDAP. If you do not want the link to appear, you can disable the feature from the Appian Authentication page of the Administration Console.