The Platform Configuration Tool works for upgrades from 2019.10, 2020.10, 2021.10, and 2022.4 to 2022.10. Post-installation checks and operations work after installing Orchestrator.
The UiPath 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.
The tool is available for download below and is also bundled with the
UiPathOrchestrator.msi installer. The bundled script can be found in the
Tools folder of the Orchestrator installation directory,
C:\Program Files (x86)\UiPath\Orchestrator\ by default. The script checks the Orchestrator machine. In the case of a multi-node installation, it is enough to run the tool on one node.
The Platform Configuration Tool does not follow the same versioning scheme as the
UiPathOrchestrator.msi installer and can be updated outside of the product release cycle. We recommend that you always download and use the latest version of the tool which is available below.
The script consists of three cmdlets intended to perform specific functions. A cmdlet-invoking command and its relevant parameters can be entered in the command line for immediate execution.
| Invoked using the |
Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation.
| Invoked using the |
Updates the public address of Orchestrator and checks if the new address is valid with the current certificate.
| Invoked using the |
Updates the Orchestrator SSL certificate or the Identity Server token-signing certificate.
| Invoked using the |
Adds a system administrator to the host tenant.
Checks if ASP.NET Core IIS module v3.1.x+ is installed and functional. If it's not, you are prompted to uninstall and reinstall the ASP.Net Core Hosting Bundle.
Checks if the CyberArk AIM agent is installed under the
C:\Program Files (x86)\CyberArk folder. If it's not, the user is prompted to add
CLIPasswordSdk.exe in the
UiPath.Orchestrator.dll.config file using
Plugins.SecureStores.CyberArk.CLIPasswordSDKExePath key after the installation.
This check is not performed if CyberArk is not found in
Checks if the
web.config file is decrypted. If encrypted, you need to manually decrypt it before upgrading. After the upgrade, most of Orchestrator's configuration settings are moved to
Learn how to encrypt the
Checks if the
<system.webServer> element contains any locked sections. If such sections exist, you need to manually unlock them in IIS.
Checks if SQL Server Scaleout is used. You are informed that during the installation Redis Scaleout is enabled.
Checks that external credential store plugins target a supported framework.
Checks that NLog plugins target a supported framework.
This check validates that the
Buckets.FileSystem.Allowlist app setting is present in Orchestrator versions starting with 2020.4. This covers both pre-installation checks (Orchestrator 2020.4) and post-installation checks (Orchestrator 2020.10+). Orchestrator versions prior to 2020.4 skip this check.
- To perform the following checks, you need to decrypt the
appSettingsconfig sections. If any of these configuration sections is encrypted, then a warning prompts you in the terminal, and the rest of the buckets validations are skipped.
Could not determine if any buckets with file system provider are in use. Config section 'connectionString' is encrypted, could not find the sql connection string to the UiPath database.
- If, for any reason, the buckets could not be retrieved from the database, a warning prompts you in the terminal, and the rest of the validations are skipped as well.
Could not determine if any buckets with file system provider are in use. Could not connect to the UiPath Database.
This validation is performed on the retrieved buckets root paths from the Orchestrator database buckets table. If there are any unqualified paths, then a warning prompts you in the terminal. A similar check for the unqualified paths is done for the paths in the
Buckets.FileSystem.Allowlistapp setting in the config file.
If any of the paths in the two sources is not valid or is unqualified, then it is not be taken into considerations for the rest of the validations described below.
Buckets.FileSystem.Allowlistapp setting is not set in the config file, then the terminal prompts you with an error asking you to add the allowlist to the config file. The suggested paths are the root path of the buckets that use the file system provider.
All storage buckets using the file system provider are not on the allowed list. Add the following setting in the configuration file to allow all exiting buckets root paths: <add key="Buckets.FileSystem.Allowlist" value="C:\work\stuff\Bucket\|C:\work\stuff\Bucket1\" />
- If the
Buckets.FileSystem.Allowlistapp setting is set in the config file, then a validation is performed on the buckets root path that use the FileSystem provider. If a bucket root path is not a subpath of any of the paths defined in the allowlist, then a warning prompts you in the terminal asking you to add the bucket root path to
There are some storage buckets using the file system provider that are not on the allowed list. The buckets feature will not work for buckets with root paths that are not on the allowed list. Check if any of the following paths are required to be on the allowed list and add them to the 'Buckets.FileSystem.Allowlist' key in configuration file: |C:\work\stuff\Buckets\|C:\work\stuff\Bucket1\
- Otherwise, if every bucket root path is a subpath of any path in the allowed list, then the terminal displays a success message.
All storage buckets using file system provider have the root path on the allow list in the configuration file.
Checks that all certificate requirements are met by your Orchestrator instance after an upgrade.
SSL Certificate Checks
hostnameof the Orchestrator site matches the Subject or a Subject Alternate Name (including wildcards) on the certificate,
- has a valid trust chain, and
- is not expired.
Identity Server Token-Signing Certificate Checks
- The certificate has the appropriate key size (
2048bits or larger),
- has a private key accessible by the AppPool user, and
- is not expired.
Check the docs on installation considerations for other areas impacted by an upgrade to 2020.10+ that you need to be aware of.
|Command & Parameters||Description|
|Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation.|
|Updates the public address of Orchestrator.|
The SQL Server PowerShell module is required to use this command. The module is installed by default with SQL Server. If you’re working on a machine that doesn’t have the module installed, see here how to install it.
Use this command with caution as it does not have a roll-back mechanism if a step errors out during execution.
|Updates the Orchestrator SSL certificate or the Identity Server token-signing certificate. Use it in conjunction with the |
|If access to the host organization is lost (for example, if the password for the system administrator is lost or the only users with system administrator accounts leave the company), you can use this command to add or restore a system administrator.|
|Optional. The name of the Orchestrator website on the target machine. Defaults to |
|Optional. Displays information about the tool options or available commands, such as the commands' syntax or the checks it performs.|
|Optional. The path of Orchestrator's installation directory. Usually |
Note: Make sure the installation directory path ends with a trailing backslash (
|Mandatory. The new public address of Orchestrator.|
|Optional. UiPath database connection string. If left empty, the value is read from the |
|Optional. The thumbprint of the new token signing certificate.|
|Optional.The thumbprint of the new SSL certificate.|
|Only mandatory when using the |
|Email of the host admin user to create or restore when using the |
Azure Active Directory
*SAML with email user mapping strategy
|Password of the host admin user to create when using the |
To work with the Platform Configuration Tool script, open an Administrator PowerShell script.
Locate the directory where you unzipped the Platform Configuration Tool archive and change the directory to that location:
cd C:\Program Files (x86)\UiPath\Orchestrator\Tools\UiPath.Platform.Configuration.Tool
The following example enables you to perform a validation of the pre-installation requirements of Orchestrator. The procedure logs its steps and output extra information at the
.\Platform.Configuration.Tool.ps1 ` -Readiness ` -SiteName "UiPath Orchestrator"
Pre-Installation checks successful output (for upgrades from 2020.4).
Validating 22.10 pre-installation requirements... Checking AspNetCore hosting module... AspNetCore hosting module is installed. Checking CyberArk CLIPasswordSDK.exe path... CyberArk CLIPasswordSDK.exe was found at the default installation path 'C:\Program Files (x86)\CyberArk\ApplicationPasswordSdk\CLIPasswordSDK.exe'. Checking Web.config sections encryption... Web.config sections are not encrypted. Checking IIS configuration locked sections... Configuration sections are not locked. Checking Orchestrator ssl certificate subject alternative names... Orchestrator host name is valid for the ssl certificate subject alternative names. Checking sql server scaleout use... Sql server scaleout is not used. Checking external credential store plugins target framework... Credential stores plugins validation is finished. Checking external NLog plugins target framework... NLog plugins validation is finished. Checking buckets with file system storage provider... All storage buckets using file system provider have the root path on the allowed list in the configuration file. Checking platform certificates... Platform certificates validation is finished. All 22.10 pre-installation checks are done. Platform readiness validations: 10 succeeded, 0 failed and 0 warning(s).
The following example enables you to update the Orchestrator SSL and the Identity Server token-signing certificates.
.\Platform.Configuration.Tool.ps1 ` -UpdateUiPathCertificate ` -KeepOldCertificate $false -SiteName "UiPath Orchestrator" ` -NewSSLThumbprint "a1b2c3d4" ` -NewTokenSigningThumbprint "z6y5x4v3"
Make sure the certificates have the appropriate permissions set to prevent an internal server error. Refer to Troubleshooting Certificates for more details.
If the private key has not been added to the certificate, you can add it manually by taking the following steps:
- To locate the private key, start Internet Information Service (IIS) Manager, and select Application Pool. You should find the private key for each service under the Identity column.
- Go to Manage Computer Certificates under Control Panel.
- Go to Personal/Certificates.
- Right-click New certificate, then go to All Tasks > Manage PrivateKey to add the private key.
The following example enables you to update the Orchestrator URL.
.\Platform.Configuration.Tool.ps1 ` -UpdateUiPathUrl ` -OrchestratorUrl "https://mydomainname" ` -SiteName "UiPath Orchestrator" ` -SqlConnectionString "Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;"
Although we recommend using lowercase for the Orchestrator URL, the tool automatically converts any uppercase string to lowercase.
The following example creates a new system administrator on the host tenant using basic authentication. Note that if an external identity provider is set as exclusive, basic authentication is only accessible through the
hostlogin URL documented in Accessing Identity Management Portal.
.\Platform.Configuration.Tool.ps1 ` -AddHostAdmin ` -SiteName "UiPath Orchestrator" ` -HostAdminUsername someuser ` -HostAdminPassword som3pwd! ` -HostAdminEmail email@example.com
The output is color-coded.
Elements are missing or are not configured and will prevent the installation.
You can install Orchestrator, but additional benefits will be absent.
The environment is ready for installation.
Updated 2 months ago