KB-1089 How to rename a user in Appian

This article includes instructions on how to change/edit/alter a user's username in Appian. If the account was created with the wrong name, the suggested approach is to create a new one with the desired name and deactivate the other one. This is feasible for accounts which are not yet associated with processes. If it is not feasible to create a new user, follow the instructions below.

Instructions

20.1 and later

Beginning in Appian 20.1, there are three new methods to rename users directly from the product and without the need for an outage. All methods can be performed by a System Administrator.

1. From the user profile page (Admin Console and Appian Designer)
2. Through the Rename Users smart service (bulk rename enabled)
3. Through the a!renameUsers() expression function that calls the smart service (bulk rename enabled)

See the following documentation for more details:

• 20.1 release notes 
• User Management
• Rename Users Smart Service & a!renameUsers()

19.4 and earlier (self-managed only)

Note the following:

• You MUST shut down all application server instances before running the rename. Failure to do so may cause user synchronization issues that can significantly degrade the end user experience on the site.
• Renaming users using this method is resource intensive, because it acts as a simple search and replace in every engine in Appian. These steps must be executed during off-hours.
• You will also need to update the username in any other systems where it is saved, including business datasources.

1. Contact Appian Technical Support for the correct version of the script based on the version of Appian used. If any of the user(s) being renamed are referenced in Decision objects, notify Appian Technical Support.
2. Disable LDAP Synchronization. It is important this remains disabled during the process, otherwise it is possible that the user will get re-introduced with the old username.
3. Unzip the script under <APPIAN_HOME>/_admin/_scripts on the server running the engines. 
4. Grant execute permissions on the file if using Linux. Otherwise just start a command line as the Administrator.
5. Navigate to <APPIAN_HOME>/_admin/_scripts.
6. Execute the following commands first to verify that the rename will execute successfully:
   1. Linux: ./renameUsers.sh --oldUsernames "oldUsername1;oldUsername2" --newUsernames "newUsername1;newUsername2" --validate.
   2. Windows: renameUsers.bat --oldUsernames "oldUsername1;oldUsername2" --newUsernames "newUsername1;newUsername2" --validate.
7. If there are any warnings, review your input parameters or contact Appian Support. If the script verifies that the new usernames are available and that all the old usernames exist, proceed with the following command:
   
   1. Linux: ./renameUsers.sh --oldUsernames "oldUsername1;oldUsername2" --newUsernames "newUsername1;newUsername2" &.
   2. Windows: renameUsers.bat --oldUsernames "oldUsername1;oldUsername2" --newUsernames "newUsername1;newUsername2".
8. Alternatively, if renaming a larger number of users, use the --usernamesFile option:
   • Linux: ./renameUsers.sh --usernamesFile "/home/john.smith/names.csv" &.
   • Windows: renameUsers.bat --usernamesFile "/home/john.smith/names.csv".
   • The usernamesFile should be named like <filename>.csv and have each line formatted as follows: <oldUsername>,<newUsername>.
9. Once the script is finished, an output file will get generated: <APPIAN_HOME>\_admin\_scripts\renameUsers_sql_queries_MM_DD_YY_hhmmss.sql.
10. Copy the generated SQL statements, log into the database containing the Appian data source with a user that has SELECT and UPDATE privileges over the database, and execute them. This will update the username in the primary DB. If the user has never logged into the environment, there will be no username to update in the primary DB.
11. Check that the user has been renamed.
12. You can re-enable LDAP Synchronization once the username has been updated.

Affected Versions

This article applies to all versions of Appian.