UiPath Installation and Upgrade

The UiPath Installation and Upgrade Guide

Web.Config

The web.config file (C:\Program Files (x86)\UiPath\Orchestrator) contains multiple settings that enable you to configure Orchestrator to your liking. Most of the parameters that interest you can be found under appSettings, but there might be some logging configurations that can be changed after install.

πŸ“˜

Note:

It is recommended that only administrators change the values of these parameters.

It is recommended that you shut down the IIS site in order to modify web.config settings under any circumstances.

Parameters that are not documented in this page should not be changed, or have counterparts in the Settings pages.

All parameters are case sensitive.

App Settings

Advanced Installation Settings

  • DeploymentUrl - The address of a web app that uses the NuGet protocol (NuGet, MyGet), so that you can store your packages. By default, this is empty as Orchestrator provides a default NuGet package manager. This value should be changed only if you install Orchestrator in a cluster. For this to work properly, you also have to configure the following parameters: requireApiKey, NuGet.Packages.ApiKey, and NuGet.Packages.Path as described below. The default value is used in the initial seeding of the database.
  • Logs.RobotLogs.ReadTarget - Enables you to configure the source from which Orchestrator reads and populates logs (e.g. database or robotelasticbuffer).
  • EncryptionKeyPerTenant.Enabled - Enables you to use different encryption keys per tenant, based on a Microsoft Azure Key Vault account. The following values can be attributed:
    • false - Uses a single encryption key on the entire Orchestrator instance. This is the default value.
    • true - Uses a different encryption key for each tenant, enhancing your tenant security and providing a better segregation of sentive data. If you enable this feature, you must also fill in the EncryptionKeyPerTenant.KeyProvider parameter, as well as the ones in the SecureAppSettings section.
  • EncryptionKeyPerTenant.KeyProvider - Enables you to indicate in which key management application to store the encryption keys generated per tenant from Orchestrator. Set it to AzureKeyVault to use a preconfigured Microsoft Azure Key Vault. We do not provide Azure Key Vault licenses. Please note that you also have to configure the parameters described in the SecureAppSettings section. If EncryptionKeyPerTenant.Enabled is set to false, the parameter is not used.

Changes made to the encryption settings here need to be mirrored in the Identity Server appsettings.Production.json file, according to the following field equivalence:

Orchestrator Web.Config Field

Identity Server appsettings.Production.json Field

EncryptionKeyPerTenant.Enabled

EncryptionKeyPerTenant

Azure.KeyVault.VaultAddress

AzureKeyVaultAddress

Azure.KeyVault.CertificateThumbprint

AzureKeyVaultCertificateThumbprint

Azure.KeyVault.ClientId

AzureKeyVaultClientId

πŸ“˜

Note:

In order for changes concerning cron jobs to take effect, the Database.EnableAutomaticMigrations parameter must be set to true beforehand.

Queues

  • autogenerateStatistics - Automatically generates transaction charts. By default, this parameter is set to true.
  • inProgressMaxNumberOfMinutes - The maximum amount of time queue items can have the In Progress status. After this time, the status of the queue items changes to Abandoned. By default, this is set to 1440 minutes (24 hours).
  • QueuesStatisticsScheduleCron - The amount of time at which to update queue items statistics in the Dashboard and Transactions page, and the Chart window. By default, they are updated every minute.
  • UpdateUncompletedItemsJobCron - The amount of time at which to look in the database for queues that need to be moved to Abandoned. By default, this parameter is set to every hour.
  • Queue.MaxSlaInMinutes - The maximum value the SLA can be set to, expressed in minutes. By default, the value is 129600 minutes (90 days), and it is displayed by default in web.config, including in update scenarios.
  • Queue.MaxSchemaFileSizeInKilobytes - The maximum file size, in KB, of the JSON schema against which queue item data and output is validated. This setting does not appear by default in the web.config file.
  • Queue.SlaReadaheadTimeLimitHours - The amount of time in which queue item deadlines must fall for the items to be taken into account when making predictions. The default value is 24 hours. This parameter is not displayed by default in web.config.
  • Queue.MaxSpecificDataSizeInKiloBytes - The maximum size of Specific Data content for new queue items, in kilobytes. For clean Orchestrator installations, this parameter is hidden and has a default value of 1024 (1MB). In upgrade scenarios, this parameter is visible and has a value 204800 (200MB).

Alerts

  • DailyAlertMailJobCron - Enables you to configure a cron expression which controls when daily email alerts are sent. This only works if email alerts are enabled. The report contains all the Fatal and Error severity alerts generated the previous day. By default, it is sent every day at 7 a.m.
  • Alerts.Email.Enabled - Enable or disable email alerts for Fatal and Error messages. This parameter corresponds to the Enable Alerts Email check box from the Settings page. By default, it is set to false. For it to work, you also have to configure the email related settings, from the Settings page. The default value is used in the initial seeding of the database. Changing the value afterwards does not toggle email alerts.
  • Alerts.Email.SendTimeoutMs - Enables you to configure timeout duration for each email alert. It is used for the periodic errors email alert, daily email alert, and license expiration email alerts. This parameter is not displayed by default in web.config. The default value is 5000 milliseconds.
  • NotificationDistributerJobCron - The frequency with which alert notifications are sent to the interface. By default, alerts are sent every 10 seconds.
  • PeriodicErrorMailJobCron - Enables you to configure a cron expression which controls the frequency with which periodic email alerts are sent. This only works if email alerts are enabled. The default value is every 10 minutes, meaning the report contains Fatal and Error severity alerts generated in the past 10 minutes. If no alerts have been generated, no report is sent.
  • PasswordComplexity - Controls the validation rules for password complexity and is expressed using regular expressions. The complexity applies to all passwords (including the host admin one) by default but each tenant can customize their user login password complexity on the Security tab in the Settings page. By default, passwords must contain at least 8 characters and at least one letter and a digit.
  • SystemJobs.DetectNotRespondingRobots.MaxAlertCount - Enables you to limit the number of alerts that are sent when Robots become unresponsive. This parameter can be useful if your Orchestrator instance deals with a very large number of Robots and most of them become unresponsive often. Please note that it is not displayed in the configuration file by default. For example, if you want to limit the number of alerts you receive for unresponsive Robots to 10, add <add key="SystemJobs.DetectNotRespondingRobots.MaxAlertCount" value="10" /> in the web.config file, under all the other alerts parameters. If you apply this setting, please note that a warning is raised in the Event Viewer when the total number of alerts is higher than that of the one configured, such as: Alerts not published: total number of unresponsive sessions (21) is bigger than configured max allowed (10)..
  • SystemJobs.LicenseExpirationAlert.DaysBefore - Enables you to define the time intervals before the license expiry date when you receive email alerts. The default value is 180,90,30,14,7,1, meaning you receive email alerts 6 times: 180, 90, 30, 14, 7 and 1 day before your license expires. You can define fewer values in order to reduce the email alerts' frequency. For example, this can be done by adding the following key in the web.config file: <add key="SystemJobs.LicenseExpirationAlert.DaysBefore" value="90,30,14" />.

Deployment

  • NuGet.Repository.Type - Specifies where NuGet packages are saved. It can be populated as follows:
    • Legacy - Uses FileSystem for package sync. This is the default value in update scenarios. Packages and activities are saved in the locations specified in the NuGet.Packages.Path and NuGet.Activities.Path parameters, respectively. Can be used with either NuGet.EnableRedisNodeCoordination or NuGet.EnableFileSystemMonitoring. Example: <add key="NuGet.Repository.Type" value="Legacy" />.
    • Composite - Package metadata is saved to the SQL database for faster search and filtering. Packages are saved to the location specified through the Storage.Type and Storage.Location parameters. Example: <add key="NuGet.Repository.Type" value="Composite" />. This parameter with Storage.Type set to FileSystem is the default in clean installs.

πŸ“˜

Note:

The use of copy-paste commands in the packages-dedicated folder is not supported if NuGet.Repository.Type is set to Composite.

  • Storage.Type - Defines the target where packages in the Composite scenario, and execution media are to be saved. It can be populated with the following targets:
    • FileSystem - such as <add key="Storage.Type" value="FileSystem" />.
    • Azure - such as <add key="Storage.Type" value="Azure" />.
    • Amazon - such as <add key="Storage.Type" value="Amazon" />.
    • Minio - such as <add key="Storage.Type" value="Minio" />.
  • Storage.Location - Defines the actual location where packages in the Composite scenario, and execution media are to be saved. Particularities:
    • FileSystem - provide an absolute path in the RootPath=C:\FolderName\AnotherFolderName format, such as <add key="Storage.Location" value="RootPath=C:\FolderName\AnotherFolderName" />. In the provided folder, three other sub-directiories are created: ExecutionMedia, Packages, and Libraries. Files are saved according to their type in dedicated folders, at the specified location. By default, they are stored at the following path: C:\Program Files (x86)\UiPath\Orchestrator\Storage\Orchestrator-tenantKey, where Orchestrator-tenantKey is the key of your tenant as found in the database. For example C:\Program Files (x86)\UiPath\Orchestrator\Storage\Orchestrator-12ab1234-a567-456b-a12b-ab3456b123ab.
    • Azure - provide a connection string, such as <add key="Storage.Location" value="DefaultEndpointsProtocol=https;AccountName=usr;AccountKey=...;EndpointSuffix=core.windows.net" />.
    • Amazon - provide a connection string, such as <add key="Storage.Location" value="EndpointRegion=eu-west-3;accessKey=AKIAZGUEIGXUJ3BBI4MW;secretKey=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;useHttp=false" />.
    • Minio - provide a connection string, such as <add key="Storage.Location" value="host=localhost:9001;accessKey=YVKYFJ0ZY246KDKP0634;secretKey=bdBEk2ubhIFsTNPuQ80PjKL+oqZBj67HoSWBFnw1" />.

Example:

<add key=\"NuGet.Repository.Type\" value=\"Composite\" />
<add key=\"Storage.Type\" value=\"Azure\" />
<add key=\"Storage.Location\" value=\"DefaultEndpointsProtocol=https;AccountName=usr;AccountKey=...;EndpointSuffix=core.windows.net\" />

The configuration above instructs Orchestrator:

  • to store the package metadata in the SQL database;
  • to keep the actual files in the Azure Blob storage at the location indicated by the DefaultEndpointsProtocol=https;AccountName=usr;AccountKey=...;EndpointSuffix=core.windows.net connection string;
  • to use the default naming convention for the Azure container name - Orchestrator-tenantKey.

🚧

Important!

If you have more than 99 tenants in Orchestrator, increase your default AWS S3 bucket account limit to match the number of tenants. This is required because a separate bucket is created for each tenant.

  • NuGet.Packages.Path - The NuGet path to the packages folder in the Legacy scenario. By default, this is ~/NuGetPackages. This can be a virtual or physical path.
  • NuGet.Packages.ApiKey - The license key of your NuGet account. If the activities and packages are stored in the same NuGet feed, the value of this parameter has to be identical to the NuGet.Activities.ApiKey one. The default value is used in the initial seeding of the database. Please note that arbitrary strings are also accepted.
  • NuGet.Activities.Path - The NuGet path to the activities folder in the Legacy scenario. By default, this is ~/NuGetPackages/Activities.
  • NuGet.Activities.ApiKey - The license key of your NuGet account. If the activities and packages are stored in the same NuGet feed, the value of this parameter has to be identical to the NuGet.Packages.ApiKey one. Please note that arbitrary strings are also accepted.
    Package synchronization between multiple Orchestrator nodes and the interface can be done either by monitoring the file system or using Redis. This can be configured using the configuration below. The recommended way is through Redis.
  • NuGet.EnableFileSystemMonitoring - If set to true, constant file system monitoring is used to reflect the updates and changes from the packages folder. If set to false, the sync of cache files on all nodes (cluster environment) or the sync between the packages directory and the Orchestrator interface (single-node environment) is done every 60 minutes. By default, this parameter is set to true.
  • NuGet.EnableRedisNodeCoordination - If set to true, then the synchronization of the package cache between Orchestrator nodes is done using Redis, instead of File System Monitoring. The sync is triggered whenever a package is uploaded or removed from Orchestrator through the interface, API or Studio publishing functionality. Please note that if you manually copy and paste package files (.nupkg) in the Orchestrator packages folder, the sync of cache files of all nodes is done every 60 minutes. If this setting is used, the Redis component is mandatory. Please note that if you use this parameter, you have to set NuGet.EnableFileSystemMonitoring to false. By default, this parameter is set to false.
  • Processes.AllowUpdateWithRunningJobs - Specifies whether you are able or not to delete a process while having running or pending jobs associated with it. Note that this parameter is hidden by default. The following values are available:
    • true - Processes can be deleted while having associated running or pending jobs.
    • false - Processes cannot be deleted while having associated running or pending jobs. Trying to delete a process, in this case, displays the following error message: "Modifying this process is not possible at the moment, because there are active jobs associated with it. (#1666)". This is the default value.
      For example, if you want to be able to remove your processes while having an associated job running, add <add key="Processes.AllowUpdateWithRunningJobs" value="true" /> in the web.config file.
  • Deployment.Libraries.AllowTenantPublish - Enables you to specify whether the tenants using the host feed are able or not to upload libraries into the feed. The following values are available:
    • true - Libraries uploaded at tenant level are propagated to the host feed. This is the default value.
    • false - Libraries uploaded at tenant level are not propagated to the host feed. However, note that users do have access to the existing libraries in the feed.

You can configure this from the user interface as well. The corresponding option, Allow Tenant Users to Upload into the Feed, can be found at host level, on the Settings page. Details here.

Storage Buckets

  • Buckets.ContentSecurityPolicy - Used to whitelist domains outside the trusted ones to which Orchestrator can make requests. Multiple values can be entered as a comma-separated list. This parameter overrides the corresponding Orchestrator settings in regards to Azure and AWS, so make sure to add Azure and/or AWS as well, if needed. This parameter does not appear by default in the web.config file.
  • Buckets.AvailableProviders - Used to restrict which providers can be used in creating storage buckets. The available providers are: Orchestrator, FileSystem, Amazon, Azure, and Minio. Multiple value can be entered with a comma separator. This key does not appear by default in the web.config file, and by default all providers are available.

Authorization

The external authentication providers' configuration has been moved to Identity Server's External Providers page.

πŸ“˜

Note:

The WindowsAuth.Enabled, WindowsAuth.Domain and AcceptedRootUrls parameters have to be configured before you can import Active Directory groups.

  • WindowsAuth.Enabled - Enables or disables Windows Active Directory's user import functionality. In order to enable the authentication using Windows Active Directory please configure the settings within the External Providers page in Identity Server.
  • WindowsAuth.Domain - All domains and subdomains from forests that are 2-way trusted with the domain specified here are available when adding AD users/groups. You can only specify one domain in this parameter.
  • WindowsAuth.GroupMembershipCacheExpireHours - The amount of time (in hours) after which the cache of AD groups added to Orchestrator expires. This setting is not displayed by default in the web.config file, with the default value being set to 1 hour.
  • WindowsAuth.ConvertUsersAtLogin - If set to true it converts each local user into a directory user after the first login with AD credentials. As an alternative, you can use the script documented here to convert all the local users that have logged in with AD credentials into directory users. This parameter is not displayed by default in the web.config file. It is set to false by default.
  • WindowsAuth.GroupMembershipFetchStrategy - Switch to a faster strategy for fetching Active Directory group membership. It can be enabled by adding the following key in web.config: <add key="WindowsAuth.GroupMembershipFetchStrategy" value="TokenGroups" />. This parameter is not displayed by default in web.config and the strategy is not enabled by default, implicitly.

🚧

Important

This strategy works best for large AD environments made of nested groups, with users residing in a single domain. It does not work across multiple domains. A user belonging to a specific domain cannot inherit access-rights from parent groups in other domains, despite having a two-way trust relationship between them.

  • AcceptedRootUrls - Enables you to add a list of trusted URLs. If no value is attributed to this setting, then no one can access Orchestrator. If you want to add multiple URLs, do it without spaces and separate items through commas (,), such as "https://server1,https://server2".
  • Auth.Cookie.Expire - The amount of time after which you are automatically logged off, in minutes. By default, this is set to 30 minutes.
  • Auth.Bearer.Basic.Expire - The amount of time after which your bearer token expires. By default, it is set to 30 minutes.
  • Auth.Bearer.Robot.Expire - The amount of time after which the bearer token of your Robot expires. By default, it is set to 30 minutes.
  • Auth.Cookie.ValidateInterval - The amount of time (in seconds) until you are logged out after a password reset or after a new session is detected. By default, this is set to 60 seconds. This parameter is not displayed by default in the web.config file. For example, if you want to set it to 20 seconds, add the following key in web.config: <add key="Auth.Cookie.ValidateInterval" value="20"/>.
  • Auth.DisabledPermissions - Enables you to configure permissions to be disabled from the user interface and ignored when using API. Note that this parameter is hidden by default. The permissions need to be added as they are used in API, and they have to be separated by commas. For example, if you want to disable Delete permissions on Libraries and Machines you need to add the following key in web.config: <add key="Auth.DisabledPermissions" value="Machines.Delete,Libraries.Delete" />.
  • Auth.RememberMe.Enabled - Enables you to configure whether the Remember Me check box on the Login page is displayed or not. By default, the parameter is set to true, meaning the check box is displayed. Set it to false to hide it. This setting is not displayed by default in the web.config file.
  • Auth.AllowChangePassword - Enables you to configure whether a user can change his password from the Security section, in the Profile page. This setting is not displayed by default in the web.config file. The following values are available:
    • true - The user can change his password on the Profile page. This is the default value.
    • false - The use cannot change his password on the Profile page.
  • Auth.AllowSelfEmailUpdate - Enables you to configure whether a user can change his email address from the General section, in the Profile page. By default, the parameter is set to true, meaning you can update it. Set the parameter to false to make the field read-only. This setting is not displayed by default in the web.config file.
  • Auth.RestrictBasicAuthentication - Enables you to configure if a user can make an authenticated API request to an Orchestrator instance using basic authentication credentials. This setting is not displayed by default in the web.config file. The following values are available:
    • true - The user cannot make authenticated requests using basic authentication credentials.
    • false - The user can make authenticated requests using basic authentication credentials. This is the default value.
  • Auth.EnableBasicAuthenticationForHostTenant - Enables you to configure if a host admin can make an authenticated API request to the host tenant of an Orchestrator instance using basic authentication credentials. This setting is not displayed by default in the web.config file. The following values are available:
    • true - The host can make authenticated requests using basic authentication credentials. This is the default value.
    • false - The host admin cannot make authenticated requests using basic authentication credentials.

This parameter bypasses the Auth.RestrictBasicAuthentication parameter, meaning that if you set Auth.EnableBasicAuthenticationForHostTenant to true and Auth.RestrictBasicAuthentication to true, you can only log in with basic authentication credentials at host level.

  • ExternalAuth.AccessTokenAuth.Enabled - Enables you to configure if you can authenticate to Orchestrator using a bearer access token issued by Auth0. This setting is not displayed by default in the web.config file. The following values are available:
    • true - The user can make authenticated requests using an access token issued by Auth0. This is only taken into account if you set a valid audience for the ExternalAuth.AccessTokenAuth.Audience parameter.
    • false - The user cannot make authenticated requests using an access token issued by Auth0. This is the default value.
  • ExternalAuth.AccessTokenAuth.Audience - Enables you to control the target audience of the access token. This parameter needs to be set to a valid audience which is used to check against the Auth0 token audience. For example, if you want to set the audience to https://cloud.uipath.com, you need to add the following key in web.config: <add key="ExternalAuth.AccessTokenAuth.Audience" value="https://cloud.uipath.com" />. This setting is not displayed by default in the web.config file.
  • ExternalAuth.ShowPII - Allow for Orchestrator PII display by adding the following key in web.config. . The key is not displayed by default in web.config, and the default behavior does not allow for PII display.
  • WindowsAuth.GroupMembershipCacheExpireHours - Enables you to configure AD group membership cache. The default value is 1, meaning changes made to AD group membership are synced with Orchestrator once every hour for active user sessions. See Behavior section here.

Load Balancer

These settings should only be modified if you are using a load balancer.

  • LoadBalancer.UseRedis - Use Redis as a database to distribute messages and cache to and from all the machines connected through your load balancer. By default, it is set to false.
  • LoadBalancer.Redis.ConnectionString - Can only be used if LoadBalancer.UseRedis is set to true. A connection string that enables you to set up your Redis server, which contains the URL of the server, the password, and port used with Redis. It is also possible to enable SSL encrypted connections between the Orchestrator nodes and the Redis service. For more information, please click here. Examples:
    • with SSL enabled - <add key="LoadBalancer.Redis.ConnectionString" value="DOCWREDIS02:6379,password=12345678,ssl=true" />
    • without SSL enabled - <add key="LoadBalancer.Redis.ConnectionString" value="DOCWREDIS02:6379,password=12345678" />

Password Vault

These settings should be updated to include the plugins of any credential stores you are using, such as CyberArk or Azure Key Vault. The credential stores plugins are located in the \Orchestrator\Plugins folder of your installation directory. For example:

  • <add key="Plugins.SecureStores" value="UiPath.Orchestrator.CyberArk.dll"/>

πŸ“˜

Note:

When upgrading an Orchestrator instance with an existing CyberArk integration, this setting is pre-populated with the CyberArk plugin. For all other installations the setting value is empty by default.

If multiple credential stores are supported, separate each entry using , or ;. For example:

  • <add key="Plugins.SecureStores" value="UiPath.Orchestrator.CyberArk.dll,UiPath.Orchestrator.AzureKeyVault.SecureStore.dll"/>

Azure AD Authentication

The configuration of the Azure AD authentication has been moved to Identity Server's External Providers page.

Logs

  • Logs.RequestAbortedLogBehavior - Specifies the logging behavior for cancellation exceptions which are thrown upon cancellation of an operation that was executing. These are generated, for example, when you click a button and before the operation is executed, you click a different one. Note that this parameter is hidden by default. The following values are available:
    • Ignore - All cancellation exceptions are ignored if the corresponding requests were aborted. This is the default value.
    • Info - Cancellation exceptions are logged with Info severity level.
    • None - Cancellation exceptions are logged with Error severity level.

For example, if you don't want any cancellation exceptions to be logged, add <add key="Logs.RequestAbortedLogBehavior" value="Ignore" /> in the web.config file.

  • Logs.Elasticsearch.SharedIndex - Enables you to log to the same index for all tenants. It must be set to the same value as used for the index parameter in the NLog target. For example, <add key="Logs.Elasticsearch.SharedIndex" value="robotlogs" />. Details here. Note that this parameter is hidden by default.

Webhooks

🚧

Important!

This section in web.config is deprecated. Webhooks settings are now configured in the appsettings.json file specific to Webhooks Service.
Click here for docs on the appsettings.json file for Webhooks.

  • Webhooks.Enabled - By default, it is set to true. This setting enables you to enable or disable the webhooks feature. If set to <add key="Webhooks.Enabled" value="false" />, the feature is disabled.
  • Webhooks.Quotas.MaxCountPerTenant - This setting is not displayed by default in the web.config file. The maximum number of webhooks that can be enabled per tenant. By default, they are set to 100. To change the max count to 150 you can, for example, add the following: <add key="Webhooks.Quotas.MaxCountPerTenant" value="150" />.
  • Webhooks.Requests.Timeout - This setting is not displayed by default in the web.config file. The amount of time after which each HTTP request is canceled. Please note that each request that times out is retried, according to the Webhooks.Requests.RetryAfter parameter. By default, the timeout time is set to 15 seconds.
  • Webhooks.Requests.RetryAfter - This setting is not displayed by default in the web.config file. The amount of time, in seconds, after each failed request is retried. It is populated as a comma-separated list of integers, and is, by default set to 0, 15, 60, meaning that there are a maximum of 3 retries as follows:
    • the first request retry is executed immediately after the first attempt failed;
    • the second retry is executed 15 seconds after the first retry failed;
    • the third retry is executed 60 seconds after the second one fails.
      It is possible to change the number of delays. For example, if you write <add key="Webhooks.Requests.RetryAfter" value="0,10" />, you have only two retries, the first being immediate, while the second after 10 seconds. We recommend that you always set the first retry to 0, and never set time amounts greater than 300 seconds (5 minutes).
  • Webhooks.Quotas.MaxPayloadSize - This setting is not displayed by default in the web.config file. It represents the maximum number of bytes a JSON payload (UTF-8) can have, 1048576 being the default value. Any webhook event whose payload size is greater than the limit is dropped.
  • Webhooks.Quotas.MaxParallelRequests - The maximum number of webhooks a single CPU core should handle. By default, it is set to 100 per CPU core. This setting is not displayed by default in the web.config file.

Scalability

  • Scalability.Heartbeat.PeriodSeconds - The time interval, expressed in seconds, at which the Robot sends a heartbeat to Orchestrator, letting the latter know its status. By default, it is set to 30 seconds.
  • Scalability.Heartbeat.FailureThreshold - The number of successively failed heartbeats send by a Robot until it is marked as unresponsive in Orchestrator. By default, it is set to 4, meaning that after 2 minutes of failed heartbeats (4 x 30 seconds = 2 minutes) a Robot is flagged as unresponsive.
  • Scalability.SignalR.Enabled - Specifies if the Robot service should subscribe to Orchestrator's SignalR channels. By default, it is set to true. This parameter is used in the initial seeding of the database. To make changes after installation, use the Settings page, at tenant or host level.
  • Scalability.SignalR.Transport - Specifies the transport protocol used to connect to Orchestrator's SignalR channels. The following values can be attributed (any combination - bitwise OR):
    WebSocketTransport = 1
    ServerSentEventsTransport = 2
    LongPollingTransport = 4
    Default value: 7 (WebSocketTransport | ServerSentEventsTransport | LongPollingTransport)
    This parameter is used in the initial seeding of the database. To make changes after installation, use the Settings page, at tenant or host level.
  • Scalability.SignalR.AuthenticationEnabled - If set to true, enables the Robot SignalR authentication method, a method that ensures secure communication between Orchestrator and Robot. This feature is disabled by default - set to false. Please note that if you enable this feature, you cannot execute jobs on Robots with a version lower than 2018.4.4.
  • Scalability.AzureSignalR.ConnectionString - Helps you enable Azure SignalR Service, facilitating a direct communication between your Robot fleet and the SignalR Service - Orchestrator no longer intermediates it. This option should be used only if you have an Azure-hosted Orchestrator instance. Can be used in conjunction with the Scalability.AzureSignalR.ConnectionCount key. This parameter is enabled in our Cloud offering. It is not displayed by default in the web.config file.
    Please note that, if enabled, Robots with a version lower than 2019.2 rely only on the Heartbeat protocol to communicate to Orchestrator, meaning that any command given from Orchestrator is picked up by a Robot only every 30 seconds. To enable this parameter, populate its value with the connection string to Azure Service. Example: <add key="Scalability.AzureSignalR.ConnectionString" value="Endpoint=https://test.signalr.net;AccessKey=M1ug+sBu07hyyi12AgyJ52SEd4OgC2Mm6BvllVHCC9c=;Version=1.0;" />.
  • Scalability.AzureSignalR.ConnectionCount - Enables you to change the number of connections (per hub) between the server and Azure SignalR Service. The default value is 5. Example: <add key="Scalability.AzureSignalR.ConnectionCount" value="7" />. This setting is not displayed by default, and cannot be used without the Scalability.AzureSignalR.ConnectionString key.

Insights

  • Insights.ParallelBuildCount - Enables you to set the maximum number of Insight data cube builds that can occur simultaneously. By default the value is set to 4.
    Note: This setting is optional and not displayed by default in the web.config file.
  • Insights.TableCreationRetryCount - Enables you to set the maximum number of retry attempts for new table creation. By default the value is set to 3.
    Note: This setting is optional and not displayed by default in the web.config file.
  • Insights.TableCreationRetryBackoffSeconds - The amount of time, in seconds, between retry attempts. By default the value is set to 60.
    Note: This setting is optional and not displayed by default in the web.config file.

Analytics

  • Telemetry.Enabled - Enables or disables the usage and performance data collection that UiPath uses to help diagnose problems and help improve Orchestrator. For more details about UiPath’s privacy practices, please review the privacy statement. The following values are available:
    • true - The telemetry feature is enabled. This is the default value.
    • false - The telemetry feature is disabled.
      It is also possible to opt in or out of the performance and usage data collection when you install or update your Orchestrator instance, as described here.

Media Recording

  • MediaRecording.Enabled - Set it to true to enable the recording feature. By default, it is set to false, meaning the feature is disabled. File storage is impacted by the NuGet.Repository.Type parameter, and configured using the Storage.Type and Storage.Location parameters when NuGet.Repository.Type is set to Composite.

Pagination

  • Pagination.Limits.Enabled - Set to true by default for Cloud Platform and clean installs of on-premise Orchestrator instances. Adds a default $top value for all calls to API endpoints with pagination parameters (e.g. odata/Users).

SecureAppSettings

  • EncryptionKey - The encryption key used to secure passwords from credential assets. If you are using an environment with a network load balancer, this key should be the same for all machines.

The following parameters enable you to set up your Azure Key Vault, where you can store your tenant-based encryption keys. Please note that these parameters can be used only if EncryptionKeyPerTenant.Enabled is set to true, and EncryptionKeyPerTenant.KeyProvider set to AzureKeyVault. Additionally, ensure that you provide all key, secret, and certificate permissions to your Orchestrator instance, in the Access policies of your Azure Key Vault. For the full procedure, please see this page.

  • Azure.KeyVault.ClientId - The application ID of your Orchestrator instance. This can be found in Azure in App Registrations and should have the ae11aa1a-1234-1234-a123-a12a12aaa1aa format. This setting is not displayed by default in the web.config file. Example: <add key="Azure.KeyVault.ClientId" value="ae11aa1a-1234-1234-a123-a12a12aaa1aa" />.
  • Azure.KeyVault.CertificateThumbprint - The thumbprint generated by Azure for the Orchestrator certificate. You can find this value in Azure in App Services > Your instance > SSL Settings > Private Certificates (or Public Certificates). This setting is not displayed by default in the web.config file. Example: <add key="Azure.KeyVault.CertificateThumbprint" value="1234123412341234123412341234124312341234" />.
  • Azure.KeyVault.VaultAddress - The DNS name of your Azure Key Vault. This can be found in the Overview of your vault, in the DNS Name field, and should have the https://CustomVaultName.vault.azure.net/ format. This setting is not displayed by default in the web.config file. Example: <add key="Azure.KeyVault.VaultAddress" value="https://CustomVaultName.vault.azure.net/" />.

Others

  • Features.LongRunning.Enabled - Enables you to configure whether long running workflows are supported in your instance or not. Add the following key in web.config to enable it: <add key="Features.LongRunning.Enabled" value="true" />.
  • Tasks.ModuleEnabled - Enables you to configure whether the Actions feature is enabled in your instance. Add the following key in web.config to enable it: <add key="Tasks.ModuleEnabled" value="true" />. This setting makes the feature available at instance level. To configure it on a per-tenant basis, follow the steps here. The Features.LongRunning.Enabled parameter needs to be set to true in order for this setting to take effect.
  • ActiveDirectory.SearchInputMinimumLength - The minimum query size which triggers the search. The default value is 2, meaning the search is performed after you fill in a minimum of 2 characters. This parameter is not displayed by default in the web.config file. Example: <add key="ActiveDirectory.SearchInputMinimumLength" value="4" />.
  • ActiveDirectory.SearchResultsSizeLimit - The maximum number of results returned when searching for AD users or groups. It is by default set to 20. This parameter is not displayed by default in the web.config file. Example: <add key="ActiveDirectory.SearchResultsSizeLimit" value="30" />.
  • ActiveDirectory.SearchResultsTimeLimitSeconds - The maximum allowed search time of a query, meaning that whenever this limit is exceeded, searching is interrupted and the results found until then are returned. It is by default set to 30 seconds. This parameter is not displayed by default in the web.config file. Example: <add key="ActiveDirectory.SearchResultsSizeLimit" value="40" />.
  • OData.BackwardsCompatible.Enabled - Enables you to control how special characters are parsed in the Orchestrator API. If set to true, special characters in the body of requests and responses are parsed. By default, this parameter is hidden and set to false.
  • NotRespondingRobotsJobStartDelay - Enables you to set a delay, in seconds, of the first check performed on your Robots' status after an upgrade. This parameter is not displayed by default in web.config.
  • Upload.Queues.MaxNumberOfItems - Enables you to lower the maximum number of items which can be uploaded at once using the bulk upload functionality. The default value is 15000. Please note that this parameter is not displayed by default in web.config.
  • Processes.FilterOutDeleted - Enables you to optimize the way in which Orchestrator retrieves processes. Optimization is achieved by removing unnecessary verifications for orphaned processes whose associated packages were deleted. This improves the overall performance of your instance, especially if it's a large deployment. The following values are available:
    • false - Package retrieval is optimized, verifications are not performed for orphaned processes.
    • true - Package retrieval is not optimized.

Note that this parameter is hidden and set to true by default, meaning process retrieval is not optimized.

system.webServer

HTTP Compression

The element below enables the compression of dynamic content, respectively large downloadable .csv reports, in Orchestrator. By default, this feature is enabled - set to true. To disable it change the value of the enabled attribute to false.

<httpCompression>
  <dynamicTypes>
    <remove mimeType="text/csv" />
    <add mimeType="text/csv" enabled="true" />
  </dynamicTypes>
</httpCompression>

Identity Server Settings

This section contains settings for configuring SSO login, S2S access tokens and Robot provisioning access tokens.

Single Sign-On

The following parameters allow you to configure SSO login through the Identity Server:

  • ExternalAuth.System.OpenIdConnect.Enabled - Enables/disables the connection of Orchestrator to an external authentication system. By default, the value is set to true.
  • ExternalAuth.System.OpenIdConnect.Authority - Enables you to set the location of the external authentication system. By default, the value is set to https://Orchestrator/Identity, where Orchestrator is the installation address of your Orchestrator.
  • ExternalAuth.System.OpenIdConnect.ClientId - Enables you to set the Orchestrator application ID (clientId) registered insider Identity Server. The value is generated at install time and saved within Identity Server.
  • ExternalAuth.System.OpenIdConnect.ClientSecret - Enables you to set the Client Secret for the Orchestrator application to be recognized by the external authentication system. The value is generated at install time and saved within Identity Server.
  • ExternalAuth.System.OpenIdConnect.RedirectUri - Specifies the redirect URL to Orchestrator, after authenticating to Identity Server. This URL is automatically preconfigured inside Identity Server and Orchestrator, and you shouldn't change it. Its default vaue is http://Orchestrator/signinsystemopenidconnect.
  • ExternalAuth.System.OpenIdConnect.PostLogoutRedirectUri - The address that Identity Server redirects to after a user logs out of Orchestrator. This value is automatically populated with yourOrchestrator URL.

For example, web.config should contain these keys:

<add key="ExternalAuth.System.OpenIdConnect.Enabled" value="true" />
<add key="ExternalAuth.System.OpenIdConnect.Authority" value="https://Orchestrator/Identity" />
<add key="ExternalAuth.System.OpenIdConnect.ClientId" value="orchestrator" />
<add key="ExternalAuth.System.OpenIdConnect.ClientSecret" value="49C1A7E1-0C79-4A89-A3D6-A37998FB86B0" />
<add key="ExternalAuth.System.OpenIdConnect.RedirectUri" value="https://Orchestrator/signinsystemopenidconnect" />
<add key="ExternalAuth.System.OpenIdConnect.PostLogoutRedirectUri" value="https://Orchestrator/" />

Integration

In order to securely propagate data to Identity Server, Orchestrator needs an access token for token authentication. This token is fetched from Identity Server via client credential flow (S2S). The following keys should be added to web.config:

  • IdentityServer.Integration.Enabled - Enables/disables the integration of Identity Server to Orchestrator. By default, the value is set to true.
  • IdentityServer.Integration.Authority - Enables you to set the location of the Identity Server. By default, the value is set to https://Orchestrator/Identity, where Orchestrator is the installation address of your Orchestrator.
  • IdentityServer.Integration.ClientId - Enables you to set the application Id (Client Id) used to generate S2S access tokens, registered inside Identity Server. The value is generated at install time.
  • IdentityServer.Integration.ClientSecret - Enables you to set the Client Secret for the Orchestrator S2S application to be recognized by Identity Server. The value is generated at install time.
  • IdentityServer.Integration.AccessTokenCacheBufferInSeconds - Enables you to set the time in seconds before the cache buffer of the access token expires. By default, the value is set to 50.
  • IdentityServer.Integration.UserOrchestratorApiAudience - The Identity Server can generate multiple access tokens with different audiences. Orchestrator APIs requests can be authorized using user access tokens that have this audience. By default, the value is set to OrchestratorApiUserAccess.
<add key="IdentityServer.Integration.Enabled" value="true" />
<add key="IdentityServer.Integration.Authority" value="https://Orchestrator/Identity" />
<add key="IdentityServer.Integration.ClientId" value="orchestratorapiaccess" />
<add key="IdentityServer.Integration.ClientSecret" value="a5d57b1d-5b25-49ba-bff7-33aa57f96a58" />
<add key="IdentityServer.Integration.AccessTokenCacheBufferInSeconds" value="50" />
<add key="IdentityServer.Integration.UserOrchestratorApiAudience" value="OrchestratorApiUserAccess" />

In order to consume client credential (S2S) access tokens generated by Identity Server, Orchestrator needs the following keys to be added to web.config:

  • IdentityServer.S2SIntegration.Enabled - Enables/disables the consumption of S2S access tokens. It has no default value in web.config.
  • IdentityServer.Integration.S2SOrchestratorApiAudience - Enables you to set the audience that Orchestrator will check when validating an S2S access token. By default, the value is set to OrchestratorApiS2SAccess.

Make sure web.config also contains the following pre-existent keys with their values set to true:

  • MultiTenancy.AllowHostToAccessTenantApi - When set to true, it allows the host users to access other tenants' specific data. By default, the value is set to true.
  • MultiTenancy.TenantResolvers.HttpGlobalIdHeaderEnabled - When Orchestrator receives an API call authorized using S2S access token, a true setting allows Orchestrator to identify the tenant by reading the tenant global id from the API's request header.
<add key="IdentityServer.S2SIntegration.Enabled" value="true" />
<add key="IdentityServer.Integration.S2SOrchestratorApiAudience" value="OrchestratorApiS2SAccess" />
<add key="MultiTenancy.AllowHostToAccessTenantApi" value="true" />
<add key="MultiTenancy.TenantResolvers.HttpGlobalIdHeaderEnabled" value="true" />

Robot Provisioning Access Tokens

Orchestrator acts as a Token Generator for Robots. Robots call the Orchestrator endpoint to generate an access token. The access token is then passed to activities that can call different resources, such as AI Fabric. With the integration of Identity Service with Orchestrator, Identity Server takes over the generation of the access tokens.

Logging Configuration

Robot Logs

This is the corresponding web.config key: <logger name="Robot.*" writeTo="database,robotElasticBuffer" final="true" />. It is used to configure log messages generated by Robots. The following parameters have to be configured:

  • writeTo - The location where log messages generated by the Robot are written. The following values are available:
    • database - Logs are sent to Orchestrator's SQL database. This is one of the default values.
    • robotElasticBuffer - Logs are sent to Elasticsearch. This is the second default value. Please remember this requires additional settings. Details here.
      Having logs sent both to the Orchestrator's SQL database and Elasticsearch enables you to have non-repudiation logs. Delete one of the values to stop logging to that location.
  • final - A flag that indicates what to do when a match between a logged message and the logger name is found. When set to true, it does not look for another match. When set to false, other rules matching the same source are checked. By default, it is set to true.

Schedules Logs

This is the corresponding web.config key: <logger name="Quartz.*" minlevel="Info" writeTo="eventLogQuartz" final="true" />. It is used to configure log messages generated by schedules.

πŸ“˜

Note:

To ensure a smooth run for schedules in an Orchestrator setup with a load balancer you should also set the quartz.jobStore.clustered parameter to true.

Monitoring Logs

This is the corresponding web.config key: <logger name="Monitoring.*" writeTo="monitoring" minlevel="Warn" final="true" />. It is used to configure the error logs displayed on the Monitoring page. Please note if you remove this rule or alter the target, no error logs will display on the Monitoring page.

Business Exception Logs

This is the corresponding web.config key: <logger name="BusinessException.*" minlevel="Info" writeTo="businessExceptionEventLog" final="true" />. It is used to configure the logs for thrown business exceptions. For example validation issues (e.g Invalid username) or business conflicts (e.g. License expired).

Other Logs

This is the corresponding web.config key: <logger name="*" minlevel="Info" writeTo="eventLog" />. It is used to configure all other logs besides the ones described above, including those generated by Orchestrator.

πŸ“˜

Note:

If you maintain more than two million logs in the SQL database, you might have some performance issues. For more than that, we recommend using Elasticsearch.

Additional Settings

Elasticsearch

The following NLog target must be populated according to your Elasticsearch configuration:

<target xsi:type="ElasticSearch" name="robotElastic" uri="<elasticSearch_url_1>,<elasticSearch_url_2>, <elasticSearch_url_3>" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="logEvent" includeAllProperties="true" disablePing="true"  layout="${message}" excludedProperties="agentSessionId,tenantId,organizationUnitId,indexName" />
  • uri - the Elasticsearch URL; note that you have to include the protocol and port, such as http://elastic_server:9200. You can remove the need for a load balancer by populating this parameter with the Elasticseach URL of each node, such as uri="http://elastic-node1:9200,http://elastic-node2:9200,http://elastic-node3:9200".
  • excludedProperties - data that you do not want to be saved to Elasticsearch.
  • index - the format of the logging index, which can be either unique per tenant or shared across all tenants. Details below.

Index Configuration

  • Individual Index - index="${event-properties:item=indexName}-${date:format=yyyy.MM}" - A separate index is used for each tenant, meaning that logs specific to one tenant are generated and retrieved based on a unique tenant identifier, in this case, indexName which defaults to the name of the tenant. This is the default configuration. In this case, logs are generated per month.

  • Shared Index - index="robotlogs-${date:format=yyyy.MM.dd}" - One index is used for all tenants, meaning that all logs, regardless of tenant, use the same index. In this case, logs are generated per day. To use a shared index, you are also required to add the following key in web.config: <add key="Logs.Elasticsearch.SharedIndex" value="robotlogs" />. Mare sure to set it to the same value as for the index parameter in the NLog target.

🚧

Important!

Logs generated using an individual index are kept if you shift to a shared index. However, logs generated using a shared index are lost if you shift to an individual one.

Logging Events in the Database

To store system event logs in the database rather than Event Viewer, follow these steps:

  1. Create a new database table, for example:
CREATE TABLE [dbo].[EventLogs](
    [Id] [bigint] IDENTITY(1,1) NOT NULL,
    [Timestamp] [datetime] NOT NULL,
    [Level] [int] NOT NULL,
    [Message] [nvarchar](max) NULL,
    [Exception] [nvarchar](max) NULL)

In the above query, we create a table named EventLogs with the following columns:

  • Id - to hold an ID number for each log, here starting with 1 and incrementing the value with each log added;
  • Timestamp - to hold the time each event was logged;
  • Level - to hold the numerical logging level of each event;
  • Message - to hold the message of each event, if applicable;
  • Exception - to hold the exception logged for each event, if applicable.

πŸ“˜

Note:

You can use any name for your table, and remove any columns from the above query or add others to suit your needs.

  1. In the web.config file, add a new NLog target:
<target xsi:type="Database" connectionStringName="Default" name="eventLogDatabase" keepConnection="true">
        <commandText>
          INSERT INTO dbo.EventLogs (Timestamp, Level, Message, Exception)
          VALUES (@timestamp, @level, @message, @exception)
        </commandText>
        <parameter name="@timestamp" layout="${date:format=yyyy-MM-dd HH\:mm\:ss.fff}" />
        <parameter name="@level" layout="${event-properties:item=levelOrdinal}" />
        <parameter name="@message" layout="${message}" />
        <parameter name="@exception" layout="${onexception:${exception:format=tostring:maxInnerExceptionLevel=5:innerFormat=tostring}}" />
</target>

Defining a corresponding parameter for the data to be added in each database column, in this example @timestamp, @level, @message, and @exception.

  1. Lastly, associate the newly created target with the NLog logger classification for all Orchestrator messages, from above, by adding:
<logger name="*" minlevel="Info" writeTo="eventLog,eventLogDatabase" />

Enabling NLog Debugging

NLog is an open-source, easily configured, and extensible logging platform for a variety of .NET platforms. With NLog, you can store or pass log data to any number of predefined or custom targets, such as a local file, an event log, email, or database.

Though there exists some overlap, NLog and Orchestrator have several differentiating logging levels. For NLog you can select either Trace, Debug, Info, Warn, Error, Fatal, or Off. See Logging Levels for a description of the available levels in Orchestrator.

You can enable debugging in NLog to ensure that it is functioning properly. By default NLog is set to Off, it is enabled by configuring the following section of the web.config file:

<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" autoReload="true" throwExceptions="false" internalLogLevel="Off" internalLogFile="">
The attributes which must be set are:
* `internalLogLevel` - the desired logging level
* `internalLogFile` - the location of the log file

For example:
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" autoReload="true" throwExceptions="false" internalLogLevel="Debug" internalLogFile="C:\logs.txt">

πŸ“˜

Note:

The user profile under which Orchestrator is running must have access to the path specified in the internalLogFile attribute.

Updated 14 days ago


Web.Config


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.