Kofax RPA

Upgrade Guide
Version: 11.2.0

Date: 2021-06-01
© 2019–2021 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
Preface.......................................................................................................................................................... 4
Related Documentation...................................................................................................................... 4
Training............................................................................................................................................... 5
Getting help with Kofax products....................................................................................................... 5
Chapter 1: Kofax RPA Upgrade Guidelines............................................................................................. 7
General Upgrade Guidelines..............................................................................................................7
Start by upgrading only the Management Console.................................................................8
Create a new cluster............................................................................................................... 9
Move projects to the upgraded cluster....................................................................................9
Remove the old cluster......................................................................................................... 10
Important................................................................................................................................ 10
Keep your projects small.......................................................................................................11
Upgrade a RoboServer Service Installation.....................................................................................11
Upgrade Document Transformation Service.................................................................................... 12
Automatic Desktop Automation Service upgrade............................................................................ 12
Upgrade Kofax Analytics for RPA.................................................................................................... 13
Process Discovery Upgrade Notes.................................................................................................. 13
Upgrade From Assisted Entry to Manual Entry............................................................................... 13
Enable Dynamic License Distribution Mode.................................................................................... 15

3
Preface

This guide is intended for system administrators who upgrade the existing installation of Kofax RPA to a
newer version in the enterprise environment.

Related Documentation
1
The documentation set for Kofax RPA is available here:

[Link]

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 Administrator's Guide

Describes administrative and management tasks in Kofax RPA.

Help for Kofax RPA

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.

1
You must be connected to the Internet to access the full documentation set online. For access without an
Internet connection, see the Installation Guide.

4
Kofax RPA Upgrade Guide

Kofax RPA Getting Started with Document Transformation Guide

Provides a tutorial that explains how to use Document Transformation functionality in a Kofax RPA
environment, including OCR, extraction, field formatting, and validation.

Kofax RPA Developer's Guide

Contains information on the API that is used to execute robots on RoboServer.

Kofax RPA Desktop Automation Service Configuration Guide

Describes how to configure the Desktop Automation Service required to use Desktop Automation on a
remote computer.

Kofax RPA Application Programming Interface documentation

Contains information about the Kofax RPA Java API and the Kofax RPA .NET API, which provide
programmatic access to the Kofax RPA product. The Java API documentation is available from both the
online and offline Kofax RPA documentation, while the .NET API documentation is available only offline.

Note The Kofax RPA APIs include extensive references to RoboSuite, the original product name. The
RoboSuite name is preserved in the APIs to ensure backward compatibility. In the context of the API
documentation, the term RoboSuite has the same meaning as Kofax RPA.

Training
Kofax offers both classroom and computer-based training to help you make the most of your Kofax RPA
solution. Visit the Kofax Education Portal at [Link] for details about the available training
options and schedules.

Also, you can visit the Kofax Intelligent Automation SmartHub at [Link] 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, go to the Kofax website and select Support on the home page.

Note 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.

5
Kofax RPA Upgrade Guide

• 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.
• Access to the Kofax Customer Portal (for eligible customers).
Click the Customer Support link at the top of the page, and then click Log in to the Customer Portal.
• Access to the Kofax Partner Portal (for eligible partners).
Click the Partner Support link at the top of the page, and then click Log in to the Partner Portal.
• Access to Kofax support commitments, lifecycle policies, electronic fulfillment details, and self-service
tools.
Scroll to the General Support section, click Support Details, and then select the appropriate tab.

6
Chapter 1

Kofax RPA Upgrade Guidelines

This chapter includes best practices and important information about how to perform an upgrade to Kofax
RPA 11.2.0 from an earlier version of the product.

To ensure a successful transition to Kofax RPA Kofax RPA, we highly recommend that you install it
alongside your existing version of the product on the same computer. This approach gives you the ability
to acquaint yourself with the new product features, while continuing to use the earlier version for a period
of time to perform your daily work. While using both versions in parallel, you can open and test the default
project from the earlier version in Design Studio 11.2.0. Note that if you save the default project in version
11.2.0, it can no longer be opened with the earlier version of Design Studio.

Important If you use the API in your Kofax RPA environment, the Java and .NET files must be
updated when upgrading Kofax RPA. The new API files are located in the API folder of your Kofax RPA
installation folder, such as C:\Program Files\Kofax RPA [Link]\API.

General upgrade guidelines

Read the General Upgrade Guidelines topic to learn how to best handle upgrading from one major or
minor version to another.
Upgrade a RoboServer service installation
Read the Upgrade a RoboServer Service Installation topic if you are upgrading to a newer version of a
RoboServer service.
Upgrade Document Transformation Service
Read the Upgrade Document Transformation Service topic if you are upgrading to a newer version of
Document Transformation Service.
Upgrade Kofax Analytics for RPA
Read Upgrade Kofax Analytics for RPA if you are upgrading Kofax Analytics for RPA.
Upgrade from Assisted Entry to Manual Entry
Read the Upgrade From Assisted Entry to Manual Entry topic if you are upgrading from Kofax RPA10.3.0
or earlier and your existing robots use the Call SOAP Web Service step in Assisted Entry mode.
Upgrade from earlier versions
If you are upgrading from version earlier than 10.x, consult Kofax support for upgrade guidelines.

General Upgrade Guidelines

This section explains how to perform an upgrade from one major or minor product version to another.
Although the examples are based on an upgrade from version 11.0 to 11.1, the same information applies
to an upgrade from any 10.x version to another 10.x or 11.x version.

7
Kofax RPA Upgrade Guide

Note The process for adding a service pack or fix pack to your installation may require fewer steps. For
more information, refer directly to your service pack or fix pack documentation.

We always recommend testing and validating your business-critical robots when upgrading Kofax RPA. In
this topic, we are presenting a method to upgrade your production system when robots are deployed.

Although Kofax is always committed to making Kofax RPA backward compatible with your already defined
robots, types, snippets, mappings, and the like, it is always a good practice to validate your robots in a
test environment before upgrading your production system. A new version of Kofax RPA may introduce
subtle changes to robot language semantics, timing, website, and automation API compatibility. In turn, it
could lead to unwanted behavior of your robots. Some changes may be due to third-party library updates
required to ensure security, or to software enhancements and revisions.

Note Do not reuse cluster and log databases from the previous version of Kofax RPA Management
Console with a newer version of the Management Console. It may lead to errors.

If you use Oracle database for collecting analytics data in Kofax RPA and specify the same database
while upgrading to a new version, you must manually drop and create tables in the database. See the
"RoboServer log database" and "Scripts for Creating Database Tables" topics in Help for Kofax RPA for
details on creating database tables.

To mitigate the transition from one version of Kofax RPA to the next, Kofax RPA allows you to run
RoboServers for different versions in parallel in the same installation environment for a period of time.
That way, you can continue to use the existing version to run robots in a production environment, while
validating them in parallel within a test environment. Once you are satisfied and confident with the results
in the newer test environment, you can transition to the new version for use in production.

Start by upgrading only the Management Console

Upgrading the Management Console without upgrading the RoboServers means getting the newest
features from the Management Console and then adding RoboServers and Desktop Automation Services
with the newest version into clusters at a later time.

In our example, we are upgrading from Kofax RPA 11.0 to Kofax RPA 11.1 and have two RoboServers
running. In the Management Console > Admin > RoboServers section, notice how the 11.0
RoboServers are successfully connected from the newly upgraded Management Console.

8
Kofax RPA Upgrade Guide

If you look at your Desktop Automation Services in the Admin > Devices section, you can see how those
are also seamlessly connected to the 11.1 Management Console.

Create a new cluster

Next step is to create a new cluster to place upgraded RoboServers and Desktop Automation Services to.

In our example, we have created a new cluster named Production110 for placing upgraded RoboServers.
We have also upgraded one of the RoboServers and placed it in this cluster.

Likewise, we have upgraded one of the Desktop Automation Services to match the RoboServer version
and placed it into this cluster.

Move projects to the upgraded cluster

When a project has been validated to work on the newest version, it can be moved to the new cluster.
This action requires changing the cluster related to schedules in the project as in the following screen
shot.

Schedules

In the validated project, navigate to Schedules and click Edit from the context menu for schedules. On
the Basic tab, scroll down to the Run on cluster setting.

9
Kofax RPA Upgrade Guide

Services

Moving to a new cluster also requires changing the service cluster for REST and SOAP services.
Navigate to Admin > Projects, click Edit from the context menu for your project, and then select the
Services tab. On the Service cluster list, select the new cluster.

Remove the old cluster

When all your projects have been validated to run on the newest version and all RoboServers and
Desktop Automation Services have been upgraded and placed into the new cluster, you can now delete
the old cluster.

Important
While a project is running on a cluster with RoboServers from a previous version, your robots can only be
edited with the previous version of Design Studio. As soon as a robot is opened and saved with a newer

10
Kofax RPA Upgrade Guide

version of Design Studio, it is migrated to the format of the newest version (you can see the version/format
of a robot by looking at it in the repository of your Management Console).

A robot in the repository reveals its version.

If a robot has been edited with the newest version of Design Studio, you can no longer run the robot with
previous versions of the RoboServer. So, if you want to change the robot, you need to either edit it with
the older version of Design Studio or validate it (and other robots in the same project) to work on the
newest RoboServer and bump the entire project to the upgraded cluster.

Also, if you attempt to mix RoboServers from different versions into the same cluster, the robots may
switch from one version to another when they are run.

Keep your projects small

For this method of upgrading to work more efficiently, always try to keep your projects small.

Upgrade a RoboServer Service Installation

This section provides details about how to upgrade a RoboServer service.

Perform the following steps to upgrade your Linux installation of Kofax RPA.

1. Stop the RoboServer manually and wait for robots to finish executing (optional).
2. Update the packages.
3. Change the configuration in the new [Link] file (optional).
4. Restart the computer or use RoboServerService start command to restart the RoboServer.

Note the following when upgrading Kofax RPA on Linux:

• Upgrading a package replaces all the files in the /opt/Kofax RPA/ directory.
• When you start the upgrade procedure, the init.d service is stopped and replaced with a new
version. The service is stopped immediately without waiting for robots to finish executing. If you do not
want to interrupt the execution of the robots, stop the RoboServer manually before upgrading.
• A new [Link] file is created for the new service. The new file is created in /home/
Kofax RPA/.Kofax RPA/<release_version>/Configuration/ similarly to the old one. That
means a new directory is created for the new release so that the old configuration file remains intact
in the folder with the older release name. The link to the configuration file in /etc/opt/Kofax RPA/
[Link] points to the settings file in the last installed release.
• The configuration from the old [Link] file is not transferred to the new one, this must
be done manually.

11
Kofax RPA Upgrade Guide

Upgrade Document Transformation Service

To upgrade the Document Transformation Service, you need to perform the following actions:
• Upgrade the program files and installed IIS services (Kofax RPA Document Transformation Service and
Kofax RPA Document Transformation Client). Upgrading the program files is only required if they reside
on the same computer where the Document Transformation Service is running. By default, the program
files are located in C:\Program Files\Kofax DTS.
• Move created data such as projects, custom configurations, and so on.

Before upgrading, create a backup of your Document Transformation folder, including projects, Online
Learning files, and any custom configuration such as adjustments to [Link] files. By default, the
folder is located on the C drive (C:\Document Transformation). When upgrading, it is important that
you consider the following details:
• Existing batches that are waiting for validation may not work with the newer version. Finish processing
all existing batches before you start the upgrade. Otherwise, batches waiting for validation may not be
processed successfully after the upgrade.
• Remove the existing program files and IIS services. To remove the program files,
uninstall Kofax RPA Document Transformation through the Windows Control Panel. If the
EnableDocumentTransformationWindows scripts were used to create the IIS services, remove the
created IIS Application Pools, websites, and the installed Document Transformation Service folder.

Note Uninstalling may fail to stop the Document Transformation Service Scheduler. Manually stop the
Scheduler before uninstalling Kofax RPA Document Transformation.

After removing the program files and services, you can use the Document Transformation Service
installer for the newer version. Afterward, use the applicable EnableDocumentTransformationWindows
script to install the new services.
• Manually reapply any custom configuration to the services. Do not copy and paste the older
configuration files as they may not be compatible with the services.
• Manually reapply any custom configuration to the built-in standard projects. Otherwise, you can give the
older projects new names to continue using them in the newer version.

Automatic Desktop Automation Service upgrade

Starting from version 10.7, new Desktop Automation Service version packages are installed automatically
if the Lock package option is not selected on the Windows tab of the Desktop Automation Service
window. The first time a newer version Management Console (or Design Studio if a direct connection is
used) tries to connect to the Desktop Automation Service, a new service version package is installed.
The packages in ZIP files are installed to C:\ProgramData\Kofax RPA on the automated computer.
The appropriate package is selected automatically depending on the Kofax RPA component version. For
details, see "Windows tab options" in the "Configure Desktop Automation Service" topic in Help for Kofax
RPA or in the Desktop Automation Service Configuration Guide.

Automatic Desktop Automation Service upgrade is supported by Kofax RPA version 10.2 and later.
Version 10.7 and later support this mode immediately after installation. To use automatic service upgrade
in versions 10.2 to 10.6, update your copy of Kofax RPA to at least one of the following versions:

12
Kofax RPA Upgrade Guide

[Link]
[Link]
[Link]
[Link]
[Link]
[Link]
[Link]

Upgrade Kofax Analytics for RPA

Kofax Analytics for RPA 2.5 is designed to use Kofax Insight 6.3. The RPA views in the Kofax Analytics
for RPA 2.5 have changed, but you can use the analytics and log databases from the previous version of
Kofax RPA.

The Process Discovery views have changed and can only work with the data collected and analyzed by
the Process Discovery in Kofax RPA 11.2.0.

For Kofax Insight upgrade, see the "Upgrade Insight" chapter in the Kofax Insight Installation Guide. You
can also consult Kofax support before performing an upgrade.

Process Discovery Upgrade Notes

Note the following when upgrading to the latest version of Process Discovery.

General Process Discovery upgrade notes

• Agents and Analyzer of the previous version are removed when you upgrade to a new version of
Process Discovery.
• After upgrading to a new version of Process Discovery, Agent and Analyzer configuration is overwritten.
• For mass agent upgrade, use silent installation of Process Discovery Agents, as described in the
Deploy Process Discovery Agents section of the Kofax RPA Administrator's Guide.
• You can restore Process Discovery Group configuration using Management Console backup. See Back
Up Management Console in the Kofax RPA help.
Notes on upgrading Process Discovery Analyzer
• Agent database must match the version of the Analyzer.
• Analyzer database must match the version of the Analyzer.

Upgrade From Assisted Entry to Manual Entry

Since version [Link] the Call SOAP Web Service step does not support Assisted Entry mode. If you are
upgrading from an earlier version of Kofax RPA, update the step as described below.
1. Open the robot in an earlier version of Design Studio, for example [Link]. Create a copy of the
robot to ensure that you have a backup and because it is easier to upgrade. In the following steps we
will update the step in the copy of the original robot.

13
Kofax RPA Upgrade Guide

2. Open the copy of the robot in Design Studio, execute it to the Call SOAP Web Service step, and
change the entry mode to Manual Entry.
3. Switch to the original robot. Execute to the Call SOAP Web Service step. Open the Browser Tracer
from the Tools menu or by pressing F12. In the Browser Tracer click the red button to start trace
recording.
4. Execute the Call SOAP Web Service step by clicking the step after it.
5. If the original step has a specified Web Service URL, copy it from the step in the original robot to the
step in the updated robot. Otherwise, select the original robot in the editor to ensure that what you
see in the Browser Tracer is for that robot. In the Browser Tracer, click the single HTTP event entry,
copy the URL, and paste to the Web Service URL property of the updated step.
6. In the Browser Tracer, click the single HTTP event entry and find the header property called
SOAPAction on the Request tab. The Browser Tracer should look similar to the following example:

Copy the value of the SOAPAction header, switch to the updated robot and paste it to the property
called SOAP Action. To copy the value, double-click the header in the list and copy its value from
the Show HTTP Header dialog box.
7. In the Browser Tracer, find the event again, click the Request Data tab, copy the entire text of the
request, and paste it to the SOAP Request property of the updated step.
8. Ensure that the updated step uses the correct SOAP version by looking at the WSDL file used by
the original step. If this WSDL file uses the namespace [Link]
soap/, the version is 1.1. If it uses the namespace [Link]
soap12/, the version is 1.2.
9. Make sure that Output, Options, and other properties on the updated step have the same value as
on the original one.
10. Test the updated robot, save it. Open it in Kofax RPA 10.4.0 and test it.

14
Kofax RPA Upgrade Guide

11. All the previous steps assumed that parameter values in the step are static, that is, do not depend
on variables. If parameter values in your step are taken from variables, create the value of the SOAP
Request property using an expression instead of a static value.
Start by taking a copy of the request. Change the option from XML to XML from Expression and
paste the request into the Expression text field. This will produce an expression with an error. You
fix this by surrounding it with >> and <<.

Dynamic property values

All the previous steps assumed that parameter values in the step are static, which means they are
hardcoded and do not change during the execution of the robot. If parameter values in your step are taken
from variables, create a value of the SOAP Request property using an expression instead of a static
value.
Start by making a copy of the request. Change the option from XML to XML from Expression and paste
the request into the Expression text field. This should produce an expression with an error. Fix it by
surrounding the request with double greater than and less than signs (>> <<).
For instance, if the value of the parameter zipCodeList is taken from a variable that is also called
zipCodeList, the SOAP Request surrounded by >> << should look as follows (some details are left out).
>><?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope ...>
<soapenv:Body>
<ns1:LatLonListZipCode ...>
<zipCodeList xsi:type="xsd:string">90210</zipCodeList>
</ns1:LatLonListZipCode>
</soapenv:Body>
</soapenv:Envelope><<
The value of the zipCodeList parameter in the example is static and equals 90210. To use the value of
the zipCodeList variable instead of the hardcoded value, replace the actual value of the parameter with
the variable name in the following format:
<< + zipCodeList + >>
The code example looks like the following:
>><?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope ...>
<soapenv:Body>
<ns1:LatLonListZipCode ...>
<zipCodeList xsi:type="xsd:string"><< + zipCodeList + >></zipCodeList>
</ns1:LatLonListZipCode>
</soapenv:Body>
</soapenv:Envelope><<
Continue this process to replace all parameters with variables.
If a parameter depends on an expression and not just a variable, use that expression instead of the
variable. For example, if a parameter depends on the expression x+1, replace the value with:
<< + (x+1) + >>

Enable Dynamic License Distribution Mode

In Dynamic license distribution mode, RoboServers receive the licenses from the cluster per request.
A RoboServer can get as many licenses as it requests if they are available. In this mode, RoboServers
communicate only with the Management Console and block other requests, such as API calls.

15
Kofax RPA Upgrade Guide

Dynamic license distribution mode is supported by Kofax RPA version 10.3 and later. Version 10.7 and
later support this mode immediately after installation. To use dynamic license distribution, in versions 10.3
to 10.6, update your copy of Kofax RPA to at least one of the following versions:
[Link]
[Link]
[Link]
[Link]
[Link]
[Link]
[Link]

Note If you change the license distribution mode from Static to Dynamic for RoboServers that do not
support this mode, those RoboServers disappear from the RoboServers section in the Management
Console. To see the missing RoboServers in the Management Console, change the mode to Static and
restart the Management Console.

16