KB-2269 How to use the change-paths.(sh|bat) script

Purpose

This article describes how to use the change-paths script in different scenarios and operating systems. This script should be utilized when errors related to process notes and/or archived processes are observed after changing Appian's <APPIAN_HOME> path or when migrating from one server to another.

Instructions

Please make sure that Service Manager(s) and Engines are up and running in the environment while executing change-paths.(sh|bat). This script can be run from any node in the environment as long as the node can communicate with the Service Manager(s) properly.

If the issues persist after utilizing change-paths.(sh|bat), please create a support case for further investigation with Appian Support.

Change the Path for Process Notes

Note: Failures related to process notes location should not impact the execution of Process Models. The process note feature has also been deprecated since Appian 16.3.

Symptoms

The following errors are observed in tomcat-stdOut.log:

2022-05-02 16:08:20,117 [ForkJoinPool-1-worker-1] ERROR com.appiancorp.process.notes.services.NotesContentServiceImpl - User Administrator sent an invalid notes location of '<OLD_APPIAN_HOME>/_admin/process_notes/exec/00/0/0' 
(Canonical: '<OLD_APPIAN_HOME>/_admin/process_notes/exec/00/0/0'); a notes location must be under '<NEW_APPIAN_HOME>/_admin/process_notes' (Canonical: '<NEW_APPIAN_HOME>/_admin/process_notes').

2021-12-24 12:55:04,884 [ForkJoinPool-1-worker-9] ERROR com.appiancorp.common.config.ConfigObject - An error occurred while trying to initialize the config LoadExceptionHandling [0ms] [resources 27ms]
java.nio.file.InvalidPathException: Cannot store the note content, because the location is not valid.: <NEW_APPIAN_HOME>/_admin/process_notes/exec/00/0/0

Actions

Go to <APPIAN_HOME>/_admin/_scripts/tools/

Edit the change-paths.(sh|bat) and update the OLD_PATH_NOTES and NEW_PATH_NOTES variables with absolute paths. Comment out the other lines. See below for an example:

#!/bin/bash
#OLD_PATH_MSG=/appian/server/msg
#OLD_PATH_MWS=/appian/_admin/mini
OLD_PATH_NOTES=<OLD_APPIAN_HOME>/_admin/process_notes
#OLD_PATH_ARCHIVED=/appian/server/archived-process
#NEW_PATH_MSG=/appian_new/server/msg/
#NEW_PATH_MWS=/appian_new/_admin/mini
NEW_PATH_NOTES=<NEW_APPIAN_HOME>/_admin/process_notes
#NEW_PATH_ARCHIVED=/appian_new/server/archived-process

pushd ..
#java -cp classpath.jar com.appiancorp.tools.ChangePaths MWS $OLD_PATH_MWS $NEW_PATH_MWS
#java -cp classpath.jar com.appiancorp.tools.ChangePaths FORUMS $OLD_PATH_MSG $NEW_PATH_MSG
java -cp classpath.jar com.appiancorp.tools.ChangePaths NOTES $OLD_PATH_NOTES $NEW_PATH_NOTES
#java -cp classpath.jar com.appiancorp.tools.ChangePaths ARCHIVED $OLD_PATH_ARCHIVED $NEW_PATH_ARCHIVED
popd

Restart the application server to verify if the error persists in tomcat-stdOut.log.

Change the Path for Archived Processes

Symptoms

Archived processes are not showing up in the expected <NEW_APPIAN_HOME>/server/archived-process/ folder.
Processes may be archived into <OLD_APPIAN_HOME>/server/archived-process/ folder. Customers may notice that the folder is automatically created if it did not exist before.

Actions

Go to <APPIAN_HOME>/_admin/_scripts/tools/

Edit the change-paths.(sh|bat) and update the OLD_PATH_ARCHIVED and NEW_PATH_ARCHIVED variables with absolute paths. Comment out the other lines. See below for an example:

#!/bin/bash
#OLD_PATH_MSG=/appian/server/msg
#OLD_PATH_MWS=/appian/_admin/mini
#OLD_PATH_NOTES=/appian/_admin/process_notes
OLD_PATH_ARCHIVED=<OLD_APPIAN_HOME>/server/archived-process
#NEW_PATH_MSG=/appian_new/server/msg/
#NEW_PATH_MWS=/appian_new/_admin/mini
#NEW_PATH_NOTES=/appian_new/_admin/process_notes
NEW_PATH_ARCHIVED=<NEW_APPIAN_HOME>/server/archived-process

pushd ..
#java -cp classpath.jar com.appiancorp.tools.ChangePaths MWS $OLD_PATH_MWS $NEW_PATH_MWS
#java -cp classpath.jar com.appiancorp.tools.ChangePaths FORUMS $OLD_PATH_MSG $NEW_PATH_MSG
#java -cp classpath.jar com.appiancorp.tools.ChangePaths NOTES $OLD_PATH_NOTES $NEW_PATH_NOTES
java -cp classpath.jar com.appiancorp.tools.ChangePaths ARCHIVED $OLD_PATH_ARCHIVED $NEW_PATH_ARCHIVED
popd

Archive a process and confirm if the .l file is displayed in <NEW_APPIAN_HOME>/server/archived-process

Debug

For Appian 21.2 and later, two debug flags are available to help users determine the values of OLD_PATH_NOTES and NEW_PATH_NOTES.

Note: Running the script with debug flags will not actually execute the change paths action.

To print single representative notes location from each server, edit the relevant line in change-paths.(sh|bat) to java -cp classpath.jar com.appiancorp.tools.ChangePaths NOTES <old path> <new path> NOTES_DEBUG_BRIEF
```
#!/bin/bash
OLD_PATH_NOTES=<OLD_APPIAN_HOME>/_admin/process_notes
NEW_PATH_NOTES=<NEW_APPIAN_HOME>/_admin/process_notes

pushd ..
java -cp classpath.jar com.appiancorp.tools.ChangePaths NOTES $OLD_PATH_NOTES $NEW_PATH_NOTES NOTES_DEBUG_BRIEF
popd
```
The script output will be similar to the following:
To print all notes locations from each server, edit the relevant line in change-paths.(sh|bat) to java -cp classpath.jar com.appiancorp.tools.ChangePaths NOTES <old path> <new path> NOTES_DEBUG_BRIEF so that the script will be similar to the following:
```
#!/bin/bash
OLD_PATH_NOTES=<OLD_APPIAN_HOME>/_admin/process_notes
NEW_PATH_NOTES=<NEW_APPIAN_HOME>/_admin/process_notes

pushd ..
java -cp classpath.jar com.appiancorp.tools.ChangePaths NOTES $OLD_PATH_NOTES $NEW_PATH_NOTES NOTES_DEBUG_FULL
popd
```
In the script output, "All notes locations" will be shown instead of "Sample notes location" from the sample output above and the user will be able to see all the subdirectories under <APPIAN_HOME>/_admin/process_notes/exec/

Windows

Refer the sections above for usage of the script. Instead of using change-paths.sh, makes the change in change-paths.bat and execute accordingly.
Despite being on Windows, please use / in the path variables instead of \ , e.g. set NEW_PATH_NOTES=E:/appian/_admin/process_notes
Add :: to comment out the lines that are not desired, e.g. ::set NEW_PATH_NOTES=c:/appian_new/_admin/process_notes

Affected Versions

This article applies to all versions of Appian.

Last Reviewed: November 2023