KB-1089 How to rename a user in Appian

Purpose

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

On-Premise

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.
  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" &.
    • WindowsrenameUsers.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 SELECTand 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 Syncrhonization once the username has been updated.

An enhancement has been logged to the Appian Product Team to allow for the functionality of renaming users in the product without the need for running a script or updating records in the usr table in the Appian data source. The reference number for this request is AN-53337.

Cloud

Create a support case with Appian Technical Support and provide the following information:

  • A time frame during off-hours to perform the user rename. A minimum of 2 hours is needed for user renames. During this time, the site will be inaccessible as the application server(s) will be shutdown. 
    • Note: Depending on the size of the engines, Appian Technical Support may determine a longer time frame is needed. This will be determined and coordinated through the support case if necessary.
  • A csv file of usernames to be renamed in the format below. Each <old_username>,<new_username> pair should be on it's own line. Appian Technical Support requires usernames to be provided in this format for user renames:
    <old_username_1>,<new_username_1>
    <old_username_2>,<new_username_2>

Affected Versions

This article applies to all versions of Appian.

Last Reviewed: June 2019

Related
Recommended