How To Migrate On-Prem Orchestrator And MSSQL To New Servers?

What are the steps to migrate Orchestrator, its database, or both to another server with minimal effort?

Description

Several scenarios may require migrating Orchestrator and/or its database to another server, including hardware and OS updates, domain name changes, etc.
This article will address the most common scenarios and provide guidance for a successful server migration of the platform and its components.

Resolution

Migrating Orchestrator and database

This process covers migrating Orchestrator and MS SQL database to a new server. These may or may not be on the same server.

  1. Stop the Orchestrator server in IIS

  2. Backup the Orchestrator database

  3. Backup Orchestrator installation folder

  4. Confirm the new SQL server meets the hardware and software requirements of the target version and install SQL Server.

  5. Confirm the new Orchestrator server meets the hardware and software requirements of the target version and configure the prerequisites.

  6. Create a new certificate. This may be a CA-issued or self-signed certificate, as it best meets security requirements.

  7. Restore the original database to the new SQL Server and grant the needed permission (db_owner).

  8. Install Orchestrator from the command line using the parameters.json file created following the Adding Nodes to Multi-node Orchestrator process or by specifying the DB_CONNECTION_STRING and APP_ENCRYPTION_KEY parameters.

    For more information on command line parameters, see Command Line Parameters. This method will preserve the license information since this information is stored in the SQL database.

    Example installation command with parameters file:

    https://uipath.lightning.force.com/lightning/r/Knowledge__kav/ka05b000000ENi2AAG/view
    

    Example installation command with command line parameters specified:

    UiPathOrchestrator.msi APPPOOL_IDENTITY_TYPE=USER APPPOOL_USER_NAME=serviceAccount APPPOOL_PASSWORD=1234qwer DB_CONNECTION_STRING="Server=.\sqlexpress;Trusted_Connection=True;Database=UiPath" APP_ENCRYPTION_KEY=yk0nz5oh9sw++uGScQiK82FbfAwrA0Td1E1RB8XscJw=” /l*vx 
    
  9. Update the Orchestrator URL, if needed.

  10. Migrate packages from the original Orchestrator location, if originally installed on the local filesystem.

  11. Perform an IISRESET to restart IIS and Orchestrator.

  12. Once Orchestrator access is confirmed, Delete the temporary database.

Alternative installation, replacing steps 7 & 8 above

  1. Install Orchestrator and create a new, temporary database automatically by referring to The Windows Installer. Run the installer as the user account that will be used for the Application Pool User and database user to minimize permission issues.

  2. Restore the original database to the new SQL Server, and grant the needed permission (db_owner).

  3. Update the "EncryptionKey" value in the section from the original Orchestrator server's web.config. Below is an example:


  4. Update database connection strings in Orchestrator to connect to the new database:
    {Orchestrator Install Folder}\UiPath.Orchestrator.dll.config
    {Orchestrator Install Folder}\Identity\appsettings.Production.json
    {Orchestrator Install Folder}\Webhooks\appsettings.Production.json
    {Orchestrator Install Folder}\Resource Catalog\appsettings.Production.json
    {Orchestrator Install Folder}\UiPath\TestManager\appsettings.Production.json

  5. Continue from step 9 in the above process.

Migrate Orchestrator server only

  1. Stop the Orchestrator server in IIS

  2. Backup the Orchestrator database

  3. Backup Orchestrator installation folder

  4. Confirm the new Orchestrator server meets the hardware and software requirements of the target version and configure the prerequisites.

  5. Create a new certificate. This may be a CA-issued or self-signed certificate, as it best meets security requirements.

  6. Install Orchestrator from the command line using the parameters.json file created following the Adding Nodes to Multi-node Orchestrator process.

    Example Installation Command:

    UiPathOrchestrator.msi SECONDARY_NODE=1 PARAMETERS_FILE=install.json /l*vx  /Q
    
  7. Follow the steps in Changing the Orchestrator URL to update the configuration and database URL references.

  8. Migrate packages from the original Orchestrator location, if originally installed on the local filesystem.

  9. Perform an IISRESET to restart IIS and Orchestrator.

  10. Confirm Orchestrator access.

Migrate SQL database only

  1. Backup the Orchestrator database

  2. Confirm the new SQL server meets the hardware and software requirements of the target version and install SQL Server.

  3. Restore the original database to the new SQL Server and grant the needed permission (db_owner).

  4. Stop the Orchestrator server.

  5. Update database connection strings in Orchestrator to connect to the new database:
    {Orchestrator Install Folder}\UiPath.Orchestrator.dll.config
    {Orchestrator Install Folder}\Identity\appsettings.Production.json
    {Orchestrator Install Folder}\Webhooks\appsettings.Production.json
    {Orchestrator Install Folder}\Resource Catalog\appsettings.Production.json
    {Orchestrator Install Folder}\UiPath\TestManager\appsettings.Production.json

  6. Restart the Orchestrator server.

  7. Confirm Orchestrator access.

Troubleshooting failed migrations

If, after following the steps above for the relevant scenario, the migration fails, please create a support case and share the following:

  • Installation logs for Orchestrator migrations

  • The Zip file output of the Orchestrator-Logs-2.0.ps1.zip. The script collects the following information:

    • Application logs

    • Security logs

    • System logs

    • CAPI2 logs (for certificate issues)

    • Appsettings.Production.json

    • UiPath.Orchestrator.dll.config

    • IIS logs from the last 7 days

    • Output of the Platform Configuration Tool readiness check

    • Network trace (optional, can be enabled during the script execution)

  • To use the script, run it in an Administrator PowerShell window on the Orchestrator machine.

    1. During the execution, specify the Orchestrator installation path; press enter to use the default path.

    2. Subsequently, there will be an option to initiate a network trace (Note that this can significantly increase the script's runtime).

    3. Reproduce the identifiable issue and once done, press enter to continue.

    4. The script will then gather all the necessary logs, output the results of the Readiness check, and save everything in an archive. This archive should then be sent back to us for further analysis.