orchestrator

2023.4

false

Orchestrator User Guide

DELIVERY:

Automation Cloud Automation Cloud Public Sector Automation Suite Standalone

Last updated Oct 17, 2024

Auto Updating Client Components

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.

Note: The Auto Updating Client Components feature only works for updating already installed Robot, Studio, and UiPath Assistant products to a newer version. If a version downgrade is needed, the downgrade process must be done manually or using tools independent of UiPath.

Prerequisites

Orchestrator, Studio and Robot 2021.10 or later.
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 in a different way:

Unattended Robot: UiPath.UpdateService.Worker.exe is installed as Windows Service, while UiPath.UpdateService.Agent.exe is not installed.
Attended Robot: UiPath.UpdateService.Worker.exe is installed as Windows Service, while UiPath.UpdateService.Agent.exe is installed as a 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 any processes are running on the machine, the Robot user is prompted to either stop the process or wait for it to finish before the update can proceed. If a Studio session is open, the Robot user is asked to save its progress.
If the Robot user does not react, Studio closes, and saves the process as-is at that time. The process can be recovered after the update is completed.
If a certain time limit is reached, the service-mode Robot forces an update even if a job is still running. Due to this behavior, the job can fail. The default waiting time is:
- 10 minutes for service-mode Robots.
- 1440 minutes for user-mode Robots.

Update Process Steps

The update process is split into seven stages:

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.
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.
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.
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.
Install Approved
- Once the approval is received by the update service, the actual installation starts.
Installing
- The new version is installed on the machine keeping the same settings as the previous version.
Success / Error
Based on the install result, the update status is reported back to the update server.
Note: If the Chrome extension was already installed on the robot machine, the auto-update functionality updates it as well. Otherwise, the extension has to be installed manually.

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.

You are also able to manually retry the update using the button if the auto-update failed.

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.

Warning: 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.

Important: For users that have the Automation Express license assigned, the update policy cannot be edited and is set to deliver the latest enterprise version.

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

Navigate to Tenant > Manage access. The Users window is displayed.
For the desired user/user group, click Edit. The Edit User window is displayed.
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.

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:

Navigate to Tenant > Machines. The Machines window is displayed
For the desired machine object, click Edit. The Edit Machine window is displayed.
Access the Maintenance tab. The Auto Update configuration menu is displayed.
Configure the update policy.

Note: Erratum - 28 April 2023

To enable this feature, you need to add the Features.MachineMaintenanceSchedule.Enabled parameter to the UiPath.Orchestrator.dll.config file and set it to true.

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 John.Doe@domain.com user.
An update policy applies to john.doe@domain.com which is set to push the 2021.10.2 version.
john.doe@domain.com is also part of group_1.
An update policy applies to 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.

Warning:

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:

No policy - no policy is defined
Update in progress - this status is presented when the update process is ongoing on the machine
Compliant – the robot version on the machine is matching to the update policy.
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)
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 exclude 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.

Important: 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 status column on the User sessions tab of the Monitoring window allows you to check the status of the client component version for your users against the associated policy.

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 at the host level, then select General, and then 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:

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.
To set the values for ClientId and ClientSecret, run the script below:
Note:
The scripts needed for the commands below can be retrieved by downloading the UiPath Update Server Scripts from the Product Downloads section in Customer Portal.

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>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>".\Provision-IdentityClient.ps1 -IdentityUri "<IDENTITY_URL>" -InstallationToken "<INSTALLATION_TOKEN>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>"
```
The values set for ClientId and ClientSecret should be used later when calling the Product-Versions.ps1 script

Get available versions

.\Product-Versions.ps1 get -ApiBaseUri "<ORCHESTRATOR_URL>" -IdentityUri "<IDENTITY_URL>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>".\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.10.3/UiPathStudio.msi".\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.10.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>"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>".\Provision-IdentityClient.ps1 -IdentityUri "<IDENTITY_URL>" -InstallationToken "<INSTALLATION_TOKEN>" -ClientId "<CLIENT_ID>" -ClientSecret "<CLIENT_SECRET>"

Based on the requirements, the following product IDs can be used in the scripts:

ProductId	Product
FD97813F-44F7-45A0-BB55-0DAF0088F568	UiPath Assistant for Mac (x64)
46C978F2-A5FE-4F71-AD88-D6A07118F790	UiPath Assistant for Mac (arm64)
B69FDACF-6DD0-46FB-88C7-AF2D87CAF5AA	UiPath Automation Bundle (UiPathStudio.msi)

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