Installation

Prerequisites to Installation

1. Ensure that you meet the Hardware and Software Requirements for Insights.
2. Enable IIS 10+.

   To enable IIS 10+, go to Control Panel > Programs > Turn Windows features on or off > IIS.

   
   

   

   
   
   Enable the following Web Server (IIS) modules:

   • Web Server
     • Common HTTP Features
       • Default Document
       • Directory Browsing
       • HTTP Errors
       • Default Document
       • Static Content
     • Health and Diagnostics
       • HTTP Logging
     • Performance
       • Static Content
     • Security
       • Request Filtering
   • Management Tools
     • IIS Management Console
   
3. Download and install .NET Hosting Bundle version 3.1.17+.
   1. Download .NET Hosting Bundle.
   2. In Command Prompt, run net stop was /y and then net start w3svc.
4. Install Orchestrator and enable the Insights feature. You need to get an installation access token from Orchestrator.
   Important:

   • Make sure that you select the db_owner role as this is required when you add the database owner role during the Insights SQL Server configuration.

   • Both the Orchestrator and Insights versions need to match. For example, if you run Orchestrator version 2021.10.1, you need to run the same version of Insights to establish proper communication between the two UiPath products.

   
   

   

   
   
5. Enable HTTPS on your server using an SSL certificate. The procedure is similar to the one provided for Orchestrator. See Using a Certificate for the HTTPS Protocol.
   1. Get self-signed certificate with your DNS and import it into certlm.msc.
      
      

      

      
      
   2. Run the following command:

      $cert = New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname <your-dns-name> -KeySpec KeyExchange
      $pwd = ConvertTo-SecureString -String '<your-password>' -Force -AsPlainText
      $path = 'cert:\localMachine\my\' + $cert.thumbprint
      Export-PfxCertificate -cert $path -FilePath <path-to-save>\cert.pfx -Password $pwd

      Note: Make sure to replace the following:

      • <your-dns-name> with the DNS name of your server or virtual machine
      • <your-password> with the password you want to encrypt the certificate with
      • <path-to-save> with the location where you want to save the exported .pfx format certificate
   3. Manually install the certificate in both Personal and Trusted using the certificate manager.
      Important: It is preferable to use a SAN SSL certificate submitted to a Certificate Authority rather than a self-signed one.

      • Self-signed certificates (and those from your own certificate authority) must be installed in both the Trusted Root and Personal certificate stores on the Insights machine, and must also be marked as Exportable.
      • Certificates submitted to a Certificate Authority only need to be installed in Trusted Root.

      Note that when using a self-signed certificate, you may experience issues if accessing Insights via Firefox or Edge. Internet Explorer support is no longer offered for Insights 2021.4 or newer.

6. When specifying a hostname for Insights, make sure that the desired hostname is resolvable within your DNS.
   
   

   

   
   
7. Verify that the server where Insights will be installed can communicate with the server(s) where Orchestrator is installed and vice versa.
8. If you are using a local or a cloud-hosted VM, it must support nested virtualization on Windows operating systems.
   • Azure - See more
   • AWS - See more
9. Make sure to use TLS 1.1 or 1.2.
10. Make sure the following ports are open and accessible: 543 (default), 9999, and 19999.
    Create an inbound port rule for each port to open it up: 543, 9999, 19999.

    
    

    

    
    
    • Port 543:
      
      

      

      
      
    • Port 9999:
      
      

      

      
      
    • Port 19999:
      
      

      

      
      
11. Install Docker based on your environment.
    Install Docker for Windows Server 2019:

    1. Using PowerShell, create the following variable:

       $TMP_WORKDIR="c:\docker"

    2. Using PowerShell, create the following directory:

       New-Item $TMP_WORKDIR -ItemType Directory -force

    3. Enable the following Windows features: Hyper-V and Container. To do this, take the following steps:
       1. Navigate to the Control Panel, then go to Programs.
       2. Click Turning the Windows features on or off.
       3. Select the checkboxes next to Hyper-V in the Server Roles tab and Container in the Features tab.
       4. Restart the server if required.
          
          

          

          
          
          
          

          

          
          
    4. You can use PowerShell to download Docker and unzip the Linux Containers to the $TMP_WORKDIR folder, by running the following command:

       Invoke-WebRequest -URI "https://download.docker.com/win/static/stable/x86_64/docker-20.10.24.zip" -OutFile "$TMP_WORKDIR\docker-20.10.24.zip"

    5. You can use PowerShell to download lcow kernel and unzip the Linux Containers to the $TMP_WORKDIR folder, by running the following command:

       Invoke-WebRequest -Uri "https://github.com/linuxkit/lcow/releases/download/v4.14.35-v0.3.9/release.zip" -UseBasicParsing -OutFile "$TMP_WORKDIR\release.zip"

    6. Next, install Docker and lcow:

       Expand-Archive $TMP_WORKDIR\Docker-20.10.24.zip -DestinationPath $Env:ProgramFiles -Force
       Expand-Archive $TMP_WORKDIR\release.zip -DestinationPath "$Env:ProgramFiles\Linux Containers\." -Force

    7. Next, using PowerShell, set the environment variables by running the following command:

       [Environment]::SetEnvironmentVariable("PATH", $Env:PATH + ";$Env:ProgramFiles\docker", [EnvironmentVariableTarget]::Machine)
       [Environment]::SetEnvironmentVariable("LCOW_SUPPORTED", "1", "Machine")
       [Environment]::SetEnvironmentVariable("LCOW_API_PLATFORM_IF_OMITTED", "linux", "Machine")

    8. Using PowerShell, enable the Experimental Features in daemon.json by running the following command:

       $configfile = @"
       {
           "experimental": true
       }
       "@
       $configfile|Out-File -FilePath C:\ProgramData\docker\config\daemon.json -Encoding ascii -Force

    9. Register the service by running the following command in PowerShell:

       cd $Env:ProgramFiles\docker
       .\dockerd.exe --register-service

    10. Lastly, restart your computer by running the following command in PowerShell:

        Restart-Computer -Force

    Install Docker on air-gapped VMs:

    To install Docker in air-gapped environments, you need to perform two steps. First, download the installation files to an online VM, then copy the files to your offline VM, where you want to install it.

    Requirements

    • Make sure the offline VM meets the requirements for the Insights Server.
    • The online VM needs to run Windows Server 2019+ and have internet access.

    Download Docker installation files on the online VM

    In your online VM, open PowerShell as Administrator and run the following commands to create a new Docker folder.

    # variables
    $TMP_WORKDIR="c:\docker"
    
    # Create tmp_workdir
    New-Item $TMP_WORKDIR -ItemType Directory -force
    
    # Install Hyper-V and Containers
    Install-WindowsFeature Hyper-V
    Install-WindowsFeature containers

    Download lcow kernel and unzip the Linux Containers to the $TMP_WORKDIR folder.

    # Get docker
    Invoke-WebRequest -URI "https://download.docker.com/win/static/stable/x86_64/docker-20.10.24.zip" -OutFile "$TMP_WORKDIR\docker-20.10.24.zip"
    
    # Get lcow
    Invoke-WebRequest -Uri "https://github.com/linuxkit/lcow/releases/download/v4.14.35-v0.3.9/release.zip" -UseBasicParsing -OutFile "$TMP_WORKDIR\release.zip"

    Install Docker on the offline VM

    In your offline VM, open PowerShell as Administrator and run the following commands to install Docker, register the service and restart the machine.

    # Install
    Expand-Archive $TMP_WORKDIR\Docker-20.10.24.zip -DestinationPath $Env:ProgramFiles -Force
    Expand-Archive $TMP_WORKDIR\release.zip -DestinationPath "$Env:ProgramFiles\Linux Containers\." -Force
    
    # Add Environment Variables
    [Environment]::SetEnvironmentVariable("PATH", $Env:PATH + ";$Env:ProgramFiles\docker", [EnvironmentVariableTarget]::Machine)
    [Environment]::SetEnvironmentVariable("LCOW_SUPPORTED", "1", "Machine")
    [Environment]::SetEnvironmentVariable("LCOW_API_PLATFORM_IF_OMITTED", "linux", "Machine")
    
    # Enable Experimental Features in Docker daemon.conf
    $configfile = @"
    {
        "experimental": true
    }
    "@
    $configfile|Out-File -FilePath C:\ProgramData\docker\config\daemon.json -Encoding ascii -Force
    
    # Register service
    cd $Env:ProgramFiles\docker
    .\dockerd.exe --register-service
    
    # Restart Computer
    Restart-Computer -Force

12. If you use VMWare, make sure to use VMwareToolboxCmd 11.0.6+. Earlier versions may cause Docker container to restart unexpectedly.

SQL Server Configuration

Before installing Insights, you need to configure the Insights SQL Server instance that you want to use.

Note: The Insights SQL database is case insensitive (“InsightsDB” = “insightsdb”). If it is created during the Insights installation process, it is automatically set as such. If not, you have to configure it manually as case insensitive.

If you create your own Insights database, you need to set the collation sequence to Latin1_General_CI_AS.

Prerequisites

Make sure that you have the following either at hand or have them worked through, as the initial configuration steps:

• The name of the SQL Server machine.
• The name of the instance, if it’s not the default instance.
• The SQL Server port is open in the firewall of the SQL Server machine.
• The TCP Protocol in SQL Server Configuration Manager is enabled.
• The SQL Server service is set to listen on a fixed port, not on a dynamically allocated one.

Recommendations

To configure the default MAXDOP of your database, see Configure the max degree of parallelism Server Configuration Option.

SQL Server Authentication Methods

Configure one of the following authentication methods through which Insights can connect to the SQL Server database:

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. Looker, the analytics platform used by Insights, runs in a Linux container. To enable Windows Authentication, SQL Server needs to support authentication through the Kerberos protocol.

Considerations when configuring Windows Integrated Authentication

• Before configuring the Kerberos authentication, make sure that the Insights Server can access your Active Directory (AD) and SQL Server. You can review this with your IT administrator.
• SQL Server needs to be added to your AD domain.
• Insights Server needs to be on the same network as the AD Domain and SQL Server.
• DNS should be configured so that Insights Server can resolve the domain names for both AD Domain and SQL Server.
• AD user should exist with access to SQL server and DB permissions as defined in the Permissions section. Domain, username, and password for this user must be provided during the Insights install process. Keep in mind that the username is case sensitive and that this also serves as the sAMAccountName of the user.
  Open cmd as admin and run set user to get the USERDNSDOMAIN and USERNAME.
• SQL server needs to have SPN entries in AD. For more information, see Register a Service Principal Name for Kerberos Connections.
  Important: It is critical that the Insights server needs to resolve the domain names of both AD Domain and SQL Server. You can verify this by running nslookup <your_AD_domain_name> and nslookup <your_SQL_server_domain_name> on the host machine.

Create new login in SQL Server Management Studio

1. In the Object Explorer panel, navigate to Security > Logins.
2. Right-click the Logins folder and select New Login.
3. Select the Windows Authentication option. The window is updated accordingly.
   
   

   

   
   
4. In the Login name field, type the user domain you want to use as a service account.
5. 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 Insights 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.
6. Click OK to save the configuration.

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

SQL Server Authentication

For this authentication method, you need an SQL Server user.

Important: Consider using a non-SA (system administrator) account for security reasons.

Create SQL user in SQL Server Management Studio

1. In the Object Explorer panel, navigate to Security > Logins.
2. Right-click the Logins folder and select New Login. The Login - New window is displayed.
3. Select the SQL Server authentication option. The window is updated accordingly.
   
   

   

   
   
4. Fill in the Login Name,Password, and Confirm Password fields appropriately.
5. 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 Insights 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.

Permissions

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

The Windows installer 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 Orchestrator 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 permission on dbo schema
  
  

  

  
  

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

• if Windows Integrated Authentication is used:

  USE UiPath Insights
  GO
  GRANT EXECUTE ON SCHEMA::dbo TO [domain\user]
  GO

• if SQL Server Authentication is used:

  USE UiPath Insights
  GO
  GRANT EXECUTE ON SCHEMA::dbo TO [sql_user]
  GO

Insights Installation

Note:

• When upgrading to 2021.10, users with Insights permissions are not currently migrated to the new version. A script to do so will be available soon.
• The Installer will use the Windows Display Language if it is one of the following languages: en-US, fr-FR, de-DE, es-ES, es-MX, ja-JP, ko-KR, pt-BR, pt-PT, ru-RU, tr-TR, zh-CN. If the Windows Display Language is not one of these languages, then the installer will use English.

1. Run the InsightsInstaller.msi installer as administrator using the command prompt or PowerShell console.
2. Type cmd or powershell, then right-click the app and Run as administrator.
3. Type the cd <path-to-msi> command, where <path-to-msi> is where your .msi installer is located. E.g., C:\Users\yourUsername\Downloads>.
4. Run the Insights installer using the following command:

   msiexec /i InsightsInstaller.msi

   Alternatively, you can use the following command:

   .\InsightsInstaller.msi

5. The Insights installer should now check the prerequisites. If all prerequisites are met, the UiPath Insights Setup Wizard shows up and guides you through the Insights installation and configuration.
   
   

   

   
   
   Note:

   If the installation failed or you want to check the installation log, you can go to the %temp% or %temp%/<sessionID> folder and check the latest MSI{random chars}.LOG.

   If you would like to specify a different directory, use the command msiexec.exe /i InsightsInstaller.msi /L*V logfilepath. For more details, see the Support page.
6. Accept the License Agreement and click Next.
   
   

   

   
   
7. Change the Insights server settings as follows:
   • Insights Server URL - the hostname or the URL of the Insights Server.
   • Port - the port you want to use to enable the communication between the computer and Insights.
   • Certificate - the Subject or Thumbprint of the SSL certificate you want to use to secure connections with Insights.
     
     

     

     
     
8. Configure the Orchestrator settings as follows:
   • Orchestrator URL - the URL of Orchestrator
   • Separate Identity Server - If you have a separate identity server, enable this option.
   • Installation Token - enter the Installation Access Token you generated on Identity Server's Installation Access Token page by logging in as the host tenant. For more details, see Installation Access Token.
     Note: You need a new Installation Access Token on every installation. The token is valid for 2 hours, after which it expires. Generate another if experiencing an installation failure.
     
     

     

     
     
9. Configure the Insights database settings as follows:
   • Server Name - the name of the SQL Server machine where the Insights database is located
   • Database Name - the name of the Insights database
   • Authentication Type - choose one of the following authentication methods:
     Important: You must use the fully-qualified domain name for the database (e.g., mysever.my.domain instead of myserver). Preferably the SQL Server must join the AD domain directly.
     • Windows Authentication - if selected, Insights connects to the database, creates tables, and runs the IIS Application Pool using the specified credentials. The installer validates the connection using the Windows credentials you are currently logged in with. If you select this option, you must specify the domain, username, and password.

     • SQL Authentication - if selected, the connection is made using SQL authentication. If using this option, the Username and Password fields become editable, and you must provide the SQL username and password used to connect to the database.

       
       

       

       
       
   • Configure the email settings as follows:
   • Configure Email Service (SMTP) - check to configure the email service
     • Server - the SMTP host
     • From - the email address to send mail messages from. It must match that provided for Username.
     • Username - the username of the SMTP server, if it requires authentication. For example, if you are using Gmail, fill in this field with the email address used to send messages.
       Important: Consider using SMTP with authentication, as SMTP with no authentication may not be supported in the future.
     • Password - the email account password
     • Port - the SMTP port.
   • TLS/SSL - check to enable TLS/SSL.
     • TLS/SSL Version - only visible TLS/SSL is checked. Choose between TLSv1_1 and TLSv1_2
       
       

       

       
       
       Note: Once this step is completed, an email is sent using the SMTP server details. This is to ensure the SMTP details are correct.
   • Click Next to start the installation. Once the installation process completed, click Close to exit the installer.
     
     

     

     
     
     Important: After Insights installation has finished, make sure to restart Docker.

Offline Installation

For offline installation, you need to consider the following:

• Install Docker for Windows Server 2019.
• Both Orchestrator and Insights Database are accessible.
• Make sure the SMTP email server is accessible, if configured.

Post-Installation Steps

Verifying the Insights Services

Note: Do not remove the C:\Users\yourUsername\_insights folder.

Accessing Looker

To verify that Looker is running, make sure the Docker container is up.

After Insights installation has finished, navigate to the browser to confirm a successful installation.

Addressing log4j Vulnerability

To address the log4j vulnerability, make sure you run the hotfix to update dependencies to the latest non-vulnerable version of Apache Log4j.

For more information, see the UiPath Insights (version 2021.10+) / Automation Suite Advisory section in UiPath Security Advisory CVE-2021-44228, CVE-2021-45046 & CVE-2021-45105.

Modifying Insights

Keep the original installation file in case you want to modify or uninstall it.

For more information, see Modifying Insights configurations.

Tenant Setup

After installing Insights, you must then enable it for your desired tenant(s) from the Orchestrator host portal. For more details, see Enabling or disabling features.

Note: There are scenarios where the Orchestrator table dbo.tenants has the key and accountId columns in uppercase values. This typically only happens with older versions of Orchestrator (Orchestrat 18.X or lower).

1. Check the logs under %programdata%/UiPath Insights/Provisioning
2. There should be an error about the OrchestratorTenantJob failing.
3. Login to the Orchestrator DB using a sql client.
4. Check the dbo.Tenants table.
5. Check if the columns 'Key' and 'AccountId' are all capitalized.
6. If they are, making them lowercase fixes the issue.
7. If there is a tenant that's lowercase, try just enabling that tenant and see if the error still occurs.
8. To fix the issue, change the case of the fields (make sure to backup the DB before hand. Also make a note of the KEYs that are already lowercase).
   • UPDATE [UiPath].[dbo].[Tenants]
   • set [key] = LOWER([key]), [AccountId] = LOWER([AccountId])
9. To revert the change, run
   • UPDATE [UiPath].[dbo].[Tenants]
   • set [key] = UPPER([key]), [AccountId] = UPPER([AccountId])
   • WHERE [key] NOT IN ('xx-xx-xx-xx', 'xx-xx-xx-xx');
10. Doing an IIS reset (or just recycling the Provisioning application pool) maybe necessary. The provisioning service tries to provision instance every 10 minutes so if this isn't done, just wait 10 minutes at most.
11. If the issue is still occurring, raise a ticket with UiPath and include the following
    • Screenshot of the dbo.tenants table.
    • The provisioning logs mentioned above.

Related Articles

• 2021.10 Upgrade Cheat Sheet
• Upgrading Insights
• Troubleshooting
• Support files