Configuring an on-premise Robots Agent

The default configuration of the Robots Agent is set during installation. Before using the Robots Agent, review the configuration settings and make sure they are appropriate for your organization. In particular, make sure that Permitted file uploads is set appropriately.

Note

The information in this topic applies only to organizations that use an on-premise Robots Agent to run ACL scripts in ACL robots.

Individuals and organizations with ACL Robotics Professional Edition do not have an on-premise Robots Agent. Python/HCL scripts that run in HighBond robots or Workflow robots do not use the Robots Agent.

Where to specify configuration settings

You specify Robots Agent configuration settings in two locations:

  • the Agent management screen in Robots
  • the Agent.exe.config file in the Robots Agent installation directory on the Windows server

Note

Configuration settings in the Agent management screen take precedence over settings in the Agent.exe.config file.

Configure settings in the Agent management screen

Note

Configuration settings in the Agent management screen apply to all agents in a multi-agent cluster.

  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. Under Configuration, select the appropriate option for Permitted file uploads.

    Permitted file uploads controls which output results are uploaded from the Robots Agent to the Robots app in the cloud:

    • Result files and logs only

      If specified in an analytic header, result files (such as Excel) and logs are uploaded. You can also manually upload related files to the Robots Input/Output tab.

    • Result tables, files, and logs

      If specified in an analytic header, Analytics result tables, result files (such as Excel), and logs are uploaded. You can also manually upload related files to the Robots Input/Output tab.

    • File uploads not permitted

      No files of any kind can be uploaded by scripts or manually by users. Analytic scripts with //RESULT FILE or //RESULT LOG tags will not run.

  6. Under Configuration, specify the appropriate directories for Paths configuration and click Save.
    • Data storage

      The Windows server or network directory for permanent storage of Analytics data tables output by analytic scripts with a //DATA tag.

      A separate directory for data tables allows you to specify a more economical, cold storage location for large files that are accessed only periodically.

    • Results path

      The Windows server or network directory for Analytics result tables output by analytic scripts with a //RESULT TABLE tag.

    Important

    The directory or directories that you specify under Configuration must be accessible to the Robots Agent, or to all agents if you are using a multi-agent cluster. For each specified directory, the service account running the agent must have Read/Write/List permissions. For more information, see On-premise Robots Agent security.

Configure settings in the Agent.exe.config file

To update configuration settings, edit the Agent.exe.config file in the Robots Agent installation directory and then restart the Robots Agent Windows service.

The default location of the configuration file is:

C:\Program Files (x86)\ACL Software\Robots Agent\agent\Agent.exe.config.

Note

You must restart the Robots Agent service for any changes to take effect.

For multi-agent installations, you must update the Agent.exe.config file, and restart the Robots Agent service, on each Windows server. Configuration settings for each agent can be identical or they can differ, depending on your particular needs.

Configuration properties in Agent.exe.config

Key Value
RuntimeBasePath

The base folder for:

  • temporary analytic job folders

  • non-Analytics result files output by analytic scripts with a //RESULT FILE tag

  • Analytics log files output by analytic scripts with a //RESULT LOG tag

  • Analytics log files output by failed analytic scripts

The default base folder is C:\acl\robots\data\

A separate runtime base folder allows you to locate analytic job processing on a faster, high-performance device such as a solid state drive (SSD).

Example of a full path to an analytic job folder with a user-configured base folder: E:\acl\robots\runtime\Production\Robot12\Task1\Run29\Temp
DataBasePath

The base folder for permanent storage of Analytics data tables output by analytic scripts with a //DATA tag.

The default base folder is C:\acl\robots\data\

A separate base folder for Analytics data tables allows you to specify a more economical, cold storage location for large files that are accessed only periodically.

Example of a full path to a data files folder with a user-configured base folder: D:\acl\robots\data\Production\Robot12\Data

Note

The DataBasePath value is not used if a different value appears in the Data storage configuration setting in the Agent management screen in Robots.

For more information, see Configure settings in the Agent management screen.
ResultsBasePath

The base folder for Analytics result tables output by analytic scripts with a //RESULT TABLE tag.

The default base folder is C:\acl\robots\data\

Example of a full path to a results folder with a user-configured base folder: C:\acl\robots\results\Production\Robot12\Task1\Run29\Results\Prohibited transactions

Note

The ResultsBasePath value is not used if a different value appears in the Results path configuration setting in the Agent management screen in Robots.

For more information, see Configure settings in the Agent management screen.
AclSEProfileBase

The base folder for working with tables when connecting from Analytics to the Robots Agent using the Robots Data Service.

The default base folder is C:\acl\robots\aclse\
LogFile

The file path and name of the Robots Agent log file.

The default path and name is C:\acl\robots\logs\application.log
EnginePath

The file path of the executable file that runs tasks.

The default location is C:\Program Files (x86)\ACL Software\Robots Agent\AclScript.exe
KeepJobFolder

Specifies whether the temporary analytic job folder is retained when a robot task fails.

  • true the temporary analytic job folder is retained after task failure

  • false the temporary analytic job folder is deleted after task failure

    The default value is false.

Note

The KeepJobFolder setting has no effect when a robot task succeeds. After successful execution of a task, the temporary analytic job folder is automatically deleted.

Caution

You can set the value to true to retain files for troubleshooting purposes. Leaving the value set to true permanently may cause the server hard drive, or a solid state drive, to run out of space.
AllowExecuteCommand

Specifies how the Robots Agent handles the EXECUTE command when encountered in an analytic script:

  • true the EXECUTE command is processed

  • false the EXECUTE command is not processed and the script containing the command fails

    The default value is false.

    A message is written to the log, explaining the reason for the failure.
MaxLogSizeKB

The maximum size of the Robots Agent log file before the file is archived and a new log file is created.

The default value is 102400 (100 MB).

The current log file is application.log. Archived log files are saved in the same folder as the current log file and given an incrementing numeric suffix: application.0.log, application.1.log, and so on.
SkipPathAccessCheck

Controls which folders the Robots Agent can access when reading or writing tables or files.

  • true Folder access is not checked. Scripts run by the Robots Agent can read or write tables or files in any ACL robot.

  • false Folder access is checked. Scripts run by the Robots Agent can only read or write tables or files in the same robot as the script.

    The default value is false.

Setting the value to true, and skipping the folder access check, may improve the performance of the Robots Agent when it runs scripts in some environments. You also have the ability to perform read or write operations across robots.

Caution

Restricting which folders a script can access is a Robots security feature that prevents accidental or intentional data access violations. Set the value to true only if you are sure that allowing ACL scripts to read or write tables or files in any ACL robot does not pose a security risk.

Note

The SkipPathAccessCheck setting has no effect on the ability to share and link specific Analytics data tables between robots. For more information, see Sharing and linking data tables in ACL robots.

Configure the Robots Agent to work with a specific proxy server

You can manually configure the Robots Agent to connect to the Robots app using a proxy server that you designate. To perform the manual configuration you need to do the following:

  • Add an additional section to the Agent.exe.config file

  • Update two additional configuration files, AgentService.exe.config and Worker.exe.config

Steps

  1. On the server where the Robots Agent is installed, go to the Robots Agent installation directory.

    The default location of the installation directory is:

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

  2. Refer to the table below to update the configuration files in the \agent subfolder.

  3. After you have saved all the files, restart the Robots Agent Windows service to begin communication between the Robots Agent and the Robots app using your designated proxy server.

Note

Different proxy server configuration settings are possible. The example configuration information below may not exactly match your requirements. For more information, consult Microsoft technical documentation:

File name Configuration information
Agent.exe.config

Update this file by adding the <system.net> section in the location shown in the example.

  • Substitute the appropriate proxy server address and port for your organization.

  • useDefaultCredentials="true" specifies that the credentials for the account that runs the Robots Agent Windows service are used to access the proxy server.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <appSettings>
        <other configuration settings>
    </appSettings>
    <system.net>
        <defaultProxy useDefaultCredentials="true">
            <proxy proxyaddress="YOUR PROXY SERVER ADDRESS:YOUR PORT" bypassonlocal="true" />
        </defaultProxy>
    </system.net>
</configuration>

AgentService.exe.config

Worker.exe.config

In both of these files, update the <defaultProxy> section based on the example shown below.

  • Substitute the appropriate proxy server address and port for your organization.

  • useDefaultCredentials="true" specifies that the credentials for the account that runs the Robots Agent Windows service are used to access the proxy server.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <system.net>
        <defaultProxy useDefaultCredentials="true">
            <proxy proxyaddress="YOUR PROXY SERVER ADDRESS:YOUR PORT" bypassonlocal="true" />
        </defaultProxy>
    </system.net>
</configuration>