Tip: 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 21.2 or later. If you are on an earlier version of Appian, upgrade to 21.2 first before upgrading to the current release.
To view your current Appian version:
In this document, the following conventions are used to indicate the locations you have selected on your servers during installation:
<OLD_APPIAN_HOME>
<APPIAN_HOME>
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:
Open <OLD_APPIAN_HOME>/logs/data-server/k4_license.info
. For example:
1
2
3
4
5
6
7
$ cat $APPIAN_PATH/logs/data-server/k4_license.info
#System auto-generated log on 2021-08-20T09:24:11Z
VERSION=4.0
RELEASE_DATE=2021-02-02
EXPIRY_DATE=2022-06-01
UPDATE_DATE=2022-06-01
BANNER_TEXT=example.com #123456
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, open a support case for assistance obtaining a valid K4 version 4.0 license before continuing with the Appian upgrade process.
The 22.4 release includes an update to the Hibernate object-relational mapping library that requires replacement of specific JPA annotations that are no longer supported: @TableGenerator
, @PrimaryKeyJoinColumn
, @DiscriminatorColumn
, and @DiscriminatorValue
. When upgrading from a release prior to 22.4 you should search your environments for occurrences of these annotations and replace them with supported annotations.
To determine if your environments are using the unsupported annotations:
Search for occurrences of @TableGenerator
, @PrimaryKeyJoinColumn
, @DiscriminatorColumn
, and @DiscriminatorValue
by executing the following command:
1
cat <AE-HOME>/logs/jpa_annotation_details.log | grep -E "(TableGenerator|PrimaryKeyJoinColumn|DiscriminatorColumn|DiscriminatorValue)"
If no occurrences of @TableGenerator
, @PrimaryKeyJoinColumn
, @DiscriminatorColumn
, or @DiscriminatorValue
are returned, you can continue with the next step of the upgrade. If any occurrences of these annotations are found, use the directions on Replace Deprecated JPA Annotations to make the necessary changes.
Review the release notes and system requirements for more details.
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.
See System Requirements - Transport Layer Security for information on configuring TLS.
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.
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.
If your application contains custom Application Portal and non-SAIL forms, See the How to upgrade legacy customizations knowledge base article for instructions.
The following is applicable if you are upgrading to 21.4 or later on Windows operating system:
Download and install the Microsoft Visual C++ 2010 Service Pack 1 Redistributable Package MFC Security Update. This update securely installs libraries that are required on your windows system to run Appian 21.4 or later.
Halt any scheduling for the following scripts to prevent system changes while upgrading or unnecessary jobs from continuing.
Refer to Starting and Stopping Appian for the version of Appian that you are upgrading from for instructions on how to shut down Appian.
<OLD_APPIAN_HOME>
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
.
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:
conf.suite.BASE_PATH
property in custom.properties file located in the <APPIAN_HOME>/conf/
directory using forward slashes on both UNIX and Windows.<APPIAN_HOME>/conf/
. The contents of this file should match across all servers in the environment.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.
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.
Copy the custom.properties file located at <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.
Copy over the data service 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 Service Connection Restrictions.
If you use the configure script to register and install a new version of Appian, and you copy the configurations from the old Appian version into the repository for the new Appian version, you may have a mismatch between the conf.data.search-server.restclient.apiKey
value in the REPO/conf/custom.properties.ENV
file and the conf.search-server.http.auth.apiKey
value in the REPO/search-server/conf/custom.properties.ENV
file.
This mismatch will cause the configure script validation to fail because conf.data.search-server.restclient.apiKey
does not exist in Appian version 20.4 and older. To avoid issues, copy the conf.search-server.http.auth.apiKey
value in the REPO/search-server/conf/custom.properties.ENV
file to the conf.data.search-server.restclient.apiKey
value in the REPO/conf/custom.properties.ENV
file before you validate or deploy the configurations in the new repository. 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, you may also encounter a similar apiKey
mismatch and resulting error. To resolve this issue, copy the value of conf.search-server.http.auth.apiKey
in <APPIAN_HOME>/search-server/conf/custom.properties.ENV
to conf.data.search-server.restclient.apiKey
in <APPIAN_HOME>/conf/custom.properties.ENV
. This additional step will ensure that the apiKey
values are the same.
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
Note: 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.
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.
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
.
Reschedule the administrative script(s) you disabled in the first step.
Make sure to update the script location to the new instance.
If you used customized email templates in the prior version, reapply these changes to the new templates used in your new version of Appian.
Upgrade Guide