Installing or upgrading an on-premise Robots Agent

Download the installation package

1. Download the Robots Agent installation package (RobotsAgent17.exe) from Launchpad:
   1. Sign in to Diligent One (www.highbond.com).
   2. In Launchpad, under Audit & Analytics, click the Analytics tile to access downloads.
   3. In the top menu, click Robots Agent.
   4. Click Download version 17.
2. With the downloaded installation package on your Windows server, double-click the installation package.

3. If a security warning dialog box appears, verify the information listed, and click Yes.

   Tip

   The security warning dialog box could be hidden behind any windows you have open.

Extract and run the installer

1. Select the language that you want to use for your installation and click OK.
2. In the Setup Extraction Location page, specify the folder where the installation files will be extracted, and click Extract.

   You can click Browse to select a folder, or accept the default location:

   C:\Users\user_account_name\Downloads\ACL Installers\RobotsAgent17

   The setup files are extracted to the destination folder you specified. After the files are extracted the installer starts automatically.

   Note

   If the installer fails to start automatically for any reason, you can use Windows Explorer to navigate to the folder where the setup files were extracted and double-click setup.exe.

Install prerequisites, if required

If you are prompted to install prerequisites, click Install.

After the prerequisites are installed, the installer automatically proceeds.

For a list of prerequisites, see On-premise Robots Agent system requirements.

Configure the installation properties

1. In the Welcome page, click Next.
2. In the License Agreement page, select I agree to the above terms and click Next.
3. In the Robots Agent Edition Selection page, select the edition you want to install and click Next:
   • Non-Unicode
   • Unicode

   Caution

   Ensure that the edition you install is the correct edition for your company. To open Robots Agent tables in Analytics, the editions must match.

   If you are setting up a multi-agent cluster, all agents in the cluster must be the same edition. All non-Unicode, or all Unicode.

   For more information, see Diligent Unicode products.

4. In the Optional Analytics data connectors page, leave the Install option selected unless you have a reason for not installing the optional connectors and click Next.

   Note

   If you choose not to install the optional connectors and you later want to use one of them, you must uninstall and reinstall the Robots Agent.

5. In the Enable machine learning page, leave the Enable option selected unless you have a reason for not installing the Python engine and click Next.

   Note

   If you choose not to install the Python engine and you later want to use it for running machine learning commands, you must uninstall and reinstall the Robots Agent.

6. In the Robots Agent Services Settings page, complete the following service account settings, and then click Next:
   • Robots Data Service port number Specify a port for the data service, or use the default of 10000.

     You can specify any available port between 0 and 65536.

   • Robots Agent Service account Specify an existing domain account to run the Robots Agent service and provide the password.

     The account must be a domain account, specified using the form Domain\service_account. The account requires permission to run services on the Windows Server operating system as well as full access to the data folder that you specify during installation. For more information, see On-premise Robots Agent security.

     Note

     If required, you can change the Robots Agent service account post-installation.

7. If you are prompted to grant the Log on as a service right to the Robots Agent service account, click Yes and then OK.

8. In the Destination Folders page, complete the following destination and connection settings, and then click Next:
   • Robots Agent Destination Folders
     • Select a destination folder for the Robots Agent installation, or use the default location.

       Default: C:\Program Files (x86)\ACL Software\Robots Agent\

     • Select a data folder location, or use the default location.

       Default: C:\acl\robots\

       Note

       Do not place the data folder inside the installation destination folder, or the other way around. Doing so may cause data loss when uninstalling the Robots Agent.

   • Robots Agent registration file location
     • Select Copy registration file and then browse to the location where you saved the registration.key file, or enter the file path manually.

       When the installer runs, it automatically copies the keyfile to the correct location in the Robots Agent directory structure.

       Note

       Leave Copy registration file deselected, and do not specify a registration file, if you plan to change the Robots Agent service account after installing the Robots Agent.

Complete the installation

1. In the Ready to Install the Program page, click Install.

   Robots Agent is installed.

2. If a prompt appears that gives you the option to install Microsoft Access Database Engine, do one of the following:
   • Click Yes to install the Database Engine if you need the Robots Agent to import from, or export to, older Excel files (*.xls), or Microsoft Access files (*.mdb).
   • Click No to exclude the Database Engine if you use the Robots Agent with only the current generation of Excel file (*.xlsx), and you do not use older Excel files, or Microsoft Access files. The Database Engine can cause compatibility issues with other, newer Microsoft Office products. For this reason, you should exclude the Database Engine unless you actually need it.
3. When the installation process is complete, click Finish.

Confirm the Robots Agent service is running

The Robots Agent service must be running for the Robots Agent to connect to the Robots app. Without a connection, the Robots Agent cannot process robot tasks and scripts.

If required, you can change the Robots Agent service account at the same time that you confirm the Robots Agent service is running.

Use the Robots Agent service account that you specified during installation

1. Open the Windows Services manager.

2. Check that both Robots Agent Windows services are running:

   • Robots Agent
   • Robots Data Service

   If necessary, start one or both services.

   Note

   If an error message appears stating that the Robots Agent service started and then stopped, registration of the Robots Agent may not have been successful.

   Check that the registration keyfile (registration.key) is present in the Robots Agent installation directory. If the registration keyfile is not there, manually copy the keyfile from the location where you saved it to the installation directory. Try again to start the Robots Agent service.

   The default installation directory is: C:\Program Files (x86)\ACL Software\Robots Agent\agent

3. Check the application log file to confirm that the Robots Agent is successfully connected to the Robots app.

   Go to the end of the log file and look for an INFO|Connected entry with a date and time that aligns with the start of the Robots Agent service.

   The default location of the log file is: C:\acl\robots\logs\application.log

4. In the Robots app, go to the Agent management screen and press F5 to reload the page.

   If the Robots Agent appears with a status of Online, it was successfully registered.

Change the Robots Agent service account

Follow these steps if you left Copy registration file deselected during installation of the Robots Agent, and you want to change the Robots Agent service account.

Manually install the registration keyfile

1. Copy the registration keyfile (registration.key) from the location where you saved it.
2. Navigate to the Robots Agent installation directory, and paste the registration keyfile in the agent subfolder.

   The default installation directory is:  C:\Program File (x86)\ACL Software\Robots Agent\agent

   If necessary, delete or overwrite an existing keyfile.

Change the Robots Agent service to a different account

1. Open the Windows Services manager.
2. Right-click the Robots Agent service and select Properties.
3. In the Log On tab, click Browse.
4. In the Select User dialog box, in the Enter the object name to select field, enter the name of the service account that you want to use and click Check Names.

   The service account should be prefilled in the field.

5. Click OK.
6. In the Log On tab, enter and confirm the password for the service account and click OK.
7. In the Windows Services manager, restart (or start) the Robots Agent service.
8. If necessary, start the Robots Data Service.

Confirm the Robots Agent is successfully registered

1. Check the application log file to confirm that the Robots Agent is successfully connected to the Robots app.

   Go to the end of the log file and look for an INFO|Connected entry with a date and time that aligns with the start of the Robots Agent service.

   The default location of the log file is: C:\acl\robots\logs\application.log

2. In the Robots app, go to the Agent management screen and press F5 to reload the page.

   If the Robots Agent appears with a status of Online, it was successfully registered.

Configure Robots Agent settings in the Robots app

If appropriate for your organization, in the Robots app update the default values for two Robots Agent configuration settings:

• Permitted file uploads controls whether output results are uploaded from the Robots Agent to the Robots app in the cloud
• Paths configuration specifies the Windows server or network directories for Analytics data tables and result tables

For more information, see Configuring an on-premise Robots Agent.

Create an Analytics project and download the test file

1. Create a new Analytics project called Robots Agent test.acl.
2. Right-click the link below and save the file in the same folder as the project you just created:

   Robots_Agent_test_file.txt

Copy the test script

1. In the Analytics project, create a new script called Robots_Agent_test_script.
2. Click the link below to open the test script in a browser:

   Robots_Agent_test_script.txt

3. Press Ctrl+A to select the entire script, and Ctrl+C to copy it to the clipboard.
4. Paste the script into Robots_Agent_test_script and click Save the Open Project .

Commit the script to Robots and create a robot on the fly

1. From the Analytics main menu, select File > Commit Scripts.
2. If required, in the Select Destination dialog box, double-click the appropriate Diligent One instance.

   The Robot Collection appears with the list of existing robots, if any already exist. A robot is a container for scripts, data, and automated tasks.

3. Type Test Robot in the New Robot field, and click Create.

   The robot is created, and a robot ID is automatically generated.

4. In the Commit Scripts dialog box, enter a commit message such as "Upload test script", and click OK.

   The script is committed to Robots and located in the robot that you just created.

5. In the Commit Scripts Successful dialog box, click the second link.

   Result The Robots app opens in a browser window, with the Script versions tab selected. You may be required to sign in to Diligent One. You should see the script version that you just committed.

6. In Analytics, click OK to exit the Commit Scripts Successful dialog box.

Upload the test file

1. In Robots, select the Input/Output tab.
2. Click choose from your computer and browse to the location where you saved Robots_Agent_test_file.txt.
3. Select the file and click Open.

   Result The file is uploaded and appears under Files in the Input/Output tab.

Create a task and run the test script

1. Select the Tasks tab and click Create task.
2. Type the name Test Task for the task and click Save.
3. Select Robots Agent test script and click Skip to end > Confirm and create task.
4. On the Tasks tab, in the Test Task, click > Run now.

   Result The task with the test script runs.

   If the task completes with a status of Success, the on-premise Robots Agent you installed is working correctly.

   Note

   If the task fails, check that the Robots Agent service is running on the server where you installed the Robots Agent. Start the service if it is not running, and try running Test Task again.

   If the task continues to fail, contact Diligent Support for assistance.

Verify the script output

Check the following locations in Robots to make sure the test script output the correct files.

Stop the Robots Agent Windows services

1. On the Windows server where the Robots Agent is located, open the Windows Services manager.
2. Stop both Robots Agent Windows services:
   • Robots Agent
   • Robots Data Service

Download the installation package

1. Download the Robots Agent installation package (RobotsAgent17.exe) from Launchpad:
   1. Sign in to Launchpad (www.highbond.com).
   2. Under Resources, click Downloads.
   3. In the top menu, click Robots Agent.
   4. Click Download version 17.
2. With the downloaded installation package on the Windows server , double-click the installation package.

3. If a security warning dialog box appears, verify the information listed, and click Yes.

   Tip

   The security warning dialog box could be hidden behind any windows you have open.

Extract and run the installer

1. Select the language that you want to use for your installation and click OK.
2. In the Setup Extraction Location page, specify the folder where the installation files will be extracted, and click Extract.

   You can click Browse to select a folder, or accept the default location:

   C:\Users\user_account_name\Downloads\ACL Installers\RobotsAgent17

   The setup files are extracted to the destination folder you specified. After the files are extracted the installer starts automatically.

   Note

   If the installer fails to start automatically for any reason, you can use Windows Explorer to navigate to the folder where the setup files were extracted and double-click setup.exe.

3. Click Yes in the upgrade prompt.
4. In the Robots Agent Installer Information dialog box, click OK only if you have complied with the listed requirements.

   If you have not yet complied with the requirements, comply with them now before continuing with the upgrade. If necessary, temporarily disable any robot task scheduled to run shortly.

Install prerequisites, if required

If you are prompted to install prerequisites, click Install.

After the prerequisites are installed, the installer automatically proceeds.

For a list of prerequisites, see On-premise Robots Agent system requirements.

Configure the installation properties

1. In the Welcome page, click Next.
2. In the License Agreement page, select I agree to the above terms and click Next.
3. In the Robots Agent Edition Selection page, click Next.

   The installer enforces the edition of the Robots Agent that you currently have installed (non-Unicode or Unicode).

   Note

   You cannot change the edition during an upgrade. To change the edition, you must uninstall the current version of the Robots Agent and then install version 17.0.

4. In the Optional Analytics data connectors page, leave the Install option selected unless you have a reason for not installing the optional connectors and click Next.

   Note

   If you choose not to install the optional connectors and you later want to use one of them, you must uninstall and reinstall the Robots Agent.

5. In the Enable machine learning page, leave the Enable option selected unless you have a reason for not installing the Python engine and click Next.

   Note

   If you choose not to install the Python engine and you later want to use it for running machine learning commands, you must uninstall and reinstall the Robots Agent.

6. In the Robots Agent Services Settings page, complete the following service account settings, and then click Next:
   • Robots Data Service port number Keep the existing port specified for the data service, or specify a different port.

     You can specify any available port between 0 and 65536.

   • Robots Agent Service account Keep the existing domain account that runs the Robots Agent service, or specify a different account. Provide the password for the account.

     The account must be a domain account, specified using the form Domain\service_account. The account requires permission to run services on the Windows Server operating system as well as full access to the existing Robots Agent data folder. For more information, see On-premise Robots Agent security.

     Note

     If you need to change the Robots Agent service account, a better option is to change it post-upgrade.

     If you change the account in the installer during the upgrade, you need to re-register the Robots Agent. Re-registering an installed agent is potentially disruptive to the configuration of your organization's Robots instance.

     For more information, see Changing the Robots Agent service account.

7. Review the configuration information in the next screen, and click Next.

Complete the upgrade

1. In the Ready to Install the Program page, click Install.

   Robots Agent is upgraded.

2. If a prompt appears that gives you the option to install Microsoft Access Database Engine, do one of the following:
   • Click Yes to install the Database Engine if you need the Robots Agent to import from, or export to, older Excel files (*.xls), or Microsoft Access files (*.mdb).
   • Click No to exclude the Database Engine if you use the Robots Agent with only the current generation of Excel file (*.xlsx), and you do not use older Excel files, or Microsoft Access files. The Database Engine can cause compatibility issues with other, newer Microsoft Office products. For this reason, you should exclude the Database Engine unless you actually need it.
3. When the upgrade process is complete, click Finish.
4. Click Yes to restart the server and complete the upgrade.

5. In the Windows Services manager, check that both Robots Agent Windows services are running:

   • Robots Agent
   • Robots Data Service

   If necessary, start one or both services.

These instructions refer to Server #1 and Server #2:

• Server #1 The Windows server on which you installed the first instance of the Robots Agent
• Server #2 An additional Windows server on which you install an additional instance of the Robots Agent

  Note

  You can repeat the process for as many additional agents and servers as you need.

Install the Robots Agent on Server #2

1. On Server #2, perform the same installation process that you used to install the Robots Agent on Server #1.

2. In the Destination Folders page in the installer, do not select Copy registration file, and leave the Robots Agent registration file location field blank.

For the installation steps, see Install the Robots Agent.

Retrieve the RSA key name from the Robots app

1. Sign in to Diligent One (www.highbond.com).
2. From the Launchpad home page, under Audit & Analytics, select the Robots app.
3. In the upper-right corner of the dashboard, click Settings.
4. In the left-hand pane, make sure Agent management is selected.
5. Click How to add additional agents.
6. Click to copy the RSA key name to the clipboard.
7. Paste the RSA key name into a text file for temporary storage.

Bundle the Robots Agent RSA key in a file

Use the EncryptionKeyCLI.exe utility on Server #1 to bundle the Robots Agent RSA key in a file.

1. On Server #1, open the Windows command prompt as administrator.
2. Run the following command to change to the Robots Agent installation directory:

   cd C:\Program Files (x86)\ACL Software\Robots Agent\agent

   Specify the appropriate path if you did not install the Robots Agent in the default directory.

3. Run the following command to bundle the Robots Agent RSA key in a zip file:

   EncryptionKeyCLI.exe export RSAKeyfile ACL_XXXXXXXX

   For ACL_XXXXXXXX , substitute the actual RSA key name that you copied from the Agent management screen in Robots.

   RSAKeyfile can be any file name, without spaces, that you want to specify. You can optionally specify a file path to an existing folder on the server. If the path contains any spaces, enclose the entire path and the file name in double quotation marks.

4. If required, enter Y to overwrite an existing file.

   Result The RSA key is bundled in a zip file and saved in the default location (C:\ProgramData\robots\RSAKeyfile.zip) or in the location that you specified.

   Note

   If you do not see the ProgramData folder it may be hidden. To make the folder visible, in Windows File Explorer select Hidden items in the C:\ root directory (View tab > Hidden items).

Migrate the RSA keyfile to Server #2

Use the EncryptionKeyCLI.exe utility on Server #2 to extract the Robots Agent RSA key from the zip file and import it to the Microsoft keystore.

1. Copy RSAKeyfile.zip from Server #1 to the Robots Agent installation directory on Server #2.

   The default installation directory is: C:\Program Files (x86)\ACL Software\Robots Agent\agent

2. On Server #2, open the Windows command prompt as administrator.
3. Run the following command to change to the Robots Agent installation directory:

   cd C:\Program Files (x86)\ACL Software\Robots Agent\agent

   Specify the appropriate path if you did not install the Robots Agent in the default directory.

4. Run the following command to extract the Robots Agent RSA key from the zip file and import it to the Microsoft keystore on Server #2:

   EncryptionKeyCLI.exe import RSAKeyfile

   If you did not use RSAKeyfile as the name of the zip file, substitute the name that you used.

Copy the registration keyfile to Server #2

Copy the registration keyfile (registration.key) from the Robots Agent installation directory on Server #1 to the Robots Agent installation directory on Server #2.

The default installation directory is: C:\Program Files (x86)\ACL Software\Robots Agent\agent

Restart the Robots Agent service on Server #2

On Server #2, open the Windows Services manager and restart (or start) the Robots Agent service.

Check that the additional agent was successfully registered

In the Robots app, go to the Agent management screen and press F5 to reload the page. If the additional Robots Agent appears in the list with a status of Online, it was successfully registered. The agent is now part of the agent cluster used for analytic processing and load balancing.