orchestrator
2021.10
false
OUT OF SUPPORT
Orchestrator Installation Guide
Automation CloudAutomation Cloud Public SectorAutomation SuiteStandalone
Last updated Oct 31, 2024

About Updating and Migrating

Overview

Warning: Please keep in mind that this information pertains to the version that you are upgrading to, NOT to the version that you are upgrading from. As such, make sure that you read the correct details before proceeding.

You can directly update Orchestrator to 2021.10 if you currently use any of the following versions:

  • 2021.x
  • 2020.x
  • 2019.x
  • 2018.4

    Important:

    If you use a version lower than 2018.4, you need to upgrade to v2018.4 or v2019.x or 2020.x, and then jump to 2021.10.

    We recommend using 2019.10 as an intermediate version.

To see the latest available versions, please check the Release Notes page.

Preinstallation Checklist

Before proceeding with an Orchestrator upgrade/installation, carefully review the following task list:

Description

Details

available Review the system requirements

Ensure that you meet the prerequisites, hardware and software requirements for the version you want to install.

available Learn about changes introduced by the new deployment

A new Orchestrator deployment brings about changes that you should be aware of. Some of the items must be taken care of before an upgrade/installation. Some are notes on the biggest changes and recommendations on how to get the best of the new version.

available Run the Platform Configuration Tool

The Platform Configuration Tool is a PowerShell script used to assist you in the successful installation/upgrade of Orchestrator. It helps you check the sanity and readiness of your environment before an upgrade, and assists you in performing several operations post-installation.

available Stop Orchestrator

Upgrades of your Orchestrator must be made with the application stopped. Performing any updates while the application is running can result in errors and is not supported.

Directly Updating Orchestrator

Installation artifacts are provided when you first purchase Orchestrator or they can be provided by your customer success manager or our support team. There are a few ways to directly update:

Using the Windows Installer

UiPathOrchestrator.msi performs an in-place update that copies all your settings and creates a backup folder for the old version. It is suitable for both one node and multi-node architecture. Some web.config settings are not copied if the version you are upgrading from was installed using the deprecated scripts. The repair functionality of the Windows Installer is not supported.
If the Orchestrator you want to update was installed using the now deprecated UiPathPlatformInstaller.exe, use the Windows installer to update to this version.

Using the Azure Script

A complex update of Orchestrator and its components on one or multiple nodes, in the Azure Portal.

Using the UiPathPlatform Installer

An executable that enables you to update Orchestrator, Robot, and Studio. It is suitable for one-node architectures. The processes are the same as those you would go through using the Windows installers, UiPathStudio.msi and UiPathOrchestrator.msi.
Unlike UiPathStudio.msi and UiPathOrchestrator.msi, UiPathPlatformInstaller.exe does not accept command line arguments.

Update Considerations

Encryption

During an Orchestrator update, the installer cannot read an encrypted SecureAppSettings section within web.config . In order to read the EncryptionKey from Orchestrator's web.config and then migrate it into Identity Server's appsettings.Production.json, the key must be plain text. You need to manually decrypt the section before updating Orchestrator. After the Orchestrator update process was finalized, remember to re-encrypt the SecureAppSettings section in web.config.

Certificates

Note the new certificate requirements. If your existing certificate doesn't meet them, here is how to get a valid certificate and how to replace it in the existing Orchestrator instance, before upgrading.

For security reasons, for the certificate used to sign the access tokens generated by the Identity Server, make sure to use a public key on 2048 bits. The certificate's location has to be set within appsettings.Production.json's Signing Credential section.

Database

Regardless of how you choose to update, if the database you point to does not exist, it is automatically created while running the update. If you point to an existing database, it is updated during the same process. The Orchestrator SQL database is automatically set to be case-insensitive (“OrchDB” = “orchdb”) at installation.

External Providers

While performing the update, if you have any external providers enabled in web.config, you are prompted about the manual changes you need to perform on your preexistent external providers.

Known Issues

Database timeout errors while upgrading to 2023.10+

Having more than 100,000 groups in Orchestrator may cause a timeout error while upgrading to 2023.10+.

To overcome this, run the following script directly in your database, then retry the upgrade:

-- 1. Delete group subscriptions

DECLARE @rowCount BIGINT = 1
DECLARE @batchSize BIGINT = 4000
DECLARE @pivotDate DATETIME = GETUTCDATE()
WHILE (@rowCount > 0)
BEGIN
    DECLARE @subscriptionsToDeleteIds TABLE(
        [Id] UNIQUEIDENTIFIER NOT NULL
    )
    INSERT INTO @subscriptionsToDeleteIds
    SELECT TOP(@batchSize) [ns].[Id]
    FROM [dbo].[NotificationSubscriptions] [ns]
    JOIN [dbo].[Users] [u] ON [u].[Id] = [ns].[UserId]
    WHERE [u].[Type] = 3 AND -- Group
        [u].[CreationTime] <= @pivotDate AND
        [u].[IsDeleted] = 0
    DELETE FROM [dbo].[NotificationSubscriptions]
    WHERE [Id] IN (
        SELECT [Id] FROM @subscriptionsToDeleteIds
    )
    OPTION (MAXDOP 1)
    SET @rowCount = @@ROWCOUNT
    WAITFOR DELAY '00:00:00.1'
END

-- 2. Create index on UserNotifications

IF NOT EXISTS(SELECT * FROM sys.indexes WHERE OBJECT_ID = OBJECT_ID(N'[dbo].[UserNotifications]') AND NAME = N'IX_UserId_CreationTime')
   CREATE NONCLUSTERED INDEX [IX_UserId_CreationTime] ON [dbo].[UserNotifications]
   (
       [UserId] ASC,
       [CreationTime] ASC
   ) INCLUDE ([TenantNotificationId]) WITH (ONLINE = ON);-- 1. Delete group subscriptions

DECLARE @rowCount BIGINT = 1
DECLARE @batchSize BIGINT = 4000
DECLARE @pivotDate DATETIME = GETUTCDATE()
WHILE (@rowCount > 0)
BEGIN
    DECLARE @subscriptionsToDeleteIds TABLE(
        [Id] UNIQUEIDENTIFIER NOT NULL
    )
    INSERT INTO @subscriptionsToDeleteIds
    SELECT TOP(@batchSize) [ns].[Id]
    FROM [dbo].[NotificationSubscriptions] [ns]
    JOIN [dbo].[Users] [u] ON [u].[Id] = [ns].[UserId]
    WHERE [u].[Type] = 3 AND -- Group
        [u].[CreationTime] <= @pivotDate AND
        [u].[IsDeleted] = 0
    DELETE FROM [dbo].[NotificationSubscriptions]
    WHERE [Id] IN (
        SELECT [Id] FROM @subscriptionsToDeleteIds
    )
    OPTION (MAXDOP 1)
    SET @rowCount = @@ROWCOUNT
    WAITFOR DELAY '00:00:00.1'
END

-- 2. Create index on UserNotifications

IF NOT EXISTS(SELECT * FROM sys.indexes WHERE OBJECT_ID = OBJECT_ID(N'[dbo].[UserNotifications]') AND NAME = N'IX_UserId_CreationTime')
   CREATE NONCLUSTERED INDEX [IX_UserId_CreationTime] ON [dbo].[UserNotifications]
   (
       [UserId] ASC,
       [CreationTime] ASC
   ) INCLUDE ([TenantNotificationId]) WITH (ONLINE = ON);

Antivirus software issues

Some antivirus software can prevent Data Migration scripts from functioning correctly during an upgrade.

Login attempts issues

After updating your Orchestrator from 2019.10 or older, the Profile page won't display login attempts previous to that update.

Updating Your License After Installation

After you upgrade or migrate Orchestrator, we recommend that you update your license information from the Licenses page using either online or offline activation. For instructions, see Activating Your License.

Important: If you are upgrading or migrating from a version that is older than 2019.10, you must update your license information, otherwise you do not benefit from the grace period at license expiration, which can cause service disruption.

Package Migration

In v2020.10+, Legacy is no longer a supported NuGet repository type. Packages previously residing in a Legacy repository are migrated to a Composite repository. For composite repositories, package location is configured using the Storage.Type and Storage.Location parameters in UiPath.Orchestrator.dll.config. After the upgrade, all Legacy-related app settings become deprecated and no longer have an effect:
  • NuGet.Packages.Path
  • NuGet.Activities.Path
  • Nuget.EnableRedisNodeCoordination
  • Nuget.EnableNugetServerLogging
  • NuGet.EnableFileSystemMonitoring
  • NuGet.Repository.Type
The new package location depends on how you configured the NuGet.Packages.Path and NuGet.Activities.Path parameters in web.config for the previous Orchestrator version.

Default Location

If you stored the packages in the default locations (~/NuGetPackages and ~/NuGetPackages/Activities), the new package location becomes RootPath=.\Storage.

Pre 2020.10 Key Defaults - web.config

2020.10+ Key Defaults - UiPath.Orchestrator.dll.config

<add key="NuGet.Packages.Path" value="~/NuGetPackages" />

<add key="NuGet.Activities.Path" value="~/NuGetPackages/Activities" />

<add key="Storage.Type" value="FileSystem" />

<add key="Storage.Location" value="RootPath=.\Storage" />

Custom Location

If you stored the packages in a custom location, during the installation you are asked for a new storage location. For silent installs, the STORAGE_TYPE and STORAGE_LOCATION parameters become mandatory, unless you specifically add them in web.config (Storage.Type and Storage.Location) prior to the upgrade.

Packages Migration Matrix

The matrix below describes when the STORAGE_TYPE and STORAGE_LOCATION parameters are requested or ignored during an upgrade. The matrix takes into consideration the version you are upgrading from, as well as the package location customization in both the previous version and in 2020.10 and later.

For example, based on this feature combination, the matrix shows that the two parameters are requested (flagged with a check mark) in Silent Mode in the following cases:

  • For an upgrade from version 2018.4, if the package was stored in a custom location
  • For an upgrade from version 2019.4+, if the package was stored in a custom location, but its new storage location is a default one

    Upgrade From

    Previous Legacy Location

    New Composite Location

    Parameters Requested in the Storage Window

    Parameters Requested in Silent Mode

    Parameters Ignored from CMD

    2018.4

    Default

       

    available

    2018.4

    Custom

     

    available

    available

     

    2019.4+

    Default

    Default

      

    available

    2019.4+

    Default

    Custom

      

    available

    2019.4+

    Custom

    Default

    available

    available

     

    2019.4+

    Custom

    Custom

      

    available

Migration Errors

If, for any reason, package migration fails, you are presented with the following options:

  • Retry - Package migration is restarted. Packages that have already been migrated are skipped.
  • Abort - The installation is restarted. During the migration step, packages that have already been migrated are not skipped and are migrated again. For this reason, you may find duplicate files in different containers. This only happens when migrating from versions older than 2019.4.
  • Continue - The migration is being carried on with.

Upgrades from 2019.10

Migration as part of an upgrade from 2019.10 can sometimes cause package names to change, thus becoming unavailable in Orchestrator. If this happens, we recommend that you manually upload any affected package.

Was this page helpful?

Get The Help You Need
Learning RPA - Automation Courses
UiPath Community Forum
Uipath Logo White
Trust and Security
© 2005-2024 UiPath. All rights reserved.