Configure Desktop Automation Service

This chapter describes the Desktop Automation Service configuration. It consists of the following topics:

Prerequisites

All Desktop Automation Service requirements and prerequisites are listed in the "Dependencies and Prerequisites" chapter of the Kofax RPA Installation Guide.

The Desktop Automation Service relies on Windows UI Automation API. Do not run any UI Automation API clients on the same computer simultaneously with the Desktop Automation Service.

There is no hard-coded limit to the number of elements that the Desktop Automation Service can read in the automated application tree. The depth is limited by the stack thread size, while the total number of nodes is limited by the available memory. Use the Max Depth and Max Siblings settings in the Tree Modes setting to prevent any device issue errors and limit the number of elements to be loaded.

Configure the Desktop Automation Service

Once your computers meet all the necessary requirements, you can install and configure the Desktop Automation Service.

  1. If you need to automate Java applications, install Java JRE or JDK on remote devices and check that the Java Access Bridge is enabled on your devices. See Check Java Access Bridge for details.
  2. Download and run the Kofax RPA Desktop Automation Service installer on your device.
  3. Start the Desktop Automation Service from the Start menu. Once the service starts, you can see its status by looking at the icon in the notification area.

    Icon

    Status

    Device automation service is starting

    Desktop Automation Service is starting and trying to connect to the configured Management Console.

    Device automation service is running and it is not connected to a Management Console

    Desktop Automation Service is running and either connected to a Management Console or running in single user mode depending on configuration.

    Device automation service is running and connected to a Management Console

    Desktop Automation Service is running and in use by a RoboServer or Design Studio.

    Device automation service is not running

    Desktop Automation Service is not running.

    Device automation service error

    Desktop Automation Service is not running due to an error.

  4. To edit the Desktop Automation Service options, right-click the Desktop Automation Service icon in the notification area and select Configure. This opens the Desktop Automation Service window. After changing the options, click Save and Restart.

    To manually edit the options, open the server.conf file on your automation desktop. The file is located in Users > UserName > AppData > Local > Kofax RPA 11.3.0 folder where UserName is the name of the user the service is running under.

  5. Check that the device is registered in the Management Console under Admin > Devices tab.

The following is a Desktop Automation Service configuration window. Refer to the table later in this section for detailed information on the available Desktop Automation Service options.


Device automation service configuration dialog box

As soon as the Desktop Automation Service connects to the Management Console, the Management Console tests the connection to the Desktop Automation Service. If it is successful, the status "ready" is shown.

Configuration Window Option

server.conf Option

Value and Description

Single User

Select for direct connection to the automation desktop from Design Studio or when using the RDP connection.

"singleUser"

Cleared (default)

Leave empty to automatically register the Desktop Automation Service with the specified Management Console.

For direct connection to the automation desktop, select the option and specify a token.*

Host name

"hostName"

Name or local IP address of the computer running the Desktop Automation Service.

If a computer has multiple names or IP addresses, specify the one that RoboServers and Design Studio contact this Desktop Automation Service with. That is, the host name or IP address must be reachable from RoboServers and Design Studio.

Command port

"commandPort"

49998 (default)

If the Desktop Automation Service is started without being manually configured, it uses the default configuration and listens on the default 49998 port.

Reassign this port to the automation desktop if necessary.

Stream port

"streamPort"

49999 (default)

This port is used to send data between Design Studio and Desktop Automation Service. If set to "0", the Desktop Automation Service selects a random port number.

You might need to reassign the stream port if there is a firewall between Design Studio and the automation desktop.

CA file

"caFile"

Empty (default)

You can communicate with the Management Console using SSL. If the default certificate in node.js is not used, you can specify a path to another certificate file using this parameter. Note that you need to have a root certificate for this to work. To save a root certificate in a file from a Google Chrome browser, do the following:

  1. Right-click the lock icon in the address bar and click Certificate (valid).

  2. On the Certificate Path tab, select the top most (root) certificate and click View Certificate.

  3. On the Details tab, click Copy to File and then complete the wizard to export the root certificate as a base-64 encode X.509 certificate.

Now you can specify the path to the file with exported certificate.

Timeout

"commandTimeout"

This option specifies the timeout for command execution in seconds. A command is an instruction sent to automation desktop, such as click mouse button, open application, add a location found guard, and so forth. If a command cannot be completed in a specified time, the service sends a notification and execution of the robot stops.

Note that in case of a Guarded Choice step, this setting applies to invoking the guard in the workflow, but waiting for the guard to be satisfied is not bound to this timeout and can wait forever. Similar situation occurs when using the Move Mouse and Extract steps. The commands must be invoked on the device withing the timeout specified in this field, but the robot waits for up to 240 seconds for the commands to complete.

The command timeout for automating terminals or browsing websites in a Robot is set either on the Desktop Automation tab of the Design Studio Settings window for executing the workflow in Design Studio, or in the Automation Device section on the Security tab of the RoboServer Settings window for RoboServer execution.

Token on Single User tab

"token"

Empty (default)

If the Single User option is not selected, leave this option empty. If you use the direct connection to the automation desktop (Single User is selected), specify a token. It can be any token you define.

Certificates tab
Certificates tab of the Options dialog box

"tlsServerConfig"

Kofax RPA provides TLS communication between automation desktop and RoboServer or Design Studio. The communication uses certificates for encrypting the communication. The following is a server.conf file code extract. For more information see Use TLS Communication.

  "tlsServerConfig": {
    "key": "kofax.remote.das.pem",
    "cert": "kofax.remote.das.cert.pem",
    "ca": "./serverCa"
  },

Windows tab

"automationnative"

  • Use legacy Java-Access-Bridge

    In some situations, the Java Access Bridge does not work and it can help to switch to legacy mode. By default, the option is not selected.

  • Installed packages

    Lists Desktop Automation Service packages installed on this computer. Starting from version 10.7.0, new version packages are installed automatically if the Lock package option below is not selected. The packages in ZIP files are installed to C:\ProgramData\Kofax RPA on the automated computer. The appropriate package is selected automatically depending on the RoboServer version. If you want to specify only one version package to be used, select Lock package and select one of the installed packages.

  • Lock package

    When selected, you can choose a version package as the only one to work with. A RoboServer with a different version cannot connect to this service. By default, the option is not selected.

    Select this option or change the setting to true in the server.conf file to run robots with triggers.

  • Map RFS share to drive letter

    The Windows drive that the Robot File System file share is available in. When the file share is mapped to a Windows drive, other Windows applications can also access this file share.

OCR tab

"ocrConfig"

Specifies one or more languages and an engine to perform an OCR operation. You can choose from Tesseract (default) and OmniPage OCR engines. To use the OmniPage engine, select Use Kofax OmniPage OCR (only for packages version 11.1 or later) on the OCR tab. Specify OCR languages in the Enabled OCR languages field. For example, to use the Japanese language, either replace eng (default) with jpn or, if you want to use more than one language, add jpn using the plus sign, such as eng+jpn.

For Tesseract, Kofax RPA installs only the English language. See Change Default OCR Language for Robot below for language installation instructions.

System tab

This tab helps you open the log file to examine any errors and shows the version and location of the service file. Using this tab, you can check whether Java Access Bridge is properly installed on the computer where the service is running. See Check Java Access Bridge for details.

If you need to restart your computer frequently, but you cannot use the automatic login feature of Windows, click the Configure Screen Lock on Startup button to enable the Desktop Automation Service to automatically create a session and lock the screen after the computer is restarted.

After clicking the button:

  1. The system requests elevation. You may get an UAC elevation prompt. The elevation may require entering the credentials for another account that has administrative privileges.
  2. You must provide the credentials of the user account used to log in and create a session after a computer restart. The user field in the credentials dialog is pre-filled with the currently logged in user. Note that it is not necessarily the user account that is used for the elevation.
  3. A Task Scheduler, which will execute the Lock Screen a minute after the computer is (re)started, is created. This task is created under the folder Kofax/RPA.

To delete the lock on restart, go to the folder Kofax/RPA in the Task Scheduler and delete the task "Lock screen after boot."

Each time you change the user's account password, update it directly in the Task Scheduler or click the Configure Screen Lock on Startup again.

Management Console Options

MC Path

Connection protocol, name or IP address, port number, and path of the Management Console the device must register with. The format is as follows:

http://10.10.0.136:50080.

"hostName"

Name or IP address of the Management Console the device must register with.

"port"

Connection port of the specified Management Console.

"schema"

Connection protocol of the specified Management Console.

"path"

Empty (default)

The part of the path to the standalone Management Console after the port number. For example, if your Management Console is deployed on Tomcat at http://computer.domain.com:8080/ManagementConsole/, specify "/ManagementConsole/" in this parameter. Leave this parameter empty for the embedded Management Console installation.

User name

"user"

Empty (default)

User name to authenticate on the specified Management Console.

Password

"password"

Empty (default)

Password to authenticate on the specified Management Console.

Cluster

"cluster"

Production (default)

Cluster name on the specified Management Console.

Labels

"labels"

"label1,label2" (default)

Labels to distinguish the automation devices.

Ping interval (ms)

"pingInterval"

5000 (default)

Time interval for the Desktop Automation Service to ping the Management Console.

Use proxy to connect to Management Console

"useProxy"

Select this option for the Desktop Automation Service to use proxy when connecting to Management Console. All necessary parameters are specified in the following fields.


Parameters to use proxy to connect to Management Console

Under Linux, you can set up proxy parameters in the managementConsole section of the server.conf file.

    "useProxy": true,
    "proxyHostName": "proxyhost.com",
    "proxyPort": 9000,
    "proxyUserName": "username",
    "proxyPassword": "pwd"

* The direct connection to the automation desktop is recommended for creating and debugging a robot in Design Studio as well as for using with RDP connection.

Logging for Desktop Automation Service

Kofax RPA collects usage information on specific Desktop Automation Service events, which may be useful to improve the service performance.

  • If the Desktop Automation Service is connected to a Management Console, the events are stored in the RoboServer Log Database of the Management Console. To view the events, on the Log view page, select DAS messages.

    When the connection parameters for the Management Console are specified in the Desktop Automation Service configuration window, the events are always logged to the Management Console, even if the Single User mode is selected, that is, the connection to the automation desktop is established directly, without the Management Console.

  • If the Desktop Automation Service cannot connect to a Management Console (as Management Console is not configured), it writes the events to the Desktop Automation Service Usage.csv log file, which resides in: {path}\AppData\Local\Kofax RPA\<version number>\Logs\

    The file location can be configured in the log4net.xml file.

The information for each event includes:

  • Time that the event occurred (in UTC).
  • Type of event: start, stop, connect, disconnect, suspend or lock screen.

  • Identification of Desktop Automation Service, consisting of an ID in the form host:port, the user account running the service, and the labels defined for the service.

  • Name of the robot and the execution ID (only for connect and disconnect).

  • Severity indication (always "Info").

  • Message (always empty).

Configure Proxy Servers in Desktop Automation

All Desktop Automation Service robots can use the Kofax RPA global proxy settings. The Desktop Automation Service uses the same proxy settings as Design Studio and Management Console. There are two ways to configure proxy server settings.

The local proxy settings of the built-in browser in the Desktop Automation Service have a higher priority than the Kofax RPA global proxy settings configured in Design Studio > Design Studio Settings. Make sure that the robot uses the Kofax RPA global proxy settings, unless the task requires it to use local proxy settings.

Also, the cef.cfg file should not be used to configure proxy settings, but if it is used, it has a higher priority than all of the above proxy settings.

  1. For all robots running in the Desktop Automation Service, in the Design Studio Settings dialog box, on the Proxy Servers tab, complete the following Proxy Server details.

    • Host

    • Port number

    • User name

    • Password

    • Excluded host names

  2. For all deployed robots, on the Management Console > Admin > RoboServers > Cluster settings > "Proxy servers" tab, select New proxy and complete the following proxy server details.

    • Host name

    • Port number

    • User name

    • Password

    • Excluded host names

Check Java Access Bridge

Java Access Bridge is an essential component to automate your Java applications. Depending on the Java version, some necessary files may be missing in system folders and Java Access Bridge may be disabled on the computer where the Desktop Automation Service is installed. To check your Java Access Bridge installation, perform the following steps.

  1. Right-click the Desktop Automation icon in the notification area and select Configure.
  2. Click the System tab and click Check Java Access Bridge files.

    The Java Access Bridge dialog box opens showing installed Java versions and Java Access Bridge installation status for each version. If JAB Installed column, Java Access Bridge is installed into Windows system folders, and Java Access Bridge is enabled show YES, Java Access Bridge is properly installed and enabled on the computer.


    Java Access Bridge dialog box to check the proper installation of Java Access Bridge
  3. If your implementation of Java is not listed under Java Home Directories, click Add Folder and specify a home folder with installed Java files.

  4. If any of the files are missing, such as JAB Installed column shows NO, click Show Missing Files.

    The Java Access Bridge Missing Files dialog box shows files that must be copied to specified folders.

  5. If Java Access Bridge is enabled shows NO, click Enable Access Bridge.

Change Default OCR Language for Robot

Kofax RPA uses either the Tesseract or OmniPage OCR engines to capture text from images. For Tesseract, Kofax RPA installs only the English language, while OmniPage includes all supported languages in the installation. When your robot performs text recognition in the Extract Text From Image step, Kofax RPA uses the language selected on the OCR tab of the Desktop Automation Service window. To change the default language for OCR, perform the following steps.

  1. Right-click the Desktop Automation icon in the notification area and select Configure.
  2. Click the OCR tab and type the language code of the language you want to use for OCR in the Enabled OCR languages field. The language code must be in ISO 639-3 or ISO 639-1 format. To use more than one language, add another language using the plus sign, such as eng+jpn.

    Using more than one language simultaneously for screen recognition slows down robot execution and deteriorates recognition results.

  3. Click Save and Restart.

If you use Tesseract for text recognition of the language other than English, you must first download and copy necessary language packs as follows.

  1. Download the .traineddata file for the required language from the https://github.com/tesseract-ocr/tessdata. For example, the file for the French language is fra.traineddata.
  2. Copy the downloaded trained data file to Kofax RPA\<version>\lib\tessdata in the ProgramData folder. Example:

    C:\ProgramData\Kofax RPA\11.3.0.110\lib\tessdata

You can train Tesseract to recognize your character set using either TTF fonts or UI screen shots. See Train Tesseract for more information.

Activate the virtual input driver

Virtual input driver is a Windows device driver capable of simulating hardware keyboard and mouse. For the operating systems supported by the driver, see the Kofax RPA Technical Specifications document available on the Kofax RPA documentation site: https://docshield.kofax.com/Portal/Products/RPA/11.3.0_5cdzhlgb3t/RPA.htm. See the Kofax RPA Installation Guide for information on installing the driver.

The virtual input drivers do not function when the desktop of the automated computer is being locked, such as by the Lock Screen function or an RDP step.

To enable the virtual input driver for keyboard and mouse operations on the automated computer, set the environment variable KOFAX_RPA_VIRTUAL_INPUT to Y. To cancel the virtual input driver usage, set the environment variable to N.

Enable integration with SAP

To work with the SAP application in Robots, from the product installation files, download and save the RegSAPSurrogate.reg file on the computer running the Desktop Automation Service. Run it accepting any warnings and then restart the Desktop Automation Service agent. The file resides in the {path}\DesktopAutomationService\bin folder.