Update Guide

Overview

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

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

Conventions

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/
      Metadata dt*.kdb Not copied. The metadata engine was removed in the 7.10 release.
      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.10 or earlier, the values for the following configuration properties in custom.properties are automatically migrated to the Appian data source upon the first startup of the application server. Once you have verified that these values are present in the User Profile page of the Appian Administration Console, they can be deleted from custom.properties. After they are migrated, they will no longer be read from custom.properties. These properties have been combined into a single value in the Administration Console and the post-update configuration will be based on the value of conf.security.user.DEFAULT_VISIBILITY at update time. If conf.security.user.DEFAULT_VISIBILITY is set to viewer-details at update time, user profile visibility will be set to allow users to see all other users by default and emails will include user's display names. If conf.security.user.DEFAULT_VISIBILITY is set to none at update time then user profile visibility will be set to not allow users to see all other users by default and emails will not include user's display names.

  • conf.security.user.DEFAULT_VISIBILITY
  • conf.security.user.TEMPO_NOTIF_DISPLAYNAMES

For customers updating from 7.10 or earlier, the value of resources.appian.ap.application.appian.ap.session.timeoutwarn in custom.properties is no longer respected and the idle timeout warning will always appear 5 minutes before a session timeout. The amount of time between the timeout warning and the timeout is no longer configurable. You should remove this configuration from custom.properties.

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

If you have modified web.xml, merge it with the base file in <APPIAN_HOME>/ear/suite.ear/web.war/WEB-INF/. Support for configuring Appian through modification of web.xml has been deprecated 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.

In 7.11, the default scheme changed from HTTP to HTTPS. Prior to 7.11, running your Appian instance over HTTPS required modifying web.xml. In 7.11 and above the default version of web.xml specifies that the site should run over HTTPS. If you wish your site to run over HTTPS you should revert the relevant section of web.xml. If you wish to run over HTTP (which is only supported for non-production deployments), you will need to modify web.xml as specified in the Post-Install Configuration Guide.

In 7.11 and above, Appian manages the session timeout duration through the Appian Administration Console rather than relying on the value specified in web.xml. When updating from a version before Appian 7.11 to version 7.11 or above, Appian will read the session timeout configuration specified in web.xml and store it in the Appian data source. If the value configured in web.xml is less than the minimum of 15 minutes or more than the maximum of 8 hours, the stored value will be either the minimum or maximum, respectfully. After this point the value specified in web.xml will be ignored. If you have previously modified this setting in web.xml, you should revert that modification when updating to 7.11 or above.

Merge Your Custom Spring Security Files

As of version 7.11, support for custom Spring Security configurations has been deprecated 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.

  • In 7.10, Remember Me authentication configuration is no longer managed by spring-security-03-auth-mgr-override.xml. It is instead managed in the Appian Administration Console. The first time your application server starts up on version 7.10 or above we will make a one-time read of the rememberMeConfiguration bean in spring-security-03-auth-mgr-override.xml and migrate the values configured there into the Administration Console. If you wish to migrate your current Remember Me configuration into the Administration Console, uncomment the rememberMeConfiguration bean in spring-security-03-auth-mgr-override.xml. If you use the default configuration you may leave that bean commented out.

  • In 7.11, The version of Spring Security that Appian uses was updated from version 3.1 to 4.0. All Spring Security configuration files have changed and if you have overridden any of them you need to merge any changes with the base files located in <APPIAN_HOME>/ear/suite.ear/web.war/WEB-INF/.

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

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.

References to Outdated Data Types

Starting in Appian 7.11, the following design objects will always use the latest version of a data type:

  • Record types
  • Tempo reports
  • Web APIs
  • Third-party credentials

In previous releases, these objects could reference an older version of the data type if they were not updated when a new version of a data type was saved. Now all references to data types in these objects will automatically always use the latest version without any additional effort on the part of designers.

No additional action is required if you have always updated all references to data types when modifying them or if all data type changes you have made on your system are backward compatible (no field removals or field data type changes).

However, since it's possible that these objects could have been missed during a data type update, you must review objects of the types listed above to ensure that they are using the latest version of the data type prior to updating. To do so, follow these steps on all environments on your current version of Appian. It is most important to do these steps on the production environment to ensure no behavior changes after update.

  1. Create an application containing all record types, reports, and web APIs.
  2. Export the application.
  3. Check the export log for any warnings regarding references to deleted types. The message will have the text “The object references the deleted type ...”
  4. Review any test expressions in Third Party Credentials in the Appian Administration Console for the presence of type!<TypeName> and ensure they do not end with “^N” where N is some number.

If any deleted type warnings are listed for these listed object types, review and edit the object definition to ensure it will continue to work when using the latest data type definition.

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.

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.

Email Headers from Send Email Smart Service

Emails sent from a Send Email Smart Service configured to send from the process initiator (pp!initiator) or process designer (pp!designer) will carry a Sender header and Return-Path header set to the email address configured in the conf.mailhandler.ntf_sndr_addr property.

This change means emails that previously would bounce to the process initiator or process designer's email address will now bounce to the site-wide notification sender's email address, which does not necessarily correspond to a valid mailbox to collect the bounced messages. If collection of bounced emails is desired, configure the conf.mailhandler.ntf_sndr_addr property to a valid email address within your control or create a mailbox on your mail server for the existing address.

This change is necessary in order to comply with the best practices for web-generated email, as recommended by the Sender Policy Framework. If preserving the previous behavior is critical, you must configure the email-address-config.xml in /ear/suite.ear/web.war/WEB-INF/conf/process/email-address-config.xml by overriding it with a custom configuration that does not have the sender attribute for processInitiator and processDesigner.

See also: Configuring Custom Email Senders and Sender Policy Framework: Best Practices/Webgenerated

Process Unarchival Limit Change

As of version 7.10, unarchiving processes archived before Appian version 6.0 is no longer supported. Previously, the limit was version 5.6.1.0. Before updating to 7.10, unarchive and rearchive any processes that were archived prior to Appian 6.0 if you think you may need to unarchive those processes in the future.

See also: Managing Process Archives

Remove Metadata From Topology Configuration

As of version 7.10, the metadata engine is no longer part of the Appian architecture. If an appian-topology.xml file is being used to configure engines and their ports, any entries involving the metadata engine (e.g., <engine name="metadata"/>) must be removed.

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.

FEEDBACK