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, a Windows service (UiPath.UpdateService.Agent.exe) is added to the client machine. This service connects to Orchestrator and communicates with the update server in Orchestrator.

🚧

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 service on the machine communicates with the update server during regular polling, and when it finds a change in the policy, checks with the client apps to see 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 reopening the notification from 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 within 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 checks 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 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.

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 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 in 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 again 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.

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.

❗️

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

Per group

📘

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.

Configuring policies for machine objects

Configuring an update policy for machine objects allows administrators to update the robot versions on all machines connected to Orchestrator using that machine key. The configuration is done at the machine object level:

  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. In the Update policy settings section, change the update policy to one of the following values:

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.

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 and can be copied directly using the searchsearch button next to each log. Complete logs for the update are found on the machine in the %localappdata%/Uipath/UpdateService/logs file.

❗️

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.

🚧

Note:

Linux 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.

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.


Managing Update Versions Manually

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. NOTE: In order to enable this option, you need to be logged in as a host admin.

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 Download Center and upload them to a location that is accessible from the client computers (e.g. local HTTP server or network share).

Once this is done, you need to register the installers in the update server using the location above as the value for the DownloadUri parameter. Follow these steps:

NOTE: If you already have a ClientId and a ClientSecret you can skip to step 3.

  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 has to be acquired from the authentication settings in the users menu of Automation Suite admin panel.
  2. Provision a new Identity Server client using a ClientId and a ClientSecret of your choosing:
.\Provision-IdentityClient.ps1 -IdentityUri "<IDENTITY_URL>" -InstallationToken "<INSTALLATION_TOKEN>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>"
  1. Using the ClientId and ClientSecret values above you can use the following commands to manage update versions in update server:
.\Product-Versions.ps1 get -ApiBaseUri "<ORCHESTRATOR_URL>" -IdentityUri "<IDENTITY_URL>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>"
.\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 delete -ApiBaseUri "<ORCHESTRATOR_URL>" -IdentityUri "<IDENTITY_URL>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>" -ProductId "b69fdacf-6dd0-46fb-88c7-af2d87caf5aa" -Version "<NEW_VERSION>"
.\Product-Versions.ps1 update -ApiBaseUri "<ORCHESTRATOR_URL>" -IdentityUri "<IDENTITY_URL>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>" -ProductId "b69fdacf-6dd0-46fb-88c7-af2d87caf5aa" -Version "<NEW_VERSION>" -DownloadUri "<DOWNLOAD_URL>"

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

Diagnostic Tool Setup

Updated 6 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.