advertisement
Kofax RPA
Upgrade Guide
Version: 11.3.0
Date: 2022-03-23
© 2019–2022 Kofax. All rights reserved.
Kofax is a trademark of Kofax, Inc., registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in any form without the prior written permission of Kofax.
Table of Contents
3
Preface
This guide is intended for system administrators who upgrade the existing installation of Kofax RPA to a newer version in the enterprise environment.
Related Documentation
The documentation set for Kofax RPA is available here:
https://docshield.kofax.com/Portal/Products/RPA/11.3.0_5cdzhlgb3t/RPA.htm
In addition to this guide, the documentation set includes the following items:
Kofax RPA Release Notes
Contains late-breaking details and other information that is not available in your other Kofax RPA documentation.
Kofax RPA Technical Specifications
Contains information on supported operating systems and other system requirements.
Kofax RPA Installation Guide
Contains instructions on installing Kofax RPA and its components in a development environment.
Kofax RPA Administrator's Guide
Describes administrative and management tasks in Kofax RPA.
Kofax RPA Help
Describes how to use Kofax RPA. The Help is also available in PDF format and known as Kofax RPA
User's Guide .
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.
The Kofax RPA APIs include extensive references to RoboSuite, the original product name. The
RoboSuite name is preserved in the APIs to ensure backward compatibility. In the context of the
API documentation, the term RoboSuite has the same meaning as Kofax RPA.
Training
Kofax offers both classroom and computer-based training to help you make the most of your Kofax
RPA solution. Visit the Kofax Education Portal at https://learn.kofax.com/ for details about the available training options and schedules.
Also, you can visit the Kofax Intelligent Automation SmartHub at https://smarthub.kofax.com/ to explore additional solutions, robots, connectors, and more.
Getting help with Kofax products
The Kofax Knowledge Base repository contains articles that are updated on a regular basis to keep you informed about Kofax products. We encourage you to use the Knowledge Base to obtain answers to your product questions.
To access the Kofax Knowledge Base:
1.
Go to the Kofax website home page and select Support .
2.
When the Support page appears, select Customer Support > Knowledge Base .
The Kofax Knowledge Base is optimized for use with Google Chrome, Mozilla Firefox or
Microsoft Edge.
5
Kofax RPA Upgrade Guide
The Kofax Knowledge Base provides:
• Powerful search capabilities to help you quickly locate the information you need.
Type your search terms or phrase into the Search box, and then click the search icon.
• Product information, configuration details and documentation, including release news.
Scroll through the Kofax Knowledge Base home page to locate a product family. Then click a product family name to view a list of related articles. Please note that some product families require a valid Kofax Portal login to view related articles.
From the Knowledge Base home page, you can:
• Access the Kofax Community (for all customers).
Click the Community link at the top of the page.
• Access the Kofax Customer Portal (for eligible customers).
Click the Support link at the top of the page. When the Customer & Partner Portals Overview appears, click Log in to the Customer Portal .
• Access the Kofax Partner Portal (for eligible partners).
Click the Support link at the top of the page. When the Customer & Partner Portals Overview appears, click Log in to the Partner Portal .
• Access Kofax support commitments, lifecycle policies, electronic fulfillment details, and selfservice tools.
Go to the General Support section, click Support Details , and then select the appropriate tab.
6
Chapter 1
Kofax RPA Upgrade Guidelines
This chapter includes best practices and important information about how to perform an upgrade to Kofax RPA 11.3.0 from an earlier version of the product.
To ensure a successful transition to 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.3.0. Note that if you save the default project in version 11.3.0, it can no longer be opened with the earlier version of Design
Studio.
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 11.3.0.0\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.
7
Kofax RPA Upgrade Guide
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.
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.
Do not reuse Management Console configuration, 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
Kofax RPA Help 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.
If you want to restore your Management Console configuration using a backup, first set up a new version of the Management Console with all new databases and then restore the
Management Console configuration from a backup.
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.
9
Kofax RPA Upgrade Guide
If you set up a newer version environment and want to run older robots that use KCU licensing in a newer RoboServer (for example, you want to add a 10.3.2.2 RoboServer to a Management
Console 11.2 environment), create a new cluster in the new Management Console and place the older RoboServer node into that cluster. See Create New Cluster in the "RoboServers" topic in Help for Kofax RPA.
If you upgrade to a newer version of Kofax RPA using a backup, the RoboServer threshold version is not updated automatically. To ensure the robots can run, navigate to Cluster settings >
General > Threshold version and manually specify the RoboServer threshold version.
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.
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.
10
Kofax RPA Upgrade Guide
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 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.
11
Kofax RPA Upgrade Guide
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 roboserver.settings
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 roboserver.settings
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/RoboServer.conf
points to the settings file in the last installed release.
• The configuration from the old roboserver.settings
file is not transferred to the new one, this must be done manually.
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 Web.config
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
12
Kofax RPA Upgrade Guide the created IIS Application Pools, websites, and the installed Document Transformation Service folder.
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 Kofax RPA Help 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:
10.2.0.8
10.3.0.9
10.3.1.2
10.3.2.6
10.4.0.4
10.5.0.2
10.6.0.3
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.3.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.
13
Kofax RPA Upgrade Guide
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 10.3.0.1 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 10.3.0.0. 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.
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.
14
Kofax RPA Upgrade Guide
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 http://schemas.xmlsoap.org/ wsdl/soap/ , the version is 1.1. If it uses the namespace http://schemas.xmlsoap.org/ wsdl/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.
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
15
Kofax RPA Upgrade Guide 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.
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:
10.2.0.8
10.3.0.9
10.3.1.2
10.3.2.6
10.4.0.4
16
Kofax RPA Upgrade Guide
10.5.0.2
10.6.0.3
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.
17
advertisement