Platform Configuration Tool

Important: The Platform Configuration Tool works for upgrades from 2018.4, 2018.10, 2019.10, and 2020.4 to 2020.10. Post-installation checks and operations work after installing Orchestrator.

Overview

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 and UiPlatformInstaller.exe installers. 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 and UiPlatformInstaller.exe installers 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.

Download the tool

Prerequisites

Software	Compatible Version
PowerShell	5.1
WebAdministration Module	N/A

Script Cmdlets

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.

Cmdlet	Description
Test-PlatformReadiness	Invoked using the -Readiness command. Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation.
Update-UiPathUrl	Invoked using the UpdateUiPathUrl command. Updates the public address of Orchestrator.
Update-UiPathCertificate	Invoked using the UpdateUiPathCertificate command. Updates the Orchestrator SSL certificate or the Identity Server token-signing certificate.

Pre-Installation Checks

Asp.Net Core

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.

CyberArk AIM

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 UiPath.Orchestrator.dll.config.

Web.config Encryption

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 UiPath.Orchestrator.dll.config.

Learn how to encrypt the UiPath.Orchestrator.dll.config file.

Web.config Locked Sections

Checks if the <system.webServer> element contains any locked sections. If such sections exist, you need to manually unlock them in IIS.

SQL Server Scaleout

Checks if SQL Server Scaleout is used. You are informed that during the installation Redis Scaleout is enabled.

Credential Store Plugins

Checks that external credential store plugins target a supported framework.

NLog Plugins

Checks that NLog plugins target a supported framework.

FileSystem Buckets

This check validates that the Buckets.FileSystem.Allowlist app setting is present in Orchestrator versions starting with v2020.4. This covers both pre-installation checks (Orchestrator v2020.4) and post-installation checks (Orchestrator v2020.10). Orchestrator versions prior to v2020.4 skip this check.

• To perform the following checks, you need to decrypt the connectionStrings and appSettings config 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.Allowlist app 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.
• If the Buckets.FileSystem.Allowlist app 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.Allowlist app 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 Buckets.FileSystem.Allowlist .

  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.

Post-Installation Checks

Certificate Requirements

Checks that all certificate requirements are met by your Orchestrator instance after an upgrade.

SSL Certificate Checks

• the hostname of 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 (2048 bits or larger),
• has a private key accessible by the AppPool user, and
• is not expired.

Other Considerations

Check the docs on installation considerations for other areas impacted by an upgrade to v2020.10+ that you need to be aware of.

Running the Script

Command Reference

Command & Parameters	Description
-Readiness	Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation. Parameters: -SiteName -Help -InstallationDirectory
-UpdateUiPathUrl	Updates the public address of Orchestrator. Parameters: -SiteName -OrchestratorUrl -SqlConnectionString Important: 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. Important: Use this command with caution as it does not have a roll-back mechanism if a step errors out during execution.
-UpdateUiPathCertificate	Updates the Orchestrator SSL certificate or the Identity Server token-signing certificate. Use it in conjunction with the -readiness command to check the validity of the new certificates. Parameters: -SiteName -NewTokenSigningThumbprint -NewSSLThumbprint

Script Parameters

Parameter	Description
-SiteName	Mandatory. The name of the Orchestrator website on the target machine. -InstallationDirectory and SiteName are mutually exclusive.
-Help	Optional. Displays information about the tool options or available commands, such as the commands' syntax or the checks it performs.
-InstallationDirectory	Optional. The path of Orchestrator's installation directory. Usually C:\Program Files (x86)\UiPath\Orchestrator\ . -InstallationDirectory and SiteName and SiteName are mutually exclusive. Note: Make sure the installation directory path ends with a trailing backslash (\).
-OrchestratorUrl	Mandatory. The new public address of Orchestrator.
-SqlConnectionString	Optional. UiPath database connection string. If left empty, the value is read from the appsettings.Production.json file.
-NewTokenSigningThumbprint	Optional. The thumbprint of the new token signing certificate.
-NewSSLThumbprint	Optional.The thumbprint of the new SSL certificate.

Examples

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

Performing a Readiness Check

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 -verbose level.

.\Platform.Configuration.Tool.ps1 `
  -Readiness `
  -SiteName "UiPath Orchestrator"

Pre-Installation checks successful output.

Validating 20.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 20.10 pre-installation checks are done.
Platform readiness validations: 10 succeeded, 0 failed and 0 warning(s).

Changing Certificates After Installation

The following example enables you to update the Orchestrator SSL and the Identity Server token-signing certificates.

.\Platform.Configuration.Tool.ps1 `
  -UpdateUiPathCertificate `
  -SiteName "UiPath Orchestrator" `
  -NewSSLThumbprint "a1b2c3d4" `
  -NewTokenSigningThumbprint "z6y5x4v3"

Note: Make sure the certificates have the appropriate permissions set to prevent an internal server error. Refer to Troubleshooting Certificates for more details.

Changing Orchestrator URL

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;"

Output

The output is color-coded.

Color	Description
Red	Blockers Elements are missing or are not configured and will prevent the installation.
Yellow	Warnings You can install Orchestrator, but additional benefits will be absent.
Green	Messages The environment is ready for installation.