Subscribe

UiPath Orchestrator

The UiPath Orchestrator Guide

Auto updating client components

This article describes some key concepts about the update feature which allows administrators to update multiple UiPath client products to new versions at once.

About


This feature allows administrators to update Robot, Studio, and UiPath Assistant clients to newer versions from Orchestrator. This provides an easy way to deliver a version update to a large base of machines from a centralized location, helping remove user friction and streamlining the update process.

Prerequisites

  1. Orchestrator, Studio and Robot 2021.10 or later.
  2. Studio and/or Robot 2021.10 or later installed on the client machine and connected to Orchestrator.

Components that take part in the update process


Client side

  • Client Apps:
    • Robot
    • Assistant
    • Studio
  • Robot Service
  • Update Agent - a Windows process responsible for the communication between the user and update service. (only present in the user mode and attended robot installation)
  • Update Service - a Windows Service responsible for the communication between the client machine and the update server.

Server side

  • Orchestrator: provides the user interface for administrators to set auto-update policies and see the version status for client apps.
  • Update server: a centralized service responsible for managing the auto-update policies and maintaining the communication with the client machines through the update service.

How this works


As an administrator, you can choose the specific version to be deployed on a specific machine.

For this to happen, when Studio and Robot are installed, two executables are also added to the machine: UiPath.UpdateService.Worker.exe and UiPath.UpdateService.Agent.exe.
Depending on the type of Studio/Robot installation, they are installed run in a different way:

  • Unattended Robot: UiPath.UpdateService.Worker.exe is installed as Windows Service and UiPath.UpdateService.Agent.exe is not installed.
  • Attended Robot: UiPath.UpdateService.Worker.exe is installed as Windows Service; UiPath.UpdateService.Agent.exe is installed as LogOn Task in Task Scheduler.
  • Quick Install (user mode): UiPath.UpdateService.Worker.exe and UiPath.UpdateService.Agent.exe are installed as LogOn Tasks in Task Scheduler.

🚧

Important!

When installing UiPath Studio and Robot on the machine in attended - user mode, for the update service to connect to the update server, make sure to add the Orchestrator URL during setup. If the Orchestrator URL is not added during installation, a user with administrator rights on the machine has to log on to the machine and connect the robot to Orchestrator.

When a new policy is defined or changed, the update server sends a command to the update service on the client machine, which asks the client apps if they are ready to start the update process.

To be ready to receive an update, a product must be in a neutral state:

  • Studio - no running processes or active sessions.
  • Robot - no running jobs or processes.
  • Assistant - no running processes or pending activities (installing or downloading processes).

📘

Note:

During the update process, the Robot does not start any jobs until the update is completed.

In the attended scenario, an update prompt is displayed giving the user two options:

  • Update Now - stops all running jobs and closes all Studio instances on that machine then proceeds with the update.
  • Later - mutes the notification and the update process can be resumed by going to the UI icon in the system tray and clicking check for updates.
    When the user accepts the prompt, the confirmation is sent to the update service and the update process starts. If no response is provided in 24 hours since the first notification, the update installed automatically.

In the unattended scenario, the update service confirms that the client app is in a neutral state (as described above) before sending the confirmation back to the update server.

📘

Note:

If there are any processes running on the machine, the user is prompted to choose to either stop the process, or wait for it to finish and continue with the update. If a Studio session is open, the user is prompted to save the progress.
If the user doesn’t react, Studio closes and the process is saved as-is at that time and can be recovered after the update is completed, while the Robot waits for any process to complete and starts the update process afterwards.

Update process steps

The update process is split into seven stages:

  1. Downloading
  • The update service is checking the update server every three hours for an update request. If the update request is received, the update process starts the download process. If the download process has been started successfully, the update request is added to the update server database with the status Downloading.
  1. Downloaded
  • The Downloaded state acts as a marker, so that the update service can start the post-processing phase. This state marks the fact that the update file has been downloaded successfully.
  1. Processing
  • This step handles the post-processing of the downloaded file. In this step, the file is checked and if no errors appear, the install process starts.
  1. Ready to Install
  • The update agent informs the user that an update is awaiting install and asks for approval or checks if the client apps are ready to receive the update.
  1. Install Approved
  • Once the approval is received by the update service, the actual installation starts.
  1. Installing
  • The new version is installed on the machine keeping the same settings as the previous version.
  1. Success / Error
  • Based on the install result, the update status is reported back to the update server and in the Orchestrator interface.

Retry mechanism

During the update process, if the file cannot be retrieved in the first download, the update service retries three more times. The retry intervals are: one hour after the initial attempt, then two hours after the first retry, and four hours after the last retry. Before each retry, the user is informed through the notification system.

For each download attempt, the logs are added to the Orchestrator update logs and locally on the machine in the %localappdata%/Uipath/UpdateService/logs file.

The process is similar for installing, meaning that if the first install fails, the update service tries again three times with the same frequency (one hour after the initial attempt, then two after the first retry, and four hours after the last retry).

The update server waits 72 hours for the update to complete since it started. If the new version is not installed after this interval expires, a detailed error is added to the logs. The update is retried the next time a request is received.

Service-mode vs user-mode robot deployments


The technical aspects on the server side are identical for both service-mode and user-mode deployments, as they use the same connection type between the update server and update service. The difference consists in how the Robot service communicates with the update service on the client machine, as explained below.

Service mode

In service-mode deployments, the robot service and update service both run in the local system account session.

12801280

User mode

In user-mode deployments, the robot service runs in the user session and the update service runs in the local system account session.

🚧

Important:

When Robot and Studio are deployed in user mode, sending the update command to one Robot on the machine affects all users on that specific machine.

12801280

❗️

Important!

After the update process is completed, Studio and Robot must be started manually.

Configuring policies


Policies can be set for users, groups of users (recommended for attended use cases), or machines (recommended for unattended use cases).

Configuring policies for users/user groups

Configuring update policies for users or user groups allows administrators to control the Studio, Robot and Assistant version for a specific user or user group.

  • Specific user - to granularly update components tied to a specific user.
  • Group of users - to update access to all group members without the need to set the access level for each user individually.

Policies are configured by editing a specific user or group from the Manage Access tab in Orchestrator.

  1. Navigate to Tenant > Manage access. The Users window is displayed.
  2. For the desired user/user group, click Edit. The Edit User window is displayed.
  3. In the Update policy settings section, change the auto-update policy to one of the following values:

Per user

12441244

Per group

15631563

📘

Note:

If the policy applied to the user is set to None, but they are also part of a group that has a specific policy set (e.g. Latest Patch), the group policy applies. If you want the components for that specific user to not be updated, you must either remove them from the group that has the policy or set the update policy to be at the current version that is installed.
If the user has a policy set to push a specific version and they are also part of a group that has a different policy, the user level policy takes precedence.

Per Machine Objects

Configuring an update policy for machine objects allows administrators to update the robot versions on all machines connected to Orchestrator using a specific machine key.

To configure the update policies for machine objects, follow the steps below:

  1. Navigate to Tenant > Machines. The Machines window is displayed
  2. For the desired machine object, click Edit. The Edit Machine window is displayed.
  3. Access the Maintenance tab. The Auto Update configuration menu is displayed.
  4. Configure the update policy using the options described here.
16401640

Auto-Update Scheduling

From the Maintenance tab you are also able to schedule the update to start at a certain time and date to match other maintenance windows in your company. You can also set the duration of the maintenance window. If the time set for the maintenance window elapses and the update did not start, it is scheduled during the next available interval.

Policy Priority

In the event a user-level policy, a group-level policy, and a machine-level policy apply to the same Robot, the user-level policy takes precedence.

Example:

  • Machine_1 has a 2021.10 version of Robot and Studio installed.
  • On machine_1, the robot is connected to Orchestrator through Interactive Sign In with the [email protected] user.
  • An update policy applies to [email protected] which is set to push the 2021.10.2 version.
  • [email protected] is also part of group_1.
  • An update policy applies to the group_1 which is set to push the 2021.10.3 version.
  • An update policy applies to machine_1 which is set to push the 2022.4 version.
    Result: when the update policies trigger, the components on that machine are updated to 2021.10.2 version.

📘

Note:

When using Robot Accounts please note that the machine-level policy is used in order to handle the update.

Version availability in policies

When creating an update policy, you can choose one of the following options:

Latest major version

Latest patch

Specific patch

Installs the latest available version found on the update server.

Installs the latest patch available for each of the supported versions. (e.g. Latest 2021.10 patch, Latest 2022.4 patch).

Installs a specific patch from the list of the ones available in the Update Server.

Update logs


In the Orchestrator user interface, the update logs are available for failed and successful updates. Complete logs for the update are found on the machine in the %localappdata%/Uipath/UpdateService/logs file.

24982498 14071407

❗️

Important!

When robots are deployed on virtual environments where the machines are cloned, the machine name, guid, drive id, and mac address are the same. This can cause conflicts as Orchestrator receives different update statuses from multiple machines with the same identifiers.
In this scenario, the update status in Orchestrator is shown based on the last machine that connected.
This can also impact orchestrator logs, as multiple machines have the same identifiers, duplicate logs can appear.

Version statuses


The Version status column allows you to check the status of the Robot version for your machines against the associated policy.

The following values are available:

  • searchsearch No policy - no policy is defined
  • searchsearch Update in progress - this status is presented when the update process is ongoing on the machine
  • searchsearch Compliant – the robot version on the machine is matching to the update policy.
  • searchsearch Non-compliant - the robot version on the machine is different than what was setup in the policy. (e.g. robot version is 2021.10.3, the policy is set up as 2021.10.1)
  • searchsearch Update failed - this status shows when the update process failed. More details can be found in the update logs.
  • N/A - this status shows up when the setting to ignore inactive machines is enabled and the robot hasn’t been connected for a while, or when the machine type is not compatible with the auto-update process.

Version status for machines

The Version status column on the Orchestrator Machines tab allows you to check the status of the Robot version for your machines against the associated policy.

24952495

🚧

Note:

Elastic Robots are not compatible with the Auto-Update feature. For these, the version status shows as N/A with the "Auto-update is not applicable for this type of machine" tooltip.

Excluding inactive machines

If multiple machines are connected to Orchestrator using the same key and one of them is inactive, the version status of the machine template becomes Non compliant. This is happening as the machine template communicates with the update server using the same machine key, and if one of the machines connected is unable to receive an update, the overall status of the machine template is impacted.
To avoid this, access the General section of the Settings menu at the tenant context, select the Client Binaries checkbox and set the preferred inactivity interval. This excludes inactive machines from the update process and no longer takes them into account when the update status is reported.

13461346

Version status for users

The Version Statuses column on the Robots tab in Orchestrator allows you to check the status of the client component version for your users against the associated policy.

24932493

Managing update versions


If your Orchestrator instance has Internet access, by default, version management is done by UiPath, and the list of available versions in the policies is automatically populated. If you want to manually manage the versions, go to Settings > General, and clear the Auto-fill available product versions checkbox.

If you choose not to have the version management done by UiPath or your Orchestrator instance does not have Internet access, you must manually download the installers of the client components from the UiPath Customer Portal - Product Downloads page and upload them to the update server using the steps below:

  1. Acquire the -InstallationToken from the Identity Server using the steps described in Installation Access Token. NOTE: If you are using Automation Suite, the installation token is acquired after you log in to the host tenant/org as a host admin, opening a new tab and going to https://baseURL/identity/api/Account/ClientAccessToken.
  2. If you need the ClientId and ClientSecret values, run the script using the command below:

📘

Note:

The scripts needed for the commands below are located in the installation folder (default path is C:\Program Files (x86)\UiPath\Orchestrator\Tools\UpdateServerScripts) on the Orchestrator machine.

The supported product versions to be used in the scripts are found in the Product Lifecycle documentation page. For the update scripts, the short format of the version is used (e.g. 22.4.3 instead of 2022.4.3).

.\Provision-IdentityClient.ps1 -IdentityUri "<IDENTITY_URL>" -InstallationToken "<INSTALLATION_TOKEN>"

Once the required parameter values are fetched, you can use one of the following commands to manage update versions.

Get available versions

.\Product-Versions.ps1 get -ApiBaseUri "<ORCHESTRATOR_URL>" -IdentityUri "<IDENTITY_URL>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>"

Publish a new version in the update server

.\Product-Versions.ps1 register -ApiBaseUri "<ORCHESTRATOR_URL>" -IdentityUri "<IDENTITY_URL>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>" -ProductId "b69fdacf-6dd0-46fb-88c7-af2d87caf5aa" -Version "<NEW_VERSION>" -DownloadUri "<DOWNLOAD_URL>"
.\Product-Versions.ps1 register -ApiBaseUri "https://intranet/orchestrator_" -IdentityUri "https://intranet/identity_" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>" -ProductId "b69fdacf-6dd0-46fb-88c7-af2d87caf5aa" -Version "22.4.3" -DownloadUri "https://download.uipath.com/versions/22.4.3/UiPathStudio.msi"

Delete a specific version from the update server

DELETE
.\Product-Versions.ps1 delete -ApiBaseUri "<ORCHESTRATOR_URL>" -IdentityUri "<IDENTITY_URL>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>" -ProductId "b69fdacf-6dd0-46fb-88c7-af2d87caf5aa" -Version "<NEW_VERSION>"

Publish a new version on the client machine

.\Provision-IdentityClient.ps1 -IdentityUri "<IDENTITY_URL>" -InstallationToken "<INSTALLATION_TOKEN>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>"

Proxy Configuration

For scenarios in which the robots are sitting behind a proxy, for the auto-update feature to work, additional configuration might be needed. Based on the installation type, proxy configurations can either be inherited from the user-level proxy settings, or set manually by editing the uipath.config file.

Installation Type

Robot Deployment

Update Service

Update Agent

Proxy Settings

Unattended Robot

Windows Service

Windows Service

N/A 1

From the uipath.config file.

Attended Robot

User-level executable

Windows Service

User-level executable

From the uipath.config file.

Quick Install

User-level executable

User-level executable

User-level executable

From the user level proxy settings.

1 when the robot is installed in unattended mode, the update agent is not added to the machine.

Collecting Error Logs

When an update fails, you can use the Diagnostic Tool to collect logs which can be sent to our Support Team which are used for further investigation on the specific error.

Error Message

470470

Diagnostic Tool Setup

820820

Updated 22 days ago


Auto updating client components


This article describes some key concepts about the update feature which allows administrators to update multiple UiPath client products to new versions at once.

Suggested Edits are limited on API Reference Pages

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