- Getting Started
- Requirements
- Best Practices
- Installation
- Updating
- Identity Server
- Troubleshooting startup errors
About Updating and Migrating
You can directly update Orchestrator to 2022.4 if you currently use any of the following versions:
- 2021.x
- 2020.x
-
2019.x
Important:If you use version 2018.4 you need to upgrade to 2019.x or 2020.x or 2021.x and then jump to 2022.4.
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 2022.4.
We recommend using 2019.10 as an intermediate version.
To see the latest available versions, please check the Release Notes page.
Before proceeding with an Orchestrator upgrade/installation, carefully review the following task list:
Description |
Details |
---|---|
Review the system requirements |
Ensure that you meet the prerequisites, hardware and software requirements for the version you want to install. |
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. |
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. |
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. |
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:
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.
UiPathPlatformInstaller.exe
, use the Windows installer to update to this version.
A complex update of Orchestrator and its components on one or multiple nodes, in the Azure Portal.
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
.
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.
appsettings.Production.json
's Signing Credential section.
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.
web.config
, you are prompted about the manual changes you need to perform on your preexistent external providers.
When upgrading to the latest Orchestrator version, all your local accounts are automatically migrated from Orchestrator to Identity Server and converted to the required format.
This change does not impact your robots.
Once the conversion is complete, you can no longer use basic authentication to log in with the respective users.
While upgrading to the latest Orchestrator version, we strongly recommend to use the same Application Pool identity type for Identity Server and Webhooks as the one used for Orchestrator during the original installation.
For example, if you set the Application Pool identity type as a custom account during the Orchestrator v2020.10 installation, while upgrading to v2021.10, select the same Application Pool identity type (i.e., custom account) for both Identity Server and Webhooks applications. Otherwise, the access to the SQL server may be blocked.
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.
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.
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
NuGet.Packages.Path
and NuGet.Activities.Path
parameters in web.config
for the previous Orchestrator version.
~/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 |
---|---|
|
|
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.
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 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 |
---|---|---|---|---|---|
2019.4+ |
Default |
Default |
| ||
2019.4+ |
Default |
Custom |
| ||
2019.4+ |
Custom |
Default |
|
| |
2019.4+ |
Custom |
Custom |
|
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.
- Overview
- Preinstallation Checklist
- Directly Updating Orchestrator
- Using the Windows Installer
- Using the Azure Script
- Update Considerations
- Encryption
- Certificates
- Database
- External Providers
- Users
- Application Pool Identities
- Known Issues
- Updating Your License After Installation
- Package Migration
- Default Location
- Custom Location
- Packages Migration Matrix
- Migration Errors