advertisement
Kofax RPA
Desktop Automation Service Configuration Guide
Version: 11.3.0
Date: 2022-03-23
© 2017–2022 Kofax. All rights reserved.
Kofax is a trademark of Kofax, Inc., registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in any form without the prior written permission of Kofax.
Table of Contents
3
Preface
This guide describes how to configure the Desktop Automation Service required to use Desktop
Automation on a remote computer.
Related Documentation
The documentation set for Kofax RPA is available here:
https://docshield.kofax.com/Portal/Products/RPA/11.3.0_5cdzhlgb3t/RPA.htm
In addition to this guide, the documentation set includes the following items:
Kofax RPA Release Notes
Contains late-breaking details and other information that is not available in your other Kofax RPA documentation.
Kofax RPA Technical Specifications
Contains information on supported operating systems and other system requirements.
Kofax RPA Installation Guide
Contains instructions on installing Kofax RPA and its components in a development environment.
Kofax RPA Upgrade Guide
Contains instructions on upgrading Kofax RPA and its components to a newer version.
Kofax RPA Administrator's Guide
Describes administrative and management tasks in Kofax RPA.
Kofax RPA Help
Describes how to use Kofax RPA. The Help is also available in PDF format and known as Kofax RPA
User's Guide .
1
You must be connected to the Internet to access the full documentation set online. For access without an Internet connection, see the Installation Guide .
4
Kofax RPA Desktop Automation Service Configuration Guide
Kofax RPA Best Practices Guide for Robot Lifecycle Management
Offers recommended methods and techniques to help you optimize performance and ensure success while using Robot Lifecycle Management in your Kofax RPA environment.
Kofax RPA Getting Started with Robot Building Guide
Provides a tutorial that walks you through the process of using Kofax RPA to build a robot.
Kofax RPA Getting Started with Document Transformation Guide
Provides a tutorial that explains how to use Document Transformation functionality in a Kofax RPA environment, including OCR, extraction, field formatting, and validation.
Kofax RPA Developer's Guide
Contains information on the API that is used to execute robots on RoboServer.
Kofax RPA Application Programming Interface documentation
Contains information about the Kofax RPA Java API and the Kofax RPA .NET API, which provide programmatic access to the Kofax RPA product. The Java API documentation is available from both the online and offline Kofax RPA documentation, while the .NET API documentation is available only offline.
The Kofax RPA APIs include extensive references to RoboSuite, the original product name. The
RoboSuite name is preserved in the APIs to ensure backward compatibility. In the context of the
API documentation, the term RoboSuite has the same meaning as Kofax RPA.
Training
Kofax offers both classroom and computer-based training to help you make the most of your Kofax
RPA solution. Visit the Kofax Education Portal at https://learn.kofax.com/ for details about the available training options and schedules.
Also, you can visit the Kofax Intelligent Automation SmartHub at https://smarthub.kofax.com/ to explore additional solutions, robots, connectors, and more.
Getting help with Kofax products
The Kofax Knowledge Base repository contains articles that are updated on a regular basis to keep you informed about Kofax products. We encourage you to use the Knowledge Base to obtain answers to your product questions.
To access the Kofax Knowledge Base:
1.
Go to the Kofax website home page and select Support .
2.
When the Support page appears, select Customer Support > Knowledge Base .
5
Kofax RPA Desktop Automation Service Configuration Guide
The Kofax Knowledge Base is optimized for use with Google Chrome, Mozilla Firefox or
Microsoft Edge.
The Kofax Knowledge Base provides:
• Powerful search capabilities to help you quickly locate the information you need.
Type your search terms or phrase into the Search box, and then click the search icon.
• Product information, configuration details and documentation, including release news.
Scroll through the Kofax Knowledge Base home page to locate a product family. Then click a product family name to view a list of related articles. Please note that some product families require a valid Kofax Portal login to view related articles.
From the Knowledge Base home page, you can:
• Access the Kofax Community (for all customers).
Click the Community link at the top of the page.
• Access the Kofax Customer Portal (for eligible customers).
Click the Support link at the top of the page. When the Customer & Partner Portals Overview appears, click Log in to the Customer Portal .
• Access the Kofax Partner Portal (for eligible partners).
Click the Support link at the top of the page. When the Customer & Partner Portals Overview appears, click Log in to the Partner Portal .
• Access Kofax support commitments, lifecycle policies, electronic fulfillment details, and selfservice tools.
Go to the General Support section, click Support Details , and then select the appropriate tab.
6
Chapter 1
Desktop Automation Service Configuration
This chapter describes Desktop Automation Service configuration. It consists of the following topics:
•
Desktop Automation Prerequisites
•
Configure the Desktop Automation Service
•
Logging for Desktop Automation Service
•
Configure Proxy Servers in Desktop Automation
•
•
Change Default OCR Language for Desktop Automation
•
Activate the virtual input driver
•
•
Desktop Automation Prerequisites
All Desktop Automation requirements and prerequisites are listed in the "Dependencies and
Prerequisites" chapter of the Kofax RPA Installation Guide.
Desktop Automation service relies on Windows UI Automation API. Do not run any UI
Automation API clients on the same computer simultaneously with Desktop Automation Agent.
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 for Desktop Automation, you can install and configure the Desktop Automation Agent.
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
details.
2.
Download and run the Kofax RPA Desktop Automation installer on your device.
7
Kofax RPA Desktop Automation Service Configuration Guide
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
Desktop Automation Service is starting and trying to connect to the configured Management
Console.
Desktop Automation Service is running and either connected to a Management Console or running in single user mode depending on configuration.
Desktop Automation Service is running and in use by RoboServer or Design Studio.
Desktop Automation Service is not running.
Desktop Automation Service is not running due to an error.
4.
To edit the Desktop Automation Service parameters, right-click the Desktop Automation
Service icon in the notification area and click Configure . This action 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 the Admin > Devices section.
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 Agent options.
8
Kofax RPA Desktop Automation Service Configuration Guide
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
Single User
Select for direct connection to the automation desktop from Design
Studio or when using the RDP connection.
server.conf Option
"singleUser"
Value and Description
Cleared (default)
Leave empty to automatically register the
Desktop Automation Agent with the specified
Management Console.
For direct connection to the automation desktop, select the option and specify a token.*
9
Kofax RPA Desktop Automation Service Configuration Guide
Configuration Window Option
Host Name
Command port
Stream port
CA file server.conf Option
"hostName"
"commandPort"
"streamPort"
"caFile"
Value and Description
Name or local IP address of the computer running the Desktop Automation Agent.
If a computer has multiple names or IP addresses, specify the one that RoboServers and Design Studio contact this Desktop
Automation Agent with. That is, the host name or IP address must be reachable from
RoboServers and Design Studio.
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.
49999 (default)
This port is used to send data between
Design Studio and the Desktop Automation
Agent. If set to "0", the Desktop Automation
Agent selects a random port number.
You might need to assign the stream port if there is a firewall between Design Studio and the automation desktop.
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.
10
Kofax RPA Desktop Automation Service Configuration Guide
Configuration Window Option timeout
Token on Single User tab server.conf Option Value and Description
"commandTimeout" This option specifies the timeout for command execution in seconds. A command is an instruction sent to the 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. A similar situation occurs when using the Move Mouse and Extract steps. The commands must be invoked on the device with 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 Robots 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" Empty (default)
If the Single User option is set selected, leave this option empty. If you use the direct connection to the automation desktop (Single
User is not selected), specify a token. It can be any token you define.
11
Kofax RPA Desktop Automation Service Configuration Guide
Configuration Window Option
Certificates tab
Windows tab server.conf Option
"tlsServerConfig"
"automationnative"
Value and Description
Kofax RPA provides TLS communication between the automation desktop and the 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" in the Kofax RPA Help.
"tlsServerConfig": {
"key": "kofax.remote.das.pem",
"cert":
"kofax.remote.das.cert.pem",
"ca": "./serverCa"
},
• 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.
12
Kofax RPA Desktop Automation Service Configuration Guide
Configuration Window Option
OCR server.conf Option
"ocrConfig"
Value and Description
Specifies one or more languages and an engine to perform an OCR operation on the automated desktop. 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, if you want 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
Language for Desktop Automation
below for language installation instructions.
13
Kofax RPA Desktop Automation Service Configuration Guide
Configuration Window Option
System tab server.conf Option Value and Description
This tab helps you open and examine the log file for any errors, or to view 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
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 prefilled 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
14
Kofax RPA Desktop Automation Service Configuration Guide
Configuration Window Option
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 .
server.conf Option
"hostName"
"port"
"schema"
"path"
User Name
Password
Cluster
Labels
Ping interval (ms)
"user"
"password"
"cluster"
"labels"
"pingInterval"
Value and Description
Name or IP address of the Management
Console the device must register with.
Connection port of the specified Management
Console.
Connection protocol of the specified
Management Console.
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.
Empty (default)
User name to authenticate on the specified
Management Console.
Empty (default)
Password to authenticate on the specified
Management Console.
Production (default)
Cluster name on the specified Management
Console.
"label1,label2" (default)
Labels to distinguish the automation devices.
5000 (default)
Time interval for the Desktop Automation
Service to ping the Management Console.
15
Kofax RPA Desktop Automation Service Configuration Guide
Configuration Window Option
Use proxy to connect to
Management Console server.conf Option
"useProxy"
Value and Description
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.
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 only for creating and debugging a robot in Design Studio as well as for using with an RDP connection. See "Use RDP
Connection" in Kofax RPA Help.
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).
16
Kofax RPA Desktop Automation Service Configuration Guide
• 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. For more information, see Kofax RPA Help .
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
• Username
• Password
• Excluded hosts
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 .
17
Kofax RPA Desktop Automation Service Configuration Guide
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.
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 Desktop Automation
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 using Desktop Automation Service, the service 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 .
18
Kofax RPA Desktop Automation Service Configuration Guide
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.
• 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
.
• Copy the downloaded trained data file to Kofax RPA\<version>\lib\tessdata in the
ProgramData folder. Example:
C:\ProgramData\Kofax RPA\11.3.0.0.110\lib\tessdata
You can train Tesseract to recognize your character set using either TTF fonts or UI screen shots.
See the Train Tesseract topic in Kofax RPA Help for more information.
Activate the virtual input driver
Virtual input driver is a Windows device driver capable of simulating a hardware keyboard.
For the operating systems supported by the driver, see the Kofax RPA Technical Specifications document available on the 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 use the driver, set the environment variable " KAPOW_KEYBOARD_INPUT_METHOD " to
" VIRTUAL_KEYBOARD " on the automated device. To cancel the virtual input driver usage, remove the environment variable.
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.
Manage Remote Desktop
You can perform the following actions using the Desktop Automation Service shortcut menu.
19
Kofax RPA Desktop Automation Service Configuration Guide
Manage the Desktop Automation Service
The following commands help you manage the Desktop Automation Service running on a remote computer.
• Stop DA service : Stops the service, which makes the remote device unavailable. The computer running the Desktop Automation Service is removed from the list in the Management Console.
• Restart DA service : Stops and starts the service. A robot or Design Studio loses the connection to the device and must be reloaded to restore it.
• Suspend DA service : Suspends the device. If suspended, the service is displayed as suspended in the Management Console. To restore the service operation, a user or an administrator needs to manually start the Desktop Automation Service on the device.
The suspended state makes the DA service unavailable for robots to use, but the state information is send to the Management Console via the ping mechanism and the devices is displayed in the Admin > Devices section. This command is useful if for some reason the service or the computer running it needs some configuration changes.
• Lock Screen : Locks the screen on the remote device.
• Configure : Opens the Desktop Automation Service configuration dialog box.
20
advertisement