UiPath Orchestrator Guide

Prerequisites for Installation

Orchestrator Server

  • Windows Server Operating System - version 2008 R2 SP1, 2012 R2, or 2016.
  • PowerShell - minimum required version: 4.0. To download PowerShell version 4.0, visit this link and install Windows Management Framework 4.0.
  • .NET Framework - minimum required version: 4.5.2. To find out which .NET version is installed on the computer, please see Finding the Installed .NET Version. To download .NET Framework 4.5.2, you can use either the web installer, or the offline one.
  • IIS 7.5 and above - this is part of the Web Server (IIS) role and is automatically enabled by the provided InstallRolesAndFeatures.ps1script, which can be found in this archive.
  • Web-Deploy extension - enables you to deploy a website. Please download and install Web Deploy Extension 3.5 by accessing this link. Select the 64bit version.
  • URL Rewrite - enables the website to redirect the calls to http (as in http://servername), instead of https (as in https://servername). Please download and install URL Rewrite by accessing the link below.
    https://www.microsoft.com/en-us/download/details.aspx?id=47337
  • Add the necessary Server Roles and Features. We provide a PowerShell script that automatically adds the required roles and features to the application server(s). The list of roles and features is presented in Server Roles and Features. Please note that this chapter is for informational purposes only.
  • The Application Pool user needs to have the Log on as a batch job right, in the Local Computer Policy.
  • Run the InstallRolesAndFeatures.ps1 script using PowerShell. The archive containing the script and the XML file can be downloaded here.

A Web Certificate (SSL Certificate)

The use of HTTPS protocol is mandatory for all communication between Robots and Orchestrator on all the browsers on which the web application is accessed by the users.

The following 3 types of web certificates can be used.

  • A web certificate issued by a trusted Certification Authority, such as GoDaddy, VeriSign, etc. The web certificate has to be imported to Server Certificates in IIS. You need to know the name of the "Issued To" entity, which has to be provided when prompted by the installation script.
  • You are a Certification Authority which can issue certificates trusted in the Windows domain. Please see Using a Certificate for the HTTPS Protocol.
  • A self-signed certificate, which is not recommended for Production. The certificate is not trusted inside the domain. For that reason, you need to export its public key, and then import it on all Robot machines. See Using a Certificate for the HTTPS Protocol for further information.
    The name of the certificate that you provide when prompted by installation script, or the one mentioned in the command line using -sslCertificate is the same one that appears in the "Issued To" column in Server Certificates in IIS.

SQL Server

A SQL server machine with one of the following versions: 2008 R2 with SP3 as a minimum requirement, 2012, 2014, 2016, or 2017 Standard or Enterprise Edition.

  • If you want to have the AlwaysOn feature, use 2012 R2 Enterprise Edition, 2014 Standard, or 2016 Standard. The SQL Server product can be either installed on the same machine as the Application Server (not recommended for the Production environment) or provided as a separate machine. The SQL Server machine can be shared with other applications. It does not need to be dedicated to Orchestrator.
  • If you plan to connect Orchestrator to the database using a SQL Server user enable the Windows and SQL Server Authentication mode. Otherwise, "Windows Authentication mode" is enough. If SQL Server is already installed, please select this option as shown in the pictures below:
  • The collation sequence can be the default one - Latin1_General_CI_AS.
  • SQL Server Management Studio is necessary to configure the login of the domain user that accesses the SQL Server. The application pool runs on the application server under the name of the domain user.

SQL Server Configuration

Before installing Orchestrator, it is necessary to configure the SQL Server instance that you want to use.

Note:

The Orchestrator SQL database has to be case insensitive (“OrchDB” = “orchdb”). If it is created during the Orchestrator installation process, it is automatically set as such. If not, you have to manually configure it as case insensitive.

Requirements:

  • the name of the SQL Server machine;
  • the name of the instance, if it’s not the default instance;
  • the value of the TCP port, if it’s not the default port - 1433;
  • the SQL Server port is open in the firewall of the SQL Server machine;
  • the TCP Protocol in SQL Server Configuration Manager has to be enabled;
  • the SQL Server service needs to listen on a fixed port, not on a dynamically allocated one.

Select one of the following options through which Orchestrator can connect to the SQL Server database.

  1. Windows Integrated Authentication. For this option, a new login is required for the SQL Server as a service account. The service account should be a domain user whose password never expires.

To create a new login in SQL Server Management Studio:
a. In the Object Explorer panel, navigate to Security > Logins.
b. Right-click the Logins folder and select New Login. The Login - New window is displayed.
c. Select the Windows Authentication option. The window is updated accordingly.

d. In the Login name field, type the user domain you want to use as a service account.
e. From the Default Language list, select English.

Important

Ensure that the Default Language is set to English. If it isn't, the website cannot start, and the Event Viewer on the computer on which Orchestrator is installed displays the following error message: “The conversion of a varchar data type to a datetime data type resulted in an out of range value”.

f. Click OK. Your configurations are saved.
If the service account has already been created and added to the Security > Logins section of the SQL Server, please check whether the Default Language of that SQL account is set to English. If it isn't, please make the necessary adjustments.

  1. SQL Server username and password. In this case, a SQL Server user is required. We strongly recommend not to use a sa account.

To create a new SQL user in SQL Server Management Studio:
a. In the Object Explorer panel, navigate to Security > Logins.
b. Right-click the Logins folder and select New Login. The Login - New window is displayed.
c. Select the SQL Server authentication option. The window is updated accordingly.

d. Fill in the Login Name, Password, and Confirm Password fields appropriately.
e. Ensure that the Enforce password expiration and User must change password at next login options are not selected.

Important!

Ensure that the Default Language is set to English. If it isn't, the website cannot start, and the Event Viewer on the computer on which Orchestrator is installed displays the following error message: “The conversion of a varchar data type to a datetime data type resulted in an out of range value”.

If the SQL Server account has already been created and added to the Security > Logins section of the SQL Server, please check whether the Default Language is set to English. If it isn't, please make the necessary adjustments.

Regardless of the type of user (domain or SQL) you want to connect to SQL Server, please note that you need to assign it the dbcreator Server Role BEFORE installing Orchestrator, as the database is created during this installation process.

If security restrictions do not allow the use of the dbcreator Server Role in the service account, create the empty database in SQL Server. If you used the default name, UiPath, for the database, you do not need to specify its name as a parameter of the Install-Orchestrator.ps1 script.

If you name the database differently, remember to specify the name using the -mainDatabase command line parameter, if you are installing Orchestrator using the scripts.

The installation connects to SQL Server to verify the existence of the database.

After creating the database, you need to provide the user which connects to the SQL database with the db_owner user mapping role, as in the following screenshot.

If security restrictions do not allow you to use the db_owner user mapping role with the UiPath login, grant the following:

  • db_datareader
  • db_datawriter
  • db_ddladmin
  • EXECUTE permissions on any stored procedure in the UiPath database

The EXECUTE permission has to be granted by using the GRANT EXECUTE SQL command, as follows.

  • if Windows Integrated Authentication is used:
USE UiPath
GO
GRANT EXECUTE TO [domain\user]
GO
  • if SQL Server Authentication is used:
USE UiPath
GO
GRANT EXECUTE TO [sql_user]
GO

Important!

For the Robot to connect as fast as it can to Orchestrator, ensure that the Is Read Committed Snapshot On configuration is set to True, in the SQL Database Properties.

Elasticsearch Server

ElasticSearch is optional. You can choose to store the messages logged by the Robots either in the SQL server database or in another big data collector, such as Splunk, Kafka, etc.

If you choose to use ElasticSearch, please note that although it is a cross-platform product, which runs on Windows, Linux, or Unix, it requires Java. The minimum recommended version of Java Runtime Environment is 1.8.131.

If the computers are in a domain, you have to ensure that they are added in the Computers section of the domain server, in Active Directory Users and Computers. This step is required because the computer name is used during the installation process. For example, http://computername.domain.name or http://computername is used instead of http://localhost.
If this is not possible, then the computer name or the IP address should be used during the installation process.

Java Runtime Environment (JRE)

To download Java from the Oracle Technology Network website, you need to go to the Oracle download page. Select the Accept License Agreement option before starting the download process.

Setting Up JAVA_HOME

Elasticsearch needs Java and uses the JAVA_HOME environment variable.

The JAVA_HOME environment variable needs to present in the System variables, not in the User variables.

If the JAVA_HOME variable is not set, please follow the next steps:

  1. Press the Windows key and type "environment variables". Results are displayed in the Windows Start Menu.
  2. Click Edit the system environment variables. The System Properties window is displayed.
  1. In the Advanced tab, click Environment Variables. The Environment Variables window is displayed.
  1. Under the System Variables section, click New. The New System Variable window is displayed.
  2. Set the variable name to JAVA_HOME and the value to the JRE folder, and click OK.
  1. (Optional) If a Command Prompt is already open, close and reopen it. Otherwise, the new environment variable is not detected, and the installation of Elasticsearch is not carried out because JAVA_HOME is missing.

Elasticsearch

Installing Elasticsearch

  1. Download Elasticsearch 5.5.2 by accessing this page.
  2. Double-click the Elastic Search Windows installer. The Elastisearch wizard is displayed, at the Locations step.
  1. Use the default directories for installation, data, configuration, and logs, or select custom locations for each.

Note:

If you have another disk than the one where Elasticsearch is installed, you can configure Elasticsearch to store the data on the disc with more free space.

  1. Click Next. The Service step is displayed.
  1. Ensure that the following options are selected:
    • Install as a service
    • Start the service after this installation is complete
    • Start the service when Windows starts (Automatic)
  2. Click Next. The Configuration step is displayed.
  1. Configure the following options as desired:
    • Cluster name - change the value to something that reflects the purpose of this Elasticsearch installation. This is important if you have several servers with Elasticsearch in your intranet, to avoid autodiscovery.
    • Node name - a friendly name for your node.
    • Roles - the default options are recommended.
    • Memory - the default options are recommended.
    • Network host - the computer’s hostname/IP address (you can obtain the machine name in a command prompt by running the command hostname).
    • HTTP Port - the default port for Elasticsearch is 9200

Important!

If Orchestrator is installed on a different machine, please remember to open port 9200 in the Firewall of the machine where Elasticsearch is installed.

  1. Click Next. The Plugins step is displayed.
  2. (Optionally) Select additional plugins for Elasticsearch, such as X-Pack for security.
  3. Click Install. ElasticSearch is installed.

Reducing the Number of Index Sharding

By default, newly created Elasticsearch indexes have five shards. However, for an increased performance, it is recommended to reduce this number to two. For more information, please see the official documentation of Elasticsearch.

To make this change, all you have to do is make a PUT request to your Elasticsearch instance URL in the elasticUrl/_template/uipath_logs format, with the following body:

{
	"template": "*",
	"order": 1,
	"settings": {
		"number_of_shards": 2
	}
}

To test your ElasticSearch connection, use any browser to open the following URL: http://computername:9200/. Computername stands for the name of the computer on which Elasticsearch is installed. The browser should either ask you to download a .json file or open and display the file as in the picture below.

Kibana

Install Kibana

Note:

Kibana does not need Java to run. If Kibana is installed on a different machine from Elasticsearch, you don’t need to install Java for Kibana to work.

  1. Download Kibana 5.5.2 by accessing this link.
  2. Unzip the Kibana package.

Note:

Unzip to C:\ or D:\ . You do not need to create a new folder named kibana-x.y.z-windows, because the files in the archive are already placed in a folder with that name.

  1. Edit the Kibana configuration file (C:\kibana-x.y.z-windows-x86\config\kibana.yml), as follows:

Note:

At first, open the file with Wordpad and save it to convert the LF (Line Feed) characters into CRLF (Carriage Return Line Feed) characters. Afterwards, open the file with Notepad.

3.1. Uncomment the line that contains server.port. The default value is 5601. It does not need to be changed unless you want Kibana to run on a different port.
3.2. Uncomment the line that contains server.host. Change the value to the name of the computer.
3.3. Uncomment the line that contains elasticsearch.url. Change the value to the Elasticsearch URL, using the name of the computer on which Elasticsearch is installed. For example, http://computername:9200.
The screenshot below displays an example of a Kibana configuration file in which the computer names of both Kibana and Elasticsearch are JLTSQL:

3.4. Save the file.

  1. Download the setup-kibana-service.zip archive.
  2. Copy the nssm.exe and setup_kibana.bat files from the setup-kibana-service.zip archive to C:\kibana-x.y.z-windows-x86\bin.
  3. Open the setup_kibana.bat file to check whether Kibana is installed in accordance with the location set in the KIBANA_HOME variable in the BAT file. If you extracted Kibana to a diferent location, make the necessary changes.
  4. Open Command Prompt as an Administrator and change the folder to C:\kibana-x.y.z-windows-x86\bin.
  5. Run setup_kibana.bat to install Kibana.
  6. Test whether Kibana responds by typing http://computername:5601 in any web browser. computername represents the name of the computer on which you installed Kibana.

Important!

Open port 5601 in the Firewall of the machine on which Kibana is installed.

  1. Search the UiPathOrchestrator.zip archive for the AddMessageToElasticSearch.ps1 script.
  2. Add a test message in the Elasticsearch database by running AddMessageToElasticSearch.ps1.
    • If you run the PowerShell script on the same machine as Elasticsearch, no parameter is required.
    • If you execute the script on a different machine, include the -uri http://computername:9200 parameter.
    • If the AddMessageToElasticSearch.ps1 script does not report any errors, the Elasticsearch index named default-yyyy.mm is created and the message is added.

Important!

Each time a new tenant is added, a corresponding index pattern should be created in Kibana, starting with the name of the tenant. yyyy stands for the year in which the message was added. mm stands for the month in which the message was added.

  1. Read Creating an Index Pattern to Connect to Elasticsearch to learn how to create an index pattern in Kibana.

Time Synchronization

Also, please keep in mind that regardless of the type of installation you choose, for the scheduling features to work properly you must ensure that:

  • in clustered mode the clocks on all machines have to be synchronized within less than one second;
  • the clocks for the database and Orchestrator machines also have to be synchronized;
  • if the SQL database enters a faulted state it is recommended to restart the Orchestrator web server from IIS. If you are in an NLB environment, please restart all web servers.

Database Migrations

The Database.EnableAutomaticMigrations parameter in the web.config lets you control when to perform the database migration or creation. This parameter is required when upgrading Orchestrator from an old version that was installed using the scripts.

It can have the following values:

  • false - The database migration or creation takes place while installing Orchestrator. This is the default option.
  • true - The database migration or creation takes place when you first open Orchestrator.

Prerequisites for Installation