advertisement
Kofax RPA
Administrator's Guide
Version: 11.4.0
Date: 2022-11-18
© 2015–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
Start and Enter License in Embedded Management Console........................................... 17
3
Kofax RPA Administrator's Guide
Run on Docker Swarm with Management Console in High Availability........................... 57
4
Kofax RPA Administrator's Guide
5
Preface
This guide is intended for system administrators who deploy Kofax RPA in the enterprise environment.
If you are running one of the previous versions of Kofax RPA, see the Kofax RPA Upgrade Guide for upgrade procedures.
The guide includes administration information for Kofax RPA including:
•
•
•
Audit Log for Management Console
•
SQL Scripts for Kofax RPA Tables
Related Documentation
The documentation set for Kofax RPA is available here:
https://docshield.kofax.com/Portal/Products/RPA/11.4.0-vcsft2fhaw/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.
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 .
6
Kofax RPA Administrator's Guide
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 .
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 Desktop Automation Service Configuration Guide
Describes how to configure the Desktop Automation Service required to use Desktop Automation on a remote computer.
Kofax RPA Developer's Guide
Contains information on the API that is used to execute robots on RoboServer.
Kofax RPA Integration API 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.
System Requirements
For information on supported operating systems and other system requirements, see the Kofax
RPA Technical Specifications document on the Kofax RPA Product Documentation site: https:// docshield.kofax.com/Portal/Products/RPA/11.4.0-vcsft2fhaw/RPA.htm
.
7
Kofax RPA Administrator's Guide
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 .
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.
8
Chapter 1
Runtime
Kofax RPA offers a number of tools for executing robots you have developed. The following sections describe these tools:
• RoboServer is a server application that enables remote clients to execute robots. It is configured using both the Management Console and the RoboServer Settings application (for advanced configuration, such as security and authentication).
• Management Console helps you to schedule execution of robots, view logs and extracted data. It also provides a centralized place where settings for clusters of RoboServers can be configured.
After changing the configuration settings for any Kofax RPA component, restart the respective component for the changes to take effect.
Timezone definitions are embedded in the bundled JRE. In case there are changes to the definitions since the release date, the JRE can be updated using the Timezone Updater Tool provided by Oracle. Refer to the Oracle website for further information.
RoboServer
RoboServer runs robots created in Design Studio. Robots can be started in various ways; either scheduled to run at specific times by a Management Console, called via a REST web service, through the Java or .NET APIs or from a Kapplet.
9
Kofax RPA Administrator's Guide
The minimal Linux installation must include the following packages to be able to run Robots created with Default browser engine.
• libX11.so.6
• libGL.so.1
• libXext.so.6
Use yum install or sudo apt-get command to install necessary libraries on a Linux platform.
Also, make sure that the system has all the fonts installed for the Webkit robots to run. This might be necessary in case a headless Linux install is used, because some of the Linux installation packages do not contain fonts.
To install the fonts, see the instructions below:
• Instructions for installing fonts for CentOS / RedHat
• Instructions for installing fonts for Ubuntu
To be able to execute robot, RoboServer must be activated by a Management Console. A
RoboServer is active when it belongs to a cluster in a Management Console with a valid license, and sufficient KCUs have been assigned to the cluster. A RoboServer also receives settings from the
Management Console where they are configured on the clusters. See the Management Console chapter in Kofax RPA Help for more information on the administration of RoboServers and clusters.
In Kofax RPA version 11.2.0 and later, RoboServer writes logs in UTC time. By default,
RoboServers version prior to 11.2.0 write logs in local server time, which can lead to inconsistences in timestamps if both 11.2.0 (or later) and earlier versions of RoboServer log to the same logging database. If you connect RoboServers version prior to 11.2.0 to a Management
Console version 11.2.0 or later, you can configure them to write log messages in UTC time instead of local server time by uncommenting the following option in the RoboServer.conf
file: wrapper_java_additional.41=-DwriteLogdbUtc=true
Note that RoboServer must be updated to a fix pack version that supports this parameter. See the corresponding fix pack ReadMe file for details.
Start RoboServer
A RoboServer can be started in several different ways:
• By clicking the RoboServer program icon (or the Start Management Console program icon from the Start menu that starts both Management Console and RoboServer).
• By invoking it from the command line.
• By running it as a service. See
To invoke a RoboServer from the command line, open a Command Prompt window, navigate to the bin folder in the Kofax RPA installation folder and type:
RoboServer
10
Kofax RPA Administrator's Guide
If all necessary parameters are specified in the roboserver.settings
RoboServer starts.
If any of the necessary parameters is missing, the RoboServer produces an error and displays the usage help and available parameters.
RoboServer Parameters
The command line for starting a RoboServer may include the following parameters:
RoboServer [-s <service:params>] [-mcUrl <url>] [-cl <Cluster Name>]
[-b <url>] [-p <port number>] [-sslPort <port number>] [-v]
Regardless of how you start a RoboServer, it accepts the parameters in the following table. Note
for more details.
Parameter
-mcUrl <arg>
Description
This required parameter specifies which Management
Console to register to in the following format: http[s]://<username>:<password>@<hostname>:<port number>
Example: -mcUrl http:// admin:password@myserver:8080/ManagementConsole
When using Document Transformation step with a Callback option in a robot, use the RoboServer host name or IP address in the -mcUrl parameter. Do not use 'localhost', because the Document Transformation
Service will not be able to reach the Management
Console, and the callback robot will not be queued.
-cl
--cluster <arg>
-eh
--externalHost <port number>
This required parameter automatically registers a RoboServer with the specified cluster on the Management Console. In the following example the RoboServer registers itself with the
Production cluster.
Example: -cl Production
Example: -mcUrl http:// admin:password@myserver:8080/ManagementConsole cl Production
Explicitly specifies the name or IP address of the RoboServer host.
This parameter should be specified when the host address is different from what a RoboServer discovers on the local machine, such as when running with NAT in the cloud, or when you run the RoboServer in a Docker container.
Example: -eh 10.10.0.123
11
Kofax RPA Administrator's Guide
Parameter
-ep
--externalPort <port number>
-jmxPass
-v
--verbose
-V
--version
-h
--help
-pauseAfterStartupError
-s
--service <service-name:serviceparameter>
-p
--port <port number>
-sslPort <port number>
-nd
--NoDoc
-sn
--serverName
-ll
--licenseLimit <arg>
--service socket:<portNumber>
--service ssl:<portNumber>
Description
Explicitly specifies the port number of the RoboServer host.
This parameter should be specified when the host port is different from what a RoboServer discovers on the local computer, such as when running with NAT in the cloud, or when you run the RoboServer in a Docker container.
Sets the JMX password if you monitor a RoboServer with JMX application and require a password.
This optional parameter causes a RoboServer to output status and runtime events.
This optional parameter causes a RoboServer to output the version number, and then exit.
Displays help.
Pauses if an error occurred at startup.
This parameter specifies a RQL or JMX service that
RoboServer should start. This parameter must be specified at least once, and may be specified multiple times to start multiple services in the same RoboServer. The available services depend on your installation.
Example: --service socket:50000
Example: --service jmx:50100
See "Available services" in the table below for more information.
This is shorthand for calling -s socket:<port number>
Example: --port 50000
This is a shorthand for writing -s ssl:<port number>
This optional parameter disallows robot documentation requests to this RoboServer.
This optional parameter sets the server name for logging
RoboServer statistics, which is later displayed in Kofax
Analytics for RPA. If you do not specify the server name, the statistics is collected based on the server IP address.
This parameter specifies the maximum number of license units that a RoboServer may receive.
Available services
<portNumber> : The port number for the socket-service to monitor.
<portNumber> : The port number for the socket-service to monitor.
12
Kofax RPA Administrator's Guide
Parameter
--service jmx:<jmx_port_Number>,<jmx_rmi_url>
Description
<jmx_port_Number> : The port number for the JMX service to monitor.
<jmx_rmi_url> : Optional RMI host and port for the JMX service. Use if you need to connect through a firewall.
Example: --service jmx:example.com:51001
To set passwords, use either the RoboServer Settings utility or the ConfigureRS tool. For more information, see
RoboServer Configuration - Headless Mode
.
Starting from Kofax RPA version 10, all RoboServers must auto register to the Management
Console. Therefore, the URL and credentials for the Management Console along with the cluster name must be specified when starting a RoboServer (either at the command line as in the following example or using the
application on the General tab under Register to a Management Console option).
RoboServer.exe -mcUrl http://username:password@myserver:8080/
ManagementConsole -cluster Production -service socket:50000
Default user name and password are admin:admin .
Start Servers Automatically
If your installation includes any server functionality, you can configure it to start the servers automatically.
When referring to "server functionality," RoboServer and Management Console (license server) are meant. In fact, these two functionalities are provided by the same server program, RoboServer, depending on the arguments supplied to it when it starts.
The RoboServer Parameters section contains a detailed description of the command-line arguments
for the RoboServer program. To enable the RoboServer program to execute robots, specify the service argument. Similarly, the -MC argument enables the Management Console functionality
(see Management Console (License Server) in the Installation Guide ).
For information about starting RoboServer and other RPA components as services, see
Shut Down RoboServer
RoboServer can be shut down using the following command line tool. Run ShutDownRoboServer without arguments to see the various options for how to shut down the server, particularly how to handle any robots currently running on the server.
Production Configuration
RoboServer runs robots created with Design Studio. Robots can be started in various ways; either scheduled to run at specific times by the Management Console, called via a REST web service, through the Java or .NET APIs or from a Kapplet.
13
Kofax RPA Administrator's Guide
In order to get a stable and performing production environment, you may have to tweak some of the default RoboServer parameters. We will look at the following configuration options:
• Number of RoboServer instances
• Number of concurrent robots
• Memory allocation
• Automatic memory overload detection
Number of RoboServer instances
RoboServer runs on Oracle's Java Virtual Machine (JVM), which in turn runs on top of an operating system (OS), which runs on top of your hardware. JVM's and OS's are patched, hardware architecture changes, and each new iteration aims to bring better performance. Although we can give some general guidelines about performance, the only way to make sure you have the optimal configuration is to test it.
As a general rule you get a little more performance by starting two instances of RoboServer. The
JVM uses memory management known as garbage collection (GC). On most hardware, only a single
CPU core is active during GC, which leaves 75% of the CPU idle on a quad-core CPU. If you start two instances of RoboServer, one instance can still use the full CPU while the other in running GC.
However, note that the garbage collector CPU usage depends on the JDK specification that your environment operates on, so multiple CPU cores can be using during the GC process.
Number of concurrent robots
The amount of concurrent robots a RoboServer can run depends on the amount of CPU available, and how fast you can get the data RoboServer needs to process. The number of concurrent robots is configured in the Management Console cluster settings. A robot running against a slow website will use a lot less CPU than a robot running against a website with a fast response time, and here is why. The amount of CPU used by a program can be described with the following formula
CPU (core)% = 1 - WaitTime/TotalTime
If a robot takes 20 seconds to execute, but 15 seconds are spent waiting for the website, it is only executing for 5 seconds, thus during the 20 seconds it is using an average of 25% (of a CPU core).
The steps in a robot are executed in sequence, which means that a single executing robot utilizes only one CPU core at a time. Most modern CPUs have multiple cores, so a robot that executes in 20 seconds, but waits for 15 seconds, in fact only uses about 6% of a quad-core CPU.
By default RoboServer is configured to run 20 robots concurrently. The number of concurrent robots is configured in the Management Console cluster settings. If all your robots use 6% CPU, the CPU is fully utilized when you are running 16-17 robots concurrently. If you start 33 of these 6% robots concurrently, you overload RoboServer; because the amount of CPU available is constant, the result is that each robot takes twice as long to finish. In the real world the CPU utilization of a robot may be anywhere between 5-95% of a CPU core, depending on robot logic and the website it interacts with. As a result it is hard to guess or calculate the correct value for the max concurrent robots. The only way to be sure you have the right value is to do a load test and monitor the
RoboServer CPU utilization, as well as the robot runtime as load increases.
Memory allocation
Another parameter that may affect the number of concurrent robots each RoboServer can handle is the amount of memory. The amount of memory used by robots can vary from a few megabytes
(MB) to hundreds of MB. By default, RoboServer is configured to use 2048 MB for a 64-bit system.
Check
Change the RAM Allocation to see how to control memory allocation. To avoid getting an out
of memory error, provide enough memory to a RoboServer. To ensure proper memory allocation,
14
Kofax RPA Administrator's Guide monitor memory utilization during your load tests. The JVM does not allocate all of the available memory, but it reserves it from the OS. Once the JVM starts to use the memory, it is not given back to the OS. To find the optimal memory allocation, run a series of load tests that push the CPU to
100%. After each test is complete, check how much of the reserved memory was actually used by the JVM (the java.exe process). If all 2048MB (default) were used, increase (usually double) the memory and run the test again. At some point the JVM does not use all of the reserved memory, and the number of the used memory reflects the actual memory requirement and should be specified for the RoboServer.
Memory overload detection
Since RoboServer stops working if it runs out of memory, RoboServer tries to prevent memory overload. Before a RoboServer starts a new robot, it checks the memory utilization. If it is above
80%, it queues the robot instead of starting it; this greatly reduces the risk of crashing a RoboServer if the memory allocation is configured incorrectly. This mechanism is often referred to as the 80% memory threshold. Once memory usage drops below 80%, the RoboServer continues to start new robots. When a RoboServer stops starting new robots, it records the following line in the log:
"RoboServer is using " + memoryUsagePercentage + " percent of the available memory and will queue all new robot executions. " +
This usually happens if you run too many concurrent robots on the server.
When a robot starts after memory usage drops below 80%, a RoboServer logs the following message: robotLogger.logServerInfo("Normal memory usage", "The memory usage is below the threshold again and robot executions will no longer be queued queued.")
Kofax does not recommend changing Kapow.memoryThreshold
parameter, because a
RoboServer may become unstable. Before changing it, try the following:
• Decrease the number of concurrent robots (see "Number of concurrent robots" above).
• Increase the available memory (see "Memory allocation" above).
Change the Kapow.memoryThreshold
parameter only if it is required. For example, if a
RoboServer is at 79% of memory utilization and one of your robot uses 22% or more of the allocated memory, the RoboServer will crash when trying to run such a robot. In this case you can decrease the threshold value to 70% to avoid errors. The threshold value is configured in the Kapow.memoryThreshold
property in the roboserver.conf
file. To change the value to
70%, open the roboserver.conf
file in a text editor, insert the following line, and restart the
RoboServer.
wrapper.java.additional.1=-Dkapow.memoryThreshold=70
The number after wrapper.java.additional
is a counter, therefore adjust it if you have other additional settings in the file.
RoboServer Configuration
You can configure RoboServer through the RoboServer Settings application that can be started from the Windows Start menu.
15
Kofax RPA Administrator's Guide
Settings Main Window
Using this application, you can configure the following:
• General: Socket service options, Management Console connection options including the admin superuser name and password, RoboServer host settings, number of license units, and the
Verbose option.
• Security: Security settings such as authentication and permissions.
• Certificates: The use of certificates
.
• Project: The location of the default project
.
• JMX Server:
.
• Management Console: embedded Management Console configuration
.
After changing any of the settings, click OK to store the new settings, and then restart RoboServers that are running for the changes to take effect.
Starting from Kofax RPA version 10, all RoboServers must auto register to the Management
Console. Therefore, the URL and credentials for the Management Console along with the cluster
name must be specified when starting the RoboServer (either at the command line
or using the
RoboServer Settings application).
16
Kofax RPA Administrator's Guide
The name or IP address and the port number of the RoboServer host should be specified when those parameters are different from what a RoboServer discovers on the local computer, such as when running with NAT in the cloud, or when you run the RoboServer in a Docker container.
Kofax RPA contains several command-line tools to help you modify the settings in batch mode. For
example, you can create several users with specified permissions. See RoboServer Configuration -
for details.
If you need to change the maximum amount of RAM that RoboServer can use, see
Start and Enter License in Embedded Management Console
Before you can enter license information into Management Console, you need to start it. If you use
an embedded Management Console, start it as follows. See Tomcat Deployment for information
about Tomcat Management Console.
Before starting a Management Console, perform the following:
1.
Start the
RoboServer Settings application from the Start menu.
2.
On the General tab, select Register to a Management Console , and supply all necessary information including the admin superuser name and password to connect to the
Management Console. The default admin superuser name and password:
• User name: admin
• Password: admin
Windows
Use the Start Management Console item on the Start menu.
To start the Management Console from the command line, run the following command in the bin subfolder of the installation folder.
RoboServer.exe -p 50000 -MC
You can also use the command line to start a RoboServer and register it to a Management Console:
RoboServer.exe -p 50000 -mcUrl http://username:password@ServerName:port -cl
"Production" command starts a RoboServer on port 50000 and registers it to the Management
Console at ServerName:port under the Production cluster with the specified user name and password.
Linux
Start Management Console from the command line. It is part of the RoboServer program, which is found in the bin directory under the installation directory.
$./RoboServer -p 50000 -MC
Auto-start
As an alternative, if you later set up auto-start of the Management Console as described in Start
, you may select to do that now instead of starting Management Console manually.
Once the Management Console is started, open it in a browser. On Windows, click the Management
Console item on the Start menu. On all platforms, you can open a browser and go to http:// localhost:50080/ . Login to the Management Console using the default admin user credentials,
17
Kofax RPA Administrator's Guide accept the license terms and enter your license information, including your license keys. If you need to change the license information later, you can do so in Admin > License .
Embedded Management Console Configuration
The settings are available on the Management Console tab of the RoboServer Settings application.
RoboServer contains an embedded web server which runs the Management Console. The web server is part of RoboServer, but is activated only when a RoboServer is started with the -MC option.
By default, the web server interacts with port 50080, and thus the Management Console web interface is available on: http://host:50080/
Protocols and Ports
You can configure the web server to be accessible through HTTP and HTTPS on separate ports. If a protocol is enabled, a port number must be chosen; the defaults are port 50080 (HTTP) and port
50443 (HTTPS).
To enable HTTPS, a server certificate in JKS format must be stored in a file called webserver.keystore
in the Certificates/Web folder, which resides in C:Users
\[User]\AppData\Local\Kofax RPA\[version] . If a certificate password other than the default
( changeit ) must be used, enter it in the Certificate Password field.
You can also restrict who is allowed to upload JDBC driver to the embedded Management Console
(for more information, see "Database drivers" in Kofax RPA Help) . Possible choices are " Not
Allowed ", where no one can upload JDBC drivers, "Admin from localhost," which means that the admin user can upload drivers when accessing the Management Console from the local computer; and finally, "Admin from any host," which means the admin user can always upload JDBC drivers.
User Management
Management Console can be accessed not only from the same computer (localhost), but also from others. One of the points of having a Management Console is that it coordinates execution of robots, and thus it typically must be accessible to many clients.
To mitigate the potential security risk of having access to the Management Console from other computers, user management is enabled by default in embedded mode and the default admin superuser password is available (user name - admin , password - admin ). You must use these credentials for registering a RoboServer to a Management Console, when you publish a robot to the
Management Console from Design Studio, and when you access the web interface from a browser.
See Predefined User Roles for more information.
Security
On the RoboServer settings Security tab, you specify RoboServer TLS configuration, general security restrictions, whether authentication is required for accessing the RoboServer, and audit logging preferences.
18
Kofax RPA Administrator's Guide
Allow File System and Command Line Access
Enables RoboServer to create and edit files on the computer where RoboServer runs.
When using embedded Derby database, robots can create and edit files on computers when this option is not selected. We recommend using MySQL or another enterprise-class database in your network environment.
Allow the use of Connectors
When running on RoboServer, this setting enables the use of custom Connectors in robots on the computer where RoboServer runs. Use custom Connectors in the Custom Action step in Robots. See
Kofax RPA Help for details.
Accept JDBC Drivers from Management Console
Distributes JDBC drivers from the Management Console to the RoboServer.
Command Time-Out
Specifies how long the RoboServer must wait for a reply from a command on a remote device. This option applies only to automating terminals and browsing websites in Robots.
A command is an instruction sent to Automation Device, such as click a mouse button, open an 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 steps, 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.
TLS
To make RPA components work correctly, you need to set the TLS certificates for:
1.
RoboServer that applies certificates in four different ways corresponding to the four properties on the Certificates tab of the RoboServer Settings application. They refer to the communication between:
• Management Console and RoboServer
• RoboServer and automation device
• RoboServer and API
• RoboServer and a website
The "RoboServer - API and "RoboServer - website" communication properties have to do with how robots access web servers as part of their execution.
2.
Management Console that needs a certificate for the communication with API that requires
Tomcat settings, settings in the Management Console, and in some other related folders.
3.
Kapplets Service
4.
Robot File System
19
Kofax RPA Administrator's Guide
5.
Desktop Automation Service
Prepare Certificates
To prepare for the HTTPS connection, you should create a self-signed certificate. You can generate a self-signed certificate using the Java keytool utility provided along with the JDK package as follows, using a command-line tool. In the command-line, use the path [JAVA_HOME]\bin and locate keytool . Then follow the example below.
keytool -genkeypair -alias mc -keyalg rsa -validity 3650 -keystore mc.p12 -storetype
pkcs12 -ext san=dns:<host machine name>,ip:127.0.0.1,ip:::1,ip:<IP>
The certificate should include all host names/IP addresses of the Tomcat Management Console computer that you expect to use while connecting to the RPA components. The Common Name
( cn ) parameter must match the host name of the Tomcat Management Console computer.
You need to create two keystores with different names: one keystore for deploying Management
Console on Tomcat and another keystore for communicating with other parts of RPA with
Management Console ( communication.p12
). The same options can be used for both certificates.
Use the following commands to extract certificates from the keystore: keytool -exportcert -alias mc -keystore mc.p12 -file mc.cer
keytool -exportcert -alias communication -keystore communication.p12 -file
communication.cer
Management Console TLS Configuration
To ensure stable work with SSL within RPA parts, complete the following steps:
1.
Edit the server.xml file in Tomcat > Conf , as follows:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true">
<SSLHostConfig>
<Certificate certificateKeystoreFile="<path to the certificate/ mc.p12>" certificateKeystorePassword="<your password>" type="RSA"
certificateKeyAlias="mc"/>
</SSLHostConfig>
</Connector>
2.
If you always need to redirect connection to TLS (that is not to allow the HTTP connection), add the following commands to the web.xml file in Tomcat > Conf :
<security-constraint>
<web-resource-collection>
<web-resource-name>Protected Context</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
For more information on the SSL Tomcat settings, see this article available on the Apache
Tomcat website.
3.
Start Management Console: https://localhost:8443/ManagementConsole/ .
20
Kofax RPA Administrator's Guide
4.
Start Management Console and create a new cluster with Use SSL selected. Then proceed to
TLS configuration to set up the other half of the communication.
5.
Optionally, for the encrypted RQL communication with RoboServer, locate the certs.xml file in the [Tomcat_home]/webapps/[Application name(ManagementConsole)]/WEB_INF folder, and specify the following:
<property name="privateCertificateLocation" value="/WEB-INF/communication.p12"/>
<property name="privateCertPassword" value="changeit"/>
RoboServer TLS Configuration
Kofax RPA provides a means for setting up TLS communication between the automation device,
RoboServer, Kapplets, Robot File System, or Design Studio. The communication uses certificates for encrypting the communication. The encryption uses a public-private key structure for securing the connection.
In the RoboServer Settings application, on the Security tab, under TLS Configuration Settings , you can specify whether to use the built-in set of certificates or specify some other.
• To use the Kofax RPA certificates, select Use Defaults .
• To use other certificates, clear Use Defaults and specify the paths to private and public keys as well as to the trusted certificates folder in the corresponding fields.
See "Use TLS Communication" in Kofax RPA Help for more information.
Establishing SSL connection between RoboServer and the сlusters in Management Console
1.
Start Management Console and create a new cluster with Use SSL selected.
2.
In the RoboServer Settings application, navigate to Certificates > API and select Verify API
Client Certificate to accept connections only from Management Console.
3.
Add the communication.p12 certificate to the API Server Certificate.
4.
Put the communication.cer certificate from the specified Management Console certs.xml keystore (communication.p12) into:
• on Linux: [USER_HOME]/.Kofax RPA/[version]/Certificates/API/TrustedClients , and
• on Windows: [User]\AppData\Local\Kofax RPA\[version]\Certificates\API
\TrustedClients
The cn attribute of the certificate must match the resolved host name of Management Console
5.
Add communication.cer to the JRE keystore used by RoboServer: keytool -import -alias communication -keystore "C:\Program Files\[JAVA_HOME]\lib
\security\cacerts" -trustcacerts -file C:\<path>\communication.cer
6.
Start RoboServer using the Command Prompt window:
RoboServer -service ssl:50001 -mcUrl https:\\admin:admin@ <hostname or IP> cluster SSL
To enable certificate validation or to let Management Console use a certificate so that
RoboServer can verify its validity, change the settings and provide the path to the keystore
(communication.p12) in the certs.xml file under ManagementConsole\WEB-INF .
21
Kofax RPA Administrator's Guide
Request Authentication
To protect your RoboServer against unauthorized access, you can turn on authentication. This has effect on all RoboServers run from your Kofax RPA installation, including a RoboServer started as a service or from a command line.
To turn on authentication, select the Require RoboServer Authentication check box in the
RoboServer Settings application. To run robots on a RoboServer with authentication turned on, you have to add users by clicking the add button. You can then fill out the information about the user including the user name that will be shown on the list of users.
A user is configured using the properties in the following table.
User Properties
Property
User name
Password (Password Hash)
Comments
Start Robot
Stop Robot
Shutdown RoboServer
Description
The user name used by the user when accessing the
RoboServer.
The password used by the user when accessing the
RoboServer.
Here you can write a comment about the user.
Enables the user to start robots on the RoboServer.
Enables the user to stop robots on the RoboServer.
Enables the user to shut down the RoboServer from the Management Console.
Kapplets Service TLS Configuration
To establish the TLS configuration for the connection from Kapplets to Management Console, use the same settings as for deploying Kapplets, with the following differences.
1.
Use the SSL path to Management Console in kapplets.xml:
<Environment name="kapplets.services.mc.connection.url" value="https://<
hostname>8443/ManagementConsole/" type="java.lang.String" override="false"/>
2.
Add the certificate from Management Console into the JRE keystore used by the Kapplet
Service Tomcat at [JAVA_HOME]\lib\security\cacerts . To do so, use the following command: keytool -import -alias mc -keystore "C:\Program Files\[JAVA_HOME]\lib\security
\cacerts" -trustcacerts -file C:\<path>\mc.cer
Robot File System Configuration
Use the following procedure to configure the TLS connection for the Robot File System (RFS).
1.
Use the SSL Tomcat configuration as
described for Management Console.
2.
In the web.xml file, set the TLS address for Management Console: https://
<hostmachine>:8443/ManagementConsole .
3.
Add communication.cer to: C:\Program Files\[JAVA_HOME]\lib\security .
22
Kofax RPA Administrator's Guide
4.
In the RFS server configuration on the General tab of Management Console, set the TLS address for the RFS server: https://<hostmachine>:8443/rfs .
5.
Add communication.cer to the used JRE keystore used by Management Console and
RoboServer at C:\Program Files\[JAVA_HOME]\lib\security\cacerts . To do so, use the following command: keytool -import -alias communication -keystore "[JAVA_HOME]\lib\security\cacerts"
-trustcacerts -file C:\<path>\communication.cer
If Management Console and RoboServer use different Tomcat servers, generate a keypair for the Robot File System. Otherwise, ensure that the Management Console certificate has been imported to the Java cacerts .
With the Robot File System, if you use a self-signed certificate or a certificate signed with a private root CA, configure a CA certificate on every system that runs RoboServer, Design Studio, or the
Desktop Automation Service. As a result, the Robot File System will become available. To do so, complete the following steps on each system:
1.
Identify the accounts used to run RoboServer, Design Studio and/or the Desktop Automation
Service on the system.
2.
Copy the certificate.cer file to the system.
3.
Configure the system to add the environment variable NODE_EXTRA_CA_CERTS to the accounts identified in step 1.
• If the NODE_EXTRA_CA_CERTS environment variable is already defined for an account, locate the file it refers to and add the contents of the certificate.cer file to this file.
• If the NODE_EXTRA_CA_CERTS environment variable is not defined, add a definition and set its value to the full path of the certificate.cer file.
4.
Ensure that the accounts identified in step 1 have read access to the file referenced by
NODE_EXTRA_CA_CERTS .
Desktop Automation Service Configuration
To make the Desktop Automation Service available for all Kofax RPA components, complete the following steps:
1.
Use the SSL path Management Console in Desktop Automation Service > Configure
Management Console : https://<hostname>:8443/ManagementConsole/ .
2.
Download the Management Console certificate, communication.cer
, and add it to the
Desktop Automation Service, in the CA file field.
There is another way to save a root certificate as a file from the Google Chrome browser to
Management Console. To do so, complete the following steps:
1.
Right-click the lock icon in the address bar and click Certificate .
2.
On the Certificate Path tab, select the topmost root certificate and click View Certificate .
3.
On the Details tab, click Copy to File and follow the wizard to export the root certificate as a base-64 encode X.509 certificate.
23
Kofax RPA Administrator's Guide
RoboServer Configuration - Headless Mode
Kofax RPA ships with several utilities to configure your RoboServer from a command line. The utilities are located in the bin subfolder of the Kofax RPA installation folder. Note that the configuration files are user-dependent and stored in the user folder. For more information, see
"Important Folders" in the Kofax RPA Installation Guide .
• ConfigureRS: Sets the JMX password and the Management Console password in the RoboServer settings file (roboserver.settings).
• ConfigureMC: Sets protocols and ports usage, certificate passwords, and upload JDBC jar files permissions in the mc.settings
file.
• ConfigureRSUser: Adds and removes users and updates user credentials in the rsusers.xml
file.
Information in this file is used to authenticate API requests.
For help on usage, run utilities with an -h option.
To set a connection to the Management Console that a RoboServer registers to, type the following command:
ConfigureRS -mcUrl http://admin:password@localhost:8080/ManagementConsole
The default admin superuser credentials are: user name - admin , password - admin .
To create a user user1 with Password1 password and all permissions, type the next command:
ConfigureRSUser user1 Password1 -a
To enable authentication of API requests, open rsusers.xml
and change the userConfiguration enabled to true , as shown in the following example.
Sample rsusers.xml configuration file
<?xml version="1.0" encoding="UTF-8"?>
<userConfiguration enabled="true">
<users>
<user username="user1"
password_hash="20c7628c31534b8718a1da00435505e4262e3f4dc305">
<startRobot/>
<stopRobot/>
<shutdownRoboServer/>
</user>
</users>
</userConfiguration>
Sample roboserver.settings configuration file
# Settings file for RoboServer. Some configurations contains encrypted passwords and
should
not be edited by hand, these should be modified using dedicated commandline tools.
# The directory of use on RoboServer when the API used the DefaultRoboLibrary. On
windows \ must be escaped like this c:\\\\users\\AppData\\Local\\Kofax RPA\\...
defaultProject = /home/TestUser/Kofax RPA/trunk
24
Kofax RPA Administrator's Guide
# Should RoboServer be allowed to access the fileSystem, or call commands/scripts.
Values: true/false sec_allow_file_system_access = false
# Will RoboServer accept JDBC drivers sent from the Management Console. Values: true/ false sec_accept_jdbc_drivers = true
# Should RoboServer log all loaded URLs to the log4j audit log. Values true/false sec_log_http_traffic = false
# If enabled RoboServer will check credentials for API requests. Values: true/false sec_authenticate_api_requests = false
# If enabled RoboServer generate an error when accessing a https site without a valid
certificate. Values: true/false cert_verify_https_certificates = false
# If enabled, RoboServer will only allow SSL connections from trusted client. Values
true/false cert_verify_api_certificates = false
# Configures if the the JMX service should be enabled enable_jmx = false
# The port number for the JMX service to listen on.
jmx_port_Number = 50100
# If enabled, input for robots is exposed through JMX. Values: true/false jmx_show_inputs = true
# Heartbeat notification interval, in seconds jmx_heartbeat_interval = 0
# Configure if JMX should use RMI enable_jmx_rmi = false
# Optional RMI host and port for the JMX service. Use if you need to connect through a
firewall. Example: example.com:51001 jmx_rmi_url =
# Enables authentication for JMX requests. Values: true/false jmx_enable_authentication = true
# The user-name used for JMX authentication jmx_username =
# The password used for JMX authentication. This should be created using the
ConfigureRS command line tool.
jmx_password =
# Configures if the socket service should be enabled enable_socket_service = false
# Configures which port the RoboServer should be listening on port = 50000
# Configures if the ssl socket service should be enabled enable_ssl_socket_service = false
# Configures which ssl port the RoboServer should be listening on ssl_port = 50001
25
Kofax RPA Administrator's Guide
# Configures if the RoboServer should register to a Management Console enable_mc_registration = false
# Specify which Management Console to register to formatted as: http[s]://
<hostname>:<port number> mc_URL =
# The user name to use for authentication to the Management Console mc_username =
# The password to use for authentication to the Management Console mc_password =
# Specifies which cluster the RoboServer should be registered to cluster =
# Causes RoboServer to output status and runtime events verbose = false
Sample mc.settings configuration file
# Settings file for Management Console. Passwords should not be edited by hand, but
using the 'ConfigureMC' command line utility.
# Should the MC web-server start a HTTP listener. Values true/false
mc_http = true
# Configures the port of the http listener.
mc_http_port = 50080
# Should the MC web-server start a HTTPs listener. Values true/false
mc_https = false
# Configures the port of the HTTPS listener.
mc_https_port = 50443
# Password for the certificate used by the HTTPs listener. This should be created
using the ConfigureMC command line tool.
mc_https_cert_password = 3W2MTrL/b2k=
# Configures which hosts are allowed to upload JDBC jar files to MC. Values: NONE,
LOCALHOST, ANY_HOST
mc_allow_jdbc_upload = LOCALHOST
JMX Server Configuration
You can use the embedded JMX server to monitor a running RoboServer through tools such as
JConsole. Enable JConsole by providing an argument on the RoboServer command line.
Hiding Sensitive Robot Input
The Show Inputs option controls whether robot input parameters are shown in the management interface. This makes it possible to hide security sensitive information such as passwords.
26
Kofax RPA Administrator's Guide
JMX Server Access
By default, a JMX server can be accessed by all clients with access to the correct port on the server.
By selecting the Use Password option, the selected user name and password are required when connecting.
Heartbeat Notifications
If an interval (in seconds) greater than 0 is specified, the JMX server sends out a heartbeat notification with the given interval, as long as a RoboServer is running and responding to queries.
Default RoboServer Project
You can set the location of the default RoboServer project folder on the RoboServer Settings Project tab. By default, the folder is set to the default robot project created during the installation process.
See the Design Studio chapter in the Kofax RPA Help for more information on robot projects.
The RoboServer default project is used only by the API. When executing a robot using API, any references it has to types, snippets or other resources are resolved by looking in the default project.
Change the RAM Allocation
As installed, each Kofax RPA application is configured with a maximum amount of RAM that it may use. This amount usually is plenty for ordinary work, but if you run many robots in parallel on a
RoboServer, or if some robots use much RAM, it may be necessary to increase the allocation.
You can change the allocation for any of the applications by editing its .conf
file, found in the bin subfolder of the installation folder.
For RoboServer, edit: bin/RoboServer.conf
.
For Design Studio, edit: bin/DesignStudio.conf
.
To edit the file, perform the following steps.
1.
Open the corresponding .conf
file in a text editor.
2.
Find the line containing the wrapper.java.maxmemory
parameter.
3.
Un-comment the line (remove the leading #) and edit its value.
For example, to permit a RoboServer to use up to 4GB of RAM, enter the following: wrapper.java.maxmemory=4096 .
If the .conf
file does not contain the wrapper.java.maxmemory
line, add the whole line to the file. The .conf
file can be edited only by the user who installed Kofax RPA, such as the
Windows administrator.
27
Kofax RPA Administrator's Guide
Troubleshoot RoboServer Service Startup
If your service does not start, look for RoboServer messages in the Windows event log. Make sure you have installed the service with the wrapper.syslog.loglevel=INFO argument. For more information, see Kofax RPA Initial Configuration in the Kofax RPA Installation Guide .
28
Chapter 2
Tomcat Management Console
For production environment we strongly recommend deploying Management Console as a regular web application on a standalone Tomcat web server.
If your setup requires access to the Management Console outside of your corporate intranet, set up TLSv1.0 (or a later version of TLS) to work with your Tomcat server.
The following table lists the differences in the feature set.
Management Console Features and Configuration
Feature
Authentication
Management Console data store
Embedded
Single admin superuser and users defined in Management Console.
Users and Roles managed by Management Console
Administrator.
Embedded Derby database
Standalone J2SE Web Container
Users and Roles managed by Management Console
Administrator.
Role based security through Active
Directory or other LDAP provider.
Single Sign-On using CA Single
Sign-On.
Container managed Data Source
(supported platforms)
The derby JDBC driver is not distributed with the Enterprise Management Console. See Apache
Derby Web site for Derby JDBC driver download information. We recommend using MySQL or other enterprise-class database with your Enterprise Management Console.
Instructions on configuring an embedded Management Console can be found in the Kofax RPA online help. To start an embedded Management Console, see "Start Management Console" under the "Management Console" section.
Tomcat Deployment
This chapter provides details on how to manually install Management Console on a stand alone J2SE web container. For this guide we have chosen Tomcat. Your J2SE web container must be using the
Java 8 runtime or later. Visit the Oracle Java SE Downloads site and download the latest Java release.
29
Kofax RPA Administrator's Guide
If your setup requires access to the Management Console outside of your corporate intranet, set up TLSv1.0 (or a later version of TLS) to work with your Tomcat server.
Install Management Console on Tomcat
Prerequisites
• Install the latest java update from the Oracle website: http://www.oracle.com/technetwork/java/ javase/downloads/index.html
• Download Tomcat from the Apache website https://tomcat.apache.org
.
• Install Tomcat and set user password.
Installation
1.
Download full Kofax RPA installer and proceed with the installation. Select the Management
Console WAR option during the installation.
2.
Copy the ManagementConsole.war
file from the WebApps directory in the Kofax RPA installation to the webapps directory on the Tomcat server and
the .war file.
3.
Create a ManagementConsole.xml
Tomcat context file on the Tomcat server at conf/
Catalina/localhost/
. See Create a Tomcat Context File for details.
4.
Edit webapps/manager/WEB-INF/web.xml
file on Tomcat.
• To upload applications, edit the following.
<multipart-config>
<!-- 150MB max -->
<max-file-size>152428800</max-file-size>
<max-request-size>152428800</max-request-size>
<file-size-threshold>0</file-size-threshold>
</multipart-config>
• If your policies require compulsory use of HTTPS protocols on your network, enable the
HTTP Strict Transport Security Header (HSTS Header) on the Tomcat server by using the org.apache.catalina.filters.HttpHeaderSecurityFilter
class in web.xml
. See the
Apache Tomcat documentation for details.
• Management Console implements Content Security Policy as an added layer of defense that helps to detect and mitigate certain classes of attacks. A SecurityHeadersFilter filter that is mapped to all URLs is declared and configured in web.xml
. To configure the header's value, set the contentSecurityPolicy variable. This is the configuration example of header filtering in the web.xml
file:
<filter>
<filter-name>SecurityHeadersFilter</filter-name>
<filterclass>com.kapowtech.scheduler.server.servlet.SecurityHeadersFilter</filterclass>
<init-param>
<param-name>contentSecurityPolicy</param-name>
<param-value>default-src 'self' data: blob: 'unsafe-inline' 'unsafeeval'</param-value>
</init-param>
</filter>
<filter-mapping>
30
Kofax RPA Administrator's Guide
<filter-name>SecurityHeadersFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
If you do not require header filtering, either disable or remove the filter code and the corresponding filter mapping. For more information about possible options and header filtering, search the web for Content Security Policy.
5.
.
6.
Configure ManagementConsole.war
The Management Console application comes in the form of a Web Application Archive (WAR file) named ManagementConsole.war
, which is located in the /WebApps folder in the Kofax RPA installation folder.
The version of ManagementConsole.war
that ships with Kofax RPA is configured to run embedded inside RoboServer. Before deploying it as a standalone application on Tomcat, you may need to reconfigure it to fit your environment.
A WAR file is compressed using a compressed zip file. To access the configuration files, you must extract the zip file. Once the configuration files are updated, you re-zip and deploy
ManagementConsole.war
to your Tomcat server.
The table below contains a list of the configuration files relative to the root of the unzipped
ManagementConsole.war
.
Configuration Files
File
WEB-INF/Configuration.xml
Configures
Clustering, password encryption,
REST-Plugin
Notes
If you copy the file from an earlier version, it will automatically be upgraded once you start the
Management Console
WEB-INF/login.xml
Administrators and users, this is where you integrate with LDAP
Application logging WEB-INF/classes/ log4j2.properties
WEB-INF/spring/ authentication.xml
WEB-INF/roles.xml
User authentication
Built-in roles in Management
Console.
Spring Configuration Files
Configuration.xml
, login.xml
, roles.xml
, and authentication.xml
are all Spring configuration files (www.springsource.org) and share the same general syntax outlined here.
31
Kofax RPA Administrator's Guide
Spring is configured through a series of beans, and each bean has properties that configure a piece of code inside the application. The general syntax:
<bean id="id" class="SomeClass">
<property name="myName" value="myValue"/>
</bean>
File id="id" class="SomeClass"
<property name="myName" value="myValue"/>
Configures
The id of the bean is an internal handle, that the application use to refer to the bean. It is also referred to as the bean's name.
The class identifies the code component which the bean configures.
Defines a property with the name myName and the value myValue .
This configures a property on the code component defined by the class attribute.
In Kofax RPA versions prior to 9.3, user access credentials were defined manually in the login.xml file. Starting from version 9.3, user management is performed using the Users & groups section under the Admin menu in Management Console. In the enterprise version of Kofax RPA, user management is enabled by default. User population from previous installations can be performed using the Kofax RPA backup functionality. For LDAP and SAML integrations, you still need to edit the login.xml file.
Troubleshooting
If you have any problems during the installation, you should check the Tomcat log in the /logs folder in your Tomcat installation. During the configuration process it is often easier to run Tomcat from the command line, as it prints error messages directly in the command line window.
Create a New Database
We strongly recommend that you create a new database for the tables used by Management
Console. There are two requirements to the database.
• Unicode support
• Case-sensitive comparison
Unicode support is needed because non-ASCII characters, like Danish Æ, German ß or Cyrillic Ё may be given as input to robots. This input is stored in the database, and without Unicode support these characters may be stored incorrectly.
Case-sensitive comparison is needed because it is possible to upload a robot named a.robot
and another named A.robot
. Without case-sensitive comparison, uploading the latter would override the first.
Please create and maintain the Kofax RPA product databases according to the recommendations in the product documentation. If you are considering database modifications or customizations, do not proceed without consulting Kofax; otherwise, the results are unpredictable and the software may become inoperable.
32
Kofax RPA Administrator's Guide
Database servers handle Unicode and case-sensitive comparison very differently. The following list contains recommendations for the supported database systems.
Recommendations for Unicode Support and Case-Sensitive Comparison
Database
MySQL 5.7
MySQL 8.0
Oracle
Microsoft SQL Server
PostgreSQL
Recommendations
Create the database with utf8mb4_bin collation.
CREATE DATABASE KAPOW_MC COLLATE utf8mb4_bin
NVARCHAR2, NCLOB types are used for Unicode. For case-sensitive comparison, ensure that NLS_COMP is set to BINARY.
NVARCHAR, NTEXT types are used for Unicode.
For case-sensitive comparison, create the database with a Case-Sensitive collation such as
Latin1_General_100_BIN2:
CREATE DATABASE KAPOW_MC COLLATE
Latin1_General_100_BIN2
See "Configure Microsoft SQL Server in Windows
Integrated Security" in
for more information.
Create the database using CODESET UTF-8.
CREATE DATABASE KAPOW_MC ENCODING 'UTF8'
The tables used by Management Console can be grouped into 3 categories: Platform tables, logging tables, and data view tables. The platform tables hold information exclusive to Management
Console such as the uploaded robots and their scheduling information, while the logging and data view tables are shared with RoboServers.
User Privileges
When a Management Console starts, it automatically tries to create the required platform tables and logging tables (if not already created by a RoboServer). This means that the user account used to access the database must have the CREATE TABLE and ALTER TABLE privileges as well as the CREATE TEMPORARY TABLES privilege to restore a backup. Oracle users also need the CREATE
SEQUENCE privilege. If this is not possible you can ask your Database administrator to create the tables using the scripts below.
Additionally the user must be allowed to SELECT, INSERT, UPDATE, DELETE for the system to work properly.
SQL Scripts for Management Console Tables
SQL scripts are included with your copy of Kofax RPA in the documentation\sql directory. See
Scripts for Kofax RPA Tables for details.
Management Console uses a 3rd party scheduling component called Quartz. Quartz also requires a number of tables which must reside among the other platform tables. These tables are also created
33
Kofax RPA Administrator's Guide automatically when a Management Console starts, or may be created manually using the scripts in
the SQL Scripts for Kofax RPA Tables .
Create a Tomcat Context File
In an enterprise environment, databases are often accessed through a data source. This section shows you how to configure your Tomcat with a data source that connects to a local MySQL database server.
In Tomcat, data sources are defined within the applications context. The context may be declared either embedded or external to the application. When the context is embedded, it is defined in the file context.xml
, which must be located inside the WAR file in the META-INF folder. When declared externally the file must be located in the Tomcat's /conf/Catalina/localhost folder and the name of the file must be ManagementConsole.xml
(same name as the deployed WAR file). Although Tomcat recommends deploying with an embedded context, as it provides a single deployment unit, we use an external context definition in this guide, as it makes modifying the file easier. Once you have refined your configuration, you can embed the context file and deploy the
War file to your production environment.
Add Platform Data Source
Create the file ManagementConsole.xml
on Tomcat in the conf/Catalina/localhost folder and add the following content.
The following excerpts are provided as an example only, and the actual configuration may contain other settings.
To create a connection to MySQL database:
<Context useHttpOnly="true">
<!-- Default set of monitored resources -->
<WatchedResource>WEB-INF/web.xml</WatchedResource>
<Resource name="jdbc/kapow/platform" auth="Container"
type="javax.sql.DataSource"
maxTotal="100" maxIdle="30" maxWaitMillis="-1"
factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
validationQuery="/* ping */" testOnBorrow="true"
username="MyUser" password="MyPassword"
driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/KAPOW_MC?
useUnicode=yes&characterEncoding=UTF-8&rewriteBatchedStatements=true"/>
</Context>
To create a connection to PostgeSQL:
<Context useHttpOnly="true">
<!-- Default set of monitored resources -->
<WatchedResource>WEB-INF/web.xml</WatchedResource>
<Resource name="jdbc/kapow/platform" auth="Container"
type="javax.sql.DataSource"
maxActive="100" maxIdle="30" maxWait="-1"
validationQuery="SELECT 1" testOnBorrow="false"
username="username" password="password"
34
Kofax RPA Administrator's Guide
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://<URL>:<PORT>/<Database>"/>
</Context>
The url parameter above is a JDBC URL. The username and password attributes are used by
Tomcat to create a connection pool used when connecting to the database.
The data sources are defined differently for other databases. For instance, if you are using Microsoft
SQL Server, the relevant three lines above should instead be: username="MyUser" password="MyPassword"
driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
validationQuery="SELECT 1" testOnBorrow="true"
url="jdbc:sqlserver://localhost:1433;DatabaseName=MyDbName"/>
The URL jdbc:mysql://localhost:3306/KAPOW_MC?
useUnicode=yes&characterEncoding=UTF-8 refers to a database named
KAPOW_MC in your local MySQL. For MySQL it is recommended that you add ?
useUnicode=yes&characterEncoding=UTF-8 to all connection strings, otherwise the JDBC driver cannot handle Chinese, Japanese or other 3-byte utf-8 characters correctly, as we cannot have "&" directly inside the context xml file, we must encode it as & rewriteBatchedStatements=true instructs the MySQL JDBC driver batch inserts/updates and should give improved insert performance for kapplet robots.
The driverClassName parameter controls which JDBC driver is used; each database vendor provides a JDBC driver for their database, which you have to download. The JDBC driver, typically a single .jar
file, must be copied into the /lib folder on Tomcat.
The validationQuery is used by Tomcat to verify that the connection obtained from the connection pool is still valid (as the database server may have closed the connection). The validation query is lightweight and uses very few resources on the database server, this list contains validation queries for the supported databases.
Validation Queries
Database
MySQL
Microsoft SQL Server
Oracle
PostgreSQL
Query
/* ping */
SELECT 1
SELECT 1 FROM DUAL
SELECT 1
IBM DB2 is not supported as a Management Console database, but you can use it as a user's database type for LogDB and for the databases available for robots.
Note that the MySQL JDBC driver supports a special lightweight /* ping */ 'request', check
JConnector manual section 6.1 for details
For more information on context configuration and data sources, see JNDI Resources HOW-TO and
JNDI data source HOW-TO.
35
Kofax RPA Administrator's Guide
Configure Microsoft SQL Server in Windows Integrated Security
If you use Microsoft SQL Server and Windows Integrated Security, computers running a Design
Studio and a RoboServer must comply with the following:
• Run on Windows
• Run under a user account that has been granted access to the database
• The JDBC driver must be installed manually as described later in this part
To configure Microsoft SQL Server in Windows Integrated Security, do the following:
• Install JDBC drivers to the Tomcat folders: copy JAR file to the lib folder, copy DLL file to the nativelib folder.
• Do not upload the jar-file to Management Console, because it is not possible for Management
Console to distribute the JDBC driver.
• Ensure that you add ;integratedSecurity=true to the connection URL, both in your
ManagementConsole.xml
(or context.xml
) and in the Database Type definition in a
Management Console as well as any local definitions in Design Studio. See "Add Database Type" in Kofax RPA Help.
We are now ready to start the Tomcat server.
Start Tomcat
Start your Tomcat server, wait a couple of seconds for the application to be deployed, then navigate to http://localhost:8080/. You should see the following page.
36
Kofax RPA Administrator's Guide
No Providers Apache Start Page
By default, one set of credentials is available (user name - admin , password - admin ) with administrator privileges. Later you can change the password and create other users and groups on the Users & groups page under Admin in the Management Console.
Now open the http://localhost:8080/ManagementConsole you should see the login screen.
Enter admin as the username and admin as the password and click Login .
Enter License Information
After logging in, the license window is displayed.
Enter the Kofax RPA license information and click Save . You should see a dialog box displaying which features are enabled by your license key.
Predefined User Roles
Management Console provides roles that users can have. Roles are mapped to a user of a security group. User permissions are calculated based on the roles that are mapped to security groups the user is a member of. You can modify built-in roles or add additional roles. The built-in roles are defined in the roles.xml
for details.
37
Kofax RPA Administrator's Guide
Built-in Roles
Management Console provides some built-in roles that users can have. Roles are mapped to a user of a security group. User permissions are calculated based on the roles that are mapped to security groups the user is a member of. You can modify built-in roles or add additional roles.
• Project Administrator : A user with this role administrates one or multiple projects and has a right to assign a role to a group for these projects. This user has a view right to view RoboServer and cluster settings without changing them. Project Administrator is not a member of the RPA
Administrators group (for more information, see later in this section).
• Developer : Developers have a right to upload, download, and view all resource types in the repository. A user with this role can create, edit, and delete schedules, run robots, view run logs and clusters.
• Viewer : Viewers have similar view rights as developers and the rights to change or run anything.
• API (This user logs in only as a service authenticating via the API): A user with this role can use the repository API to read from and write to the repository. A user with this role cannot run robots using REST but is able to run robots using RQL.
• RoboServer (This user logs in only as a service authenticating via the API): A restricted user that can only read from the repository. This role is used by RoboServers when accessing a cluster, retrieving repository items, and requesting passwords from the password store.
• Kapplet Administrator : A user who can create, view, run, and edit Kapplets.
• Kapplet User : A user who can view and run Kapplets. A user with this role cannot access
Management Console if this user has no other rights.
For more information on Kapplet user roles, see "Kapplets User Roles" in Kofax RPA Help .
• Password Store client : A user with this add-on role can access the password store. The role is provided on top of other roles, just like the Developer role. This role only provides access to the password store in Management Console.
• DAS Client User (This user logs in only as a service authenticating via the API): This is a user that is created for remote Desktop Automation Service (DAS) clients, and can only access the DAS API.
The DAS client user has a right to announce a DAS to Management Console, and retrieve DAS configuration.
• VCS Service User (This user logs in only as a service authenticating via the API): The version control service user is granted a special set of rights for the Synchronizer. This role has a right to add, modify, and delete resources. This is the only role that can deploy on behalf of another user to use the "deployer" feature in the version control service.
• Process Discovery Client (This user logs in only as a service authenticating via the API): This role allows Process Discovery components interact with Management Console.
Built-in "admin" user admin is a superuser that has access to everything. It is not a member of the RPA Administrators group and cannot be a member of any group. The default admin user password is available (user name - admin , password - admin ). You can change the admin user password as described in "Reset password for user" in Kofax RPA Help .
In an LDAP integration setup, the admin group is defined as part of the LDAP configuration.
admin can then log in and define which LDAP groups should be mapped to the Developer, Project
Administrator, RoboServer, and other roles.
In an internal user setup, the admin user is created at first start and can then login and create
Administrators, Developers, and other users.
38
Kofax RPA Administrator's Guide
Built-in "admin" user special rights
Beside being the initial user, admin also has special rights, such as:
• In the RoboServers section in Management Console, admin can click a RoboServer node and request a stack trace from the corresponding RoboServer.
• Only admin can create and import backups.
• In the password store, admin can move passwords to another project.
When you restore a Management Console backup, the default admin superuser is replaced with a superuser from the backup. Use credentials specified in the restored Management Console.
Built-in group
RPA Administrators : Users belonging to this group have all rights for all projects (excluding special admin user rights), such as creation of new administrators and users in any project. To make a user an administrator, the user has be added to this group.
• The RPA Administrators group is visible when the internal user management is enabled, and it is empty by default.
• When restoring a backup created in version prior to 10.7, users with Administrator role become members of the RPA Administrators group.
Check for login attempts
By default, the check for number of login attempts made by a user and wait time before the next attempt is disabled. To enable this functionality, edit the following section in the authentication.xml file located in: <Tomcat installation folder>\WebApps\Management Console\WEB-INF
\spring
<bean id="loginAttemptService"
class="com.kapowtech.scheduler.server.spring.security.LoginAttemptService"
lazy-init="true">
<constructor-arg type="boolean" value="false"/>
<constructor-arg type="int" value="3"/>
<constructor-arg type="int" value="10"/>
</bean>
Set the first value to true . The second and third values are for the number of login attempts
(3 in this example) and the wait time in minutes before the next attempt (10 in this example), respectively.
Project Permissions
The admin user account used to log in bypasses the normal project permissions applied to regular users, because admin is the superuser. The superuser can not be a member of any group, and has an unrestricted access to all projects.
39
Kofax RPA Administrator's Guide
To change the admin password and create new users and groups, go to Management Console >
Admin > Users & groups . The security model is role-based; after you create a user, you need to add this user to one or more groups associated with specific roles in one or more projects, as shown in the following example procedures.
Create "Developers" Group
1.
On the Groups tab, click the plus sign.
The Create new group dialog box appears.
2.
Specify the name "Developers" and enter a description.
3.
Click OK .
The group appears in the table.
Create "Dev" User
1.
On the Users tab, click the plus sign.
The Create new user dialog box appears.
2.
Specify the user name "Dev," password, full name, and email for the user and then select the group "Developers."
3.
Click OK .
The user appears in the table.
Now you need to assign permissions to the user so the user can log in. Log in as administrator and go to Admin > Projects . In this section, click the menu icon on the right and click to display the
Permissions column. Currently, it displays "0" permissions for this project.
Initial Project Permissions
1.
Click Edit from context menu for the default project and go to the Permissions tab. There is a grid with the columns Project role and Security group . A project role determines a set
40
Kofax RPA Administrator's Guide of actions that may be performed inside Management Console, such as uploading robots, creating schedules, viewing logs, and so on. Within a project you assign a project role to a security group. That way, all users of the selected security group will be able to perform the actions allowed by the assigned project role.
2.
Click the plus sign to add permissions in this project. This adds a new line to the grid, and inserts a drop-down box allowing us to select a project role. Select the project role Developer .
3.
Now click the Security group column and select the Developers security group (of which our
"Dev" user is a member). It should look like this:
4.
Now click Submit .
All members of the "Developer" group can now perform the actions allowed by the Developer role. The Permissions column for the default project now shows "1" permission.
Then, log in as the "Dev" user and see how the permissions are reflected in the Management
Console. You log out by clicking the menu button in the upper right corner, then log in as the dev user. Now go to the Log view , select the RoboServer log in the left pane. Notice how the delete button is disabled, and hovering gives a tooltip message that you do not have permissions to delete
RoboServer messages.
You can assign multiple roles to the same security group, and you can assign the same role to multiple security groups. If a user holds multiple roles, the user can do anything that at least one of the roles allow. With multiple projects in Management Console, users of different projects can be completely separated by assigning their groups to project-specific roles.
The predefined roles are suggestions, but using the roles.xml file, you can add any number of additional roles, or change the existing roles to fit your needs.
Actions that can be performed in the Settings, Backups, and License sections are only available to users that are members of the RPA Administrators group.
For using your LDAP user accounts, see the Advanced Configuration>LDAP Integration
topic.
41
Kofax RPA Administrator's Guide
Security
In the WEB-INF/Configuration.xml
file, it is possible to configure some additional security settings for the Management Console.
The security configuration section of the file looks like this:
<bean id="securityConfiguration" class="com.kapowtech.mc.config.SecurityConfiguration">
<property name="jdbcDriverUpload" value="LOCALHOST"/>
</bean>
It contains two security settings which are described below.
By default, only the admin user when accessing the Management Console from the localhost is allowed to upload JDBC drivers. To change this behavior, modify the jdbcDriverUpload property. The following are the possible values, the property can have:
• NONE: upload of JDBC drivers is not allowed for any users
• LOCALHOST: the default value, the admin user is allowed to upload drivers if accessing the
Management Console from the localhost
• ANY_HOST: the admin user is allowed to upload drivers from any host
Deployment Checklist
Use the following checklist to ensure that all deployment tasks are completed in the proper order.
Deployment Checklist
Item
Download and install a supported version of Apache
Tomcat Server
Download and install Java
Description
If your setup requires access to the Management Console outside of your corporate intranet, make sure SSL is set up to work with your Tomcat server.
Management Console does not initialize correctly if Apache Tomcat is started using any version of Java other than the supported version. For more information, see the Kofax RPA Technical Specifications document available on the documentation site: https://docshield.kofax.com/Portal/Products/
RPA/11.4.0-vcsft2fhaw/RPA.htm
Ensure that the JAVA_HOME variable is pointed to the
Java installation.
Start up the Apache Tomcat and confirm that the Apache
Tomcat server will come online before attempting to deploy the Management
Console application.
• You can use the catalina run command from the server.
\bin directory to start the
• Going to http://localhost:8080 in the browser should display the default
Apache Tomcat start up page.
42
Kofax RPA Administrator's Guide
Item
From a Kofax RPA installation, locate the
ManagementConsole.war
file that will be deployed under the Apache Tomcat
\webapps directory
Turn the Apache Tomcat server off.
Create a new database to be used by the Enterprise
Management Console to hold its configuration.
Description
Expect errors on the initial start up of the application at this point, because the server has not been configured yet. We are simply unpacking the .war file so that we can easily gain access to the files we will need to edit to complete the installation and configuration process.
• Select one of the support platforms.
• The Kofax RPA installation contains the CREATE and DROP SQL scripts needed to create all the required database tables. See
for details. Note that these scripts only need to be used if the user account that the application will use to connect to the database does not have the CREATE privileges on the schema.
Create the DB user account to be used by the application to connect to the database via JDBC.
Create the Tomcat
Context file:
ManagementConsole.xml
• Validation query to be specified is database specific. The online help has all accepted values for all supported databases.
• Do not forget to update the Username, Password, and DatabaseName parameters in the JDBC URL string with the correct values for your database.
Prior to starting up the application, notice that the Management Console database (as specified in the
ManagementConsole.xml
) does not have any tables related to the Management
Console process at this time.
Do not forget to deploy the necessary JDBC .jar file under the Apache Tomcat installation directory.
• When the application is started, the needed database tables are automatically created if they are not present assuming that the DBUser account has the CREATE privileges.
• If the user does not have the CREATE privileges, the CREATE SQL scripts can be found in the documentation\sql directory in your Kofax RPA
installation directory. See SQL Scripts for Kofax RPA Tables
for details.
• Deploying to < APACHE_TOMCAT_INSTALL_DIR>\lib makes it available to
ALL apps running under Tomcat.
• Deploying to <APACHE_TOMCAT_INSTALL_DIR>\webapps
\ManagementConsole\WEB-INF\lib makes the JDBC .jar file only accessible to the Management Console application itself.
Restart the Apache Tomcat
Server
Try to login to the Enterprise
Management Console as user - admin, password - admin
Enter the Kofax RPA
Software License Keys
Confirm the Tomcat main home page loads: http://localhost:8080 http://localhost:8080/ManagementConsole
See Enter License Information .
43
Kofax RPA Administrator's Guide
Docker Tools for Kofax RPA Deployment
Kofax supplies Docker tools for fast and easy deployment of Kofax RPA in your Linux and Windows environments. Docker tools for Kofax RPA help you build Docker images for the RPA components.
Currently, images are available for the following components.
Due to the significantly higher resource consumption of the Windows Docker containers, the
Linux version is recommended when available. Components that run only on Windows, support only the Windows Docker container version. Also, running Windows Docker containers is only supported on Windows Server hosts.
The official Kofax RPA images are now provided through Docker Hub. You can either download the required images using the links listed below, or build them using docker-compose files (for more information, see
Deploy Kofax RPA using docker-compose files
). Note that only Linux images are available.
Linux Windows Component
Management Console https://hub.docker.com/r/kofax/rpa-managementconsole
RoboServer https://hub.docker.com/r/kofax/rpa-roboserver
Robot File System
Synchronizer https://hub.docker.com/r/kofax/rpa-synchronizer
Kapplets https://hub.docker.com/r/kofax/rpa-kapplets
Document Transformation
Kofax Analytics for RPA
Yes
Yes
Yes
Yes
Yes
No
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
This chapter provides details on Docker tools and usage examples. For more information about
Docker, see https://www.docker.com
. For more information about manual deployment of Kofax RPA
on a standalone server, see Tomcat Deployment
.
Notes for Windows Docker
For production, we recommend that you run Docker containers under the preferred operating system container specified in the table above. Windows container images do not feature the High
Availability feature or health check configurations. If a Windows Docker container is part of your
Kofax RPA setup, which is currently only mandatory for Document Transformation and Kofax
Analytics for RPA, we recommend that you deploy the setup in a hybrid Kubernetes cluster that includes Linux and Windows Server 2019 (or later) nodes. Previous versions result in significantly larger images.
44
Kofax RPA Administrator's Guide
When running Windows Docker containers, you need to make the following decisions that are specific to this operating system:
• Isolation level
Decide on the runtime isolation mode to use: "process" and "Hyper-V" are available. The Windows
Server default is "process," while the Windows 10 default is "Hyper-V." When using the "process" isolation mode, the container base version has to match the operating system version on the host. If you run the containers on a Windows Server 2019 host, the containers must be built based on a servercore version ltsc2019 .
When using the servercore version ltsc2019 or later, some operating system components need to be optimized and added to the RoboServer image for it to work. Check the Dockerfile for RoboServer located at docker-win\roboserver and note the commented part where the dxva2.dll script is copied. Move a copy to the build folder or change the COPY command to point to its location as instructed in the comment.
Also, before running the docker-compose file, ensure that you configure the
SERVERCORE_VERSION build argument in the required Dockerfile accordingly. For example, if you use Windows Server 2019, set the argument to ltsc2019 .
• Version
Decide on the Windows Server version to use. Windows base container images are significantly optimized starting with the Windows Server 2019 version. Using previous versions is not recommended due to the higher resource usage.
However, some Windows containers are not available in 2019 versions yet, such as the Microsoft
SQL Server image. The official Microsoft image only supports Linux Docker containers. Other
Microsoft provided images are not yet available as 2019 versions. Available options to follow are:
• Run in the "process" isolation mode on an operating system for which all prerequisites are available, such as Windows Server 2016, and build based on those images at an additional runtime resource cost.
• Run in the "Hyper-V" isolation mode with optimal settings for each container with the overhead of running virtual machines.
• Deploy third-party images that are not available in the optimal version (MS SQL Server) on a different computer. In this case, the official Microsoft image (Linux) is recommended.
• Wait for a Microsoft SQL Server version to become available based on "servercore:2019ltsc" or later.
• Wait for Windows Docker to support running Windows and Linux containers at the same time on a computer in the "process" isolation mode.
As running all components on one computer is not intended for production, we recommend that you use a hybrid Kubernetes cluster or a different form of a hybrid setup if Windows Docker containers are needed.
Prerequisites for RoboServer
Before running the docker-compose file with RoboServer included, in the Kofax RPA installation folder, navigate to the docker-win\roboserver folder. In the folder, locate and run the copy_fonts.ps1
script to copy Windows system fonts to the roboserver\Fonts folder.
45
Kofax RPA Administrator's Guide
Prerequisites for Kofax Analytics for RPA
Before running the docker-compose file with Kofax Analytics for RPA included, follow these steps:
1.
In the Kofax RPA installation folder, navigate to the docker-win\kafrpa folder, locate and run the copy_fonts.ps1
script to copy Windows system fonts to the docker-win\kafrpa
\Insight\Fonts folder.
2.
Rename the Kofax Analytics for RPA project bundle to kafrpa_bundle.zip
and copy it to the docker-win\kafrpa\Insight folder.
3.
Rename the Insight installation package to KofaxInsightSetup.msi
and copy it to the dockerwin\kafrpa\Insight folder.
4.
Obtain the required license file Altosoft.Insight.License.xml
and copy it to the dockerwin\kafrpa folder.
Prerequisites for Document Transformation Service
Before running the docker-compose file with Kofax Analytics for RPA included, follow these steps:
1.
In the Kofax RPA installation folder, navigate to docker-win\compose-examples , open the docker-compose-dt.yml
file, and then change the following line as applicable.
DT_LICENSE_SERVER=put-your-license-server-here.example.com # Kofax license server
2.
Copy the changed docker-compose-dt.yml
file to docker-win\documenttransformation .
3.
Copy the NLP bundles KofaxTransformation-6.3.1.0_NLP-LanguageBundles
( KofaxTransformation_Salience6.4_LanguageBundle_extended.msi
,
KofaxTransformation_Salience6.4_LanguageBundle_western-default.msi
, and
KofaxTransformation_Salience6.4_LanguageBundle_western-extended.msi
) to docker-win\documenttransformation .
4.
Copy KofaxRPADocumentTransformationService-11.4.0.0.msi
to docker-win
\documenttransformation .
Deploy Kofax RPA using docker-compose files
This topic provides basic steps for deploying Kofax RPA on a standalone server under a Linux-based or Windows-based system. For information on the composition of the example docker-compose files for Windows and Linux supplied by Kofax RPA, see the next section.
Currently, Docker Compose Version 2 uses a docker compose syntax. However, it still supports docker-compose features, and aliasing of docker-compose syntax to docker compose is enabled by default. You can run Compose V2 by replacing the hyphen ( ) with a space, using docker compose instead of docker-compose . For more information, see the Docker documentation .
To deploy Kofax RPA using a docker-compose file, perform the following steps:
1.
Install Kofax RPA on your computer.
46
Kofax RPA Administrator's Guide
2.
Download Docker from https://www.docker.com
and install it on your computer.
3.
Only applicable to Linux . Add a new user to the docker group. For example, to add a
"Kofax" user and allow the user access to Docker containers, replace docker:x:<n> with docker:x:Kofax in the /etc/group file. Log out and log in or restart the computer to update privileges.
4.
In the compose-examples folder, select the
folder, renaming the file to docker-compose.yml
when necessary.
For example, if you work on Windows, copy the docker-compose.yml
file from C:\Program
Files\Kofax RPA 11.4.0.0\docker-win\compose-examples to C:\Program Files
\Kofax RPA 11.4.0.0
.
5.
Edit the docker-compose file as applicable to your environment and your needs.
You can add license information to docker-compose.yml
in the CONFIG_LICENSE_ variables and then start the Kofax RPA services. From the product installation folder, run the following command to build an image, start the services, and set the name "kofaxrpa" for the current container.
docker-compose -p kofaxrpa up -d
Once the Management Console is running, you cannot change the license. To change the license settings, stop the composition and update the license variables in the dockercompose file. If the license settings are not included in the docker-compose file, you can change them in the Management Console without stopping the container.
Use the following default admin superuser name and password to connect to the
Management Console:
User name: admin
Password: admin
The first time you build the image, it may take some time to prepare it.
You can use separate commands to build an image and to start the services as follows.
Because the tags on Docker Hub include the build numbers, the docker-compose files use the "latest" image by default.
• To build an image.
• For Linux: docker build -f docker/managementconsole/Dockerfile -t managementconsole:11.4.0.0 .
• For Windows: docker build -f docker-win\managementconsole\Dockerfile -t managementconsole:11.4.0.0 .
Note the space and period at the end of line. The period refers to the current directory.
• To start the services.
For both Linux and Windows: docker-compose –p kofaxrpa up –d
47
Kofax RPA Administrator's Guide
After you ran the docker-compose file, as soon as it starts the containers, you should be able to open your Docker host, which, by default, is located at http://localhost , and see that a
Management Console is running with a RoboServer in a separate container. Additionally, you should be able to access other Kofax RPA containerized components that were included in the dockercompose file.
In RPA version 11.2 and later RoboServer writes logs in UTC time. RoboServers version prior to 11.2 by default write logs in local server time, which can lead to inconsistences in timestamps if both 11.2 and earlier versions of RoboServer log to the same logging database. If you connect
RoboServers version prior to 11.2 to a Management Console version 11.2 or later, you can configure them to write log messages in UTC time instead of local server time by specifying the following option in the roboserver-service>environment section of the Docker configuration file:
- WRAPPER_JAVA_ADDITIONAL_1=-DwriteLogdbUtc=true
Note that the RoboServer must be updated to a fixpack version that supports this parameter. See the corresponding RPA fixpack readme file for details.
The following sections provide detailed information about docker-compose examples and configuration settings.
Docker-compose examples
Kofax RPA includes several docker-compose files with a few simple configurations in the docker/ compose-examples folder. For Windows, the files are located in docker-win\compose-examples .
For Linux, all of the following examples rely on MySQL as the configuration database for
Management Console. Although Management Console can run on other databases, MySQL is recommended for Management Console configuration data. Documentation for the MySQL docker images is available at https://hub.docker.com/_/mysql/ . For Windows, the compose examples rely on Microsoft SQL Server as the configuration database.
For logging and robot data storage, any of the supported databases can be used. See "Supported
Platforms" in the Kofax RPA Installation Guide .
The following docker-compose files are provided for a Linux environment .
docker-compose-basic.yml
This configuration starts a Management Console, a RoboServer, a MySQL database, and connects them. Before you start this configuration, you might want to enter your license information into the compose configuration to avoid having to type it upon Management Console startup. To scale the amount of RoboServers (in the "Production" cluster), use the following command.
docker-compose -p kofaxrpa up -d --scale roboserver-service=2 docker-compose-ha.yml
This configuration starts a Management Console, a RoboServer, a MySQL, and a load balancer based on the lightweight Traefik image.
48
Kofax RPA Administrator's Guide
Management Console is configured to run with High Availability enabled using multicast discovery
(requires enterprise license). For more information, see Run on Docker Swarm with Management
Console in High Availability .
Multicast discovery requires a network overlay that supports UDP multicast.
For this configuration to work optimally, enter your license information into the docker-compose file before bringing up the services. Also, edit the following line to fit the network assigned to your containers:
- CONFIG_CLUSTER_INTERFACE=172.20.0.*
Execute the following steps to find out which network is used.
1.
Start the composition.
docker-compose -p kofaxrpa up -d
2.
List the started containers.
docker container ls
3.
Use the following command to get the host name.
docker exec kofaxrpa-managementconsole-service-1 hostname -i
4.
Stop the composition before editing the docker-compose file.
docker-compose -p kofaxrpa down
Wildcards can be used, so the IP address may be similar to 172.*.*.* . Note that hazelcast does not accept wildcards instead of all numbers, and therefore *.*.*.* is not allowed.
When starting the composition, you can scale the number of running Management Console instances using the following command.
docker-compose -p kofaxrpa up -d --scale managementconsole-service=2
Running more than two instances of Management Console is possible, but doing so increases the database load. The load balancer is set up to use sticky sessions.
docker-compose-kapplets.yml
This configuration starts a Management Console, a RoboServer, a MySQL database, and also adds
Kofax RPA Kapplets and configures them.
docker-compose-ldap.yml
This is an example configuration that uses LDAP. It starts the OpenLDAP command in a container, which is normally not needed but is included as an example.
A related file, ldap_ad_content.ldif
, is also included for testing purposes. Test this composition by running the following command.
docker-compose -p kofaxrpa up -d && docker -vv cp ./docker/compose-examples/ ldap_ad_content.ldif kapow_ldap-service_1:/ldap_ad_content.ldif && docker exec kapow_ldap-service_1 ldapadd -x -D "cn=admin,dc=example,dc=org" -w admin -f / ldap_ad_content.ldif
docker-compose-rfs.yml
This configuration starts a Management Console, a RoboServer, a MySQL database, and also adds a
Robot File System and configures it.
49
Kofax RPA Administrator's Guide
Synchronizer
Synchronizer is not included in the docker-compose files for Linux. To build a Synchronizer Docker image, use the following command: docker build -f docker/synchronizer/Dockerfile . -t synchronizer:@productVersion@
If you want to disable the Docker JMX health check, remove the lines in the Dockerfile between:
# ### start cutting here ### and # ### end cutting here ###
The following docker-compose files are provided for a Windows environment .
docker-compose.yml
This configuration starts all of the available Kofax RPA components, except Document
Transformation: Management Console, RoboServer, Synchronizer, Robot File System, Kapplets,
Kofax Analytics for RPA, and a MS SQL database.
docker-compose-dt.yml
This compose file is used to document the parameters used by the Document Transformation
Windows Docker container. If you require Document Transformation, you can use the example docker-compose-dt.yml
file as follows. Before running the file, make sure that you followed the
prerequisites for Document Transformation Service listed in Notes for Windows Docker
.
docker-compose -f .\docker-compose-dt.yml up
Optimize Docker build context size
The information in this section is applicable to Linux only .
We do not recommend building your own images. However, if you do so, this section applies to you.
As all Docker images are built with the distribution root folder as the build context, building the images can take up too much time. To optimize the build context size, dockerignore files are added to the distribution. As every component has different requirements, a separate dockerignore file is provided for every component. The file must be located next to the Dockerfile and follow the same naming convention, except that it must have a .dockerignore
suffix, such as
Dockerfile.dockerignore
.
To use this feature, the build with BuildKit must be enabled. The standard Docker build currently supports only the global .dockerfile
. To enable this feature, set DOCKER_BUILDKIT=1 in the environment, or define it in /etc/docker/daemon.json
.
If you are building with docker-compose , you also need to set COMPOSE_DOCKER_CLI_BUILD=1 in the environment. If you do not build with BuildKit, you can rename the
Dockerfile.dockerignore
file to .dockerignore
and move it into the root of your build context. If you build multiple components, such as with docker-compose , you need to combine the
.dockerignore
content. However, we recommend a build with BuildKit as it is more efficient.
50
Kofax RPA Administrator's Guide
Use Docker secrets feature for storing passwords
To avoid specifying connection passwords directly in the docker-compose file on both Linux and
Windows, you can use the Docker secrets feature to store your passwords in a safe location.
You can use the secrets feature for environment variables.
In the following example, we specify a password to connect to the MySQL database on a Linuxbased environment.
1.
Create a text file with a password in it. One file must contain one password. For this example, we created a mysqlpassword.txt
file that includes a password to the MySQL database.
2.
In the docker-compose file that you want to use, create a section called secrets on the first level (no indent), specify a variable name on the second level, and specify a path to the file with a password on the third level of indent as follows.
secrets:
mysqlpassword:
file: /kapow/linux64dist/mysqlpassword.txt
3.
In the services > mysql-service > environment section of the .yml
file, substitute the
MYSQL_PASSWORD variable with the MYSQL_PASSWORD_FILE variable and specify the variable set in the secrets section as follows: services:
mysql-service:
image: mysql:5
environment:
- MYSQL_ROOT_PASSWORD=mysqlrootpassword
- MYSQL_DATABASE=mysqldatabase
- MYSQL_USER=mysqluser
- MYSQL_PASSWORD_FILE=/run/secrets/mysqlpassword
networks:
- net
4.
On the same level as the environment section under services > mysqlservice , create a secrets section and specify the secrets variable again.
secrets:
- mysqlpassword
Using this procedure as an example, you can set up the secrets feature for other passwords in the docker-compose file.
Set up database
For Kofax RPA, we recommend to store your Management Console configuration and repository data in a containerized database, and add external databases for data storage and (audit-) logs.
However, you might want to store the Management Console internal configuration data in an external or corporate database. To change the Management Console database, correct the environment variables for the database context and add the proper JDBC driver to the image/ container.
51
Kofax RPA Administrator's Guide
In the Dockerfile for Management Console, which resides in docker/managementconsole for
Linux and docker-win\managementconsole for Windows, the following line adds the current
JDBC driver to the Management Console image in the JDBC folder.
Linux: ADD https://repo1.maven.org/maven2/mysql/mysql-connector-java/<version>/ mysql-connector-java-<version>.jar /usr/local/tomcat/lib/jdbc/
Windows: ADD https://clojars.org/repo/com/microsoft/sqlserver/sqljdbc4/4.0/ sqljdbc4-4.0.jar${CATALINA_HOME}/lib/jdbc/ , where CATALINA_HOME=
${KAPOW_HOME}\tomcat\apache-tomcat-@tomcatNumericVersion@ and KAPOW_HOME=c:
\kapow
Change this line or add more lines to the Dockerfile to add the correct JDBC driver and the correct version of the database connector for your Java. Use the latest available version of the driver.
After editing the Dockerfile, you need to rebuild the image by running the following command:
Linux: docker build -f docker/managementconsole/Dockerfile . -t managementconsole:@productVersion@
Windows: docker build -f docker-win\managementconsole\Dockerfile . -t managementconsole:@productVersion@
Or run the simple version: docker-compose -p kofaxrpa up -d
Set up SSL connection to MySQL database
The information in this section is applicable to Linux only . Use the information in this section to establish an SSL connection between a Management Console and a MySQL database. Dockercompose examples supplied by Kofax include two services: mysql and managementconsole . The mysql service is composed based on the mysql docker image. The managementconsole service is composed based on the tomcat docker image. The following procedure explains how to set up an
SSL connection between the two services.
When you start a docker-compose file with an insecure connection to the database, some versions of Tomcat produce a warning if SSL is not set up and explicitly disabled. If you do not want to set up the SSL connection to the database, you can disable the warning by specifying the useSSL=false parameter in the CONTEXT_RESOURCE_URL variable in the docker-compose file, as shown here:
CONTEXT_RESOURCE_URL=jdbc:mysql://mysql-service:3306/scheduler?
useUnicode=yes&characterEncoding=UTF-8&rewriteBatchedStatements=true&useSSL=false
To set up an SSL connection between a Management Console and a MySQL database, perform the following steps:
1.
Configure SSL in MySQL to create certificates (including ca.pem) and keys in the MySQL folder
( /var/lib/mysql ) of the corresponding mysql image. This step is necessary if you do not have your own signed certificate.
MySQL supplies the mysql_ssl_rsa_setup utility that helps you generate all necessary keys and certificates. The mysql image for the docker-compose files supplied by Kofax is configured to create necessary self-signed certificates and keys. When you start a docker-compose file that starts a MySQL service, the ca.pem
file is created in the /var/lib/mysql of the image.
2.
Add ca.pem
to the truststore.
52
Kofax RPA Administrator's Guide
You can use the Java keytool utility to add the certificate to the truststore using the following command.
keytool -importcert -alias MySQLCACert -file /<path to the certificate>/ ca.pem -keystore /<path to the truststore>/truststore -storepass
<password> –noprompt
3.
Make the truststore accessible from the Management Console.
The truststore must be accessible from the Management Console as a local file. For example, you can modify the Dokerfile.managementconsole
file and include a COPY command as follows:
COPY truststore /usr/local/tomcat/
Another way is to mount a directory with the ca.pem
file in the mysql image as a volume to the managementconsole image. Then, run the keytool utility from the managementconsole.sh
file located in the managementconsole folder. ).
4.
Specify the path to and the password of the truststore in the CONTEXT_RESOURCE_URL variable in the docker-compose file. For example:
CONTEXT_RESOURCE_URL=jdbc:mysql://mysql-service:3306/scheduler?
useSSL=true&useUnicode=yes&characterEncoding=UTF-8&rewriteBatchedStatements= true&trustCertificateKeyStorePassword=password&trustCertificateKeyStoreUrl= file:/usr/local/tomcat/truststore
Back up and restore
The information in this section is applicable to Linux only . The Management Console image contains two scripts for backing up and restoring repository and configuration information.
backup.sh
To create a backup to be saved in /kapow/backup , run the following Docker command: docker exec kapow_managementconsole-service_1 backup.sh [options]
The following script usage options are available: backup.sh [options]
Options
Option
-u, --username
-p, --password
-h, --host
-i, --project <Id>
-c, --configurationOnly <Id>
Description
Required . The user name to use when calling a
Management Console.
Required . The password to use when calling a
Management Console.
The hostname for a Management Console (default: localhost).
Project ID to use for backing up only a specific project.
An ID to back up only the configuration and no project data.
53
Kofax RPA Administrator's Guide
Option
-n, --postfix
Description
Sets the postfix for the created backup file (default is
<datetime>).
restore.sh
To restore a backup saved in /kapow/backup , run the following docker command: docker exec kapow_managementconsole-service_1 restore.sh [options]
The following script usage options are available: restore.sh [options]
Options
Option
-u, --username
-p, --password
-h, --host
-f, --filename
-a, --path
Description
Required . The username to use when calling a
Management Console.
Required . The password to use when calling a
Management Console.
The host name for a Management Console (default: localhost).
Required . The name of the backup file to restore.
The path to the backup file to restore (default: / kapow/backup/ ).
Pre-start checks
When starting a container, the ManagementConsole image, by default, runs the following checks.
1.
Checks that the database configuration works by connecting to the database using the provided JDBC URI. It also tries to run the validation query once.
2.
Checks that the LDAP configuration works. If LDAP is configured, each of the LDAP directories is checked by trying to connect and bind, and running a query to retrieve all groups. You can expand this test for debugging or validation purposes by adding a test username to use for more lookups.
If a check fails, the image retries for a configurable amount of time. If one of the checks does not succeed within the configured timeout, the container exits and you can review your configuration parameters.
You can bypass a check by setting the timeout for the check to zero (0). See the
section for more information.
Data folders
Logs, database data, and configuration from the containers are stored in folders listed below. To avoid having your container grow, these folders should be mounted to a volume or to the local file system. See the Docker documentation on volumes.
54
Kofax RPA Administrator's Guide
Logs, database, and other data stored on these volumes cannot be reused when upgrading the version of Kofax RPA.
RoboServer
Data, logs, and configuration from the RoboServer container reside in the following folder:
Linux: /kapow/data
Windows: C:\kapow\data
ManagementConsole
Tomcat logs reside in the following folder:
Linux: /usr/local/tomcat/logs
Windows: C:\kapow\tomcat\apache-tomcat-<tomcatVersion>\logs
Environment variables
The following table lists some commonly used variables that you need to set up when deploying
RPA using Docker. You can find the complete list of environment variables for different Docker containers relative to docker-compose files in the readme.md
file, which resides in the docker folder inside your Kofax RPA installation.
Variable
RFS_MC_PASSWORD_FILE
Default value
( )
Description
ROBOSERVER_MC_PASSWORD_FILE ( )
The path to a file containing the password for the Management Console, this could be a docker secret.
The path to a file containing the password when registering with the
Management Console
Convert group names to upper-case.
LOGIN_LDAP_DIRECTORY_CONVERTTOUPPERCASE_N (true)
Variables for logging
LOG4J_LOGGER_ADDITIONAL_COUNT (0) The number of additional properties to add to the log4j.properties file.
The syntax of the log4j configuration changed. log4j2 is now used. Check the log4j2.properties syntax and specify your parameters accordingly.
LOG4J_LOGGER_ADDITIONAL_KEY_N ( ) The key of the additional property N., for example:
LOG4J_LOGGER_ADDITIONAL_KEY_1
55
Kofax RPA Administrator's Guide
Variable
LOG4J_LOGGER_ADDITIONAL_VALUE_N
Default value
( )
Description
The value of the additional property
N. If you want to set logging level to debug, specify DEBUG as the value. See
"Example: Values for debug logging" below.
Example: Values for debug logging
The following example sets logging to debug level and writes detailed logging information to a file on a tomcat server. See Apache Log4j 2 on the apache.org website for details.
The syntax of the log4j configuration changed. log4j2 is now used. Check the log4j2.properties syntax and specify your parameters accordingly.
- LOG4J_LOGGER_ADDITIONAL_COUNT=10
- LOG4J_LOGGER_ADDITIONAL_KEY_1=rootLogger.level
- LOG4J_LOGGER_ADDITIONAL_VALUE_1=DEBUG
- LOG4J_LOGGER_ADDITIONAL_KEY_2=logger.spring.level
- LOG4J_LOGGER_ADDITIONAL_VALUE_2=DEBUG
- LOG4J_LOGGER_ADDITIONAL_KEY_3=appenders
- LOG4J_LOGGER_ADDITIONAL_VALUE_3=A, file
- LOG4J_LOGGER_ADDITIONAL_KEY_4=appender.file.type
- LOG4J_LOGGER_ADDITIONAL_VALUE_4=File
- LOG4J_LOGGER_ADDITIONAL_KEY_5=appender.file.name
- LOG4J_LOGGER_ADDITIONAL_VALUE_5=file
- LOG4J_LOGGER_ADDITIONAL_KEY_6=appender.file.fileName
- LOG4J_LOGGER_ADDITIONAL_VALUE_6=/usr/local/tomcat/logs/output.log
- LOG4J_LOGGER_ADDITIONAL_KEY_7=appender.file.layout.type
- LOG4J_LOGGER_ADDITIONAL_VALUE_7=PatternLayout
- LOG4J_LOGGER_ADDITIONAL_KEY_8=appender.file.layout.pattern
- LOG4J_LOGGER_ADDITIONAL_VALUE_8=%d{HH:mm:ss,SSS} %-5p %c %equals{%x}{[]}{} - %m%n
- LOG4J_LOGGER_ADDITIONAL_KEY_9=rootLogger.appenderRefs
- LOG4J_LOGGER_ADDITIONAL_VALUE_9=A, file
- LOG4J_LOGGER_ADDITIONAL_KEY_10=rootLogger.appenderRef.file.ref
- LOG4J_LOGGER_ADDITIONAL_VALUE_10=file
56
Kofax RPA Administrator's Guide
Run on Docker Swarm with Management Console in High Availability
The following procedure and setup are intended only as an example and should not be considered a recommendation.
The example in this section demonstrates how to set up Kofax RPA on a Docker swarm with more than one instance of Management Console (with
High Availability mode enabled).
This section contains an example of setting up a Docker swarm that consists of two nodes, manager and worker, which provide a higher level of fault tolerance than using only one node. The example uses PostgreSQL.
The Management Console can run as several instances in a cluster, sharing configuration, log and repository data through a database, and sharing the cluster volatile state through the Hazelcast platform. This platform requires each instance of the Management Console to be able to discover and connect to the other instances in the cluster. The two discovery methods that are currently implemented are multicast and TCP. In this example procedure, we use the multicast (UDP) discovery method. The TCP discovery method was also successfully tested.
To make multicast UDP work in a Docker swarm, the Weave Net plugin 2.5.1 is used in this procedure.
Set up a minimal Docker swarm with Management Console
Before proceeding, ensure that you have two Docker hosts running with Linux kernel 3.8 or higher.
In this procedure, the hosts are referred to as host1 and host2 .
1.
Set up your Docker swarm cluster.
a.
Create a manager node on host1 .
host1$ docker swarm init --advertise-addr <host1_IP> b.
Join host2 into the swarm as worker node.
host2$ docker swarm join --token <token> --advertise-addr <host2_IP>
<host1_IP>:<port>
Replace <token> with the token retrieved from the first command.
2.
Install the Weave Net plugin on the two hosts and enable the multicast feature as follows.
host1$ docker plugin install store/weaveworks/net-plugin:2.5.2 --grant-allpermissions --disable host1$ docker plugin set store/weaveworks/net-plugin:2.5.2 WEAVE_MULTICAST=1 host1$ docker plugin enable store/weaveworks/net-plugin:2.5.2
host2$ docker plugin install store/weaveworks/net-plugin:2.5.2 --grant-allpermissions --disable host2$ docker plugin set store/weaveworks/net-plugin:2.5.2 WEAVE_MULTICAST=1 host2$ docker plugin enable store/weaveworks/net-plugin:2.5.2
3.
On your manager node, create a Docker network using the Weave Net plugin as the driver as follows.
host1$ docker network create --driver=store/weaveworks/net-plugin:2.5.2 -attachable weavenet
57
Kofax RPA Administrator's Guide
4.
Build the Management Console and RoboServer Docker images on all of the nodes in your
Docker swarm. With a Docker repository, you can push the images to it. For information on building the Docker images, see
Docker Tools for Kofax RPA Deployment .
5.
Create a file called docker-compose.yml
, adapting the following lines to your environment.
version: '3.2'
networks:
net:
external:
name: weavenet
services:
loadbalancer:
image: traefik
command: --docker --docker.swarmmode --docker.watch --web --loglevel=DEBUG
ports:
- 80:80
volumes:
- /var/run/docker.sock:/var/run/docker.sock
networks:
- net
deploy:
mode: global
placement:
constraints: [node.role == manager]
postgres-service:
image: postgres:10
environment:
- POSTGRES_USER=scheduler
- POSTGRES_PASSWORD=schedulerpassword
- POSTGRES_DB=scheduler
networks:
- net
managementconsole-service:
image: managementconsole: @productVersion@
depends_on:
- postgres-service
environment:
- CONTEXT_RESOURCE_VALIDATIONQUERY=SELECT 1
- CONTEXT_RESOURCE_USERNAME=scheduler
- CONTEXT_RESOURCE_PASSWORD=schedulerpassword
- CONTEXT_RESOURCE_DRIVERCLASSNAME=org.postgresql.Driver
- CONTEXT_RESOURCE_URL=jdbc:postgresql://postgres-service:5432/scheduler
# enter your license here, or type it through the GUI in first login
- CONFIG_LICENSE_NAME=
- CONFIG_LICENSE_EMAIL=
- CONFIG_LICENSE_COMPANY= @licenseCompany@
- CONFIG_LICENSE_PRODUCTIONKEY= @licenseProduction@
- CONFIG_LICENSE_NONPRODUCTIONKEY= @licenseNonProduction@
- CONFIG_CLUSTER_JOINCONFIG=multicastCluster
# change to fit your network
- CONFIG_CLUSTER_INTERFACE=10.*.*.*
- CONFIG_CLUSTER_MULTICAST_GROUP=224.2.2.3
- CONFIG_CLUSTER_MULTICAST_PORT=54327
- LOG4J_LOGGER_COM_HAZELCAST=ERROR, A
deploy:
replicas: 2
labels: traefik.docker.network: weavenet
traefik.port: 8080
traefik.backend.loadbalancer.sticky: "true"
traefik.frontend.rule: PathPrefix:/
networks:
58
Kofax RPA Administrator's Guide
- net roboserver-service:
image: roboserver: @productVersion@
depends_on:
- postgres-service
networks:
- net
environment:
- ROBOSERVER_ENABLE_MC_REGISTRATION=true
- ROBOSERVER_MC_URL=http://loadbalancer/
- ROBOSERVER_MC_CLUSTER=Production
- ROBOSERVER_MC_USERNAME=admin
- ROBOSERVER_MC_PASSWORD=admin
- ROBOSERVER_ENABLE_SOCKET_SERVICE=true
- WRAPPER_MAX_MEMORY=2048
If you are copying the file, make sure to keep the original layout. Incorrect layout may result in an invalid file.
Also note:
• Replace @productVersion@ , @licenseCompany , @licenseProduction@ , and
@licenseNonProduction@ with your appropriate values.
• CONFIG_CLUSTER_INTERFACE must fit the Weave Net subnet in your Docker swarm. You can find the subnet using the following command on your manager node: host1$ docker network inspect weavenet
• The common network net refers to the external network weavenet that you created before.
• Traefik is used as the load balancer with sticky sessions.
• This setup runs a PostgreSQL database on a temporary volume. In a real production setup, the database also needs to be run clustered and with a permanent data volume.
• To run multiple instances of the RoboServer, you can add deployment constraints to roboserver-service .
• All services must use endpoint_mode: dnsrr (the default setting endpoint_mode: vip is not supported by the Weave Net plugin)
6.
Deploy the service stack on the manager node as follows.
host1$ docker stack deploy -c docker-compose.yml rpa
Starting managementconsole-service with two replicas on an empty database may lead to a race condition. If you experience this situation, change the line replicas: 2 to replicas:
1 and run the preceding command. Wait until the services are started, change the line back, and then run the preceding command again.
To stop the services, use the following command.
host1$ docker stack down rpa
7.
After deploying the stack, the Management Console can be accessed at the following URL.
http://host1/
59
Kofax RPA Administrator's Guide
Advanced Configuration
LDAP and CA Single Sign-On Integration
This topic describes how to use LDAP and CA Single Sign-On authentication.
Also, Kofax RPA supports LDAPS (LDAP over SSL). See "Secure LDAPS" and "Checklist for solving SSL connection errors when using LDAPS " later in this section.
User origin and authentication
A user that logs to a Management Console is identified by a user name and origin. The User origin field on the Users & groups page of the Management Console contains information about the user creation method as in the following table.
User origin unknown internal saml siteminder ldap#{ldapDirectoryIdentifier}
Description
The user was created after restoring a backup.
The user was created manually on the Users &
Groups page.
The user was created after logging via SAML.
The user was created after logging via SiteMinder.
The user was created after logging via LDAP.
Note the following for user authentication.
• If a user logs in and there is another user with the same name and unknown origin, the origin is changed to the one based on the current log in and a new user is not created.
• If you do not use any of the external identity providers, such as SAML, LDAP, or SiteMinder, you can change unknown origin to internal by clicking Set internal origin for the selected user on the Users & groups page in the Management Console.
• ldapDirectoryIdentifier is a required property in login.xml.
• LdapDirectory is optional and defaults to 0 (zero) if not explicitly assigned.
• The Management Console does not start if there are more than one LDAP Directory with the same ldapDirectoryIdentifier .
• You can use LDAP and SAML authentication at the same time by specifying true for the useLdap and useSaml options in the authenticationConfiguration bean in login.xml.
• When using both LDAP and SAML authentication, SAML is used for SSO in the Management
Console and LDAP is used for services authentication, such as connecting to Design Studio and so forth.
LDAP Integration
To use LDAP for authentication, enable the LDAP authentication and edit the LDAP definition in the login.xml
file.
60
Kofax RPA Administrator's Guide
To enable the LDAP authentication, set the useLdap property to true as follows:
<bean id="authenticationConfiguration"
class="com.kapowtech.scheduler.server.spring.security.AuthenticationConfiguration">
<property name="useLdap" value="true"/>
<property name="useSiteMinder" value="false"/>
</bean>
In login.xml
, you can find the following definition:
<bean id="ldapDirectories" class="com.kapowtech.mc.config.LdapDirectories" lazyinit="true">
<property name="directories">
<list>
<bean class="com.kapowtech.mc.config.LdapDirectory">
<!-- Property defining unique ldap directory name, used as part of
user's origin field.
Must be different for each LdapDirectory -->
<property name="ldapDirectoryIdentifier" value="0"/>
<!-- List of security groups which will be application
administrators.
Users in these groups will have all permissions. Only users in
these groups can
access the backup tab and create and restore backups -->
<property name="adminGroups">
<list>
<value>KAPOWADMIN</value>
<value>ENGINEERING/value>
<property name="administratorGroups">
<list>
<value>RPAADMINISTRATORS</value>
</list>
</property>
</property>
<property name="ldapServerURL" value="ldap:// ldap.kapowdemo.com:389"/>
<property name="userDn" value="CN=LDAP
test,CN=Users,DC=kapowdemo,DC=local"/>
<property name="password" value="change-me"/>
<property name="userSearchBase"
value="OU=Users,OU=TheEnterprise,DC=kapowdemo,DC=local"/>
<property name="userSearchFilter"
value="(userPrincipalName={0}@kapowdemo.local)"/>
<property name="userSearchSubtree" value="true"/>
<property name="groupSearchBase" value="OU=Security
Groups,OU=TheEnterprise,DC=kapowdemo,DC=local"/>
<property name="groupSearchFilter" value="(member={0})"/>
<property name="groupRoleAttribute" value="cn"/>
<property name="groupSearchSubtree" value="true"/>
<property name="allGroupsFilter" value="(cn=*)"/>
<property name="fullNameAttribute" value="displayName"/>
<property name="emailAttribute" value="userPrincipalName"/>
<property name="referral" value="follow"/>
</bean>
</list>
</property>
</bean>
This defines a list of ldapDirectory beans named ldap and represents a list of connections to LDAP servers. Kofax RPA supports multi-forest LDAP integration, so you can specify several connections to LDAP directories. Each bean defines a number of properties that controls the LDAP
61
Kofax RPA Administrator's Guide integration. If you are familiar with the way Tomcat integrates to LDAP, this should be quite familiar as well.
Group names must be unique across all LDAP servers in the list.
Secure LDAP
Kofax RPA supports LDAPS (LDAP over SSL) with Management Console. To use LDAPS, the ldapServerURL property must be set as follows:
<property name="ldapServerURL" value="ldaps://<hostname>:<port>"/>
By default, the LDAPS port is 636.
Deployment Checklist
Property ldapDirectoryIdentifier adminGroups administratorGroups ldapServerURL userDn password userSearchBase userSearchFilter userSearchSubtree groupSearchBase groupSearchFilter groupRoleAttribute groupSearchSubtree convertToUpperCase allGroupsFilter fullNameAttribute emailAttribute referral
Description
An LDAP directory name, used as part of user's origin field in a Management
Console. This name must be unique for each LDAP Directory.
List of LDAP groups mapped to the admin superuser in Management Console who has access to everything.
List of LDAP groups mapped to RPA Administrators in Management Console.
Users belonging to these LDAP groups have all rights for all projects (excluding special admin user rights), such as mapping of LDAP groups to roles in
Management Console.
URL to the LDAP server. This uses either the ldap:// or ldaps:// protocol.
DN (distinguished name) used to log in to LDAP to authenticate other users.
Password for the userDN account. As the password will be stored in clear text in this file you should use an account that only has 'read' access.
Subdirectory in the LDAP tree where users can be found.
Filter that is applied to find the username.
Set to true if users may be located in the subdirectory of the userSearchBase.
Subdirectory in the LDAP tree where groups can be found.
Filter that is applied to identify the users in this group.
Attribute that holds the group name.
Set to true if groups may be located in the subdirectory of the groupSearchBase
Should the group names be converted to upper case, true by default.
Optional. Controls which groups are displayed when creating project permissions, see below.
Attribute to fetch the full name of the user.
Attribute to fetch the email of the user.
Set to "follow" to allow redirection to sub nodes in the LDAP tree.
62
Kofax RPA Administrator's Guide
To use an LDAP account to administer a Management Console, you must add one of the groups that you are a member of to the administratorGroups bean in login.xml
, as described in
Permissions . Note that anyone who is a member of a group listed in
administratorGroups is the
Management Console administrator, so you may want to create a new LDAP group for this purpose.
Use the upper case group name if convertToUpperCase is true.
When you select a project permission in the Management Console, you can see that all the group names are pulled from LDAP to populate the list. The groups are located by using the groupRoleAttribute to construct a filter to fetch all groups. Sometimes you do not want all LDAP groups displayed here, in which case override this behavior by providing your own filter. This is done by adding an additional property to the LdapLogin.
<property name="allGroupsFilter" value="(cn=*)"/> : Finds all group names, if the group name is in the cn attribute (this is the default).
If you only want to find groups starting with the letter 'e' you can use the following code
<property name="allGroupsFilter" value="(cn=E*)"/>
The filter uses basic LDAP queries. See LDAP documentation for more complex queries.
Checklist for solving SSL connection errors when using LDAPS
If you experience errors connecting using LDAPS, check the following:
• LDAPS requires that the certificate presented by the LDAP server is trusted by the java running the tomcat. Import the public certificate to the Java keystore that your application uses.
• Make sure certificates are imported into the correct truststore, such as if you have multiple instances of JRE or JDK.
• Make sure the correct truststore is in use. If -Djavax.net.ssl.trustStore
is configured, it overrides the location of the default truststore.
• If connecting to a mail server, such as Exchange, ensure that authentication allows plain text.
• Verify that the target server is configured to serve SSL correctly. This can be done with the SSL
Server Test tool.
• Check if your anti virus tool has "SSL Scanning" that blocks SSL and TLS. Disable this feature or set exceptions for the target addresses.
CA Single Sign-On Integration
Management Console supports pre-authentication using CA Single Sign-On. With CA Single Sign-
On the identity of the user is established before accessing a Management Console, and the user's identity is communicated through an HTTP header. The identity of the user must be in the form of an LDAP distinguished name for a Management Console to resolve the user's LDAP group memberships.
CA Single Sign-On integration is disabled by default. You can enable it by setting the useSiteMinder property to true in the login.xml
file as follows:
<bean
class="com.kapowtech.scheduler.server.spring.security.AuthenticationConfiguration"
id="authenticationConfiguration">
<property name="useLdap" value="false"/>
<property name="useSiteMinder" value="true"/>
63
Kofax RPA Administrator's Guide
</bean>
<bean class="com.kapowtech.mc.config.SiteMinderConfiguration"
id="siteMinderConfiguration">
<property name="headerName" value="sm_userdn"/>
<property name="accountAttribute" value="sAMAccountName"/>
<property name="accountAttributePattern" value="(.*)"/>
</bean>
After you enable the CA Single Sign-On integration, specify the name of the HTTP header that contains the user's distinguished name. The accountAttribute property identifies which of the user's LDAP attributes is used as an account name (The default uses the sAMAccountName , which is the user's Windows login name). The accountAttributePattern property specifies how the account name is parsed from the attribute value, which must be a regular expression
(with a single set of parentheses identifying the account name), and the (.*) value in the accountAttributePattern property means everything in the attribute. To extract the account name from the user's email address in the configuration, you can specify the following:
<bean class="com.kapowtech.mc.config.SiteMinderConfiguration"
id="siteMinderConfiguration">
<property name="headerName" value="sm_userdn"/>
<property name="accountAttribute" value="userPrincipalName"/>
<property name="accountAttributePattern" value="([^@]*)@.*"/>
</bean>
([^@]*)@.* will match an email address and extract everything before @ as the account name.
As CA Single Sign-On uses part of the LDAP login configuration, you need to add a user group to the administratorGroups bean, before you can start configuring the Management Console.
It is not possible to log out of the system, as the presence of the CA Single Sign-On header means that you are always authenticated. To log out, close your browser.
Limitations
CA Single Sign-On integration only works when a Management Console is accessed through a browser. However, if a Management Console is accessed by applications that are not browsers, the CA Single Sign-On authentication mechanism is not used and such services require a set of credentials (username and password) set in the Management Console. These clients include, but are not limited to, the following:
Design Studio
Robot developers need to access Management Console to obtain a developer seat license, to upload robots, and get database configurations and other settings stored in the Management
Console. This requires access to the following URLs (relative to the context path where
Management Console is deployed).
• /License/*
• /secure/*
• /IDESettings/*
• /rest/*
• /ws/*
Access to the URLs above is protected by basic authentication with passwords set in the
Management Console.
64
Kofax RPA Administrator's Guide
REST services
REST services are protected by basic authentication by default, but robots can be exposed without authentication as REST services. Such services are typically invoked by external applications. REST uses /rest/* URL.
RoboServer
RoboServer is protected by basic authentication for registering to a cluster and for resource requests.
Desktop Automation service
Desktop Automation service is protected by basic authentication for registering and status updates.
Any application based on Kofax RPA Java or .Net API
Any application based on Kofax RPA Java or .Net API is protected by basic authentication when accessing a Management Console.
Example: Usage
• Jane is the designated Management Console administrator. Because she is added to the
Administrators group in the Active Directory (AD), this group is mentioned in login.xml
, and once she authenticates her browser with CA Single Sign-On, she is immediately logged in to the
Management Console.
• John is a robot developer who is a member of the group Users in the AD and currently he is declined when trying to log in to the Management Console.
Jane need to assign privileges to the Users group in the Management Console > Admin > Projects for the selected project before John can log in. For example, the Users group can be assigned a
Developer role as shown here.
65
Kofax RPA Administrator's Guide
Now John can log in to the Management Console using CA Single Sign-On.
When John starts Design Studio, he needs to enter his credentials to acquire a license.
Jane can also create local service users that are never allowed to log in to the Management Console, such as for the RoboServer service or Desktop Automation Service. Note the following:
• The groups you select for service users must originate only from Active Directory.
• The group must have the appropriate privileges set in the Management Console.
SAML Single Sign-On Integration
Management Console supports user pre-authentication using SAML Single Sign-On.
The following procedure is written with the assumption that you have already created and configured a SAML application in your identity provider. For an example configuration procedure,
see Example OneLogin Configuration
.
Management Console with SAML integration cannot start without a license. Install a valid license before you can use the application.
Integration of the Management Console with SAML Single Sign-On is disabled by default. To enable it, in the login.xml file, locate and set the useSaml property to true .
You can use LDAP and SAML authentication at the same time by specifying true for the useLdap and useSaml options in the authenticationConfiguration bean in login.xml. See
User origin and authentication for details.
<bean
class="com.kapowtech.scheduler.server.spring.security.AuthenticationConfiguration"
id="authenticationConfiguration">
<property name="useLdap" value="false"/>
<property name="useSiteMinder" value="false"/>
66
Kofax RPA Administrator's Guide
<property name="useSaml" value="true"/>
After you enable the integration in login.xml
, you need to configure the identity provider and the service provider settings. In the saml.xml
file located in the folder \WEB-INF\spring , modify the following properties to match your setup.
After changing the login.xml
and saml.xml
files, restart Tomcat.
Property assignGroups forceAuthN groupsAttributes adminGroups administratorGroups email firstname lastname idpName idpGroupNameSeparator idpUserNameRegex entityId entityBaseURL
Description
When set to false , the administrator manually assigns users to the groups, so that they have access to Management Console.
Default is true .
When set to true , the identity provider re-authenticates users and does not rely on previous authentication events. Default is false .
Group attribute. User access to Management Console is managed by means of groups that a particular user belongs to. Specify a name or a list of names matching attribute names in SAML Assertion message that contains the list of groups assigned to a user in the identity provider.
Admin groups. List of identity provider groups mapped to the admin superuser in Management Console who has access to everything.
Administrator groups. The users in this group get administrative rights to all of the RPA projects. Also, it is possible to create custom administrator groups using SAML. For more information on the user roles and groups, see "Predefined User Roles" in the
Kofax RPA Administrator's Guide.
This is the name of the attribute from the SAML Response that contains the user's email.
This is the name of the attribute from the SAML Response that contains the user's first name.
This is the name of the attribute from the SAML Response that contains the user's last name.
Name of the identity provider. Possible values are OKTA ,
ONELOGIN , and AZURE . Otherwise, set to DEFAULT .
Delimiter to use to separate identity provider group names.
Takes effect only if the identity provider specified with idpName is OneLogin. Otherwise, this property is ignored.
Update the existing parameter by adding the ^[\p{L}0-9 ]*$ pattern if some of the user names contain special characters.
URL of a Management Console, plus saml/login . You can get this URL from your SAML application. For example: http:// localhost:8080/ManagementConsole/saml/login
Base URL of a Management Console. For example: http:// localhost:8080/ManagementConsole
67
Kofax RPA Administrator's Guide
Property maxAuthenticationAge responseSkew maxAssertionTime java.lang.String
of
HTTPMetadataProvider bean java.io.File
of
FilesystemMetadataProvider bean useSamlSingleLogout
Description
Validity of single sign-on in seconds. Time window allowed for users to sign in after they are initially authenticated with the identity provider. By default, it is 86400 seconds, which is 24 hours.
Use this property to change the default.
Inaccuracy tolerance in seconds for comparing clocks between the identity provider server and the computer where
Management Console is deployed. As the clock synchronization may not be fully accurate, a tolerance of 60 seconds is applied by default.
Use this property to change the default.
Validity of assertions processed during the single sign-on. If the assertion time reaches the configured limit, the authentication becomes invalid. By default, it is limited to 6000 seconds, which is 100 minutes.
Use this property to change the default.
URL to the identity provider metadata. You can get this URL from your SAML application. For example: http://example.okta.com/saml/ metadata/222670a0-2b96-48ef-975a-b7267446d09e
Some identity providers, such as Microsoft Azure, do not require this property.
Path to the XML file containing the identity provider metadata.
Use this property if your identity provider does not allow reading of metadata in real time.
Some identity providers, such as OneLogin, do not require this property.
If set to true , the user logs out of the SAML application in your identity provider when clicking Logout in Management Console.
Default is false .
The following snippets from the example saml.xml
file contain the properties you need to configure.
<bean id="samlEntryPoint" class="org.springframework.security.saml.SAMLEntryPoint"
lazy-init="true">
<property name="defaultProfileOptions">
<bean class="org.springframework.security.saml.websso.WebSSOProfileOptions">
<property name="includeScoping" value="false"/>
<property name="forceAuthN" value="false"/>
<property name="passive" value="false"/>
</bean>
</property>
<property name="filterProcessesUrl" value="/saml/entry"/>
</bean>
<bean id="samlAuthenticationProvider" class="com.kapowtech.scheduler.server.spring.sec urity.GroupProvidingSAMLAuthenticationProvider" lazy-init="true"> <constructor-arg ref
="platformEMF"/>
<property name="internalAuthenticationProvider"
ref="internalAuthenticationProvider"/>
<property name="customerNameMapper" value="false"/>
<property name="customerNameMapperIdentifier" value=""/>
68
Kofax RPA Administrator's Guide
<property name="groupsAttributes">
<list>
<value>groups</value>
</list>
</property>
<property name="adminGroups">
<list>
<value>KapowAdmins</value>
</list>
</property>
<property name="assignGroups" value="true"/>
<property name="consumer" ref="webSSOprofileConsumer"/>
<property name="email" value="email"/>
<property name="firstname" value="firstname"/>
<property name="lastname" value="lastname"/>
<property name="idpName" value="ONELOGIN"/>
<property name="idpGroupNameSeparator" value=";"/>
<property name="idpUserNameRegex" value="^[a-zA-Z0-9]*$"/>
<property name="idpEmailRegex" value="^[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,6}$"/>
</bean>
<bean id="useSamlSingleLogout" class="java.lang.Boolean">
<constructor-arg value="false"/>
</bean>
<bean id="metadataGeneratorFilter"
class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
<constructor-arg>
<bean class="org.springframework.security.saml.metadata.MetadataGenerator">
<property name="entityId" value="http://localhost:8080/ManagementConsole/ saml/login"/>
<property name="requestSigned" value="false"/>
<property name="entityBaseURL" value="http://localhost:8080/
ManagementConsole"/>
<property name="extendedMetadata">
<bean
class="org.springframework.security.saml.metadata.ExtendedMetadata">
<property name="idpDiscoveryEnabled" value="false"/>
<property name="signMetadata" value="false"/>
</bean>
</property>
</bean>
</constructor-arg>
</bean>
<bean id="webSSOprofileConsumer"
class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl">
<property name="maxAuthenticationAge" value="86400"/>
<property name="responseSkew" value="600"/>
<property name="maxAssertionTime" value="6000"/>
</bean>
<bean id="metadata"
class="org.springframework.security.saml.metadata.CachingMetadataManager">
<constructor-arg>
<list>
<bean class="org.opensaml.saml2.metadata.provider.HTTPMetadataProvider"
lazy-init="true">
<constructor-arg>
<value type="java.lang.String">http://example.okta.com/saml/ metadata/222670a0-2b96-48ef-975a-b7267446d09e</value>
69
Kofax RPA Administrator's Guide
</constructor-arg>
<constructor-arg>
<value type="int">10000</value>
</constructor-arg>
<property name="parserPool" ref="parserPool"/>
</bean>
<bean
class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
<constructor-arg>
<value type="java.io.File">classpath:security/idp.xml</value>
</constructor-arg>
<property name="parserPool" ref="parserPool"/>
</bean>
</list>
</constructor-arg>
</bean>
Example OneLogin Configuration
This section provides an example procedure on how to configure a SAML application in the
OneLogin identity provider for use with Kofax RPA.
1.
On the OneLogin website , create an account.
2.
When the account is created, open the page {your-domain-name}.onelogin.com and open the
Administration page.
3.
On the menu, click APPS and select the option to add a new application. Select the following application type: SAML Test Connector (Advanced) .
4.
On the Configuration tab, set the application parameters as shown in this table. Leave the other parameters as they are.
Parameter
RelayState
Audience
Recipient
ACS (Consumer) URL Validator
ACS (Consumer) URL
Single Logout URL
Login URL
SAML Initiator nameID format issuer type
Value http://<IP-address>:8080/ManagementConsole/ saml/login http://<IP-address>:8080/ManagementConsole/ saml/login http://<IP-address>:8080/ManagementConsole/ saml/login http://<IP-address>:8080/ManagementConsole/ saml/login http://<IP-address>:8080/ManagementConsole/ http://<IP-address>:8080/ManagementConsole/ saml/SingleLogout http://<IP-address>:8080/ManagementConsole/ saml/login
OneLogin
Specific
70
Kofax RPA Administrator's Guide
Parameter signature element encryption method
Value
Response
TRIPLEDES-CBC
5.
On the Parameters tab, set the application parameters as shown in this table.
Parameter
NameID email firstname group lastname
Value
Email name part
First Name
User Roles
Last Name
Also, select the option Include in SAML assertion .
6.
The SSO tab contains the issuer URL required to configure the Kofax RPA saml.xml
file.
Make sure that X.509 Certificate is set to Standard Strength Certificate (2048-bit) and SAML
Signature Algorithm is set to SHA-1 .
Copy the Issuer URL property value and use it in the "IDP Metadata configuration" section in your saml.xml
file. For an example, see below.
7.
On the menu, click USERS > Roles and select the option to add a new role.
Add roles that correspond to your Management Console groups and assign to them the application created before. The KapowAdmins role is mandatory in Kofax RPA, so ensure that you add it.
8.
On the menu, click USERS > All users and select the required roles for the user.
You have now configured a OneLogin application.
9.
Now you need to configure group attributes in saml.xml
located in the folder \WEB-INF
\spring to match the OneLogin application you have created.
After changing the file, restart Tomcat.
Example
<property name="groupsAttributes">
<list>
<value>group</value>
</list>
</property>
<property name="adminGroups">
<list>
<value>KapowAdmins</value>
</list>
</property>
...
<property name="idpName" value="ONELOGIN"/>
...
71
Kofax RPA Administrator's Guide
<bean id="metadataGeneratorFilter"
class="org.springframework.security.saml.metadata.MetadataGeneratorFilter" lazyinit="true">
<constructor-arg>
<bean
class="org.springframework.security.saml.metadata.MetadataGenerator">
<property name="entityId" value="http://<IP_address>:8080/
ManagementConsole/saml/login"/>
<property name="requestSigned" value="false"/>
<property name="entityBaseURL" value="http://<IP_address>:8080/
ManagementConsole"/>
<property name="extendedMetadata">
<bean
class="org.springframework.security.saml.metadata.ExtendedMetadata">
<property name="idpDiscoveryEnabled" value="false"/>
<property name="signMetadata" value="false"/>
</bean>
</property>
</bean>
</constructor-arg>
</bean>
...
<!-- IDP Metadata configuration - paths to metadata of IDPs in circle of trust
is provided here
-->
<bean
class="org.springframework.security.saml.metadata.CachingMetadataManager"
id="metadata" lazy-init="true">
<constructor-arg>
<list>
<!-- <bean
class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
<constructor-arg>
<value type="java.io.File">classpath:security/idp.xml</ value>
</constructor-arg>
<property name="parserPool" ref="parserPool"/>
</bean> -->
<bean
class="org.opensaml.saml2.metadata.provider.HTTPMetadataProvider" lazyinit="true">
<constructor-arg>
<value type="java.lang.String">https:// app.onelogin.com/saml/metadata/d237b5c5-b110-4f42-a646-7678ae08feae</value>
</constructor-arg>
<constructor-arg>
<value type="int">10000</value>
</constructor-arg>
<property name="parserPool" ref="parserPool"/>
</bean>
<!-- <bean
class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
<constructor-arg>
<value type="java.io.File">classpath:security/idp.xml</ value>
</constructor-arg>
<property name="parserPool" ref="parserPool"/>
</bean> -->
</list>
72
Kofax RPA Administrator's Guide
</constructor-arg>
</bean>
High Availability
If high availability (failover) is required, you can configure multiple Management Console instances to work together as a cluster. The following components must be clustered to achieve full failover.
Cluster Components
Component
Load balancer
Description
An HTTP load balancer is required to distribute requests between multiple
Tomcat servers.
When configuring high availability mode, all other services, such as
RoboServers and Kapplets must be configured to access Management
Console via the load balancer instead of the direct connection to
Management Console.
Clustered platform database The Management Console stores schedules, robots, and other in the platform database. In a failover scenario, the platform database should run on a clustered DBMS to avoid a single point of failure.
Tomcat session replication Although the Management Console does not store any data directly in the user's session (except during Import/Export), the session holds the user's authentication information.
If session replication is not enabled, the user will have to login again if the
Tomcat he is currently connected to crashes.
Apache Tomcat Connector
Hazelcast mod_jk is an Apache module used to connect the Tomcat servlet container with web servers such as Apache, iPlanet, Sun ONE (formerly Netscape) and even IIS using the Apache JServ Protocol.
Hazelcast (www.hazelcast.com) is used to cluster data structures over multiple
JVMs. Inside the Management Console this is used to provide clustering of vital data structures, and to provide intercommunication between application instances.
Here is a example: When you run a robot on a RoboServer, a thread is required to process the status messages returned by the RoboServer. This thread runs inside a specific Tomcat instance. In a clustered environment, a user trying to stop the robot may in fact be generating the stop request on another Tomcat instance than the instance running the robot. In that case the stop request is broadcast through Hazelcast to all instances and the instance running the robot will receive it and act to stop the robot.
Multiple Management Console Instances
You should have two or more identical Tomcat installations, and deploy the same version of
ManagementConsole.war
on them all. Make sure the web.xml
, Configuration.xml
, login.xml
, and roles.xml
files are the same across all the instances.
73
Kofax RPA Administrator's Guide
Install and Configure Components
This topic describes how to install and configure necessary components for high availability configuration using multicast clustering. In this configuration we will set up two host computers: one host (host1) contains Tomcat server and a database, another host (host2) contains Tomcat server and Apache server as a load balancer.
Step-by-Step Procedure
The following procedure helps you to install components for high availability configuration.
1.
Set up a database on "host1" computer.
2.
Download Tomcat from the Apache website: https://tomcat.apache.org
3.
Install Tomcat on both hosts and set user password. See Tomcat Deployment
for more information.
4.
on Tomcat on both hosts.
5.
Start Tomcat application on both computers and make sure they go online. You should have two identical Tomcat installations, and deploy the same version of ManagementConsole.war on them all. Make sure the web.xml
, Configuration.xml
, login.xml
, and roles.xml
files are the same on both installations.
6.
Shut down Tomcat servers.
7.
Download Apache server from the Apache website: http://httpd.apache.org/ download.cgi#apache24 . Install the Apache server on "host2" and start the Apache service. See
Apache doc for details: http://httpd.apache.org/docs/
8.
Download Apache mod_jk connector from the Apache website: https://tomcat.apache.org/ download-connectors.cgi
.
• Unzip the files to a directory on your disk.
• Copy mod_jk.so
file to the <host2>\module directory.
• Edit <host2>\conf\httpd.conf
as follows:
LoadModule jk_module modules/mod_jk.so
<IfModule mod_jk.c>
JkWorkersFile "<apache>\conf\workers.properties"
JkLogFile "<apache>\logs\mod_jk.log"
JkLogLevel error
JkLogStampFormat "[%a %b @d %H:%M:%S %Y] "
JkRequestLogFormat "%w %V %T"
</IfModule>
JkMount /ManagementConsole/* loadbalancer
JkMount /ManagementConsole loadbalancer
• Create a <host2>\conf\workers.properties
file with the following content: worker.list=host1, host2, loadbalancer worker.host1.host=<ip address or host name> worker.host1.port=8009 worker.host1.type=ajp13 worker.host1.lbfactor=1 worker.host2.host=<ip address or host name> worker.host2.port=8009 worker.host2.type=ajp13
74
Kofax RPA Administrator's Guide worker.host2.lbfactor=1 worker.loadbalancer.type=lb worker.loadbalancer.balance_workers=host1, host2
Where <ip address or host name> is the address or the host name of the host computers running Tomcat.
9.
For both Tomcat servers enter the following lines to the conf\server.xml
file.
<Engine name="Catalina" defaultHost="localhost" jvmRoute="jvm1">
<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>
<Connector protocol="AJP/1.3"
address="0.0.0.0"
port="8009"
redirectPort="8443"
secretRequired="false" />
For more information, see Tomcat Session Replication .
10.
On each Tomcat server, edit webapps\ManagementConsole\WEB-INF\Configuration.xml
file as follows. Note that you must specify valid IP addresses of the host computers on your network.
<!-- Cluster configuration --
>
<bean id="cluster" class="com.kapowtech.mc.config.ClusterConfig" >
<property name="port" value="5701"/>
<property name="interface" value="<mask for the IP address>"/>
<!-- Uncomment the line below to enable clustering via multicast. Your license must support High Availability for this to work -->
<!--property name="joinConfig" ref="multicastCluster"/>
<!-- or uncomment this line to enable clustering via TCP-IP. Your license must support High Availability for this to work-->
<property name="joinConfig" ref="tcpCluster"/-->
<property name="managementCenterUrl" value=""/>
</bean>
<!-- definition for a TCP cluster. You need to add peers to this list, so each
client can locate at least one other functioning cluster member -->
<bean id="tcpCluster" class="com.kapowtech.mc.config.TcpJoinConfig" lazyinit="true">
<property name="peers">
<list>
<bean class="com.kapowtech.mc.config.TcpPeer">
<property name="host" value="<ip address or host name>"/>
<!-- port is only needed if the other machine is not using the same port as this
instance-->
<!--property name="port" value="5701"/-->
</bean>
<bean class="com.kapowtech.mc.config.TcpPeer">
<property name="host" value="<ip address or host name>"/>
<!-- port is only needed if the other machine is not using the same port as this
instance-->
<!--property name="port" value="5701"/-->
</bean>
</list>
</property>
</bean>
For more information, see Hazelcast Replication
.
Now you can log in to the Management Console on the load balancer by navigating to
<host2>:80/ManagementConsole , where "host2" is the name of the computer running Apache
75
Kofax RPA Administrator's Guide server. Once you log in, go to Admin > High availability nodes , and you should see two nodes with correct IP addresses.
Load Balancer Startup
This section describes how to determine if the application started correctly.
If the ManagementConsole.xml
(context configuration) or web.xml
files are invalid, the application cannot be deployed on Tomcat, and requests normally return error code 404 (as it hits the Tomcat's
ROOT application which does not have anything deployed on /ManagementConsole/ ).
Any other errors encountered during application startup are shown to the user when the application loads. This way you do not always have to check the log to figure out why the application did not load correctly. This is, however, a bit impractical as the application returns 200
OK even if there are errors during startup. Also, if authentication is enabled, you have to login before you can see the error messages.
To make it easier for load balancers to see if the application started correctly, you can make a request to the URL /ManagementConsole/Ping . This either returns HTTP status code 200 if the application loaded correctly, or 500 with a stack trace of the error.
Tomcat Session Replication
Session replication is configured in /conf/server.xml
. Here is an example that uses multicast for instance discovery on Tomcat.
<Cluster className="org.apache.catalina.cluster.tcp.SimpleTcpCluster"
managerClassName="org.apache.catalina.cluster.session.DeltaManager"
expireSessionsOnShutdown="false"
useDirtyFlag="true"
notifyListenersOnReplication="true"
printToScreen="true">
<Membership
className="org.apache.catalina.cluster.mcast.McastService"
mcastAddr="228.0.0.4"
mcastPort="45564"
mcastFrequency="500"
mcastDropTime="3000"/>
<Receiver
className="org.apache.catalina.cluster.tcp.ReplicationListener"
tcpListenAddress="auto"
tcpListenPort="4002"
tcpSelectorTimeout="100"
tcpThreadCount="6"/>
<Sender
className="org.apache.catalina.cluster.tcp.ReplicationTransmitter"
replicationMode="pooled"
ackTimeout="150000"
waitForAck="true"/>
<Valve className="org.apache.catalina.cluster.tcp.ReplicationValve"
filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*
\.txt;"/>
<Deployer className="org.apache.catalina.cluster.deploy.FarmWarDeployer"
76
Kofax RPA Administrator's Guide
tempDir="/tmp/war-temp/"
deployDir="/tmp/war-deploy/"
watchDir="/tmp/war-listen/"
watchEnabled="false"/>
<ClusterListener
className="org.apache.catalina.cluster.session.ClusterSessionListener"/>
</Cluster>
You also have to set the jvmRoute attribute on the <Engine> element in server.xml
:
<Engine jvmRoute="tomcat2" name="Catalina" defaultHost="MyHost">
If you are using mod_jk as a poor man's load balancer, the value of the jvmRoute has to match the name listed in the workers.properties
file references by the mod_jk configuration.
See your Tomcat documentation for details.
Hazelcast Replication
The most basic Hazelcast settings can be edited in Configuration.xml
, while more advanced settings such as SSL encryption must be configured in /WEB-INF/Hazelcast.xml
When a Management Console starts, it creates a Hazelcast node on port 5701 (or the next available port if 5701 is unavailable). By default this Hazelcast node binds to IP address 127.0.0.1. You have to change the bind address to a public IP/host name before it can participate in a cluster. This is done by modifying the interface property of the cluster bean in Configuration.xml
. It might look like this:
<bean id="cluster" class="com.kapowtech.mc.config.ClusterConfig" >
<property name="port" value="26000"/>
<property name="interface" value="10.0.0.*"/>
.......
</bean>
The * is used as a wildcard, in this case the application will try bind to the 'first' interface that has an
IP address starting with 10.0.0. It is possible, but not recommended to use *.*.*.* as you may end up binding to 127.0.0.1, or another virtual interface.
When you start additional instances of Management Console, their Hazelcast instances will try to find any existing Hazelcast node and join the cluster. This discovery can be done through multicast or through TCP/IP.
To use multicast discovery you must modify the cluster bean in Configuration.xml
. This is done my un-commenting the following line:
<property name="joinConfig" ref="multicastCluster"/> multicastCluster is a reference to the multicastCluster bean, which defines the multicast group and port. You may change it to fit your network topology.
If your network does not allow multicast you will have to use the tcpCluster. That is done by uncommenting this line instead:
<property name="joinConfig" ref="tcpCluster"/>
77
Kofax RPA Administrator's Guide
The tcpCluster bean contains a list of TcpPeer, one for each other Hazelcast node. If you use the same TCP port for all Hazelcast nodes you do not need to specify a port number (each node will assume that its peers are running on the same port as itself). If you have two nodes configured in a
TCP cluster it could look like this:
<bean id="tcpCluster" class="com.kapowtech.mc.config.TcpJoinConfig">
<property name="peers">
<list>
<bean class="com.kapowtech.mc.config.TcpPeer">
<property name="host" value="10.0.0.25"/>
</bean>
<bean class="com.kapowtech.mc.config.TcpPeer">
<property name="host" value="10.0.0.26"/>
</bean>
</list>
</property>
</bean>
Notice that both nodes are in the list. This means that regardless which node starts first it will be able to find its peer. It also allows you to use identical Configuration.xml
files in both applications. Also, TCP ports numbers are not defined, so each peer will try to connect to the other one on the same port as it is listening on itself.
Application Nodes
You can verify that the application is properly clustered by going to Admin > High Availability
Nodes .
The Interface column lists the IP/host and port that Hazelcast is using for inter-cluster communication. The Connected to column shows which of the two nodes you are connected to at the moment. If you shut down the server you are currently connected to, you will automatically be re-routed to another live instance by the load balancer.
From the context menu for a node, you can request a thread dump, which may be useful for debugging purposes.
URI Encoding
If you plan to upload robots with names that contain non-ASCII characters, like Danish ÆØÅ or
German ß to the repository, you have to configure the URI Encoding on your web container to
UTF-8.
On Tomcat this is done on the <connector> definition found in server.xml
file inside the /conf folder. Here you add the attribute URIEncoding="UTF-8" like this:
<Connector port="8080" URIEncoding="UTF-8"....../>
Password Encryption
Management Console uses certificate based (public-, private-key) encryption when storing passwords. When you import from a previous version password will automatically be re-encrypted using the new certificate based algorithm.
The certificate and the matching private key is stored in a Java keystore, Management Console ships with a keystore that contains a default certificate and private key. As all customers get the same
78
Kofax RPA Administrator's Guide keystore we recommend that you create your own keystore, otherwise anyone will be able to load your exports and potentially get your passwords.
Create Your Own Keystore
If you have already started a Management Console, you need to upgrade the certificate. The keystore must be in pkcs12 format, and can be created using the keytool application that comes with the Java SDK (which can be downloaded from Oracle.com). The following command creates a new pkcs12 keystore with a certificate that is valid for 365 days.
keytool -genkey -alias mc -keyalg RSA -validity 3650 -keystore mc.p12 storetype pkcs12
You will be prompted for password, and the information that will be stored in the X.509 private key. The command will create a file mc.p12 (the value from the -keystore argument) in the current directory. -validity 3650 means the certificate will be valid for 10 years.
We do not recommend using a certificate issued by a certificate authority (CA) as pkcs12 holds both the private key and the public certificate, and the password to the private key will be written in clear text as part of the application configuration.
To instruct Management Console to use the new certificate, change the Configuration.xml
file.
The file is located inside the ManagementConsole.war
web archive, which must be unpacked, see
Deploying into Tomcat for details. Inside Configuration.xml
you will find the following entry:
<bean id="keyStore" class="com.kapowtech.mc.config.KeyStoreConfig" >
<property name="location" value="/WEB-INF/mc.p12"/>
<property name="password" value="changeit"/>
<property name="alias" value="mc"/>
</bean>
Here you must specify the location, password and alias of the keystore. If you copy the keystore into
ManagementConsole.war
the location must be relative to the root of the application. If you want to refer to a keystore stored in the file system, the location must start with file://, and must be an absolute reference to the keystore location.
Upgrading the Keystore
The first time Management Console starts, it creates a checksum using the private key from the keystore, this allows it to detect when the keystore has been replaced, and verify that passwords can in fact be decrypted with the provided certificate. If you have already started a Management
Console before installing your own keystore, you have to configure it to perform a password conversion.
To upgrade the keystore, copy the current keystore file into a new location, such as your users home folder, then modify Configuration.xml
to create a password converter with a reference to the old keystore:
<bean id="oldKeyStore" class="com.kapowtech.mc.config.KeyStoreConfig" >
<property name="location" value="file:///home/roboserver/mc.p12"/>
<property name="password" value="changeit"/>
79
Kofax RPA Administrator's Guide
<property name="alias" value="mc"/>
</bean>
<bean id="passwordConverter"
class="com.kapowtech.scheduler.server.service.PasswordConverter">
<constructor-arg ref="oldKeyStore"/>
</bean>
This configures a password converter to use the previous certificate to decrypt any existing passwords and checksum (you will have to provide correct location, alias and password for the old keystore), and use the new private key (as configured above) to re-encrypt passwords and create a new checksum. The conversion occurs the next time the Management Console is started, the conversion occurs while the application is starting and may take some time if there are many schedules. You do not have to remove the oldKeyStore and passwordConverter beans from
Configuration.xml
, as the password conversion is only triggered when the checksum and keystore is out-of-sync, and after the conversion the checksum matches the new keystore).
SSL Endpoint Verification
When you create a new Cluster you can select that you want the communication with the
RoboServers to be SSL encrypted, this prevents anyone from "listening" to the network and extracting critical information exchanged between the two parties.
In addition to encryption, SSL also offer endpoint validation. This is to ensure that you do not exchange critical information with a third party, either due to misconfiguration, or because you DNS has been hacked. For this to work you need to configure RoboServer to trust your Management
Console and configure Management Console to trust your RoboServers.
This requires you to edit files inside ManagementConsole.war
, so make sure you Tomcat server is not running when you perform this modification.
Certificates
You will need to create two certificates, one for Management Console and one for RoboServer, each certificate contains a private and a public key. Creating a certificate and exporting the public key is described here, in general it is a good idea to read the entire section of the help the discusses certificates, especially the section on API Client/Server certificates.
Endpoint verification can be separated into two parts, making RoboServer trust Management
Console and making Management Console trust RoboServer, each of these are configured individually, and you do not have to configure both.
Make RoboServer Trust Management Console
You now have to configure a Management Console to use the private key when creating the SSL connection to a RoboServer. This is done by modifying /WEB-INF/certs.xml
found inside the WAR file. Provide the location, and the password for the certificate, which could look like this:
<bean id="sslCertificationConfiguration"
class="com.kapowtech.mc.config.SSLVerificationConfiguration">
...
<property name="privateCertificateLocation" value="file:///home/roboserver/ client.p12"/>
<property name="privateCertPassword" value="changeit"/>
80
Kofax RPA Administrator's Guide
</bean>
Management Console is now using a private key when establishing SSL connections. Once the
Management Console public key is deployed in the RoboServer /TrustedClients folder, the
RoboServer can verify that it is connected to the right Management Console. Remember to enable
Verify API Client Certificates in RoboServer Settings, and deploy the public key on all RoboServers in the cluster.
Make Management Console Trust RoboServer
RoboServer already comes with an API certificate installed, therefore you have to create a new certificate and replace the pre-installed one. First create the certificate as described above, then start RoboServer Settings and go to the Certificates tab. Click the change button, select the certificate, and enter the password when prompted. RoboServer now uses the new certificate when creating SSL connection with a Management Console (and other API clients).
Now you need to configure the Management Console to only trust SSL connections from
RoboServers with the correct certificate. Like the Management Console client certificate this is
(partly) configured in /WEB-INF/certs.xml
, using the following two options:
<bean id="sslCertificationConfiguration"
class="com.kapowtech.mc.config.SSLVerificationConfiguration">
<property name="verifyRoboServerCert" value="true"/>
<property name="checkHostName" value="true"/>
...
</bean>
The option for verifying RoboServer certificates is a simple boolean flag (true/false), this is because you have to import the RoboServer public key into the JRE's default keystore. The JRE's default keystore is a file named cacerts located at /jre/lib/security/ .
To import the RoboServer public key into cacerts , use the following command: keytool -import -alias RoboServer -keystore cacerts -trustcacerts -file server.pub.cer
You will be prompted for a password, which is changeit unless you have changed it. The alias has to be unique, so if you created a separate certificate for each RoboServer, add a suffix. Also note that the references to cacerts and server.pub.cer are relative in this example.
The checkHostName option ensures that Management Console only communicates with a
RoboServer if it presents the correct certificate and is contacted using the hostname written inside the RoboServer certificate. Note that localhost and 127.0.0.1 is not considered the same host when the hostname is checked.
Troubleshooting
Troubleshooting can be quite hard as there is virtually no information available if SSL connections cannot be established, but it is important to know the following.
• Management Console does not start if it cannot find the certificate, or if the password is wrong.
• When you change the RoboServer certificate in RoboServer Settings, it checks that the password is correct before storing the certificate.
81
Kofax RPA Administrator's Guide
If a Management Console cannot connect to a RoboServer, the following may help you troubleshoot:
• Is RoboServer running? Try to telnet to the socket to be sure.
• Is the RoboServer host name correct (if checkHostName is enabled)?
• Is the v public key imported into cacerts? Use keytool -list -v -keystore cacerts -alias RoboServer if you give -alias it lists all certificates.
• Was the Management Console public certificate copied to the RoboServer /TrustedClients folder?
• Check expiration date. The public key contains the expiration data of the private key, and can be opened/viewed in both Windows and Linux.
Simultaneous Sessions for a User Account
By default, the system allows a single user account to be authenticated simultaneously from multiple locations. To restrict the possibility of concurrent sessions for a single user account, adjust the settings in the authentication.xml
file that resides in WEB-INF/spring .
In authentication.xml
, locate the following section and remove the comment tags (marked in bold here):
<!--
<bean class="com.kapowtech.scheduler.server.spring.security.KapowConcurrentSes sionControlAuthenticationStrategy" lazy-init="true"> <constructor-arg ref="ses sionRegistry"/> <constructor-arg ref="platformEMF"/> <property name="maximumSessi ons" value="1"/> <property name="exceptionIfMaximumExceeded" value="true"/> </bea n>
-->
Also, to define the timeout to automatically end the session if the user does not perform any actions, configure the session-timeout property in the web.xml
file that resides in WEB-INF . Be default, the timeout is 30 minutes.
Use Microsoft SQL Server with integrated security
If you want to run Kofax RPA Management Console with Microsoft SQL Server database that uses integrated security, as well as store data in such database, perform the following steps to set up the environment. The JDBC driver cannot be stored in the Management Console, therefore both JAR and
DLL files must be placed in the specified folders.
On Tomcat server
• Copy the JAR file of the Microsoft JDBC Driver for SQL Server to the lib folder of the Tomcat installation folder.
• Copy the DLL file of the Microsoft JDBC Driver for SQL Server to the bin folder of the Tomcat installation folder.
On developer computers for Design Studio users
• Copy the JAR file of the Microsoft JDBC Driver for SQL Server to the lib folder of the Design Studio installation folder.
82
Kofax RPA Administrator's Guide
• Copy the DLL file of the Microsoft JDBC Driver for SQL Server to the jre\bin folder of the Design
Studio installation folder.
On RoboServer computers
• Copy the JAR file of the Microsoft JDBC Driver for SQL Server to the lib folder of the RoboServer installation folder.
• Copy the DLL file of the Microsoft JDBC Driver for SQL Server to the jre\bin folder of the
RoboServer installation folder.
Users running Design Studio and RoboServers must have access rights to the database and must run on Windows.
Configure Management Console WAR file
Kofax RPA full installation contains the WebApps folder with the Configurator.jar
command-line tool to extract configuration from or apply configuration to a Management Console WAR file.
Usage: java -jar Configurator.jar <OPTIONS>
This tool can be used to apply necessary settings to Management Consoles, such as when upgrading your Kofax RPA installation without tedious manual configuration of each installed
Management Console.
You can:
• Create a template with Management Console settings.
• Extract settings from the Management Console WAR file in the existing Management Console installation.
• Apply settings to newly installed Management Consoles.
The following table contains available arguments and their description. Run java -jar
Configurator.jar -h at any time to invoke command reference.
Argument
-h,--help
-p,--use-properties <arg>
-t,--template <arg>
-w,--war-file <arg>
-x,--extract <arg>
Description
Shows command reference.
Specify the name and path to the properties file to use as input.
Creates an empty properties file containing only default values.
Specify the path to and the name of the WAR file, including the extension that contains Management Console settings.
Default: ROOT
Extract properties from the Management Console WAR file in your current installation.
The general procedure to set up installed Management Consoles is the following.
1.
Manually install and set up one instance of the Management Console.
2.
Extract configuration settings from the Management Console WAR file that you set up.
83
Kofax RPA Administrator's Guide
3.
Edit configuration file to suit new instances of the Management Console.
4.
Add the Management Console WAR file to the new Tomcat server in the WebApps folder. Copy the jdbc driver of the database you want to use to the Tomcat lib folder. Note that the Tomcat server must be stopped.
5.
Apply settings to the newly added Management Console WAR file.
6.
Start the Tomcat server.
Create a template with Management Console settings
A Management Console template file is a file that contains all Management Console configuration settings with empty values. You can later fill in the values in the file and apply those values to a newly added Management Console WAR file. The file consists of several sections. Each section title contains a file name that is comprised of the options in this section. For example, the first section contains context.xml
in its title and the section consists of settings declared in the Tomcat context.xml
file or the ManagementConsole.xml
file if declared externally. Each section and option in this file has a detailed description. The set of values is the same as environment variables for the ManagementConsole Docker container. See
for details.
To create a template file, perform the following.
1.
Locate the WebApps subfolder in your Kofax RPA installation folder.
2.
Run Configurator.jar
as follows: java -jar Configurator.jar -t <target configuration file>
Example: java -jar Configurator.jar -t config.properties
After running the command above, the WebApps folder should contain the config.properties
file with all options extracted from your Configurator.jar
.
Extract settings from existing Management Console WAR file
If you have several Management Consoles deployed in you network, it takes a lot of time to set up new instances when upgrading to a new version of Kofax RPA. Using Configurator.jar
tool you can extract configuration settings from the existing Management Console installation to apply them to newly installed Management Consoles.
To extract the settings, perform the following.
1.
Locate the WebApps subfolder in your Kofax RPA installation folder.
2.
Run Configurator.jar
as follows: java -jar Configurator.jar -x <target configuration file> -w <path to war file>
Example: java -jar Configurator.jar -x config.existing.properties -w
ManagementConsole.war
Note that some property values are not extracted, such as database settings, because database schema changes from version to version and you must use a new database with a new version of Management Console. Notes with descriptions are added to the skipped properties.
When specifying several LDAP directories on your network, specify the number of directories in the login.ldap.directory.count
property and substitute <n> in each of the LDAP properties with a serial number of the directory you specify starting with 1.
84
Kofax RPA Administrator's Guide
Apply settings to Management Console WAR file
After creating a template and editing its values or after extracting settings from the existing
Management Console installation, you can apply specified settings to a newly added Management
Console WAR file. Note that you must apply the values before you start the Tomcat server.
To apply values specified in the properties file, perform the following.
1.
Locate the WebApps subfolder in your Kofax RPA installation folder.
2.
Run Configurator.jar
as follows: java -jar Configurator.jar -p <source configuration file> -w <path to war file>
Example: java -jar Configurator.jar -p config.properties -w
ManagementConsole.war
Set up Robot File System server
Robot File System (RFS) server provides shared storage for RoboServers, Design Studio instances, and Desktop Automation agents. To set up an RFS server on a Tomcat server, perform the following steps.
The maximum size of the file that can be uploaded to the Robot File System is 100 MB.
1.
Locate the rfs.war
file in the WebApps folder in your Kofax RPA installation folder.
For example, on a Windows system, the folder resides in: C:\Program Files\Kofax RPA
11.4.0.0\WebApps
2.
Copy rfs.war
to the webapps folder in your Apache Tomcat installation folder.
For example, on a Windows system, the folder resides in: C:\apache-tomcat\webapps
3.
Restart the Tomcat server.
Once you restart the Tomcat server, the webapps folder in the Tomcat installation folder should contain the rfs subfolder.
4.
In a text editor, open the web.xml
file located in the webapps\rfs\WEB-INF folder in the
Tomcat installation folder.
5.
Locate the mc-path parameter and specify the Management Console URL in param-value .
For example, http://localhost:50080 .
Accessing the Robot File System over HTTPS with a self-signed certificate is not supported.
6.
Locate and set the allow-absolute-paths parameter to true or false .
If allow-absolute-paths is set to true , you can create RFS file shares with paths such as c:
\files , z:\data , and other paths that the RFS service user can access. If allow-absolutepaths is set to false and data-path is set to a specific folder, such as /data on Linux, the service only allows access to shares with a path within the specified folder, such as /data .
7.
Specify a folder to store temporary robot run data in data-path . For example, C:/RFSData .
Note that you can specify the absolute path only if allow-absolute-paths is set to true .
85
Kofax RPA Administrator's Guide
Temporary shares are created and deleted as subfolders of the specified folder.
8.
Leave other settings as they are and restart the Tomcat server.
9.
Open the Management Console and go to Settings > General > Robot File System server .
Select Use Robot File System server and specify the URL to the Tomcat server where you set up the RFS server. For example, http://myserver.mydomain:8080/rfs .
Now you can use file systems configured to share and store data used and/or produced by robots.
To add a configuration for a file system, see "Robot File System" in Kofax RPA Help .
Example: Map folder to Robot File System
This example provides general steps on how to map a folder on Windows to a Robot File System in Management Console and add a step to a robot in Design Studio to write data to this Robot File
System.
Before following this example, we recommend that you read the procedure "Set up Robot
File System server" above and "Robot File System" in Kofax RPA Help as they provide detailed information on configuration and usage of the Robot File System functionality.
This procedure is written with the assumption that you have completed steps 1-7 from "Set up
Robot File System server."
1.
In the web.xml
file, in the data-path parameter, specify the path to a folder to store temporary robot run data. For example, c:/rfs .
<init-param>
<!-- the path to where local data is stored -->
<param-name>data-path</param-name>
<param-value>c:/rfs</param-value>
</init-param>
Restart the Tomcat server to apply the settings.
2.
In Management Console > Settings > General > Robot File System server , select to use the
Robot File System server.
3.
In Management Console > Repository > Robot File System , add a configuration for your file system.
a.
On the General information tab, specify all required parameters.
In the File system name parameter, specify RFS1 . In the Path parameter, specify: rfs1_folder .
In this case, rfs1_folder is the root folder for RFS1 , so the absolute path would be c:/rfs/rfs1_folder . The rfs1_folder will be created automatically if not created manually.
b.
On the Authorized access tokens tab, paste the token for your Design Studio instance to make the file system accessible to that instance. Copy the token from the Help > About window in Design Studio.
4.
Save the configuration.
5.
In Design Studio, in a Robot, create a Write File step with the following properties.
86
Kofax RPA Administrator's Guide
Contents : Specify a binary variable containing data to write to the Robot File System. In this example, "content" is the string written in the file. The file content must be binary.
File Name : Specify the path to the file to which the data is written. The Robot File System name is case-sensitive.
6.
After you execute the step, the newFile.bin file will contain the data from "content". The file will be saved to c:/rfs/rfs1_folder/ .
87
Chapter 3
Run RPA Components As Services
This chapter describes how to run different RPA components as services using the
ServiceInstaller.exe
program.
ServiceInstaller.exe explained
To run a Kofax RPA component as a service you need to install it first using the
ServiceInstaller.exe
program. The following is a general example outlining the command-line arguments to the "RPAComponent" program (although displayed on multiple lines here, this is a one-line command):
ServiceInstaller.exe -i RPAComponent.conf wrapper.ntservice.account=Account
wrapper.ntservice.password.prompt=true wrapper.ntservice.name=Servicename wrapper.ntservice.starttype=Start-method wrapper.syslog.loglevel=INFO
wrapper.app.parameter.1="First-Argument" wrapper.app.parameter.2="Second-argument" wrapper.ntservice.account
The account of the user that has to run an "RPAComponent". Kofax RPA stores configuration in the user's directory and it is important to choose a user that has the correct configuration.
To run "RPAComponent" as a domain user, enter the account in the form domain\account
To run "RPAComponent" as a regular user, enter the account in the form .\account
For security reasons, do not use the LocalSystem account for the RoboServer service's login.
If LocalSystem is used, the following error occurs when Webkit (default) robots run: "Could not establish connection to WebKitBrowser. Failed to connect to bus." wrapper.ntservice.password.prompt
The value true prompts the user for the account password. If you prefer to enter the password in the command line, use wrapper.ntservice.password=<your-password> .
wrapper.ntservice.name
The name of the service to install. Note that the name of the service can not contain spaces.
wrapper.ntservice.starttype
Specify the following values.
• AUTO_START : if the service should be started automatically when the system is restarted.
• DELAY_START : if the service should be started after a short delay.
• DEMAND_START : if you want to start the service manually.
88
Kofax RPA Administrator's Guide wrapper.syslog.loglevel
Redirect the console output from "RPAComponent" to the event log.
wrapper.app.parameter.
The arguments for "RPAComponent". You can enter as few or as many as needed.
When the service is installed, the user is granted the "log on as a service" rights. If the service fails to start, check that the right is granted by opening gpedit.msc and (on Windows 10) navigate to
Administrative Tools > Local Security Policy > Local Policy > User Rights Assignment > Log on as a service > Properties and add the user.
Run RoboServer and Management Console as a service
Both RoboServer and Management Console are started by the same server program, RoboServer, depending on the arguments supplied to it when it starts.
See the RoboServer Parameters section in
for a detailed description of the command-line arguments for the RoboServer program.
The following are examples on how to start a RoboServer and Management Console automatically on Windows and Linux.
Start RoboServer on Windows
To make a RoboServer start automatically on Windows, add it as a Windows service. We will show how to add and remove Windows services using the ServiceInstaller.exe
program that is included in the Kofax RPA installation.
Add Windows Services
The following are examples of installing RoboServers in different configurations. In the examples MC means Management Console and RS means RoboServer.
• The following script installs services that start RoboServers with default parameters. The name of the service can be changed as needed.
ServiceInstaller.exe -i RoboServer.conf wrapper.ntservice.account=.
\<YOUR_USERNAME> wrapper.ntservice.password.prompt=true wrapper.ntservice.name="RoboServer11.4.0_MC" wrapper.ntservice.starttype=MANUAL wrapper.syslog.loglevel=INFO wrapper.app.parameter.1="-p" wrapper.app.parameter.2="PORT
NUMBER FOR MC RS TO RUN ON" wrapper.app.parameter.3="-mcUrl" wrapper.app.parameter.4="URL OF MC" wrapper.app.parameter.5="-cl" wrapper.app.parameter.6="NAME OF CLUSTER"
• This script creates a Windows Service that only starts the Management Console. This is the recommended configuration as the Management Console should run under its own JVM if possible. The name of the Windows Service can be changed as needed.
ServiceInstaller.exe -i RoboServer.conf wrapper.ntservice.account=.
\<YOUR_USERNAME> wrapper.ntservice.password.prompt=true wrapper.ntservice.name="RoboServer11.4.0_MC"
89
Kofax RPA Administrator's Guide wrapper.ntservice.starttype=AUTO_START wrapper.syslog.loglevel=INFO wrapper.app.parameter.1="-MC"
• The following scripts install services that start two RoboServers: one on port 50000 and the other on 50001. The service name can be different:
ServiceInstaller.exe -i RoboServer.conf wrapper.ntservice.account=.
\<YOUR_USERNAME> wrapper.ntservice.password.prompt=true wrapper.ntservice.name="RoboServer11.4.0_50000" wrapper.ntservice.starttype=AUTO_START wrapper.syslog.loglevel=INFO wrapper.app.parameter.1="-service" wrapper.app.parameter.2="socket:50000" wrapper.app.parameter.3="-mcUrl" wrapper.app.parameter.4="URL OF MC" wrapper.app.parameter.5="-cl" wrapper.app.parameter.6="NAME OF CLUSTER"
ServiceInstaller.exe -i RoboServer.conf wrapper.ntservice.account=.
\<YOUR_USERNAME> wrapper.ntservice.password.prompt=true wrapper.ntservice.name="RoboServer11.4.0_50001" wrapper.ntservice.starttype=AUTO_START wrapper.syslog.loglevel=INFO wrapper.app.parameter.1="-service" wrapper.app.parameter.2="socket:50001" wrapper.app.parameter.3="-mcUrl" wrapper.app.parameter.4="URL OF MC" wrapper.app.parameter.5="-cl" wrapper.app.parameter.6="NAME OF CLUSTER"
Remove Windows Services
To uninstall a service you can run the following command:
ServiceInstaller.exe -r RoboServer.conf wrapper.ntservice.name=Service-name wrapper.ntservice.name
The name of the service to remove.
Start Servers on Linux
The simplest way to make a RoboServer start automatically on Linux is to use crontab. Use the following command to create or edit the list of scheduled jobs in Linux for the particular user: crontab -u someUser -e
To the list of scheduled jobs add for example:
@reboot $HOME/Kofax RPA_11.4.0/bin/RoboServer -mcUrl http:// username:password@localhost:8080/ManagementConsole -p 50000 or
@reboot $HOME/Kofax RPA_11.4.0/bin/RoboServer -mcUrl http:// username:password@localhost:8080/ManagementConsole -p 50000 -MC
This way the RoboServer program starts with the indicated command-line arguments upon reboot.
Note that you must identify the bin directory under the actual installation folder.
Default user name and password are admin:admin .
90
Kofax RPA Administrator's Guide
Run Synchronizer as a service
Kofax RPA Synchronizer compares and synchronizes the state of objects between the Management
Console and your repository. For more information about Synchronizer, see "Robot Lifecycle
Management" in Kofax RPA Help .
This topic provides example of starting Synchronizer as a Windows service.
Add Windows Services
The following is an example of installing Synchronizer as a service. See
ServiceInstaller.exe explained for information about
ServiceInstaller.exe
.
ServiceInstaller.exe -i Synchronizer.conf wrapper.ntservice.account=domain
\account wrapper.ntservice.password.prompt=true wrapper.ntservice.name="Synchronizer11.4.0_MC" wrapper.ntservice.starttype=MANUAL wrapper.syslog.loglevel=INFO wrapper.app.parameter.1="-c" wrapper.app.parameter.2="--mc-url" wrapper.app.parameter.3="http://localhost:8080/ManagementConsole" wrapper.app.parameter.4="--username" wrapper.app.parameter.5="admin" wrapper.app.parameter.6="--password" wrapper.app.parameter.7="admin" wrapper.app.parameter.8="--interval" wrapper.app.parameter.9="3" wrapper.app.parameter.10="--no-host-key" wrapper.app.parameter.11="false" wrapper.app.parameter.12="--private-key" wrapper.app.parameter.13="local"
Remove Windows Services
To uninstall a service you can run the following command:
ServiceInstaller.exe -r Synchronizer.conf
wrapper.ntservice.name="Synchronizer11.4.0_MC" wrapper.ntservice.name
The name of the service to remove.
91
Chapter 4
Audit Log for Management Console
Audit log for Management Console logs all user operations in the Management Console including
API calls. By configuring the log4j2.properties
file, you can log the information to a file or a database. On a Windows system, the log4j2.properties
file is located at: User home\AppData
\Local\Kofax RPA\version\Configuration .
Logging to File
#Log4j2 log to file configuration example name = PropertiesConfig appenders = auditLogAppender appender.auditLogAppender.name = auditLog appender.auditLogAppender.type = File appender.auditLogAppender.fileName= logFilePath/logFileName.log
appender.auditLogAppender.layout.type = PatternLayout appender.auditLogAppender.layout.pattern=%d - %m%n logger.auditLog.name = auditLog logger.auditLog.level = INFO logger.auditLog.appenderRef.auditLog.ref = auditLog logger.auditLog.additivity = false
Logging to Database
The instructions below use MySQL database as an example, but other supported databases can be used for logging by using their specific JDBC drivers and URL connections.
To enable audit logging to MySQL database of the Management Console running with the embedded RoboServer, perform the following steps:
1.
Copy the MySQL connector JAR file to the lib subfolder of the Kofax RPA installation folder
(where the Kapowtech-common.jar
and platform.jar
are located). For example, mysqlconnector-java-<version>.jar
. Use the latest available version of the driver for your Java.
For more information, see https://repo1.maven.org/maven2/mysql/mysql-connector-java/ .
2.
Create a database table where you want to log the data to. The following is a MySQL script for creating tables:
CREATE TABLE LOGS
(
DATED timestamp NOT NULL,
LEVEL VARCHAR(10) NOT NULL,
MESSAGE VARCHAR(1000) NOT NULL
);
92
Kofax RPA Administrator's Guide
To prevent loss of information, make sure the message column has a minimum varchar size of 600.
3.
Add the following lines to the log4j2.properties
file:
#Log4j2 log to MySQL database configuration example name = PropertiesConfig appenders = auditLogAppender appender.auditLogAppender.name = auditLogAppender appender.auditLogAppender.type = JDBC appender.auditLogAppender.connectionSource.type = DriverManager appender.auditLogAppender.connectionSource.connectionString = jdbc:mysql:// localhost/ YourDatabaseSchemaName appender.auditLogAppender.connectionSource.username = user appender.auditLogAppender.connectionSource.password = password appender.auditLogAppender.connectionSource.driverClassName = com.mysql.jdbc.Driver
appender.auditLogAppender.tableName = LOGS appender.auditLogAppender.columnConfigs[0].type = Column appender.auditLogAppender.columnConfigs[0].name = DATED appender.auditLogAppender.columnConfigs[0].pattern = %d{yyyy-MM-dd HH:mm:ss} appender.auditLogAppender.columnConfigs[1].type = Column appender.auditLogAppender.columnConfigs[1].name = LEVEL appender.auditLogAppender.columnConfigs[1].pattern = %p appender.auditLogAppender.columnConfigs[2].type = Column appender.auditLogAppender.columnConfigs[2].name = MESSAGE appender.auditLogAppender.columnConfigs[2].pattern = %msg logger.auditLog.name = auditLog logger.auditLog.level = INFO logger.auditLog.appenderRef.auditLogAppender.ref = auditLogAppender logger.auditLog.additivity = false
Define the database schema name, user name, password and the table name that you created in the database.
The timestamp format used in the example above is not universal. The correct processing of the query depends on the database type and the time format used in the database.
Make sure timestamp format meets the database requirements.
To enable audit logging to MySQL database of the Management Console running with the Tomcat, perform the following steps:
1.
Copy the MySQL connector JAR file to the lib directory under Apache Tomcat. For example, mysql-connector-java-8.0.16.jar
. Use the latest available version of the driver for your
Java. For more information, see https://repo1.maven.org/maven2/mysql/mysql-connectorjava/ .
93
Kofax RPA Administrator's Guide
2.
Steps 2 and 3 are the same as for the Management Console running with the embedded
RoboServer. The log4j2.properties
file is located under tomcat directory\webapps
\Management Console\WEB-INF\classes .
Audit Log Reference
This section provides a list of operations that are logged when they are executed successfully or fail due to access restrictions. Log file examples are also provided for your reference.
Login Events
RoboServers are using credentials to register to the Management Console, therefore all user logins are logged. When a RoboServer starts, there is a login event in the audit log from the user that was given access to the RoboServer.
Logged Operations
The logged operations are grouped by sections in the Management Console.
Example: Logs
Here are examples of what the robot execution logs look like in different scenarios. MySQL is used as the logging database and the log message consists of timestamp, logging level, and detail message.
Robot run from REST call
A robot that is started by REST call, first logs the robot name with ID, execution ID and task ID; and then the user who started the robot with the project name and task ID.
2019-11-27 16:42:26 INFO Robot Wait60 with id = 17 execution id =
-1-9-67f20877bebb task id = 9 has requested to start
2019-11-27 16:42:26 INFO admin run Robot f1/f2/f3/Wait60.robot from Project
Default project with task id = 9 from REST
Robot run from SOAP call
2019-11-27 16:34:24 INFO Robot Wait60 with id = 17 execution id =
-1-1-67f20877bebb task id = 1 has requested to start
2019-11-27 16:34:24 INFO admin run Robot f1/f2/f3/Wait60 from Project
Default project with task id = 1 from SOAP
Robot run started from UI
This robot was started from the Robots section in Management Console.
2019-11-27 16:35:56 INFO Robot Wait60 with id = 17 execution id =
-1-2-67f20877bebb task id = 2 has requested to start
2019-11-27 16:35:56 INFO admin run Robot Wait60 with id = 17 task id = 2
Schedule triggered by time
No log.
94
Kofax RPA Administrator's Guide
Schedule triggered by user
Log messages can be referenced by schedule ID and task ID. The execution log messages with postfix "- from schedule, started by user" also indicates this robot was triggered by a manual schedule run. For example, "MultipleTaskSchedule" schedule contains 4 robot jobs: ExampleRobot1,
ExampleRobot2, ExampleRobot2, ExampleRobot3. When a user manually runs the schedule, the log messages should look as follows:
2019-12-02 10:50:22 INFO admin start Schedule MultipleTaskSchedule with id
= 373284858997185
2019-12-02 10:50:22 INFO Robot ExampleRobot1 with task id = 53 has been
queued for schedule MultipleTaskSchedule with id = 373284858997185
2019-12-02 10:50:22 INFO Robot ExampleRobot2 with task id = 54 has been
queued for schedule MultipleTaskSchedule with id = 373284858997185
2019-12-02 10:50:22 INFO Robot ExampleRobot2 with task id = 55 has been
queued for schedule MultipleTaskSchedule with id = 373284858997185
2019-12-02 10:50:22 INFO Robot ExampleRobot3 with task id = 56 has been
queued for schedule MultipleTaskSchedule with id = 373284858997185
2019-12-02 10:50:22 INFO Robot ExampleRobot1 with id = 1 execution id =
3816-53-1dc33f3a2a44b task id = 53 has requested to start - from schedule, started by
user
2019-12-02 10:50:22 INFO Robot ExampleRobot2 with id = 39 execution id =
3816-54-1dc33f3a2a44b task id = 54 has requested to start - from schedule, started by
user
2019-12-02 10:50:23 INFO Robot ExampleRobot2 with id = 39 execution id =
3816-55-1dc33f3a2a44b task id = 55 has requested to start - from schedule, started by
user
2019-12-02 10:50:23 INFO Robot ExampleRobot3 with id = 20 execution id =
3816-56-1dc33f3a2a44b task id = 56 has requested to start - from schedule, started by
user
95
Chapter 5
SQL Scripts for Kofax RPA Tables
The SQL scripts for creating and dropping tables in your database are located in the documentation\sql directory in your Kofax RPA installation directory. For example, C:\Program
Files\Kofax RPA 11.4.0\documentation\sql on the Windows system. The name of the script file includes the name of the database the script is intended for.
SQL scripts are installed together with Kofax RPA documentation and when you install Design
Studio.
SQL Scripts for Database Tables
The sql directory contains four subdirectories with different scripts as follows:
• altosoftsession : Scripts for creating and dropping tables for single sign on with Altosoft
• logdb : Scripts for creating and dropping logdb tables
• mc : Scripts for creating and dropping Management Console tables
• statistics : Scripts for creating and dropping Statistics (Kofax Analytics for RPA) tables
Management Console uses a 3rd party scheduling component called Quartz. Quartz also requires a number of tables which must reside among the other platform tables. These tables are also created automatically when the Management Console starts, or may be created manually using the scripts.
The following is a Quartz verification script.
select count(*) from QRTZ_SIMPLE_TRIGGERS; select count(*) from QRTZ_BLOB_TRIGGERS; select count(*) from QRTZ_CRON_TRIGGERS; select count(*) from QRTZ_CALENDARS; select count(*) from QRTZ_FIRED_TRIGGERS; select count(*) from QRTZ_LOCKS; select count(*) from QRTZ_PAUSED_TRIGGER_GRPS; select count(*) from QRTZ_SCHEDULER_STATE; select count(*) from QRTZ_TRIGGERS; select count(*) from QRTZ_JOB_DETAILS;
96
Appendix A
Kofax RPA Security Model
A. User login and authentication
Category
Description
Security Details
Authentication and Authorization
User provides login credentials for Kofax application.
Kofax RPA supports synchronizing users/groups with Active
Directory/LDAP. This allows Kofax RPA to take advantage of the corporate infrastructure for authentication and credential management.
Kofax RPA also has an application-specific authentication and authorization mechanism for convenience. This includes credential management and storage. Stored passwords are encrypted.
97
Kofax RPA Administrator's Guide
B. Client transmits to Kofax RPA server(s)
Category
Port
Protocol
Description
Security Details
Data in transit
80 or 443
HTTP or HTTPS
Clients transmit to the Kofax RPA servers.
All connectivity from Kofax RPA clients (Management Console and
Design Studio) to the Kofax RPA servers is via HTTP/HTTPS. HTTPS should be configured for maximum security.
C. Kofax RPA server(s) transmits to another Kofax RPA server(s)
Category
Port
Protocol
Description
Security Details
Data in transit
Configurable. Defaults 80, 443, 50000, 50443, 49999, 49998
HTTP/HTTPS, socket TCP/IP
Kofax RPA servers transmit to/from another Kofax application or server.
All Kofax RPA components can be configured to use secure encrypted communication (TLS 1.2) with custom certificates.
D. Kofax RPA servers transmit to Database server
Category
Port
Protocol
Description
Security Details
Data in transit
Varies depending on protocol
TCP/IP
Kofax RPA servers transmit to/from database
The Kofax RPA servers connect to the SQL database.
Typically, the database server system is co-located or otherwise physically protected such that transmission need not be otherwise encrypted.
However, if such encryption is needed, you can encrypt the database connection via SSL.
E. Robot and Data storage
Category
Description
Data at rest
Robots, configurations and related metadata are stored via the Management Console. Robots can store customer data in databases.
98
Kofax RPA Administrator's Guide
Security Details Robots, configurations and related metadata are stored in the
Kofax database, which is accessed through a configured system account. Database level encryption is also available using the encryption feature within the database itself.
Whether or not file system and/or database encryption is enabled, passwords (for external systems or application-specific users), are further protected. Passwords stored in the Password
Store or as input to a schedule are encrypted using a customer generated certificate. We will use the cipher selected for the certificate to encrypt any stored passwords. By default, the installation comes with an RSA 1024 bit encrypted certificate, but we strongly recommend that the customer generates their own certificate.
99
advertisement