advertisement
Kofax TotalAgility
Installation Guide
Version: 7.9.0
Date: 2021-03-11
© 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
3
Kofax TotalAgility Installation Guide
4
Kofax TotalAgility Installation Guide
5
Kofax TotalAgility Installation Guide
Create Dynamics AX 09 service reference to the TotalAgility web service......................... 152
Create Dynamics AX 12 service reference to the TotalAgility web service......................... 152
6
Kofax TotalAgility Installation Guide
7
Kofax TotalAgility Installation Guide
8
Preface
This guide includes instructions for installing and upgrading to Kofax TotalAgility 7.9.0, including:
• Preparations, decisions, precautions, settings, and tips to help you install Kofax TotalAgility.
• Instructions for installing Kofax TotalAgility in silent mode or using the wizard in a client/server or standalone configuration.
• Information about installing other Kofax products used with Kofax TotalAgility.
• Information about updating various TotalAgility configuration files post installation, instead of manually updating each configuration file and the settings separately.
Read this guide completely before installing the software.
Related documentation
The full documentation set for Kofax TotalAgility is available at the following location.
https://docshield.kofax.com/Portal/Products/KTA/7.9.0-ud9cfx6hos/KTA.htm
In addition to this guide, the documentation set includes the following items:
• Kofax TotalAgility Prerequisites Guide : Provides system requirements for installing TotalAgility, instructions for running the prerequisite utility, and a software checklist for various installation types.
• Kofax TotalAgility Integration Server Installation Guide : Describes how to install Kofax Integration
Server and integrate it with other products.
• Kofax TotalAgility On-Premise Multi-Tenant Installation Guide : Describes how to install and configure
On-Premise Multi-Tenant system.
• Kofax TotalAgility Configuration Utility Guide : Explains how to use the Configuration Utility to update settings across various configuration files for different types of installation and deployment.
• Kofax TotalAgility Administrator's Guide : Provides information to the administrator on configuring and maintaining a TotalAgility installation.
• Kofax TotalAgility Architecture Guide : Provides an overview of the TotalAgility architecture, covering various deployments for on-premise, on-premise multi-tenancy and Azure environments.
• Kofax TotalAgility Best Practices Guide : Describes the best practices you must follow when using
TotalAgility to improve performance, cost, maintenance, availability and security.
• Kofax TotalAgility Features Guide : Provides an overview of the TotalAgility features.
• Kofax TotalAgility Migration Guide : Provides information on TotalAgility upgrades from different versions and post upgrade configuration.
• Kofax TotalAgility Help : Provides details about using TotalAgility to design business jobs and cases, assign resources, create forms, integrate with external applications, and more.
• Kofax TotalAgility Workspace Help : Describes how to use the Workspace to manage activities, jobs, and resources.
9
Kofax TotalAgility Installation Guide
• Kofax TotalAgility On-Premise Multi-Tenant System Help : Describes how to create and manage tenants using the TotalAgility On-Premise Multi-Tenant system.
• Kofax TotalAgility Web Capture Control Help : Provides details on using a Web Capture control in creating multi-page documents, creating a new document in a new folder, deleting pages that have been incorrectly scanned, and more; also, describes the buttons available in a Web Capture control toolbar.
• Kofax Analytics for TotalAgility Product Features Guide : Provides an overview of the dashboards that help you track data through the workflow, analyze the effectiveness of the processes and resources, and address business problems.
• Kofax TotalAgility Tables : Describes the Kofax TotalAgility tables and fields used by Kofax Analytics for
TotalAgility.
• Migration From Kofax Products Guide : Provides information about migrating TotalAgility files and Kofax
Transformation Modules projects to TotalAgility.
Offline documentation
Customers who require offline documentation can download the individual zip files available on a per language basis, such as Kofax TotalAgilityDocumentation7.9.0_EN.zip and Kofax
TotalAgilityDocumentation7.9.0_DE.zip from the Kofax Fulfillment Site .
See Access the TotalAgility documentation for more information
Training
Kofax offers both classroom and online training to help you make the most of your product. To learn more about training courses and schedules, visit the Kofax Education Portal on the Kofax website.
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.
• 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.
10
Kofax TotalAgility Installation Guide
• 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.
11
Chapter 1
Installation planning
For information on supported operating systems and other system requirements, see the Kofax
TotalAgility Technical Specifications document on the Kofax TotalAgility Product Documentation site. The document is updated regularly, and we recommend that you review it carefully to ensure success with your TotalAgility product.
Review these important notes before you proceed with the installation.
• To view information on the system requirements for installing TotalAgility, instructions for running the prerequisite utility, and the software checklist for various installation types, download the Kofax
TotalAgility Prerequisites Guide from the Kofax Fulfillment Site.
• If your solution includes multiple Kofax products, review the Kofax Technical Specifications document.
• Obtain a license key for TotalAgility from your Account Manager or Kofax Support.
• Before extracting the TotalAgility installation ZIP file, unblock the file from the file properties window.
• The TotalAgility servers should run on the same time zone, because issues may occur if they run on different time zones.
• Upgrade installations of Kofax Transformation Designer that connects to TotalAgility 7.9.0.
• TotalAgility includes a limited number of VRS Elite licenses. You may need to purchase additional licenses, depending on the number of scanners you plan to use with VRS. See the Kofax Scanner
Configurator to verify VRS certification and licensing requirements for your scanner.
Utilities
The following utilities are available on the TotalAgility installation media.
• To ensure all the required software is installed on your computer before installing TotalAgility, run the
Prerequisite utility. For more information, see the Kofax TotalAgility Prerequisites Guide .
• After installing TotalAgility, you can update the configuration settings by editing each configuration file separately or by running the configuration utility available on the installation media. The utility allows you to modify or update the settings across multiple configuration files at one go instead of editing each file separately. You must manually copy the utility onto each server where the configuration settings are to be modified. See the Kofax TotalAgility Configuration Utility Guide .
• To test how an image will look once the eVRS setting is applied to it, run the
.
12
Kofax TotalAgility Installation Guide
License Proxy
Use TotalAgility License Proxy when the license server is not directly accessible from VRS stations or the linked TotalAgility server. For example, due to security restrictions or on using Azure. Using the License
Proxy, you can use a TotalAgility license configuration through TotalAgility web services rather than by directly addressing the license server.
A license proxy is also useful for network topologies where multiple networks are logically separate, such as Microsoft Azure cloud. A License proxy allows computers in Network A to use a TotalAgility license server in Network B. A license proxy uses TotalAgility web services (over HTTP/HTTPS) to communicate with the license server. The license proxy computer needs a working internet connection to facilitate the
HTTP/HTTPS traffic to the License server.
See TotalAgility License Proxy installation
.
Important If you have previously upgraded from Kofax TotalAgility 7.1.0 to 7.2.0 and are now upgrading to 7.9.0 and want to use License Proxy, then you must manually setup the license proxy on TotalAgility
7.2.0 before upgrading to 7.9.0. This action is not required if directly upgrading from TotalAgility 7.1.0 to
7.9.0.
Licensing information
This section provides information on licensing details.
Concurrent user licensing
In the Concurrent User model, many users can simultaneously log into the system. Each user session consumes a license. For example, if a single user logs into the TotalAgility Designer and the TotalAgility
Workspace simultaneously or the user logs into the Designer in two browsers such as Internet Explorer and Chrome, the user consumes two concurrent licenses. When a user logs off from a session, the license server automatically releases the license.
When the number of concurrent users reaches the maximum, the system automatically checks for available reserved licenses. If any reserved license is available, a new user can log on and the count of available reserve licenses is reduced by 1. Keep the following items in mind when managing reserved licenses:
• A reserved license expires seven days after you begin using the license.
• You can use each reserved license only twice within 12 months.
If the user tries to log on after the number of concurrent logons reaches the limit and there are no reserved licenses, the system displays an error message and additional users cannot log on.
If a reserved license expires, an error message appears in the TotalAgility Designer and TotalAgility
Workspace.
13
Kofax TotalAgility Installation Guide
Activate a license in TotalAgility
The license period starts once the license is activated. So you can skip activation during installation and only activate it when you are ready to use TotalAgility.
Activate a license in TotalAgility On-Premise
If you log on to TotalAgility for the first time and the license is not activated, the License Activation window opens.
1.
In the License Activation window, either click Next to accept the default values for the License
Server and Port Number , or enter the new values.
2.
Click Set license server to save the information.
3.
For further instructions, see Activate the License Server step in Perform a standard installation.
Note If you have issues activating your licence, contact Kofax support at: http:// www.kofax.com/support/tools/
Automatic recovery
After TotalAgility installation, it is possible to manually configure the Kofax License Server Service to automatically restart in the event of a service error.
1.
Go to Service Control Manger .
2.
Edit the properties for the Kofax License Server Service.
3.
Go to the Recovery tab.
4.
Configure options for how the service should respond after the first, second, and subsequent failures.
You do not need to restart the service for the changes to take effect.
Note You can also do this configuration at the command line. Example: sc.exe failure KSALicenseService actions= restart/660000/ restart/660000/""/660000 reset= 86400
Kofax Message Connector
Kofax Message Connector is a Windows service responsible for importing messages and files in many electronic formats. It retrieves documents from various sources and saves them in its internal storage making them available for retrieval through a web service interface. TotalAgility connects to the Message
Connector web service interface and retrieves the documents for import.
Kofax Message Connector can import messages and files from a number of sources:
• Email messages including attachments using various email protocols (SMTP, POP3, IMAP, EWS).
• Fax messages (via internal fax over IP server or external fax servers: Kofax Communication Server,
RightFax, Biscom).
• Files from a local or network folder.
14
Kofax TotalAgility Installation Guide
For information on prerequisites for the Kofax Message Connector, see the Kofax TotalAgility
Prerequisites Guide and for information on deployment scenarios and advanced configurations, see the
Kofax TotalAgility Administrator's Guide .
System limits
Following system limits are applicable for 64-bit installations. For 32-bit installations, these limits may vary.
• The maximum size of a message in Message Connector storage is 8 GB.
• Up to three Message Connector instances on a single computer are allowed.
• For KfxConverter, the maximum system memory usage limit is up to 4 GB.
Note The limit of the input file size may vary depending on the number of pages in a document, type of document and type of conversion.
Reporting Server
Kofax Reporting provides centralized storage of historical operational metrics and audit data. Kofax
Reporting includes components, such as the reporting service and databases.
Important Due to high process utilization by Transformation Server (99%), Reporting Server is known to produce SQL Timeout error when installed on the same machine as Transformation Server. Therefore, you must install Reporting Server separately from Transformation Server.
Kofax VRS Elite
We highly recommend Kofax VRS Elite, a patented image perfection software that dramatically improves scanning productivity and document capture efficiency when used with a VRS-certified scanner. If your scanner is not VRS-certified, you can use the Kofax image processing technology included with
TotalAgility.
Several Kofax VRS licensing options are available:
Kofax VRS Basic or Professional OEM
Automatically activate a Kofax VRS Basic or Professional OEM license that is included with many industry-standard scanners. License activation for these scanners is required only when upgrading to
Kofax VRS Elite.
Standalone workstation
Manually activate a standalone license, which stays on the workstation until it is deactivated. The standalone license can only be activated on one scan station at a time.
TotalAgility license server
Centrally manage concurrent VRS Elite licenses from the TotalAgility license server.
15
Kofax TotalAgility Installation Guide
To centrally manage VRS licenses through the TotalAgility license server, each VRS station needs to communicate with the license server directly or through a license proxy.
Web Capture Service
To enable web scanning, you must install the Kofax Web Capture Service. When installing through the browser, you must have administrative rights to complete the installation.
Install the Kofax Web Capture Service either at the default location or to a custom location.
You must install the Web Capture Service only once, and web scanning is enabled across all the supported browsers.
Temporary files are created under the folder “Interprocess”. The user must have read/write access to this folder.
You can also use the Web Capture Service on multiuser environments.
Scan Agent Service
The Scan Agent Service is an asynchronous upload capability, which allows scan operator to continue on to the next batch, without needing to wait for the previous scan job to complete upload.
This service is useful in remote scanning scenarios, where the scan station has limited network bandwidth to the main TotalAgility site.
The capability allows scan operator to keep up with physical scanning throughput, while image upload is done in the background, thus enhancing the scan operator efficiency.
This feature is only available for Scan Create New Job forms.
A Scan Create New Job form automatically uses the asynchronous image upload mode if it detects Scan
Agent Service installed on the scan station. Otherwise, it uses the synchronous image upload mode if the
Scan Agent Service is not detected.
For Device Create New Job form, a pre-condition of [SCANNED] > 0 must be added to the first activity in a process, to allow the process to wait for all images to be uploaded before moving on to the first activity.
16
Chapter 2
TotalAgility installation
This chapter describes two methods for installing TotalAgility:
•
Silent installation for multiple servers that use the same configuration.
•
using the installation wizard.
You can install TotalAgility as one of the following types:
• Database Only : Installs only the database component of Kofax TotalAgility only; no other components are installed.
• Upgrade Databases : Upgrades all the databases to the latest version of TotalAgility when TotalAgility is not installed locally.
Note Upgrading the databases prior to version TotalAgility 7.4.0 is not supported when TotalAgility is not installed locally.
• Web Server : Installs a server to point to any Application server. In case you install TotalAgility on a computer other than the default port, you must enter the Application Server machine name and port number. For example, <appserver_name:82>. A Web server installs the SDK Services and user interfaces for the TotalAgility Designer and TotalAgility Workspace.
• Application Server : Installs a server to which remote clients will connect and sets up their Web servers. An Application server only installs Core services and does not install user interfaces and any shortcuts for the TotalAgility Designer and Workspace.
• Web and Application Server : Installs the Web and Application servers on a single computer.
• Real Time Transformation Service : Installs the Real Time Transformation Service.
Note
• You must have administrator account to install TotalAgility.
• Ensure that the user who will run TotalAgility has "Log on as Service" rights.
• You can use hotkeys to navigate to next screen.
• Post installation, you can modify the configuration settings by editing each configuration file separately or running the configuration utility. The configuration utility is available on the installation media. You must manually copy the utility onto each server where the configuration settings are to be modified. See the Kofax TotalAgility Configuration Utility Guide .
Perform a silent installation
Use the TotalAgility silent installation to install TotalAgility automatically from a command line or a batch file. After you edit the silent installation file, the installation proceeds without any user interaction.
17
Kofax TotalAgility Installation Guide
See also:
•
Silent installation for Database Only
•
Silent installation for upgrading databases
•
Silent installation of Web and Application on the same server
•
Silent installation on a separate Web or Application server
•
Silent installation for Real Time Transformation Server
Silent installation for Database Only
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall and open
SilentInstallConfig.xml
using a text editor.
2.
In SilentInstallConfig.xml, update the following parameters.
Default Value Description Parameter
DatabaseInformation
InstallDatabases true
OverwriteIfExisting false
Installs the databases.
Set to false to ignore installing databases.
If set to true, overwrites the existing databases.
Note If the existing database details are not valid, or if the databases does not exist, an errors occurs and the installation fails.
Main Database
DatabaseName TotalAgility
Server server name
Specify the name of the Main database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Note When installing TotalAgility with a remote database, update
SilentInstallConfig.xml
with the server name
(<Server>servername</Server>) of the machine on which the database resides.
The account used to connect to the database during the installation requires
DB_CREATOR rights.
Security
18
Kofax TotalAgility Installation Guide
Parameter
WindowsAuthentication
UserName
Password
NewDatabase
Audit Database
DatabaseName
Server
SqlScript
CreateScript
DropScript
InitializeScript
ConversionScript
Security
WindowsAuthentication
UserName
Password
NewDatabase
Finished Jobs Database
DatabaseName
Server
SqlScript
CreateScript
DropScript
Conversion Script
Security empty empty false
TotalAgility server name
Create_Archive.sql
Drop_Archive.sql
Convert_Archive.SQL
Default Value true empty empty false
TotalAgility server name
Create_Audit.sql
Drop_Audit.sql
Initialise_Audit.sql
Convert_Audit.SQL
true
Description
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Set to true to create new database.
Specify the name of the Audit database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Accept the default.
Accept the default.
Accept the default.
Only required for patch when there are SQL changes.
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Set to true to create new database.
Specify the name of the Finished
Jobs database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Accept the default.
Accept the default.
Only required for patch when there are SQL changes.
19
Kofax TotalAgility Installation Guide
Parameter
WindowsAuthentication
Default Value true
UserName
Password empty empty
NewDatabase false
DataLayer - TotalAgility_Documents Database
DatabaseName TotalAgility_Documents server name Server
SqlScript
CreateScript
DropScript
Conversion Script
Security
WindowsAuthentication
Repository2012_Drop.sql
Repository2012_Convert.SQL
true
Set to true to create new database.
Specify the name of the
TotalAgility_Documents database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Repository2012_TablesCreate.sql Accept the default.
Accept the default.
Only required for patch when there are SQL changes.
Set to true to use Windows credentials for logging in.
If set to false, provide the username and password. Otherwise, leave the username and password blank.
UserName
Password
NewDatabase
Reporting_Analytics Database
DatabaseName empty empty false
Description
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Set to true to create new database.
Server
TotalAgility_Reporting server name
Specify the name of the
TotalAgility_Reporting database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
SqlScript
CreateScript Accept the default.
DropScript
InitializeScript
Kofax.Reporting.Analytics.
SQL_TablesCreate.sql
Kofax.Reporting.Analytics.
SQL_Drop.sql
Kofax.Reporting.Analytics.
SQL_Initialize.sql
Accept the default.
Accept the default.
20
Kofax TotalAgility Installation Guide
Parameter
Conversion Script
Security
WindowsAuthentication
UserName
Password
NewDatabase
Reporting_Staging Database
DatabaseName
Server
SqlScript
CreateScript
DropScript
InitializeScript
Security
WindowsAuthentication
UserName
Password
NewDatabase
Install Info
Default Value empty true
Description
Only required for patch when SQL changes are needed.
Set to true to use Windows credentials for logging in.
If set to false, provide the username and password. Otherwise, leave the username and password blank.
empty empty false Set to true to create new database.
TotalAgility_Reporting_Staging server name
Specify the name of the
TotalAgility_Reporting_Staging database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Kofax.Reporting.Analytics.
Staging.SQL_TablesCreate.sql
Kofax.Reporting.Analytics.
Staging.SQL_Drop.sql
Kofax.Reporting.Analytics.
Staging.SQL_Initialize.sql
Accept the default.
Accept the default.
Accept the default.
true Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
empty empty false Set to true to create new database.
21
Kofax TotalAgility Installation Guide
Parameter
InstallType
Default Value
Both
Description
Change the value to DatabaseOnly.
Note When you install only databases, the system ignores the services, and does not install services such as CoreworkerService,
ImportService and
ExportService.
<SiteRoot>
KTAResourceName
KTAResourcePassword
RunAsSystemAccount
Default Web Site empty empty false
Install TotalAgility under a custom site that uses a non-standard port other than the standard ports (80 and 443).
For example, create a custom site called "testsite" under IIS using the port number 85.
Specify a username for the
TotalAgility user to be created on installation.
Specify a password (minimum 6 alphanumeric characters) for the
TotalAgility user to be created on installation.
If set to true, the IIS AppPool and
Kofax TotalAgility services run as the
LocalSystem account.
Note If you set this parameter to true, the user can still logon using the credentials specified in the Kofax TotalAgility Resource
Credentials window when installing TotalAgility.
3.
Save and close the file.
4.
On the Command Prompt, change the command line to the root directory of the Setup.exe file.
5.
Run Setup.exe /Silent .
The databases are installed automatically.
The system generates a log file that reports errors (if any).
The success or failure of installation is indicated in the event log.
When automating the installation, if you run setup.exe from the command line, or run setup.exe as a silent installation, one of the codes returns to indicate the following:
• 0= Success
• 1= Success with warnings
• 2= Failure
See also:
•
Silent installation for upgrading databases
22
Kofax TotalAgility Installation Guide
•
Silent installation of Web and Application on the same server
•
Silent installation on a separate Web or Application server
•
Silent installation for Real Time Transformation Server
Silent installation for upgrading databases
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall and open
SilentInstallConfig.xml using a text editor.
2.
In SilentInstallConfig.xml, update the following parameters.
Parameter
<ServicesInstallOptions>
Default value Description true for all services Set to false for all the services.
Note When you upgrade
TotalAgility databases, the services, such as Core
Worker Service, Reporting
Service, License Service,
Transformation Server are ignored and not installed.
DatabaseInformation
InstallDatabases true
OverwriteIfExisting true
Set to false to ignore installing databases.
If set to true, installs the databases.
If set to true, overwrites the existing databases.
Note If the existing database details are not valid, or if the databases does not exist, an errors occurs and the installation fails.
Main Database
DatabaseName TotalAgility Specify the name of the Main database.
23
Kofax TotalAgility Installation Guide
Parameter
Server
Default value server name
Security
WindowsAuthentication true
UserName
Password
NewDatabase
Audit Database
DatabaseName
Server
SqlScript
CreateScript
DropScript
InitializeScript
ConversionScript
Security empty empty false
TotalAgility server name
Create_Audit.sql
Drop_Audit.sql
Initialise_Audit.sql
Convert_Audit.SQL
Description
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Note When installing
TotalAgility with a remote database, update
SilentInstallConfig.xml
with the server name
(<Server>servername</
Server>) of the machine on which the database resides.
The account used to connect to the database during the installation requires
DB_CREATOR rights.
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Accept the default.
If set to true, creates new database.
Specify the name of the Audit database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Accept the default.
Accept the default.
Accept the default.
Only required for patch when there are SQL changes.
24
Kofax TotalAgility Installation Guide
Parameter
WindowsAuthentication
Default value true
Description
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
UserName
Password
NewDatabase
Finished Jobs Database
DatabaseName
Server
SqlScript
CreateScript
DropScript
Conversion Script
Security
WindowsAuthentication empty empty false
TotalAgility server name
Create_Archive.sql
Drop_Archive.sql
Convert_Archive.SQL
Set to true to create new database.
Specify the name of the Finished
Jobs database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Accept the default.
Accept the default.
Only required for patch when there are SQL changes.
true Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
UserName
Password empty empty
NewDatabase false
DataLayer - TotalAgility_Documents Database
DatabaseName TotalAgility_Documents server name Server
SqlScript
CreateScript
DropScript
Conversion Script
Security
Repository2012_TablesCreate.sql
Repository2012_Drop.sql
Repository2012_Convert.SQL
Set to true to create new database.
Specify the name of the
TotalAgility_Documents database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Accept the default.
Accept the default.
Only required for patch when there are SQL changes.
25
Kofax TotalAgility Installation Guide
Parameter
WindowsAuthentication
Default value true
Description
Set to true to use Windows credentials for logging in.
If set to false, provide the username and password.
Otherwise, leave the username and password blank.
UserName
Password
NewDatabase
Reporting_Analytics Database
DatabaseName empty empty false
TotalAgility_Reporting server name Server
SqlScript
CreateScript
DropScript
InitializeScript
Conversion Script
Security
WindowsAuthentication
Kofax.Reporting.Analytics.
SQL_TablesCreate.sql
Kofax.Reporting.Analytics.
SQL_Drop.sql
Kofax.Reporting.Analytics.
SQL_Initialize.sql
empty true
Set to true to create new database.
Specify the name of the
TotalAgility_Reporting database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
Accept the default.
Accept the default.
Accept the default.
Only required for patch when SQL changes are needed.
Set to true to use Windows credentials for logging in.
If set to false, provide the username and password.
Otherwise, leave the username and password blank.
UserName
Password
NewDatabase
Reporting_Staging Database
DatabaseName empty empty false
TotalAgility_Reporting_Staging
Server
SqlScript server name
Set to true to create new database.
Specify the name of the
TotalAgility_Reporting_Staging database.
Enter the Fully Qualified Domain
Name (FQDN) of the server.
26
Kofax TotalAgility Installation Guide
Parameter
CreateScript
DropScript
InitializeScript
Security
WindowsAuthentication
UserName
Password
NewDatabase
Install Info
InstallType
<SiteRoot>
KTAResourceName
KTAResourcePassword
Default value
Kofax.Reporting.Analytics.
Staging.SQL_TablesCreate.sql
Kofax.Reporting.Analytics.
Staging.SQL_Drop.sql
Kofax.Reporting.Analytics.
Staging.SQL_Initialize.sql
true
Description
Accept the default.
Accept the default.
Accept the default.
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
empty empty false
Both
Default Web Site empty empty
Set to true to create new database.
Change the value to
UpgradeDatabasesOnly.
All the databases are upgraded to the latest version of TotalAgility.
Note Upgrading databases prior to TotalAgility 7.4.0 is not supported when TotalAgility is not installed locally.
Install TotalAgility under a custom site that uses a non-standard port other than the standard ports (80 and 443).
For example, create a custom site called "testsite" under IIS using the port number 85.
Specify a username for the
TotalAgility user to be created on installation.
Specify a password (minimum 6 alphanumeric characters) for the
TotalAgility user to be created on installation.
27
Kofax TotalAgility Installation Guide
Parameter
RunAsSystemAccount
Default value false
Description
If set to true, the IIS AppPool and
Kofax TotalAgility services run as the LocalSystem account.
Note If you set this parameter to true, the user can still logon using the credentials specified in the Kofax TotalAgility
Resource Credentials window when installing TotalAgility.
3.
Save and close the file.
4.
On the Command Prompt, change the command line to the root directory of the Setup.exe file.
5.
Run Setup.exe /Silent .
The databases are installed automatically.
The system generates a log file that reports errors (if any).
The success or failure of installation is indicated in the event log.
When automating the installation, if you run setup.exe from the command line, or run setup.exe as a silent installation, one of the codes returns to indicate the following:
• 0= Success
• 1= Success with warnings
• 2= Failure
See also:
•
Silent installation for Database Only
•
Silent installation of Web and Application on the same server
•
Silent installation on a separate Web or Application server
•
Silent installation for Real Time Transformation Server
Silent installation of Web and Application on the same server
Update the following parameters for a Web-Application server installation.
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall and open
SilentInstallConfig.xml
using a text editor.
2.
In SilentInstallConfig.xml, update the following parameters.
Note Fix the line breaks if you copy and paste the code from this guide.
Parameter
ServicesInstallOptions
CoreWorkerService
Default value true
Description
ImportService true
Installs the Core Worker Service. You can set it to false, if needed.
Installs the Import Service. You can set it to false, if needed.
28
Kofax TotalAgility Installation Guide
Parameter
ExportService
ReportingService
LicenseService
TransformationService
CoreServices
LicenseServer
LicenseServerName
PortNumber
SerialNumber
ProductCode
SkipLicense
InstallDirectory
DatabaseInformation
InstallDatabases
OverwriteIfExisting
ScriptsLocation
Default value true true true true true
Description
Installs the Export Service. You can set it to false, if needed.
Installs the Reporting Service. You can set it to false, if needed.
Installs the License Service. You can set it to false, if needed.
Installs the Transformation Service. You can set it to false, if needed.
Installs the Core services. You can set it to false, if needed.
Note Set to false to install only
Transformation Server on the
Application server so that IIS prerequisite is not needed. IIS is not required for standalone installation of the Transformation Server.
localhost
3581 empty empty true
Enter the name of the license server.
Do not change this value.
Enter your TotalAgility serial number.
Enter your TotalAgility product code.
Skips activating the license.
Set to false to activate the license; you must enter the serial number and product code to install TotalAgility.
Specify the TotalAgility destination directory.
C:\Program Files\
Kofax\TotalAgility true true
C:\Program Files
\Kofax\TotalAgility
\ DatabaseScripts\SQL
Server\
Installs the databases.
Set to false to ignore installing databases.
If set to true, overwrites the existing databases.
Note If the existing database details are not valid, or if the databases does not exist, an errors occurs and the installation fails.
Specify the directory for installing scripts.
29
Kofax TotalAgility Installation Guide
Parameter
Main Database
DatabaseName
Server
Default value
TotalAgility server name
Security
WindowsAuthentication
UserName
Password
NewDatabase
Audit Database
DatabaseName
Server
Security
WindowsAuthentication
UserName
Password
NewDatabase
Finished Jobs Database
DatabaseName
Server
Security empty empty false
TotalAgility server name true empty empty false
TotalAgility server name true
Description
Specify the name of the Main database.
Specify the fully qualified domain name
(FQDN) of the server.
Note When installing TotalAgility with a remote database, update SilentInstallConfig.xml
with the server name
(<Server>servername</Server>) of the machine on which the database resides.
The account used to connect to the database during the installation requires DB_CREATOR rights.
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Set to true to create new database.
Specify the name of the Audit database.
Specify the fully qualified domain name
(FQDN) of the server.
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Set to true to create new database.
Specify the name of the Finished Jobs database.
Specify the fully qualified domain name
(FQDN) of the server.
30
Kofax TotalAgility Installation Guide
Parameter
WindowsAuthentication
Default value true
UserName
Password
NewDatabase
Forms empty empty false empty
DataLayer - TotalAgility_Documents Database
DatabaseName TotalAgility_Documents server name Server
Security
WindowsAuthentication true
UserName
Password
NewDatabase
Reporting_Analytics Database
DatabaseName
Server
Security
WindowsAuthentication
UserName
Password
NewDatabase
Reporting_Staging Database
DatabaseName
Server empty empty false
TotalAgility_Reporting server name true empty empty false
TotalAgility_Reporting_
Staging server name
Description
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Set to true to create new database.
Specify the name of the
TotalAgility_Documents database.
Specify the fully qualified domain name
(FQDN) of the server.
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Set to true to create new database.
Specify the fully qualified domain name
(FQDN) of the server.
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Set to true to create new database.
Specify the name of the
TotalAgility_Reporting_Staging database.
Specify the fully qualified domain name
(FQDN) of the server.
31
Kofax TotalAgility Installation Guide
Parameter
Security
WindowsAuthentication
UserName
Password
NewDatabase
Identity Information
UserName
Password
Default value true empty empty false username password
RunAsSystemAccount false
RunAsNetworkServiceAccount false
Prerequisite Info
ValidOS
SQLServerInstalled
SQLClientInstalled true true false
Description
Uses Windows credentials for logging in.
If set to false, provide the user name and password. Otherwise, leave the user name and password blank.
Set to true to create new database.
Enter the user name of the Windows service account for the TotalAgility services.
Enter the password of the windows service account for the TotalAgility services.
Note If the service account name ends with a $ (dollar), do not specify the password.
If you set this parameter to true:
• The AppPool and Kofax TotalAgility services are created with LocalSystem account.
• The user can still logon using the credentials specified in the Kofax
TotalAgility Resource Credentials window when installing TotalAgility.
• The databases should be created using SQL authentication.
If set to true, the IIS AppPool and Kofax
TotalAgility services run as the NT
Authority\Network Service username.
Note Set
RunAsNetworkServiceAccount to true only for Docker installations that want to make use of a Group
Managed Service Account (gMSA).
Checks if the Operating System is valid.
Set to true to check if the SQL Server is installed.
Set to true to check if the SQL Client is installed.
32
Kofax TotalAgility Installation Guide
Parameter
IISInstalled
SslEnabled
Default value true false
Description
Checks if IIS is installed.
Set to true to enable https. See
Configure for HTTPS communication
.
Install Info
InstallAction
InstallMode
InstallType
AuthenticationMode
Transformation Server Info
Install
Silent
Both
Windows
Note Configure these settings if TransformationService is true .
TSConfigFile empty
LogFile
InstallLocation
Accept the default.
Accept the default.
Accept the default.
Set the authentication mode to Windows.
C:\Program Files
\Kofax\TotalAgility
\Transformation Server
\Tslog.txt
C:\Program Files
\Kofax\TotalAgility
\TransformationServer
Specify the path to .ini file along with the name for Transformation Server to configure.
Important If you provide the .ini
file, the TransformationServerInfo settings are taken from the .ini file; the parameters mentioned in the
SilentInstallConfig are ignored.
See the
Sample for the parameters.
Set the location where the
Transformation Server log file will be created. If the log file path is not valid, the Transformation Server installation fails.
Example:
C:\Program Files
\Kofax\TotalAgility
\TransformationServer
\TSLog.txt
To install to a different location, specify the Transformation Server destination directory.
33
Kofax TotalAgility Installation Guide
Parameter
WindowsServiceAccount
Default value username
WindowsServicePassword
UseSpecificPool password false
PoolName empty
OLEnabled true
WcfPort
ReservedSlots
9001
0
Description
Enter the name of the user who will run the Transformation Server.
To specify a domain user, enter the user name in the format Domain\User.
Ensure that the account details are correct, as under this account
Transformation Server authenticates in all places where Windows authentication is used. Example: TA database.
All communication and resource access will be run under this account. Therefore, the account under which Transformation
Server is running must be not some dummy account.
Enter the password for the user.
Set this parameter to true to add this
Transformation Server to a pool.
Any other value, including no value, is treated as false and the Transformation
Server process all activities regardless of pool.
If you set UseSpecificPool=true, enter the Transformation Server pool name.
Note If you leave the pool name empty, all activities are processed regardless of their pools.
Enables online learning tasks on this
Transformation Server instance.
Set to false or any other value to disable online learning tasks.
Note In case where multiple instances of Transformation Server are installed for improving the throughput of the capture activities, online learning should be enabled only on a single transformation server instance in the cluster.
Enter the port that is used by TotalAgility to communicate with Transformation
Server during synchronous calls, such as fuzzy searches and pushed activities.
Enter the number of slots on this
Transformation Server that are reserved for pushed activities and high-priority activities.
34
Kofax TotalAgility Installation Guide
Parameter
OverrideDefSlots
Default value
Empty
MaxSlots
EnableSyncCalls
NlpWestern
NlpWesternExtended
NlpExtended
IsIntegration Server
InstallLicenseProxy
KTAResourceName
KTAResourcePassword empty empty
StartServices
ImportWorkspacePackage
<SiteRoot> true false
Default Web Site
0 true false false false false false
CaptureConfiguration
Description
By default, the Transformation Server determines the number of simultaneously working Transformation Server controlled processes that do actual processing based on the machine CPU cores.
To specify your own values, enter the value here.
If you set CPUSERVER_OVERRI
DE_DEF_ SLOTS to true, enter the number of processing slots for this
Transformation Server.
Enables synchronous calls.
Set to false to disable synchronous calls.
If set to true, installs the Natural
Language Processing language bundle for English, Spanish, Portuguese,
French, and German.
If set to true, installs the Natural
Language Processing language bundle for Italian, Romanian, and Dutch.
If set to true, installs the Natural
Language Processing language bundle for Japanese, Chinese, and Korean.
Set to true to install the TotalAgility
Integration Server.
Set to true to install License Proxy.
If set to true, provide the username and password. Otherwise, leave the username and password blank.
Specify a username for the TotalAgility user to be created on installation.
Specify a password (minimum 6 alphanumeric characters) for the
TotalAgility user to be created on installation.
Starts the services.
Set to true to import Workspace package.
Install TotalAgility under a custom site that uses a non-standard port other than the standard ports (80 and 443).
For example, create a custom site called
"testsite" under IIS using the port number
85.
35
Kofax TotalAgility Installation Guide
Parameter
CloudStorageType
AzureBlobStorageConnectionStri ng
AzureBlobStorageContainerNa me
AmazonS3AccessKey
AmazonS3SecretKey
AmazonS3BucketName
Default value
SQLServer empty empty empty empty empty
Description
By default, the capture data is stored in the SQL Server. Change the Cloud
Storage Type to "Azure" for Windows
Azure Blob Storage and "AWS" for
Amazon S3 storage.
The Account Connection String to connect to the Blob storage service.
The Container Name of the storage service.
The access key to connect to the
Amazon S3 storage service.
The secret key to the Amazon S3 storage service.
The bucket name of the storage service.
Bucket is a fundamental container in
Amazon S3 for data storage.
AmazonS3RegionName empty The S3 region name.
3.
Save and close the file.
4.
On the Command Prompt, change the command line to the root directory of the Setup.exe file.
36
Kofax TotalAgility Installation Guide
5.
Run Setup.exe /Silent .
Based on the parameters set to True in the silent configuration file, the following items are installed:
• Kofax TotalAgility
• Kofax Import Connector (KIC)
• Kofax Transformation Designer
Note
• Transformation Designer is installed only when the TransformationDesignerInstaller.exe is available in the TotalAgility build folder.
• When you install Kofax TotalAgility from a network share, make sure the user has the Write permissions to the share; otherwise, the Import Connector will not get installed successfully.
• Utility for Kofax Export Connector
• Licensing Service
• Transformation Server, if the TransformationService parameter is set to true and the following parameters are set for Transformation Server:
• WindowsServiceAccount
• WindowsServicePassword
The system generates a log file that reports any errors.
The success or failure of installation is indicated in the event log.
When automating the installation, if you run setup.exe from the command line, or run setup.exe as a silent installation, one of the codes returns to indicate the following:
• 0= Success
• 1= Success with warnings
• 2= Failure
.INI file sample
TS_SERVICE_ACCOUNT=username
TS_SERVICE_PASSWORD=password
TS_USE_SPECIFIC_POOL=FALSE
TS_POOL_NAME=
TS_OL_ENABLED=TRUE
TS_WCF_PORT=9001
TS_RESERVED_SLOTS=0
TS_OVERRIDE_DEF_SLOTS=
TS_MAX_SLOTS=0
TS_ENABLE_SYNC_CALLS=TRUE
TS_MAIN_DB_CONNECTION_STRING=Server=servername;Trusted_Connection=Yes;Database=
TotalAgility;
TS_SYNCHRONOUS_ONLY=false
See also:
•
Silent installation for Database Only
•
Silent installation for upgrading databases
•
Silent installation on a separate Web or Application server
•
Silent installation for Real Time Transformation Server
37
Kofax TotalAgility Installation Guide
Silent installation on a separate Web or Application server
Install TotalAgility on a separate Web or Application server.
Silent installation on an Application Server
Update the following parameters for an Application Server.
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall and open
SilentInstallConfig.xml using a text editor.
2.
In SilentInstallConfig.xml, update the following parameters.
• InstallType = ApplicationServer.
• For other parameters, see
Silent installation of Web and Application on the same server .
Note You can choose to install or not to install certain components by setting the values to True/
False in the ServicesInstallOptions section of the Silent Configuration file.
3.
Save and close the file.
4.
On the Command Prompt, change the command line to the root directory of the Setup.exe file.
38
Kofax TotalAgility Installation Guide
5.
Run Setup.exe /Silent .
Based on the parameters set to True in the silent configuration file, the following items are installed:
• Kofax TotalAgility
• Kofax Import Connector (KIC)
• Kofax Transformation Designer
Note
• Transformation Designer is installed only when the Transformation DesignerInstaller.exe is available in the TotalAgility build folder.
• When you install Kofax TotalAgility from a network share, make sure the user has the Write permissions to the share; otherwise, the Import Connector will not get installed successfully.
• Utility for Kofax Export Connector
• Licensing Service
• Transformation Server, if the TransformationService parameter is set to true and the following parameters are set for Transformation Server:
• WindowsServiceAccount
• WindowsServicePassword
Note When you choose to install only Transformation service on the Application server, set
Transformation Service to true and Core Worker Service to false. If you do not exclude Core
Services, TotalAgility will prompt for IIS requirement, and IIS is not required for installing the
Transformation service on an Application Server.
The system generates a log file that reports errors (if any).
The success or failure of installation is indicated in the event log.
When automating the installation, if you run setup.exe from the command line, or run setup.exe as a silent installation, one of the codes returns to indicate the following:
• 0= Success
• 1= Success with warnings
• 2= Failure
Silent installation on a Web Server
1.
On the installation media, navigate to \\TotalAgilityInstall and open SilentInstallConfig.xml
using a text editor.
2.
In SilentInstallConfig.xml, update the following parameters.
Parameter
InstallDirectory
Default
C:\Program Files
\
TotalAgility\
TotalAgility
Description
Specify the TotalAgility destination directory.
39
Kofax TotalAgility Installation Guide
Parameter
ApplicationServerName
Default no default
Identity Information
UserName
Password username password
RunAsSystemAccount false
RunAsNetworkService
Account false
Prerequisite Info
ValidOS
SQLServerInstalled
SQLClientInstalled
IISInstalled
SslEnabled
Install Info
InstallAction true true false true false
Install
Description
Enter the Fully Qualified Domain Name (FQDN) of the application server.
Note If the Application server is installed on a non-standard port, you must modify the
<ApplicationServerName> parameter in the
SilentInstallConfig.xml on the Web server as follows:
<ApplicationServerName>FQDN:portnumber
<ApplicationServerName>"
Enter the name of the user who will run TotalAgility if
RunAsSystemAccount is false.
Enter the password for the user who will run TotalAgility if RunAsSystemAccount is false.
Note If the service account name ends with a $
(dollar), do not specify the password.
If set to true, the IIS AppPool and Kofax TotalAgility services run as the LocalSystem account.
Note If you set this parameter to true, databases should be created using SQL authentication.
If set to true, the IIS AppPool and Kofax TotalAgility services run as the NT Authority\Network Service username.
Note
• Set RunAsNetworkServiceAccount to true only for Docker installations that want to make use of a Group Managed Service Account (gMSA).
• If you set this parameter to true, databases should be created using SQL authentication.
Set to true to check if the Operating System is valid.
Set to true to check if the SQL Server is installed.
Set to true to check if the SQL Client is installed.
Set to true to check if IIS is installed.
Set to true to enable https. See
Accept the default.
40
Kofax TotalAgility Installation Guide
Parameter
InstallMode
InstallType
Default
Silent
Both
Description
Accept the default.
Enter WebServer.
<SiteRoot> Default Web Site Install TotalAgility under a custom site that uses a nonstandard port other than the standard ports (80 and
443).
For example, create a custom site called "testsite" under
IIS using the port number 85.
3.
Save and close the file.
4.
On the Command Prompt, change the command line to the root directory of the Setup.exe file.
5.
Run Setup.exe /Silent .
The Kofax TotalAgility is installed automatically.
The system generates a log file that reports errors (if any).
The success or failure of installation is indicated in the event log.
When automating the installation, if you run setup.exe from the command line, or run setup.exe as a silent installation, one of the codes returns to indicate the following:
• 0= Success
• 1= Success with warnings
• 2= Failure
See also:
•
Silent installation for Database Only
•
Silent installation for upgrading databases
•
Silent installation of Web and Application on the same server
•
Silent installation for Real Time Transformation Server
Silent installation for Real Time Transformation Server
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall and open
SilentInstallConfig.xml using a text editor.
2.
In SilentInstallConfig.xml, update the following parameters.
Parameter
InstallDirectory
Default Value
C:\Program Files\
Kofax\ TotalAgility
Description
Specify the TotalAgility destination directory.
DatabaseInformation
InstallDatabases false Set to false to ignore installing databases.
41
Kofax TotalAgility Installation Guide
Parameter
OverwriteIfExisting
Main Database
DatabaseName
Server
Default Value false
TotalAgility
Server name
SqlScript
CreateScript
DropScript
InitializeScript
ConversionScript
Security
WindowsAuthentication
Create_Main.SQL
Drop_Main.sql
Initialise_Main.sql
Convert_Main.SQL
true
UserName
Password
NewDatabase
Audit Database
DatabaseName
Server
SqlScript empty empty false
TotalAgility server name
Description
If set to true, overwrites the existing databases.
Note If the existing database details are not valid, or if the databases does not exist, an errors occurs and the installation fails.
Specify the name of the Main database.
Specify the fully qualified domain name
(FQDN) of the server.
Note When installing TotalAgility with a remote database, update SilentInstallConfig.xml
with the server name
(<Server>servername</Server>) of the machine on which the database resides.
The account used to connect to the database during the installation requires DB_CREATOR rights.
Accept the default.
Accept the default.
Accept the default.
Only required for patch when there are
SQL changes.
Set to true to use Windows credentials for logging in.
If set to false, provide the username and password. Otherwise, leave the username and password blank.
Set to true to create new database.
Specify the name of the Audit database.
Specify the fully qualified domain name
(FQDN) of the server.
42
Kofax TotalAgility Installation Guide
Parameter
CreateScript
DropScript
InitializeScript
ConversionScript
Security
WindowsAuthentication
UserName
Password
NewDatabase
Finished Jobs Database
DatabaseName
Server
SqlScript
CreateScript
DropScript
Conversion Script
Security
WindowsAuthentication
Default Value
Create_Audit.sql
Drop_Audit.sql
Initialise_Audit.sql
Convert_Audit.SQL
true empty empty false
TotalAgility server name
Create_Archive.sql
Drop_Archive.sql
Convert_Archive.SQL
true
UserName
Password empty empty
NewDatabase false
DataLayer - TotalAgility_Documents Database
DatabaseName TotalAgility_Documents server name Server
SqlScript
Description
Accept the default.
Accept the default.
Accept the default.
Only required for patch when there are
SQL changes.
Set to true to use Windows credentials for logging in.
If set to false, provide the username and password. Otherwise, leave the username and password blank.
Set to true to create new database.
Specify the name of the Finished Jobs database.
Specify the fully qualified domain name
(FQDN) of the server.
Accept the default.
Accept the default.
Only required for patch when there are
SQL changes.
Set to true to use Windows credentials for logging in.
If set to false, provide the username and password. Otherwise, leave the username and password blank.
Set to true to create new database.
Specify the name of the
TotalAgility_Documents database.
Specify the fully qualified domain name
(FQDN) of the server.
43
Kofax TotalAgility Installation Guide
Parameter
CreateScript
DropScript
Conversion Script
Security
WindowsAuthentication
Default Value
Repository2012_TablesCreate
.sql
Repository2012_Drop.sql
Repository2012_Convert.SQL
Description
Accept the default.
Accept the default.
Only required for patch when there are
SQL changes.
true Set to true to use Windows credentials for logging in.
If set to false, provide the username and password. Otherwise, leave the username and password blank.
UserName
Password
NewDatabase
Reporting_Analytics Database
DatabaseName empty empty false
TotalAgility_Reporting server name Server
SqlScript
CreateScript
DropScript
InitializeScript
Kofax.Reporting.Analytics.
SQL_TablesCreate.sql
Kofax.Reporting.Analytics.
SQL_Drop.sql
Kofax.Reporting.Analytics.
SQL_Initialize.sql
empty Conversion Script
Security
WindowsAuthentication true
Set to true to create new database.
Specify the name of the
TotalAgility_Reporting database.
Specify the fully qualified domain name
(FQDN) of the server.
Accept the default.
Accept the default.
Accept the default.
Only required for patch when SQL changes are needed.
Set to true to use Windows credentials for logging in.
If set to false, provide the username and password. Otherwise, leave the username and password blank.
UserName
Password
NewDatabase
Reporting_Staging Database empty empty false Set to true to create new database.
44
Kofax TotalAgility Installation Guide
Parameter
DatabaseName
Server
SqlScript
CreateScript
DropScript
InitializeScript
Conversion Script
Security
WindowsAuthentication
UserName
Password
NewDatabase
Identity Information
UserName
Password
Default Value Description
TotalAgility_Reporting_Staging Specify the name of the
TotalAgility_Reporting_Staging database.
server name Specify the fully qualified domain name
(FQDN) of the server.
Kofax.Reporting.Analytics.
Staging.SQL_TablesCreate.sql
Kofax.Reporting.Analytics.
Staging.SQL_Drop.sql
Kofax.Reporting.Analytics.
Staging.SQL_Initialize.sql
empty
Accept the default.
Accept the default.
Accept the default.
Only required for patch when SQL changes are needed.
true Set to true to use Windows credentials for logging in.
If set to false, provide the username and password. Otherwise, leave the username and password blank.
empty empty false username password
Set to true to create new database.
Enter the user name of the Windows service account for the TotalAgility services.
Note If the service account name ends with a $ (dollar), do not specify the password.
Enter the password of the windows service account for the TotalAgility services.
Note If the service account name ends with a $ (dollar), do not specify the password.
45
Kofax TotalAgility Installation Guide
Parameter
RunAsSystemAccount
Default Value false
RunAsNetworkServiceAccount false
Install Info
InstallType RTTS
SslEnabled
Transformation Server Info
TransformationService
TSConfigFile false true no default
Description
If set to true, the IIS AppPool and
Kofax TotalAgility services run as the
LocalSystem account.
Note When you set this parameter to true, databases should be created using SQL authentication.
If set to true, the AppPool and Kofax
TotalAgility services are created with the NT Authority\Network Service username.
Note
• Set
RunAsNetworkServiceAccount to true only for Docker installations that want to make use of a Group Managed
Service Account (gMSA).
• When you set this parameter to true, databases should be created using SQL authentication.
Accept the default.
Note When you install RTTS, it ignores the services. The services such as CoreworkerService,
ImportService, ExportService are not installed.
You can set to true to enable https. See
Configure for HTTPS Communication
.
Accept the default.
Specify the path to .ini file along with the name for Transformation Server to configure.
Important If you provide the .ini
file, the TransformationServerInfo settings are taken from the .ini file; the parameters mentioned in the
SilentInstallConfig are ignored.
Sample for the parameters.
46
Kofax TotalAgility Installation Guide
Parameter
LogFile
InstallLocation
WindowsServiceAccount
WindowsServicePassword
UseSpecificPool
PoolName
OLEnabled
WcfPort
Default Value
C:\Program Files
\Kofax\TotalAgility
\Transformation Server
\Tslog.txt
Description
Specify the location where the
Transformation Server log file will be created. If the log file path is not valid, the Transformation Server installation fails.
Example:
C:\Program Files
\Kofax\TotalAgility
\TransformationServer
\Tslog.txt
Specify the Transformation Server destination directory.
For example, C:\Program
Files (x86)\Kofax\
TotalAgility\
TransformationServer username password false empty true
9001
Enter the name of the user who will run the Transformation Server.
Enter the password for the user.
Set true to add this Transformation
Server to a pool. Set false (or leave blank or assign any other value) to have Transformation Server process all activities regardless of pool.
If you set UseSpecificPool=true, enter the Transformation Server pool name.
Note If you leave the pool name empty, all activities are processed regardless of their pools.
Set to true to enable online learning tasks on this Transformation Server instance. Set to false or any other value to disable online learning tasks.
Note In case where multiple instances of Transformation Server are installed for improving the throughput of the capture activities, online learning should be enabled only on a single transformation server instance in the cluster.
Enter the port that is used by
TotalAgility to communicate with
Transformation Server during synchronous calls (such as fuzzy searches and pushed activities).
47
Kofax TotalAgility Installation Guide
Parameter
ReservedSlots
OverrideDefSlots
Default Value
0 empty (false)
MaxSlots
EnableSyncCalls
NlpWestern
NlpWesternExtended
NlpExtended
<InstallSynchronous>
0 true false false false false
StartServices true
Description
Enter the number of slots on this
Transformation Server that are reserved for pushed activities and high-priority activities.
To override the default number of processing slots for this Transformation
Server, set this parameter to true.
Any other value, including empty, is treated as false and the system automatically sets the default number of processing slots based on the system configuration.
If you set CPUSERVER_OVERRI
DE_DEF_ SLOTS to true, enter the number of processing slots for this
Transformation Server.
Set to true to enable synchronous calls or false to disable these calls.
If set to true, installs the Natural
Language Processing language bundle for English, Spanish, Portuguese,
French, and German.
If set to true, installs the Natural
Language Processing language bundle for Italian, Romanian, and Dutch.
If set to true, installs the Natural
Language Processing language bundle for Japanese, Chinese, and Korean.
Set true to install the Transformation
Server in a synchronous mode.
Specify the port number (default:
9001) for the Transformation Server service. The port number is stored in the TotalAgility Web.config file as an application setting:
<add key=
"TSExternalServicePortFor
SyncProcessing" value="9001" />
Note If you wish to change the default port number, you must update the Web.config file and restart the Kofax TotalAgility IIS
Application Pool.
48
Kofax TotalAgility Installation Guide
Parameter
<SiteRoot>
Default Value
Default Web Site
Description
Install TotalAgility under a custom site that uses a non-standard port other than the standard ports (80 and 443).
For example, create a custom site called "testsite" under IIS using the port number 85.
3.
Save and close the file.
4.
On the Command Prompt, change the command line to the root directory of the Setup.exe file.
5.
Run Setup.exe /Silent .
The Real Time Transformation Server is installed. The Real Time Transformation Service sets up
Transformation Server in a synchronous mode and configures the core and SDK APIs of TotalAgility which clients can invoke.
The system generates a log file that reports errors (if any).
The success or failure of installation is indicated in the event log.
When automating the installation, if you run setup.exe from the command line, or run setup.exe as a silent installation, one of the codes returns to indicate the following:
• 0= Success
• 1= Success with warnings
• 2= Failure
6.
To ensure that the installation works as expected, perform the following steps: a.
Navigate to <Program Files>/Kofax/ TotalAgility/Agility.Server.Web
and open the Web.config in a text editor.
b.
Locate the TransformationServerExternalService_Binding binding parameter and ensure that the <transport ClientCredentialType> value is set to Windows.
c.
Save and close the web configuration file.
See also:
•
Silent installation for Database Only
•
Silent installation for upgrading databases
•
Silent installation of Web and Application on the same server
•
Silent installation on a separate Web or Application server
Silent installation of multiple instances of Message Connectors
You can install up to three instances of Message Connector on a computer.
1.
To install the first instance of Message Connector, before installing TotalAgility, set the value of
ImportService parameter to true in SilentInstallConfig.xml. See
Silent installation of Web and
Application on the same server
or
Silent installation on a separate Web and Application server
.
49
Kofax TotalAgility Installation Guide
2.
To install the second instance of Message Connector, run the following command on the Command
Prompt: msiexec /i <\\TotalAgility\KIC\Export\MC\MC.msi> TRANSFORMS=:I02
MSINEWINSTANCE=1 KOFAX="<path>" <options>
Where, <\\TotalAgility\KIC\Export\MC\MC.msi
> is the path of TotalAgility setup folder.
In <path>, specify the installation path for second instance of Message Connector. \KIC-ED\MC02 is appended to this path at the time of installation.
3.
To install the third instance of Message Connector, run the following command on the Command
Prompt: msiexec /i <\\TotalAgility\KIC\Export\MC\MC.msi> TRANSFORMS=:I03
MSINEWINSTANCE=1 KOFAX="<path>" <options>
Where, <\\TotalAgility\KIC\Export\MC\MC.msi> is the path of TotalAgility setup folder.
In <path>, specify the installation path for third instance of Message Connector. \KIC-ED\MC03 is appended to this path at the time of installation.
Note For second and third instances of message Connector, optionally, in <options> use the following command options:
• /qn - silent installation
• /qb - silent installation with elementary user interface (progress bar)
• ALLUSERS=1 - install for all users
Following command assumes that TotalAgility setup folder is in the C: drive and Message Connector's second instance will be installed at C:\Program Files (x86)\Kofax .
msiexec /i C:\TotalAgility\KIC\Export\MC\MC.msi TRANSFORMS=:I02
MSINEWINSTANCE=1 KOFAX="C:\Program Files (x86)\Kofax" /qn /norestart
ALLUSERS=1
Perform a standard installation
You can install TotalAgility using the standard installer wizard.
When you run the installation wizard for the Application Server or the Web/Application Server, based on the installation type selected, following items are installed:
• TotalAgility
• Kofax Import Connector
• Transformation Designer
Note
• Transformation Designer is installed only when the TransformationDesignerInstaller.exe is available in the TotalAgility installation folder.
• When you install Kofax TotalAgility from a network share, make sure the user has the Write permissions to the share; otherwise, the Import Connector will not get installed successfully.
50
Kofax TotalAgility Installation Guide
• Utility for Kofax Export Connector
• Licensing Service
• Reporting Service
Note The reporting client is installed automatically on the Transformation Server and during the
TotalAgility server installation.
Express installation
When installing TotalAgility using the standard installer wizard, do either of the following:
• Choose standard installation where you select your installation type from the available options, such as
Databases Only, Web Server, Application Server and more.
• Express installation where TotalAgility is installed with all default settings which needs minimal user interaction. The express mode installs Combined Web Application server, SQL Express and
Transformation Server. You can configure license server while installing TotalAgility or post installation.
Perform the following steps:
1.
Navigate to \\TotalAgilityInstall on the installation media and run one of the following commands:
• If UAC (User Account Control) is enabled, right-click Setup.exe and select Run as administrator .
• If UAC is not enabled, run Setup.exe
.
The system starts the installation.
2.
In the Kofax TotalAgility Installation Program window, click Next or press Enter to move to the next window.
Note To exit the setup, click Cancel or press Esc.
3.
In the Kofax Inc. Software License Agreement window, accept the terms in the License Agreement and click Next .
The Install Option Type window opens.
51
Kofax TotalAgility Installation Guide
4.
Do either of the following:
To proceed with the standard installation.
To install TotalAgility with minimum user interaction.
a.
Select Standard .
b.
Click Next .
The Type of Install window opens.
c.
Select your installation type and follow the wizard instructions to complete the installation.
a.
Select Express .
b.
Leave the Skip License checkbox unselected to provide licensing details while installing TotalAgility. If you select this option and confirm to skip providing the licensing details, the Licensing window does not appear. You must configure the license server post installation.
c.
Click Next .
The Licensing window opens if you have not selected the Skip
License checkbox.
d.
Enter the License Server details and click Next .
The Credentials window opens.
e.
Enter the username and password of the Windows account to run
Kofax TotalAgility.
The Installation Progress window displays the progress of installation. The setup installs the required files, databases, and other integrated products.
f.
Click Finish .
Your installation is now complete. Review the Summary Panel for the installation report.
If any errors occur during the installation, TotalAgility creates a log file on your desktop. Check this log file for error details.
Standard installation of Database Only
1.
Navigate to \\TotalAgilityInstall on the installation media and run one of the following commands:
• If UAC (User Account Control) is enabled, right-click Setup.exe and select Run as administrator .
• If UAC is not enabled, run Setup.exe
.
The system starts the installation.
2.
In the Kofax TotalAgility Installation Program window, click Next or press Enter to move to the next window.
Note To exit the setup, click Cancel or press Esc.
3.
In the Kofax Inc. Software License Agreement window, accept the terms in the License Agreement and click Next .
The Install Option Type window opens.
52
Kofax TotalAgility Installation Guide
4.
Select your installation option as Standard and click Next .
For Express installation, see
.
5.
In the Type of Install window, select Database Only (default: Web/Application Server) and click
Next .
The Databases window opens.
6.
Do one of the following:
• By default Install Databases is selected. Click Next to install the databases.
• If the database server already contains the same databases and you want to overwrite the existing databases, select the Overwrite databases if they exist?
check box. The Test connections option becomes available. Click Test connections to test the database connections. Once the databases are successfully connected, click OK .
Note If the database details are not valid, or if the database does not exist, connection to database fails.
• If you want to provide the database server for each database do the following: enter a database name; click ellipsis for Server and choose the mode of database server; in the Security group, either use Windows Authentication , or select the SQL Server authentication providing the user name and password, and then click OK . If all the databases reside on the same server, select the
Apply these settings to all other Databases check box.
7.
Click Next .
The DB Connection Results window opens and displays the results of connection to databases.
If the connection to databases fails, the installation cannot be progressed. Click Back and make changes as needed.
Note The DB Connection Results window opens only if the check box for "Install Databases" or
"Overwrite databases if they exist?" is selected in the previous step.
8.
Once the databases are successfully connected, click Next .
The Capture Binary Data Storage window opens.
9.
By default, the binary data such as capture documents, .NET Store DLLs and CCM Packs are stored in the TotalAgility database. You can use the preconfigured external cloud data storage services such as Amazon S3 or Windows Azure Blob Storage for saving and processing the binary data. The cloud services helps to reduce the SQL Server maintenance costs, delegate maintenance to external service and provide encryption.
Note If you change the storage type to Azure/Amazon blob storage, the binary data is saved in the selected storage type. Once the cloud storage is enabled, you cannot turn it off later.
Select one of the following capture data storage types:
Storage type
SQL Server (default)
Description
Stores capture data in the SQL Server.
53
Kofax TotalAgility Installation Guide
Storage type
Windows Azure Blob Storage
Amazon S3
Description
Stores capture data in Azure Blob Storage service.
Configure the following Cloud Account Settings: a.
Enter the Account Connection String to connect to the Blob storage service.
b.
Enter the Container Name of the storage service.
Configure the following Cloud Account Settings: a.
Enter the Access Key to connect to the Amazon S3 storage service.
b.
Enter the Secret Key .
c.
On the Region list, select a predefined S3 region, for example
Asia Pacific (Sydney). (Default: US East (Ohio) d.
Enter the Bucket Name .
Bucket is a fundamental container in Amazon S3 for data storage.
10.
Click Next .
The Kofax TotalAgility Resource Credentials window opens.
11.
Enter the credentials ( Username , Password (minimum 6 alphanumeric characters) and Confirm password) for the user to be created on installation.
By default, the username field displays the name of the logged on user. You can specify a different user name, as required.
12.
Click Next .
The Installation Review window opens and displays the settings.
13.
Review the settings and click Next to start the installation.
The Installation Progress window displays the progress of installation. The setup installs the required files, databases, and other integrated products.
The Licensing window opens.
14.
To connect to the license server, do the following: a.
In the License Server field, enter the location of the License Server.
Note To connect to a shared License Server, enter the name or the IP address of a shared
License Server.
b.
In the Port Number field, enter the port number on which the License Server listens.
Alternatively, click Skip if you want to skip connecting to the License Server now but connect when launching TotalAgility.
15.
Click Next .
The Kofax TotalAgility Installation Complete window displays the installation summary.
If any errors occur during the installation, TotalAgility creates a log file. Check this log file for error details. The success or failure of installation is indicated in the event log.
16.
Click Finish .
Your installation is now complete.
54
Kofax TotalAgility Installation Guide
Standard installation for upgrading databases
You can upgrade all the databases to the latest version of TotalAgility when TotalAgility is not installed locally.
Note Upgrading databases prior to TotalAgility 7.4.0 is not supported.
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall and run one of the following commands:
• If UAC (User Account Control) is enabled, right-click Setup.exe and select Run as administrator .
• If UAC is not enabled, run Setup.exe
.
The system starts the installation.
2.
In the Kofax TotalAgility Installation Program window, click Next or press Enter to move to the next window.
Note To exit the setup, click Cancel or press Esc.
3.
In the Kofax Inc. Software License Agreement window, accept the terms in the License Agreement and click Next .
4.
Select your installation option as Standard and click Next .
For Express installation, see
.
5.
In the Type of Install window, select Upgrade Databases (default: Web/Application Server).
To import the Workspace package, select the check box for Import system Workspace package
(default: Clear).
6.
Click Next .
The Databases window opens.
7.
To specify the lower version databases to upgrade, do the following for the databases as needed: enter the database name to upgrade; click ellipsis for Server and choose the mode of database server; in the Security group, either use Windows Authentication , or select the SQL Server authentication providing the user name and password, and then click OK . If all the databases reside on the same server, select the Apply these settings to all other Databases check box.
8.
Click Next .
The Installation Review window opens.
9.
Review the settings and click Next to start the installation.
The Installation Progress window displays the progress of installation. The setup upgrades
TotalAgility databases.
If any errors occur during installation, TotalAgility creates a log file called Kofax TotalAgility.txt on your desktop. Check this log file for error details. The success or failure of installation is indicated in the event log.
10.
The Kofax TotalAgility Installation Complete window displays the summary for the installation. Click
Finish .
Your installation is now complete.
55
Kofax TotalAgility Installation Guide
Standard installation of the Web Server
1.
On the TotalAgility installation media navigate to \\TotalAgilityInstall and run one of the following commands:
• If UAC (User Account Control) is enabled, right-click Setup.exe and select Run as administrator .
• If UAC is not enabled, run Setup.exe
.
The system starts the installation.
2.
In the Kofax TotalAgility Installation Program window, click Next or press Enter to move to the next window.
Note To exit the setup, click Cancel or press Esc.
3.
In the Kofax Inc. Software License Agreement window, accept the terms in the License Agreement and click Next .
4.
Select your installation option as Standard and click Next .
For Express installation, see
.
5.
In the Type of Install window, select Web Server (default: Web/Application Server) and click Next .
The Software Checks window displays the list of detected software. TotalAgility requires certain software to be installed on your system before installing TotalAgility.
6.
Review the Detected Software list and proceed as follows:
• If your system does not have all the required software, click Cancel to close the installer and install the software.
• If your system has all the required software, click Next .
The Destination window opens.
7.
Use the default installation folder or click Browse to select a different path, and click Next .
The Choose Server Location with Options window opens.
8.
In the Server Name field enter the name of your existing TotalAgility application server. The name must be a fully qualified, such as
<machinename>.<fullyqualifieddomainname>:<portnumber> .
Note The port number is only required if it is other than port 80.
9.
To support SSL, select the Support SSL check box.
Note The SSL option is only available if you have configured the https binding in IIS. See
Configure TotalAgility for HTTPS Communication
.
10.
Click Next .
The Credentials window opens.
11.
Enter the credentials (Password and Confirm password) for the user who will run TotalAgility.
12.
On the Root Website to host TotalAgility Application list, select the website to host the TotalAgility application. By default, the Default Web Site is selected.
Note The websites added in IIS Manager appear on this list. To add a website in IIS Manager, click
Start > Run > Inetmgr > Sites > Add Web Site .
56
Kofax TotalAgility Installation Guide
13.
Do either of the following for Windows Authentication :
• To log on automatically to TotalAgility Designer and Workspace, keep the Windows
Authentication check box selected (default).
• To log on manually to TotalAgility Designer and Workspace, clear the Windows Authentication check box.
14.
Click Next .
The Installation Review window opens and displays the settings.
15.
Review the settings and click Next start the installation.
The Installation Progress window opens. The setup installs the required files, databases, and other integrated products.
If any errors occur during installation, TotalAgility creates a log file called Kofax TotalAgility.txt on your desktop. Check this log file for error details. The success or failure of installation is indicated in the event log.
16.
Click Finish .
Your installation is now complete.
See also:
•
Standard installation of Database Only
•
Standard installation for upgrading databases
•
Standard installation of the Application Server
•
Standard installation of the Web and Application Server
•
Standard installation of Real Time Transformation Server
Standard installation of the Application Server
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall and run one of the following commands:
• If UAC (User Account Control) is enabled, right-click Setup.exe and select Run as administrator .
• If UAC is not enabled, run Setup.exe
.
The system starts the installation.
2.
In the Kofax Totalgility Installation Program window, click Next or press Enter to move to the next window.
Note To exit the setup, click Cancel or press Esc.
3.
In the Kofax Inc. Software License Agreement window, accept the terms in the License Agreement and click Next .
4.
Select your installation option as Standard and click Next .
For Express installation, see
.
5.
In the Type of Install window, select Application Server (default: Web/Application Server) and click
Next .
The Application Server window opens.
57
Kofax TotalAgility Installation Guide
6.
By default, the Windows Services and WCF Services are selected and installed. If you do not want to install any service, clear the check box for the service.
The Windows Services include:
• Core Services
• Reporting Service
• License Service (Primary license server or Backup license server)
By default, the Primary server is selected. If the primary license server fails to connect, you can connect to the backup server by manually updating the license server configuration file, or run the Configuration Utility post TotalAgility installation to automatically update the setting. Also, after upgrading TotalAgility from versions prior to 7.7.0, you must reconfigure the license server by updating the settings to use the new licensing behavior. See
Update the settings for a license server .
• Transformation Service
When you choose to install only Transformation service on the Application server by excluding all other Windows services, you must also clear the check box for WCF Core Services. If you do not exclude WCF Core Services, TotalAgility setup.exe will prompt for IIS requirement, and IIS is not required for installing the Transformation service on an Application Server.
• Import Service
You can now install multiple instances of the Message Connector. Select the check box for
Instance 2 and Instance 3 for Import Service. When you uninstall TotalAgility, all the instances of
Message Connector are also uninstalled.
• Export Service
The WCF Services include Core Services.
7.
Click Next.
The Software Checks window opens. The system displays a list of required software based on services and databases selection and whether the required software is installed.
8.
Review the Detected Software list and proceed as follows:
• If your system does not have all the required software, click Cancel to close the installer and install the software.
• If your system has all the required software, click Next .
The Destination window opens.
9.
Use the default installation folder for installing TotalAgility, or click Browse to select a different folder, and click Next .
The Credentials window opens.
10.
Enter the credentials (password and confirm password) for the user who will run TotalAgility.
When you enter the credentials of a non-admin account, changes need to be made to ensure the
Streaming Service will run.
Note If the service account name ends with a $ (dollar), do not specify the password.
11.
On the Root Website to host TotalAgility Application list, select the website to host the TotalAgility application. By default, the Default Web Site is selected.
Note The websites added in IIS Manager appear on this list. To add a website in IIS Manager, click
Start > Run > IIS Manager > Sites > Add Web Site .
58
Kofax TotalAgility Installation Guide
12.
To support SSL, select the Support SSL check box.
Note The SSL option is only available if you have configured the https binding in IIS. See
Configure TotalAgility for HTTPS communication .
13.
Click Next .
The Databases window opens.
59
Kofax TotalAgility Installation Guide
14.
Do one of the following:
Option
Use the default settings.
A database with the same name already exists, and you want to overwrite the existing database.
Description
Keep the Install Databases
check box selected and follow Step 13 .
a.
Select the Overwrite databases if they exist?
check box.
The Test connections option becomes available.
b.
Click Test connections .
A popup displays the database connection results. If the database details are not valid, or if the database does not exist, connection to database fails.
c.
Click Next .
d.
Click Yes to confirm overwriting databases.
Note
Point to an existing database on your local machine.
Point to existing databases on a different machine.
a.
Clear the Install Databases and Overwrite databases if they exist?
check boxes.
b.
Enter a name for each database and follow Step 13 .
a.
Select the Install Databases and Overwrite databases if they exist?
check boxes b.
For each database do the following:
1.
Enter a database name.
2.
Click ellipsis for Server ; select the mode of database server.
3.
In the Security group, either use Windows Authentication , or select the SQL Server authentication providing the user name and password, and then click OK .
4.
If all the databases reside on the same server, select the
Apply these settings to all other Databases check box.
Note
• If Apppool is running under a System account, the System displays an error.
• You must have a trusted account to interact with databases. Provide the SQL credentials and click OK .
• If you install TotalAgility without any databases, you can use the Configuration Utility to point to the databases when they are available at a later a stage. See the Kofax TotalAgility
Configuration Utility Guide .
60
Kofax TotalAgility Installation Guide
15.
Click Next .
The DB Connection Results window opens and displays the results of connecting to databases.
If the connection to databases fails, the installation cannot be progressed. Click Back and make changes as needed.
Note The DB Connection Results window opens only if the check box for "Install Databases" or
"Overwrite databases if they exist?" is selected in the previous step.
16.
Once the databases are successfully connected, click Next .
The Capture Binary Data Storage window opens.
17.
By default, the binary data such as capture documents, .NET Store DLLs and CCM Packs are stored in the TotalAgility database. You can use the preconfigured external cloud data storage services such as Amazon S3 or Windows Azure Blob Storage for saving and processing the binary data. The cloud services helps to reduce the SQL Server maintenance costs, delegate maintenance to external service and provide encryption.
Note If you change the storage type to Azure/Amazon blob storage, the binary data is saved in the selected storage type. Once the cloud storage is enabled, you cannot turn it off later.
Select one of the following capture data storage types:
Storage type
SQL Server (default)
Windows Azure Blob Storage
Description
Stores capture data in the SQL Server.
Stores capture data in Azure Blob Storage service.
Configure the following Cloud Account Settings: a.
Enter the Account Connection String to connect to the Blob storage service.
b.
Enter the Container Name of the storage service.
Amazon S3 Configure the following Cloud Account Settings: a.
Enter the Access Key to connect to the Amazon S3 storage service.
b.
Enter the Secret Key .
c.
On the Region list, select a predefined S3 region, for example
Asia Pacific (Sydney). (Default: US East (Ohio) d.
Enter the Bucket Name .
Bucket is a fundamental container in Amazon S3 for data storage.
18.
Click Next .
The Kofax TotalAgility Resource Credentials window opens
19.
Enter the credentials ( Username , Password (minimum 6 alphanumeric characters) and Confirm password) for the user to be created on installation.
By default, the username field displays the name of the logged on user. You can specify a different user name, as required.
20.
Click Next .
The Install Options window opens
61
Kofax TotalAgility Installation Guide
21.
To automatically start the services, keep the Automatically Start Services check box selected, and click Next .
The Installation Review window opens and displays the settings.
22.
Click Next to start installation.
The Installation Progress window opens. The setup installs the required files, databases, and other integrated products.
23.
Click Next .
The Licensing window opens.
24.
Do one of the following:
Option
Connect to the License Server
Description a.
In the License Server field, enter the location of the License
Server.
Note To connect to a shared License Server, enter the name or the IP address of a shared License Server.
b.
In the Port Number field, enter the port number on which the
License Server listens.
c.
Click Next . The second Licensing window opens. Follow the next step.
Skip connecting to the License
Server now but connect when launching TotalAgility.
OR
If you have selected to install databases manually (in Step 12).
a.
Click Skip .
b.
Click Finish .
25.
Enter your TotalAgility Serial Number and Product code .
The Serial Number and Product code appear by default, if the License Server is a shared license server.
26.
The ID of the selected License Server appears in the Machine ID field.
62
Kofax TotalAgility Installation Guide
27.
To activate the license, select the license activation method:
• Automatic : Use this option when internet connectivity is available. The license is activated online.
• Manual : Use this option when there is no internet connectivity, or if automatic activation is not successful from the installer or license utility for your Kofax product. The Activation Code box is displayed where you can specify the activation code.
a.
To obtain the activation code:
1.
Enter the following URL in your browser: http://activatelegacy.kofax.com/support/Activation/manual.aspx
The Kofax Product License Activation page opens.
2.
Enter the Serial Number issued to you at the time of purchase. If you have a hardware key, the serial number (usually 7 characters) is printed on the key.
3.
Enter the email address where Kofax can send the information you need to activate the product license.
4.
Click Next to proceed with the activation process.
Note Ignore the Version selection field if you do not have Kofax Capture or Ascent
Capture.
5.
Copy and paste the Activation Code into the field on the Licensing window.
6.
Click Activate to activate the license, or click Skip . If you skip activating the license, a warning informs that you need to activate the license later.
b.
Once you get the activation code, copy the code.
c.
Paste the code in the Activation Code field on the Licensing window.
d.
Click Activate to activate the license, or click Skip to activate the license later. If you skip activating the license, the summary panel displays the warning that you need to activate the license later.
63
Kofax TotalAgility Installation Guide
28.
Click Finish .
Your installation is now complete.
bundle.
Note
• If you want to install any further services, you should uninstall TotalAgility and reinstall by selecting the required services in the Application Server window.
• If any errors occur during installation, TotalAgility creates a log file called Kofax TotalAgility.txt at
C:\Users\xxxx\AppData\Local\Temp (where xxxx is the currently logged on user). Check this log file for error details. The success or failure of installation is indicated in the event log.
After you install TotalAgility, further configure TotalAgility to:
•
•
•
•
•
Integrate with Micro Focus Content Manager
Note To view the TotalAgility version you installed, login to TotalAgility Designer and navigate to
System > System settings. The version information is available at the bottom right corner of the
System settings page. The last three digits correspond to the build number.
See also:
•
Standard installation of Database Only
•
Standard installation for upgrading databases
•
Standard installation of the Application Server
•
Standard installation of the Web Server
•
Standard installation of the Web and Application Server
•
Standard installation of Real Time Transformation Server
Standard installation of the Web and Application Server
This installation type installs the Web and Application servers on a single machine.
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall and run one of the following commands:
• If UAC (User Account Control) is enabled, right-click Setup.exe and select Run as administrator .
• If UAC is not enabled, run Setup.exe
.
The system starts the installation.
2.
In the Kofax TotalAgility Installation Program window, click Next or press Enter to move to the next window.
Note To exit the setup, click Cancel or press Esc.
64
Kofax TotalAgility Installation Guide
3.
In the Kofax Inc. Software License Agreement window, accept the terms in the License Agreement and click Next .
4.
Select your installation option as Standard and click Next .
For Express installation, see
.
5.
In the Type of Install window, select Web/Application Server (default: Web/Application Server) and click Next .
The Application Server window opens.
6.
By default, the Windows Services and WCF Services are selected and installed. If you do not want to install any service, clear the check box for the service.
The Windows Services include:
• Core Services
• Reporting Service
• License Service (Primary license server or Backup license server)
By default, the Primary server is selected. If the primary license server fails to connect, you can connect to the backup server by manually updating the license server configuration file, or run the Configuration Utility post TotalAgility installation to automatically update the setting. Also, after upgrading TotalAgility from versions prior to 7.7.0, you must reconfigure the license server by updating the settings to use the new licensing behavior. See
Update the settings for a license server .
• Transformation Service
• Import Service
You can now install multiple instances of the Message Connector. Select the check box for
Instance 2 and Instance 3 for Import Service. When you uninstall TotalAgility, all the instances of
Message Connector are also uninstalled.
• Export Service
The WCF Services include Core Services.
Clear the check box for Core Services to install only Transformation Server on the Application server so that IIS prerequisite is not needed. IIS is not required for standalone installation of the
Transformation Server.
7.
Click Next.
The Software Checks window opens. The system displays a list of required software based on services and databases selection and whether the required software is installed.
8.
Review the Detected Software list and proceed as follows:
• If your system does not have all the required software, click Cancel to close the installer and install the software.
• If your system has all the required software, click Next .
The Destination window opens.
9.
Use the default installation folder or click Browse to select your desired location where TotalAgility will be installed.
10.
Click Next .
The Credentials window opens.
11.
Enter the credentials ( Password and Confirm password) for the user who will run TotalAgility.
Note If the service account name ends with a $ (dollar), do not specify the password.
65
Kofax TotalAgility Installation Guide
12.
On the Root Website to host TotalAgility Application list, select the website to host the TotalAgility application. By default, the Default Web Site is selected.
Note The websites added in IIS Manager appear on this list. To add a website in IIS Manager, click
Start > Run > Inetmgr > Sites > Add Web Site .
13.
To support SSL, select the Support SSL check box. (Default: Clear)
Note The SSL option is only available if you have configured the https binding in IIS. See
Configure TotalAgility for HTTPS communication .
14.
Do either of the following for Windows Authentication :
• To log on automatically to TotalAgility Designer and Workspace, keep the Windows
Authentication check box selected (default).
• To log on manually to TotalAgility Designer and Workspace, clear the Windows Authentication check box.
15.
Click Next .
The Databases window opens.
66
Kofax TotalAgility Installation Guide
16.
Do one of the following:
Option
Use the default settings. This means, new databases are installed.
Description
Ensure the following: a.
The Install Databases check box is selected.
b.
The Overwrite databases if they exist?
check box is clear.
A database with the same name already exists, and you want to overwrite the existing database.
a.
Select the Overwrite databases if they exist?
check box.
The Test connections option becomes available.
b.
Click Test connections .
A popup displays the database connection results. If the database details are not valid, or if the database does not exist, connection to database fails.
c.
Click Next .
d.
Click Yes to confirm overwriting databases.
Note If you choose to overwrite the existing databases but the database details are not valid database, or if the database does not exist, an error occurs.
Point to an existing database on your local machine.
Point to existing databases on a different machine.
Manually install the databases.
a.
Clear the check boxes for Install Databases and Overwrite databases if they exist?
.
b.
Enter a name for each database and follow Step 13.
a.
Clear the Install Databases and Overwrite databases if they exist?
check boxes b.
For each database do the following:
1.
Enter a name.
2.
Click ellipsis for Server ; select the database server where the databases reside.
3.
In the Security group, either use Windows Authentication , or select the SQL Server authentication providing the user name and password, and then click OK .
4.
If all the databases reside on the same server, select the
Apply these settings to all other Databases check box.
a.
Run the setup.exe wizard to this screen.
b.
Clear the Install Databases and Overwrite databases if they exist?
check boxes.
c.
.
d.
After installing the databases, configure appropriate settings on this screen, and follow Step 13.
67
Kofax TotalAgility Installation Guide
Note
• If Apppool is running under a System account, the System displays an error.
• You must have a trusted account to interact with databases. Provide the SQL credentials and click OK .
• If you install TotalAgility without any databases, you can use the Configuration Utility to point to the databases when they are available at a later a stage. See the Kofax TotalAgility
Configuration Utility Guide .
17.
Click Next .
The DB Connection Results window opens and displays the results of connecting to databases.
If the connection to databases fails, the installation cannot be progressed. Click Back and make changes as needed.
Note The DB Connection Results window opens only if the check box for "Install Databases" or
"Overwrite databases if they exist?" is selected in the previous step.
18.
Once the databases are successfully connected, click Next .
The Capture Binary Data Storage window opens.
19.
By default, the binary data such as capture documents, .NET Store DLLs and CCM Packs are stored in the TotalAgility database. You can use the preconfigured external cloud data storage services such as Amazon S3 or Windows Azure Blob Storage for saving and processing the binary data. The cloud services helps to reduce the SQL Server maintenance costs, delegate maintenance to external service and provide encryption.
Note If you change the storage type to Azure/Amazon blob storage, the binary data is saved in the selected storage type. Once the cloud storage is enabled, you cannot turn it off later.
Select one of the following capture data storage types:
Storage type
SQL Server (default)
Windows Azure Blob Storage
Description
Stores capture data in the SQL Server.
Stores capture data in Azure Blob Storage service.
Configure the following Cloud Account Settings: a.
Enter the Account Connection String to connect to the Blob storage service.
b.
Enter the Container Name of the storage service.
Amazon S3 Configure the following Cloud Account Settings: a.
Enter the Access Key to connect to the Amazon S3 storage service.
b.
Enter the Secret Key .
c.
On the Region list, select a predefined S3 region, for example
Asia Pacific (Sydney). (Default: US East (Ohio) d.
Enter the Bucket Name .
Bucket is a fundamental container in Amazon S3 for data storage.
68
Kofax TotalAgility Installation Guide
20.
Click Next .
The Kofax TotalAgility Resource Credentials window opens.
21.
Enter the credentials ( Username , Password (minimum 6 alphanumeric characters) and Confirm password) for the user to be created on installation.
Note By default, the username field displays the name of the logged on user. You can specify a different user name, as required.
22.
Click Next .
The Install Options window opens.
23.
To automatically start the services, keep the Automatically Start Services check box selected and click Next .
The Installation Review window opens and displays the settings.
24.
Review the settings and click Next to start the installation.
The Installation Progress window displays the progress of installation. The setup installs the required files, databases, and other integrated products.
The Licensing window opens.
25.
Do one of the following:
Option
Connect to the License Server
Description a.
In the License Server field, enter the location of the License
Server.
Note To connect to a shared License Server, enter the name or the IP address of a shared License Server.
b.
In the Port Number field, enter the port number on which the
License Server listens.
c.
Click Next . The second Licensing window opens. Follow the next step.
Skip connecting to the License Server now but connect when launching
TotalAgility.
OR
If you have selected to install databases manually (in Step 13).
a.
Click Skip .
b.
Click Finish .
26.
Click Next .
The Installation Progress window opens. The setup installs the required files, databases, and other integrated products.
27.
Click Next .
The Licensing window opens.
69
Kofax TotalAgility Installation Guide
28.
To connect to the License Server: a.
In the License Server field, enter the location of the License Server.
Note To connect to a shared License Server, enter the name or the IP address of a shared
License Server.
b.
In the Port Number field, enter the port number on which the License Server listens.
c.
Click Next . The second Licensing window opens.
Alternatively, click Skip and proceed to Step 24 in the following cases:
• If you want to skip connecting to the License Server now but connect when launching
TotalAgility.
• If you had selected to install databases manually (in Step 12).
29.
Enter your TotalAgility Serial Number and Product Code .
Note The Serial Number and Product Code appear by default if the License Server is a shared license server.
30.
The ID of the selected License Server appears in the Machine ID field.
70
Kofax TotalAgility Installation Guide
31.
To activate the license, select the license activation method:
• Automatic : Use this option when internet connectivity is available. The license is activated online.
• Manual : Use this option when there is no internet connectivity, or if automatic activation is not successful from the installer or license utility for your Kofax product. The Activation Code box is displayed where you can specify the activation code.
a.
To obtain the activation code:
1.
Enter the following URL in your browser: http://activatelegacy.kofax.com/support/Activation/manual.aspx
The Kofax Product License Activation page opens.
2.
Enter the Serial Number issued to you at the time of purchase. If you have a hardware key, the serial number (usually 7 characters) is printed on the key.
3.
Enter the email address where Kofax can send the information you need to activate the product license.
4.
Click Next to proceed with the activation process.
Note Ignore the "Version" selection field if you do not have Kofax Capture or Ascent
Capture.
5.
Copy and paste the Activation Code into the field on the Licensing window.
6.
Click Activate to activate the license, or click Skip . If you skip activating the license, a warning informs that you need to activate the license later.
b.
Once you get the activation code, copy the code.
c.
Paste the code in the Activation Code field on the Licensing window.
d.
Click Activate to activate the license, or click Skip to activate the license later. If you skip activating the license, the summary panel displays the warning that you need to activate the license later.
Note The license period starts once the license is activated. So you can skip activation during installation and only activate it when you are ready to use TotalAgility. You are required to activate the license when you log in to TotalAgility for the first time.
71
Kofax TotalAgility Installation Guide
32.
Click Finish .
Your installation is now complete.
After TotalAgility is installed, the installer prompts you to install Transformation Server.
Note
• To install any further services, you must uninstall TotalAgility and reinstall by selecting the required services in the Application Server window.
• If any errors occur during the installation, TotalAgility creates a log file called Kofax TotalAgility.txt
at C:\Users\xxxx\AppData\Local\Temp (where xxxx is the currently logged on user). Check this log file for error details. The success or failure of installation is indicated in the event log.
After you install TotalAgility, further configure TotalAgility to:
•
•
•
•
•
Integrate with Micro Focus Content Manager
Note To view the TotalAgility version you installed, login to TotalAgility Designer and navigate to
System > System settings. The version information is available at the bottom right corner of the
System settings page. The last three digits correspond to the build number.
See also:
•
Standard installation of Database Only
•
Standard installation for upgrading databases
•
Standard installation of the Application Server
•
Standard installation of the Web Server
•
Standard installation of Real Time Transformation Server
Standard installation of Real Time Transformation Server
1.
Navigate to \\TotalAgilityInstall on the installation media and run one of the following commands:
• If UAC (User Account Control) is enabled, right-click Setup.exe and select Run as administrator .
• If UAC is not enabled, run Setup.exe
.
The system starts the installation.
2.
In the Kofax TotalAgility Installation Program window, click Next or press Enter to move to the next window.
Note To exit the setup, click Cancel or press Esc.
3.
In the Kofax Inc. Software License Agreement window, accept the terms in the License Agreement and click Next .
4.
Select your installation option as Standard and click Next .
For Express installation, see
.
72
Kofax TotalAgility Installation Guide
5.
In the Type of Install window, select Real Time Transformation Service and click Next .
The Software Checks window opens. The system displays a list of required software based on services and databases selection and whether the required software is installed.
6.
Review the Detected Software list and proceed as follows:
• If your system does not have all the required software, click Cancel to close the installer and install the software.
• If your system has all the required software, click Next .
The Destination window opens.
7.
Use the default installation folder or click Browse to select a different path and click Next .
The Credentials window opens.
8.
Enter the credentials (password and confirm password) for the user who will run TotalAgility.
Note If the service account name ends with a $ (dollar), do not specify the password.
9.
On the Root Website to host TotalAgility Application list, select the website to host the TotalAgility and Workspace application. By default, the Default Web Site is selected.
Note The websites added in IIS Manager appear on this list. To add a website in IIS Manager, click
Start > Run > Inetmgr > Sites > Add Web Site .
10.
To support SSL, select the Support SSL check box.
Note The SSL option is only available if you have configured the https binding in IIS. See
Configure TotalAgility for HTTPS communication .
11.
Do either of the following in Windows Authentication option:
• To log on automatically to TotalAgility and Workspace, keep the Windows Authentication check box selected (default).
• To log on manually to TotalAgility and Workspace, clear the Windows Authentication check box.
12.
Click Next .
The Databases window opens.
13.
Use the default settings or do the following:
• If you want to point to an existing database in your local machine, enter a name for each database and enter the credentials (password and confirm password) for the user to be created on installation.
• If you want to point to the existing databases on a different machine, enter a name for each database; click ellipsis for Server ; select the database server where the databases reside; in the
Security group, either use Windows Authentication , or select the SQL Server authentication providing the user name and password, and then click OK . If all the databases reside on the same server, select the Apply these settings to all other Databases check box.
14.
Click Next .
The Installation Review window opens.
15.
Review the settings and click Next .
The Installation Progress window opens. The setup installs the required files, databases, and other integrated products.
73
Kofax TotalAgility Installation Guide
16.
Click Finish .
Your installation is now complete.
Note If any errors occur during the installation, TotalAgility creates a log file called TotalAgility.txt on your desktop. Check this log file for error details. The success or failure of installation is indicated in the event log.
17.
To ensure that the installation works as expected, perform the following steps.
a.
Navigate to <Program Files>/Kofax/TotalAgility/Agility.Server.Web
and edit the Web.config file.
b.
Locate the TransformationServerExternalService_Binding binding parameter and ensure that the <transport clientCredentialType> value is set to Windows .
c.
Save and close Web.config.
See also:
•
Standard installation of Database Only
•
Standard installation for upgrading databases
•
Standard installation of the Application Server
•
Standard installation of the Web Server
•
Standard installation of the Web and Application Server
Upgrade Transformation Designer Help
The Transformation Designer help is not automatically upgraded when you install Kofax TotalAgility 7.9.0.
As a result, you need to follow these manual steps to upgrade the documentation.
1.
Navigate to the location where the Transformation Designer documentation is installed. By default, this is %ProgramData%/Kofax/Transformation .
A directory called "Help" is displayed.
2.
Rename the folder to "Help_7.9.0" or something similar.
Leave the window open as you will need it again later.
3.
In the Kofax TotalAgility 7.9.0 ISO file, navigate to \\Transformation Designer .
A ZIP file called "Help.zip" is displayed.
4.
Extract the "Help.zip" to %ProgramData%/Kofax/Transformation and ensure that the resulting directory is called "Help"
5.
Open Transformation Designer and press F1 to open the help.
The upgraded help is displayed.
If the help does not display, ensure that the structure of the Help directory matches that of the
"Help_7.9.0" directory and try again.
74
Kofax TotalAgility Installation Guide
Perform TotalAgility installation in a Docker container
Overview
A Docker is an open platform for developing, shipping, and running applications. Docker enables you to separate an application from its infrastructure. Using Docker, you can manage your infrastructure in the same way you manage your applications.
Docker provides the ability to package and run an application such as TotalAgility in a loosely isolated environment called a Container. The isolation and security allows you to run many containers simultaneously on a given host using fewer resources than virtual machines.
You can deploy TotalAgility application into your production environment, as an independent container or an orchestrated set of containers. This works the same whether your production environment is a local datacenter, a cloud provider, or a hybrid of the two. You do not need to use the TotalAgility installation program when TotalAgility is deployed in a Docker container. Instead, TotalAgility is already installed and only the relevant configuration settings, such as database connection strings, are required when the container runs.
By default, all TotalAgility containers do not have limits for memory or CPU. SQL Server runs either on another Windows container or another machine, it does not run in the TotalAgility container.
Limitations
The following are the limitations:
• Currently, Microsoft does not officially support MSDTC on the Docker Windows containers. Due to this limitation, TotalAgility cannot have out-of-box support for split databases (main and archive). As a workaround, enable Active Directory support for the containers by making use of Globally Managed
Service Accounts (GMSA). Once the container is in the same domain as host machine and SQL server machine, MSDTC will be able to execute distributed transaction among live and archive databases by resolving machine names using Active Directory.
• Export Connectors are not supported in a container.
Prerequisites
We recommend using a standalone server for your database (not a container). Therefore before running
TotalAgility inside a container you will need to have the TotalAgility databases already setup and remotely accessible (using either IP address or fully qualified domain name).
To use this setup, you need the following configuration on the SQL server being used:
• Firewall should allow remote access to SQL Server.
• SQL Server itself should be configured to allow remote access with Mixed mode since the user is also allowed to access without Windows Authentication.
• TCP/IP protocols should be enabled for SQL Server. Note Named pipes protocol does not work.
75
Kofax TotalAgility Installation Guide
Install Docker on the Windows server 2016 and higher
Set up Docker on your Windows server. This requires Windows Server 2016 or higher to support running a TotalAgility Windows container.
Note Image Quality Analysis, Mobile ID and Mobile Card Capture are not supported when you set up
Docker on Windows Server 2016.
1.
Open an elevated PowerShell command prompt, and type the following commands:
Install-Module DockerMsftProvider -Force
Install-Package Docker -ProviderName DockerMsftProvider -Force
2.
If a reboot is required, restart your instance using the following command:
(Install-WindowsFeature Containers).RestartNeeded
If the output of this command is Yes, restart the server using the following command: Restart-
Computer .
3.
Test your Docker Engine - Enterprise installation by running the "docker info" command.
docker info
Containers: 1
Running: 0
Paused: 0
Stopped: 1
Images: 26
Server Version: 18.09.3
Storage Driver: windowsfilter
Windows:
Execution Driver: <not supported>
Logging Driver: json-file
Plugins:
Volume: local
Network: ics l2bridge l2tunnel nat null overlay transparent
Kernel Version: 10.0 14393 (14393.2828.amd64fre.rs1_release_inmarket.190216-1457)
Operating System: Windows Server 2016 Standard Version 1607 (OS Build 14393.2828)
OSType: windows
Architecture: x86_64
CPUs: 4
Total Memory: 10.04 GiB
Name: HV-Docker-QA
ID: HI53:GJSY:3BWT:Z3S5:3NWU:DEFN:6D3X:KCXO:2EMJ:ITZR:QAVY:VXFK
Docker Root Dir: C:\ProgramData\docker
Debug Mode (client): false
Debug Mode (server): false
Registry: https://index.docker.io/v1/
Labels:
Insecure Registries:
127.0.0.0/8
4.
Optional. NLP support for Transformation Server within Docker is not enabled by default. To make
Docker work with NLP within the Transformation server, and to increase the default maximum size for the Docker container images, perform the following steps: a.
Open daemon.json
available at “ C:\ProgramData\docker\config ”. If the file does not exist at that location, create the file.
b.
Append the following text to daemon.json:
{
76
Kofax TotalAgility Installation Guide
"storage-opts": ["size=50GB"]
} c.
Restart the Docker Engine service.
Use Image Quality Analysis, Mobile ID and Mobile Card Capture on Docker
To use Image Quality Analysis, Mobile ID and Mobile Card Capture in a container, Windows Server 2019 or higher must be used as a container host with the following Docker base container specified in the
Docker file: mcr.microsoft.com/windows:1809
Make the following changes in the Docker file:
• Add the following line: RUN powershell "Set-ExecutionPolicy -ExecutionPolicy
RemoteSigned" before the line, RUN powershell C:\KTA\PowershellScripts
\ConfigureContainer.ps1
Make the following changes in the InstallWindowsFeatures.ps1 powershell script:
• Identify the following line:
Install-WindowsFeature -Name NET-Framework-Features -Source C:\kta\NET-Framework35-
Features -Verbose
(Install-WindowsFeature cmdlet is not supported in Windows 1809 image)
• Replace the preceding line with the following:
• dism /Online /Add-Package /PackagePath:c:\kta\NET-Framework35-Features\Microsoft-
Windows-InternetExplorer-Optional-Package~31bf3856ad364e35~amd64~en-US~.cab
dism /Online /Add-Package /PackagePath:c:\kta\NET-Framework35-Features\microsoftwindows-internetexplorer-optional-package~31bf3856ad364e35~amd64~~.cab
dism /Online /Add-Package /PackagePath:c:\kta\NET-Framework35-Features\Microsoft-
Windows-NetFx3-OnDemand-Package~31bf3856ad364e35~amd64~en-US~.cab
dism /Online /Add-Package /PackagePath:c:\kta\NET-Framework35-Features\microsoftwindows-netfx3-ondemand-package~31bf3856ad364e35~amd64~~.cab
Note
• Additionally, Mobile ID and Mobile Card Capture has a prerequisite for the VC++ 2013 x86 redistributable. This can be automatically downloaded and installed in the Docker file.
• Make sure that following dlls are present when you run Mobile ID and Mobile Card Capture applications (32 bit dll dependency) on Windows server 2016 or 2019 Docker images. Copy the 32bit version of DLLs (avicap32.dll, avifil32.dll, msacm32.dll, msvfw32.dll) from the host's C:\Windows
\SysWOW64 and paste the DLLs in the Docker container's C:\Windows\SysWOW64 folder . You must copy these DLLs to all containers running the Transformation Service.
Create a TotalAgility Docker container image
A container is defined by its image as well as any configuration options you provide when you create or start it.
To create a Docker image, you need internet connectivity because Docker uses the Microsoft "microsoft/ aspnet" image as a base onto which the prerequisites are installed (from the base OS or from the Internet when any feature is not available on the image).
77
Kofax TotalAgility Installation Guide
Note For a TotalAgility Docker container to be successfully built, approximately 100 GB of free disk space is needed.
On-premise
To create a TotalAgility Docker image in an on-premise environment, perform the following steps.
1.
Extract the contents of KofaxTotalAgility-7.9.0.ZIP to a <source directory> .
2.
Create a new folder, <workingdirectory> .
Your Docker commands will be run from this directory.
3.
Copy the contents of <source directory>\Utilities\Docker to <working directory>.
4.
Move the contents from <source directory> folder to <working directory>\ContainerFiles .
The file structure should be as follows:
<working directory>\Dockerfile
<working directory>\ContainerFiles\all contents from <source directory>
<working directory>\ContainerFiles\PowerShellScripts
5.
Update the parameters as needed for each container type. See Silent installation configuration.
6.
To create the image, open a PowerShell window on the container host and run the following command: docker build -t <imagenamegoeshere> "<fullpathtoworkingdirectory>"
Note Container host is the machine where Docker server is installed. Performance of a build command depends on the number of processors in the container host machine. The command may take approximately one hour to complete with a quad core processors configuration.
Example The following command generates the image with the name "kofaxop" using the contents inside C:\Docker\KofaxTotalAgility : docker build -t kofaxop "C:\Docker\KofaxTotalAgility"
Silent installation configuration in Docker
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall and open
SilentInstallConfig.xml using a text editor.
78
Kofax TotalAgility Installation Guide
2.
The following are the available Docker container types for this deployment and the required configuration parameters to be updated in SilentInstallConfig.xml.
•
•
Application Server (Core Services and Core Worker)
•
•
Web Server and Application Server (Core Services and Core Worker)
•
•
•
•
Real Time Transformation Service
Note You can create a Docker container with any combinations of App server, Web server,
Reporting Server, Licensing Server and Transformation Server. Real Time Transformation Server
(RTTS) is supported only in a dedicated Docker container.
Demo
Update the following parameters for a Demo server installation.
Note Fix the line breaks if you copy and paste the code from this guide.
Parameter
ServicesInstallOptions
ImportService
ExportService
LicenseService
CoreWorkerService
ReportingService
TransformationService
CoreServices
DatabaseInformation
InstallDatabases
Identity Information
RunAsSystemAccount
Value true false true true true true true false true
Description
The Export Service is not supported inside Docker containers.
Skips installing databases as part of the Docker image installation.
When set to true, the IIS AppPool and Kofax TotalAgility services run as the LocalSystem account. This can also be used to run container as a Group Managed Service Account (gMSA).
79
Kofax TotalAgility Installation Guide
Parameter Value
RunAsNetworkServiceAccountfalse
Description
When set to true, the IIS AppPool and Kofax TotalAgility services run as the NT Authority\Network Service account. This can also be used to run container as a Group Managed Service Account (gMSA).
Note If RunAsSystemAccount or RunAsNetworkServiceAccount is true, this can be used to run container as a Group Managed
Service Account (gMSA).
Install Info
InstallType
AuthenticationMode
StartServices
Both
Anonymous false
Set the authentication mode to Windows or Anonymous.
Services are started only after the container is running.
Application Server (Core Services and Core Worker)
Update the following parameters for the Application server installation.
Parameter
ServicesInstallOptions
ImportService
ExportService
ReportingService
LicenseService
CoreWorkerService
CoreService
TransformationService
DatabaseInformation
InstallDatabases
Identity Information
RunAsSystemAccount
Value true false false false true true false false true
Description
The Export Service is not supported inside Docker containers.
Skips installing databases as part of the Docker image installation.
RunAsNetworkServiceAccountfalse
When set to true, the IIS AppPool and Kofax TotalAgility services run as the LocalSystem account. This can also be used to run container as a Group Managed Service Account (gMSA).
When set to true, the IIS AppPool and Kofax TotalAgility services run as the NT Authority\Network Service account. This can also be used to run container as a Group Managed Service Account
(gMSA).
Note If RunAsSystemAccount or
RunAsNetworkServiceAccount is true, this can be used to run container as a Group Managed Service Account (gMSA).
Install Info
80
Kofax TotalAgility Installation Guide
Parameter
InstallType
AuthenticationMode
StartServices
Value
ApplicationServer
Anonymous false
Description
Set the authentication mode to Windows or Anonymous.
Services are started only after the container is running.
Web Server
Update the following parameters for the Web server installation.
Parameter
DatabaseInformation
InstallDatabases
Identity Information
RunAsSystemAccount
Value false true
Description
Skips installing databases as part of the Docker image installation.
When set to true, the IIS AppPool and Kofax TotalAgility services run as the LocalSystem account. This can also be used to run container as a Group Managed Service Account (gMSA).
When set to true, the IIS AppPool and Kofax TotalAgility services run as the NT Authority\Network Service account. This can also be used to run container as a Group Managed Service Account
(gMSA).
Note If RunAsSystemAccount or
RunAsNetworkServiceAccount is true, this can be used to run container as a Group Managed Service Account (gMSA).
Install Info
InstallType
AuthenticationMode
StartServices
WebServer
Anonymous false
Set the authentication mode to Windows or Anonymous.
Services are started only after the container is running.
Web Server and Application Server (Core Services and Core Worker)
Update the following parameters for both Web and Application server installation.
Description Parameter
ServicesInstallOptions
ImportService
ExportService
ReportingService
LicenseService
CoreWorkerService
CoreService
Value true false false false true true
The Export Service is not supported inside Docker containers.
81
Kofax TotalAgility Installation Guide
Parameter
TransformationService
DatabaseInformation
InstallDatabases
Identity Information
RunAsSystemAccount
Value false false true
Description
Skips installing databases as part of the Docker image installation.
When set to true, the IIS AppPool and Kofax TotalAgility services run as the LocalSystem account. This can also be used to run container as a Group Managed Service Account (gMSA).
When set to true, the IIS AppPool and Kofax TotalAgility services run as the NT Authority\Network Service account. This can also be used to run container as a Group Managed Service Account (gMSA).
Note If RunAsSystemAccount or RunAsNetworkServiceAccount is true, this can be used to run container as a Group Managed
Service Account (gMSA).
Install Info
InstallType
AuthenticationMode
StartServices
Both
Anonymous false
Set the authentication mode to Windows or Anonymous.
Services are started only after the container is running.
Reporting Server
Update the following parameters for the Reporting server installation.
Parameter
ServicesInstallOptions
ImportService
ExportService
ReportingService
LicenseService
CoreWorkerService
CoreService
TransformationService
DatabaseInformation
InstallDatabases
Identity Information
RunAsSystemAccount
Value false false true false false false false false true
Description
The Export Service is not supported inside Docker containers.
Skips installing databases as part of the Docker image installation.
When set to true, the IIS AppPool and Kofax TotalAgility services run as the LocalSystem account. This can also be used to run container as a Group Managed Service Account (gMSA).
82
Kofax TotalAgility Installation Guide
Parameter
Install Info
InstallType
StartServices
Value Description
When set to true, the IIS AppPool and Kofax TotalAgility services run as the NT Authority\Network Service account. This can also be used to run container as a Group Managed Service Account (gMSA).
Note If RunAsSystemAccount or RunAsNetworkServiceAccount is true, this can be used to run container as a Group Managed
Service Account (gMSA).
Install Info
Install Type
AuthenticationMode
StartServices
ApplicationServer
Anonymous false
Set the authentication mode to Windows or Anonymous.
Services are started only after the container is running.
License Server
Update the following parameters for a License server installation.
Description Parameter
ServicesInstallOptions
LicenseService
CoreWorkerService
ReportingService
TransformationService
CoreServices
DatabaseInformation
InstallDatabases
Identity Information
RunAsSystemAccount
Value true false false false false false true
Skips installing databases as part of the Docker image installation.
When set to true, the IIS AppPool and Kofax TotalAgility services run as the LocalSystem account. This can also be used to run container as a Group Managed Service Account (gMSA).
When set to true, the IIS AppPool and Kofax TotalAgility services run as the NT Authority\Network Service account. This can also be used to run container as a Group Managed Service Account (gMSA).
Note If RunAsSystemAccount or RunAsNetworkServiceAccount is true, this can be used to run container as a Group Managed
Service Account (gMSA).
ApplicationServer false Services are started only after the container is running.
83
Kofax TotalAgility Installation Guide
Note After configuring and starting the container, licensing is not activated. You must activate licensing through the TotalAgility Designer.
Transformation Server
Update the following parameters for the Transformation server installation.
Parameter
ServicesInstallOptions
CoreWorkerService
ImportService
ExportService
ReportingService
LicenseService
TransformationService
CoreServices
DatabaseInformation
InstallDatabases
Identity Information
RunAsSystemAccount
Value false false false false false true false false true
Description
The Export Service is not supported inside Docker containers.
Skips installing databases as part of the Docker image installation.
When set to true, the IIS AppPool and Kofax TotalAgility services run as the LocalSystem account. This can also be used to run container as a Group Managed Service Account (gMSA).
When set to true, the IIS AppPool and Kofax TotalAgility services run as the NT Authority\Network Service account. This can also be used to run container as a Group Managed Service Account (gMSA).
Note If RunAsSystemAccount or RunAsNetworkServiceAccount is true, this can be used to run container as a Group Managed
Service Account (gMSA).
Install Info
InstallType
AuthenticationMode
StartServices
NlpWestern
NlpWesternExtended
NlpExtended
ApplicationServ er
Anonymous false false false false
Set the authentication mode to Windows or Anonymous.
Services are started only after the container is running.
If set to true, installs the Natural Language Processing language bundle for English, Spanish, Portuguese, French, and German.
If set to true, installs the Natural Language Processing language bundle for Italian, Romanian, and Dutch.
If set to true, installs the Natural Language Processing language bundle for Japanese, Chinese, and Korean.
84
Kofax TotalAgility Installation Guide
Note NLP support for Transformation Server within Docker is not enabled by default. To make Docker work with NLP within the Transformation server, and to increase the default maximum size for the
Docker container images, perform the following steps:
1.
Open daemon.json
available at “ C:\ProgramData\docker\config ”. If the file does not exist at that location, create the file.
2.
Append the following text to daemon.json:
{
"storage-opts": ["size=50GB"]
}
3.
Restart the Docker Engine service.
Real Time Transformation Service
Update the following parameters for the Real Time Transformation Service installation.
Parameter
ServicesInstallOptions
CoreServices
DatabaseInformation
InstallDatabases
Identity Information
RunAsSystemAccount
Value true false true
Description
Skips installing databases as part of the Docker image installation.
When set to true, the IIS AppPool and Kofax TotalAgility services run as the LocalSystem account. This can also be used to run container as a Group Managed Service Account (gMSA).
When set to true, the IIS AppPool and Kofax TotalAgility services run as the NT Authority\Network Service account. This can also be used to run container as a Group Managed Service Account (gMSA).
Note If RunAsSystemAccount or RunAsNetworkServiceAccount is true, this can be used to run container as a Group Managed
Service Account (gMSA).
Install Info
InstallType
AuthenticationMode
StartServices
RTTS
Anonymous false
Set the authentication mode to Windows or Anonymous.
Services are started only after the container is running.
Install legacy wrapper on a Docker container
You can install the legacy wrappers through PowerShell scripts on a Docker container.
1.
On the TotalAgility installation media, navigate to \\Utilities\Docker\ContainerFiles
\PowershellScripts\Startup.psl
.
2.
Open the Startup.psl in a text editor.
85
Kofax TotalAgility Installation Guide
3.
Uncomment the following snippet in this script file to install the legacy wrappers.
#if (Test-path -Path 'C:\Program Files\Kofax\TotalAgility\LegacyWrappers
\WrapperInstaller.exe')
#{
# 'C:\Program Files\Kofax\TotalAgility\LegacyWrappers\WrapperInstaller.exe'
#}
4.
Save the changes.
Run a Docker container
A Docker container runs on any machine that supports the container's runtime environment. Applications are not required to be tied to the host operating system, so both the application environment and the underlying operating environment can be kept clean and minimal.
When a container stops running, changes to its state are not lost unless they are saved in persistent storage.
Before running a Docker container, the databases must already be set up (using Database only
installation mode).
To use this setup, you need the following configuration on SQL Server:
• Firewall should allow remote access to SQL Server.
• SQL Server itself should be configured to allow remote access with Mixed mode since the user is also allowed access without Windows Authentication.
• TCP/IP protocols should be enabled for SQL Server.
Note Named pipes protocol does not work.
• To use split databases, the Main and Finished Jobs databases must point to the same database and reside on the same database server. Microsoft does not support MSDTC on Docker containers.
Note Verify that you are able to remotely connect to the database server where the databases were set up using SQL Server Management Studio that uses the IP address. The verification ensures that the
Docker containers are connected to the database server without any issues.
1.
Generate "dockersettings.env" using Configuration Utility in Docker mode. The file will be used later for the container initialization. Refer the Kofax TotalAgility Configuration Utility Guide for more information.
Note The authentication mode for accessing TotalAgility can be set using the Configuration Utility.
2.
Container access can be limited to the container host or can be port forwarded for global access.
Enable the required exposed port number in the firewall settings for the host machine.
86
Kofax TotalAgility Installation Guide
3.
For non-Windows authentication: a.
The following command brings up a container using the kofaxop image. Kofax TotalAgility settings are applied from dockersettings.env without Windows authentication. Port 80 from the container is forwarded to port 5000 on the container host.
docker run -d --hostname "opdemo2" --name "opdemo2" --env-file "C:
\Docker\TotalAgility\dockersettings.env" -p 5000:80 kofaxop b.
The following command brings up a container using the kofaxop image. Kofax TotalAgility settings are applied from dockersettings.env without Windows authentication.
docker run -d --hostname "opdemo1" --name "opdemo1" --env-file "C:
\Docker\ TotalAgility TotalAgility\dockersettings.env" kofaxop
4.
To enable licensing in a container, you must add “-p 3581:3581” to the “docker run” command. For example: docker run -d --hostname "opdemo2" --name "opdemo2" --env-file "C:\Docker
\ TotalAgility TotalAgility\dockersettings.env" -p 5000:80 -p 3581:3581 kofaxop
Note If running the License Server in a container, the associated license serial number must be activated before the Kofax TotalAgility Core Worker service can be started.
5.
Use " docker exec -it <container id\name goes here> powershell " to attach to a powershell session on the created container.
For example, the docker exec -it opdemo3 powershell will bring up a powershell session inside the container with opdemo3 as the container name.
6.
To open a port number required for Message Connector, you must add “ -p 5003:25086” to the
“docker run” command. For example: docker run -d --hostname "opdemo2" --name "opdemo2" --env-file "C:\Docker
\TotalAgility\dockersettings.env" -p 5000:80 -p 5003:25086 kofaxop
Note 5003 is an example forwarded port number for Message Connector. Use the port number that you have configured for Message Connector. Similarly, you can configure port numbers for other instances of Message Connector.
If running TotalAgility containers on multiple hosts, it is recommended to use Docker Swarm or
Kubernetes orchestrators that have a built-in DNS server to resolve container DNSs across multiple hosts.
If not using a container orchestrator and using Transformation Server synchronous processing, the
TRANS_SERVER_INSTANCE database table should be manually updated to contain the IP URL of the host running the Transformation Server container. Transformation Server service runs on port 9001 by default; however, the port can be reconfigured using the Configuration utility. This port needs to be exposed in order to be used by App container hosted on the different host machine. Use additional switch -p TS Port :9001 while running a Transformation Server container.
Access TotalAgility
After you connect to the Docker container and verify that all services are in their expected state, use the following URLs to access TotalAgility outside the container host with the port forwarded setup:
• http://<ipaddressofthecontainerhost>:<exposedportofthecontainerhost>/
TotalAgility/Designer
87
Kofax TotalAgility Installation Guide
• http://<ipaddressofthecontainerhost>:<exposedportofthecontainerhost>/
TotalAgility/Forms
For containers hosting IIS – TotalAgility website
Due to different default behavior with case-insensitive URL resolution within Docker containers, it is necessary to perform extra configuration to ensure the TotalAgility website can be resolved in a case insensitive way.
When you configure the container for the Designer / Workspace, we recommend that you use a
VirtualHost file to configure the port and URl exposure through the host OS before you access the URL.
You may also consider using a rewrite rule to ensure that any URL access is redirected to a lowercase representation.
As per RFC 2616, "...a client SHOULD use a case-sensitive octet-by-octet comparison of the entire
URIs...Comparisons of host names MUST be case-insensitive.”
The Docker daemon and cache hold case-sensitive resolutions of the URL, which can cause issues if the case of the URL is changed prior to first access. This caching issue occurs as a result of Docker's use of
WSL v1 and should be resolved in WSL v2. Within Docker you cannot expose the same container port for multiple protocols, and having previously cached a case-sensitive URL, the cache must be cleared to replace with the lowercase URL.
Access Message Connector
To access the Message Connector within the container host or from outside the host, perform the following steps.
1.
Use the following URL: http:DockerServerIP:5003/en/file/index.html
Where DockerServerIP is the IP of the Docker Container host and 5003 is the configured forwarded port number to access the Message Connector. Use the forwarded port number you have configured for Message Connector.
The Message Connector Monitor appears.
2.
To access Message Connector configuration, click the Configuration Tool .
The Message Connector Configuration tool appears.
3.
Make the necessary configuration changes and save.
4.
Optionally, to restart the Message Connector service, click the Restart service button.
To stop and restart Message Connector service from the Docker container, use the following commands: Start-service KIC-ED-MCStop-service KIC-ED-MC
Additional information
This table includes some useful Docker commands.
Docker command docker images docker ps -a docker start <containerID> docker stop <containerID>
Purpose
Gets the list of all Docker images currently available on the server.
Gets a list of all containers available on the server.
Starts the container with the ID <containerID> on the server.
Stops the container with the ID <containerID> on the server.
88
Kofax TotalAgility Installation Guide
Docker command docker rm <containerID> docker rmi <imagename> docker inspect -f "{{ .NetworkSettings.Networ
ks.nat.IPAddress }}" <containerID> docker cp "<containerID>:/<fullfilepathoncont ainer>" "<pathtofolderonserver>" docker cp "<fullfilepathonserver>" "<container
ID>:/ <fullfilepathoncontainer>" docker logs <containerID> docker logs - tail n <containerID> type <FQDN of text file>
Get-Process
Get-Service start-service ServiceNameGoesHere
Stop-service ServiceNameGoesHere
Get-WMIObject Win32_Service | select startn ame, name, status
Get-EventLog -LogName Application -newest
10 | format-table -auto -wrap import-module webadministration get-iisapppool get-itemProperty -path IIS:\APPPOOLS\Tot alAgilityAppPool -names
Purpose
Deletes the container with the ID <containerID> on the server.
Deletes the image with the ID <imagename> on the server. Deletion is successful only if no child containers use this image.
Gets the IP address of the container with the ID <containerID>.
Copies a file from the container to the server.
Copies a file from server to the container.
Displays all logs for a particular container.
Displays the last "n" logs for a particular container.
Displays the content of text file within a powershell instance.
Gets the list of all processes.
Gets the list of all services (running and stopped).
Starts a particular service.
Stops a particular service.
Gets a list of all services with some additional columns.
Gets the last 10 application logs from the event viewer.
Runs before the following commands.
Gets the name of the Application pool.
Gets the identity information for the Application pool.
Using secrets
If you are using Kubernetes secrets to store sensitive information, such as database connection string, passwords and more, you must do the following changes before building the Docker images and deploying to Kubernetes. For example, consider using the MainDBConnectionString application setting as the secret.
Kubernetes secrets
If using secrets as volumes
1.
Create a secret <maindbsecret> in Kubernetes that contains the MainDBConnectionString details.
Refer to the Kubernetes documentation on secrets to create a secret.
2.
On the Docker container installation media, navigate to \\Utilities\Docker\ContainerFiles
\PowershellScripts\ . Replace the line "$appSetting.value = $_.Value;" with the following lines which will check for 'maindbconnectionstring' setting and update its value in all the
89
Kofax TotalAgility Installation Guide
Kofax TotalAgility configuration files with the contents of the <maindbsecret> file mounted in a <target path>.
if($appSetting.key -eq "<MainDBConnectionString>")
{
$dbconnstring = (Get-Content "<target path>\<maindbsecret>") -as [string];
if($dbconnstring -ne $null)
{
$appSetting.value = $dbconnstring;
}
}
else
{
$appSetting.value = $_.Value;
}
Note All the corresponding MaindbConnectionString values in the DockerSettings.env no longer needs to be provided as it is pulled from the secrets.
3.
Save the Changes.
4.
Similarly, update the UpdateConfigAppSettings.ps1
script file for other application settings, as needed.
5.
Modify the Pod definition to add a volume <maindbvol> along with the <maindbsecret> to a chosen <target path>, for example, </kta/maindb/> in the container. Refer to the Kubernetes documentation on secrets to add a volume.
6.
When the pod is deployed, this should create a secret file <maindbsecret> which contains the connection string value under the path c:\kta\maindb\ in the container and also update the corresponding TotalAgility configuration file settings with the secret value.
If using secrets as environmental variables
1.
Create a secret <maindbsecret> in Kubernetes that contains the MainDBConnectionString details.
Refer to the Kubernetes documentation on secrets to create a secret.
2.
Modify the Pod definition to add an environmental variable <env variable name> for the secret
<maindbsecret>. The <env variable name> must be same as in dockerSettings.env, for example,
"KTA_Agility.Server.Web--web.config_MainDBConnectionString". This should set the environment variable "KTA_Agility.Server.Web--web.config_MainDBConnectionString" with the value of the secret
<maindbsecret> which contains the connection string value, once the pod is deployed. Refer to
Kubernetes documentation on secrets to add as environment variable.
3.
Similarly multiple environment variables can be added to the pod definition that needs to get the value form a secret. No changes are needed to the script files.
Docker Secrets
If you are using Docker secrets to store sensitive information, it is only available in the Swarm mode; so the standalone containers cannot use this feature.
Note The following changes need to be made before building the Docker images and deploying to swarm.
1.
Create a secret <maindbsecret> in the swarm that contains the MainDBConnectionString details.
Refer to the Docker documentation on Docker secrets to create a secret.
90
Kofax TotalAgility Installation Guide
2.
On the Docker container installation media, navigate to \\Utilities\Docker\ContainerFiles
\PowershellScripts and update the UpdateConfigAppSettings.ps1
Powershell script file.
Replace the line " $appSetting.value = $_.Value; " with the following lines which will check for 'maindbconnectionstring' setting and update its value in all the Kofax TotalAgility configuration files with the contents of the <maindbsecret> file located in a default target location (For windows containers, the default target is under 'C:\ProgramData\Docker\secrets') : if($appSetting.key -eq "<MainDBConnectionString>")
{
$dbconnstring = (Get-Content "<target location>\<maindbsecret>") -as [string];
if($dbconnstring -ne $null)
{
$appSetting.value = $dbconnstring;
}
}
else
{
$appSetting.value = $_.Value;
}
Note All the corresponding MaindbConnectionString values in the DockerSettings.env no longer needs to be provided as it is pulled from the secrets.
3.
Save the Changes. Similarly, you can update the UpdateConfigAppSettings.ps1
script file for other application settings as needed.
4.
Create/update a Docker service and provide access to the <maindbsecret> secret along with the
Docker environment file. This should create a secret file <maindbsecret> in the container and also update corresponding settings of the Kofax TotalAgility configuration files with the secret value. Refer to the Docker documentation on Docker secrets to create a service.
AWS Secrets
If you are using AWS Secrets to store sensitive information, such as database connection string, passwords, do the following changes to dynamically retrieve the secrets from the container. You can do this via AWS tools for powershell or via a custom .Net library. (For example, consider using the
MainDBConnectionString application setting as the secret.)
Note Make the following changes before building the docker images
Using AWS Tools for Powershell
1.
Create a secret <mainsecret> in AWS Secret Manager that contains the MainDBConnectionString details.
Refer to AWS documentation to create a secret.
2.
Install NuGet provider and AWS.Tools.SecretsManager in the container to retrieve secrets from
AWS.
3.
On the docker installation media, navigate to \\TotalAgility\Utilities\Docker
\ContainerFiles\PowershellScripts\ and update the UpdateConfigAppSettings.ps1
Powershell script file. In the ‘Update-ConfigFile’ Function, add the following script lines before the line
“Get-ChildItem env:*| ….” which will install the required AWS tools for powershell and updates the contents of the <mainsecret> retrieved from AWS secret:
Set-PSRepository -Name 'PSGallery' -InstallationPolicy Trusted
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
91
Kofax TotalAgility Installation Guide
If(-not(Get-InstalledModule AWS.Tools.SecretsManager -ErrorAction
silentlycontinue))
{
Install-Module AWS.Tools.SecretsManager -RequiredVersion 4.1.4.0 -Confirm:
$False -Force
}
$awsAccessKeyId = [Environment]::getEnvironmentVariable('KTA_AWS_ACCESSKEYID');
$awsSecretAccessKey =
[Environment]::getEnvironmentVariable('KTA_AWS_SECRETACCESSKEY');
$awsRegion = [Environment]::getEnvironmentVariable('KTA_AWS_REGION');
Set-AWSCredential -AccessKey $awsAccessKeyId -SecretKey $awsSecretAccessKey
Initialize-AWSDefaultConfiguration -Region $awsRegion
$awsMainSecretName =
[Environment]::getEnvironmentVariable('KTA_AWS_MAINSECRETNAME');
$awsMainSecret_response = Get-SECSecretValue -SecretId $awsMainSecretName
$mainSecretJsonobj = ConvertFrom-Json -inputObject
$awsMainSecret_response.SecretString
4.
Replace the line “$appSetting.value = $_.Value;” with the below lines which will check for
‘maindbconnectionstring’ setting and update its value in all the Kofax TotalAgility configuration files with the contents of the <mainsecret> retrieved from AWS secret:
if($appSetting.key -eq "<MainDBConnectionString>")
{
$dbconnstring = $mainSecretJsonobj.$awsMainSecretName;
if($dbconnstring -ne $null)
{
$appSetting.value = $dbconnstring;
}
}
else
{
$appSetting.value = $_.Value;
}
5.
Add the below script lines before the 'Update-License-Config' Function which will clean up the AWS environment variables.
$awsAccessKeyId = [Environment]::setEnvironmentVariable('KTA_AWS_ACCESSKEYID',
$null);
$awsSecretAccessKey =
[Environment]::setEnvironmentVariable('KTA_AWS_SECRETACCESSKEY',$null);
$awsRegion = [Environment]::setEnvironmentVariable('KTA_AWS_REGION',$null);
$awsMainSecretName =
[Environment]::setEnvironmentVariable('KTA_AWS_MAINSECRETNAME',$null);
6.
Save the Changes.
7.
When running the docker container, pass the KTA_AWS variables mentioned in above script as environment variables. The docker run commands as mentioned in 'Run a Docker Container' section must now also pass in these --env variables along with --env-file .
docker run -d --hostname "<host>" --name "<name>" --env
KTA_AWS_ACCESSKEYID=<access id> --env KTA_AWS_SECRETACCESSKEY=<key> --env
KTA_AWS_REGION=<region> --env KTA_AWS_MAINSECRETNAME=<mainsecret> –env-file
“dockersettings.env” -p <port> <image>
Note All the corresponding ‘MaindbConnectionString’ values in the DockerSettings.env no longer needs to be provided as it is pulled from the secrets.
8.
When the container is running, get the secret <mainsecret> which contains the connection string value and also update the corresponding Kofax TotalAgility configuration file settings with the secret value.
92
Kofax TotalAgility Installation Guide
9.
Similarly, you can update the UpdateConfigAppSettings.ps1 script file and docker run command to get other application settings from AWSsecret by adding new variables similar to $ awsMainSecretName and KTA_AWS_MAINSECRETNAME respectively .
Using Custom Library
1.
Create a secret <mainsecret> in AWS Secret Manager that contains the MainDBConnectionString details.
Refer to AWS documentation to create a secret.
2.
Create a .Net custom library ‘AWSSecretManager.dll’ with a GetAWSSecret() method that will retrieve the AWS secret. This will need AWSSDK.Core & AWSSDK.SecretsManager SDK for .Net
installed. The method code will be as follows: class AWSSecretManager:: public static string GetAWSSecret(string awsAccessKeyId, string awsSecretAcessKey,
string region , string awsSecretName)
{
string secret = string.Empty;
IAmazonSecretsManager client = new
AmazonSecretsManagerClient(awsAccessKeyId, awsSecretAcessKey,
RegionEndpoint.GetBySystemName(region));
GetSecretValueRequest request = new GetSecretValueRequest();
request.SecretId = awsSecretName;
request.VersionStage = "AWSCURRENT"; // VersionStage defaults to
AWSCURRENT if unspecified.
GetSecretValueResponse response = null;
// In this sample we only handle the specific exceptions for the
'GetSecretValue' API.
// See https://docs.aws.amazon.com/secretsmanager/latest/apireference/
API_GetSecretValue.html
// We rethrow the exception by default.
try
{
response = client.GetSecretValueAsync(request).Result;
}
catch (DecryptionFailureException e)
{
// Secrets Manager can't decrypt the protected secret text using
the provided KMS key.
// Deal with the exception here, and/or rethrow at your
discretion.
throw;
}
catch (InternalServiceErrorException e)
{
// An error occurred on the server side.
// Deal with the exception here, and/or rethrow at your
discretion.
throw;
}
catch (InvalidParameterException e)
{
// You provided an invalid value for a parameter.
// Deal with the exception here, and/or rethrow at your discretion
throw;
}
catch (InvalidRequestException e)
{
// You provided a parameter value that is not valid for the
current state of the resource.
93
Kofax TotalAgility Installation Guide
// Deal with the exception here, and/or rethrow at your
discretion.
throw;
}
catch (ResourceNotFoundException e)
{
// We can't find the resource that you asked for.
// Deal with the exception here, and/or rethrow at your
discretion.
throw;
}
catch (System.AggregateException ae)
{
// More than one of the above exceptions were triggered.
// Deal with the exception here, and/or rethrow at your
discretion.
throw;
}
// Decrypts secret using the associated KMS CMK.
// Depending on whether the secret is a string or binary, one of these
fields will be populated.
if (response.SecretString != null)
{
secret = response.SecretString;
}
else
{
MemoryStream memoryStream = new MemoryStream();
memoryStream = response.SecretBinary;
StreamReader reader = new StreamReader(memoryStream);
secret =
System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(reader.ReadToEnd()));
}
return secret;
}
3.
On the docker installation media, navigate to \\TotalAgility\Utilities\Docker
\ContainerFiles\PowershellScripts\ and copy the utility Dlls - AWSSecretManager.dll,
AWSSDK.Core.dll & AWSSDK.SecretsManager.dll
4.
Update the UpdateConfigAppSettings.ps1 Powershell script file. In the ‘Update-ConfigFile’ Function, add the following script lines before the line “Get-ChildItem env:*| ….” which will Load the custom library and update the contents of the <mainsecret> retrieved from AWS secret into :
$add = [Reflection.Assembly]::LoadFile("C:\KTA\PowershellScripts
\AWSSecretManager.dll")
$add = [Reflection.Assembly]::LoadFile("C:\KTA\PowershellScripts
\AWSSDK.SecretsManager.dll")
$add = [Reflection.Assembly]::LoadFile("C:\KTA\PowershellScripts\AWSSDK.Core.dll")
$awsAccessKeyId = [Environment]::getEnvironmentVariable('KTA_AWS_ACCESSKEYID');
$awsSecretAccessKey =
[Environment]::getEnvironmentVariable('KTA_AWS_SECRETACCESSKEY');
$awsRegion = [Environment]::getEnvironmentVariable('KTA_AWS_REGION');
Set-AWSCredential -AccessKey $awsAccessKeyId -SecretKey $awsSecretAccessKey
Initialize-AWSDefaultConfiguration -Region $awsRegion
$awsMainSecretName =
[Environment]::getEnvironmentVariable('KTA_AWS_MAINSECRETNAME');
Try {
94
Kofax TotalAgility Installation Guide
$awsMainSecret_response =
[AWSSecretManager.AWSSecretManager]::GetAWSSecret($awsAccessKeyId,
$awsSecretAccessKey,$awsMainSecretName)
}
Catch {
Write-Host "Exception::"
Write-Host $_.Exception
}
$mainSecretJsonobj = ConvertFrom-Json -inputObject
$awsMainSecret_response.SecretString
5.
Replace the line " $appSetting.value = $_.Value; " with the following lines which will check for
'maindbconnectionstring' setting and update its value in all the TotalAgility configuration files with the contents of the <mainsecret> retrieved from AWS secret:
if($appSetting.key -eq "<MainDBConnectionString>")
{
$dbconnstring = $mainSecretJsonobj.$awsMainSecretName;
if($dbconnstring -ne $null)
{
$appSetting.value = $dbconnstring;
}
}
else
{
$appSetting.value = $_.Value;
}
6.
Add the following script lines before the 'Update-License-Config' Function which will clean up the
AWS environment variables.
$awsAccessKeyId =
[Environment]::setEnvironmentVariable('KTA_AWS_ACCESSKEYID',$null);
$awsSecretAccessKey =
[Environment]::setEnvironmentVariable('KTA_AWS_SECRETACCESSKEY',$null);
$awsRegion = [Environment]::setEnvironmentVariable('KTA_AWS_REGION',
$null); $awsMainSecretName =
[Environment]::setEnvironmentVariable('KTA_AWS_MAINSECRETNAME',$null);
7.
Save the Changes.
8.
When running the docker container, pass the KTA_AWS variables mentioned in above script as environment variables. The docker run commands as mentioned in 'Run a Docker Container' section must now also pass in these --env variables along with --envfile.
docker run -d --hostname "<host>" --name "<name>" --env
KTA_AWS_ACCESSKEYID=<access id> --env KTA_AWS_SECRETACCESSKEY=<key> --env
KTA_AWS_REGION=<region>--env KTA_AWS_MAINSECRETNAME=<mainsecret> -env-file
"dockersettings.env" -p <port> <image>
Note All the corresponding ‘MaindbConnectionString’ values in the DockerSettings.env no longer needs to be provided as it is pulled from the secrets.
9.
When the container is running, this should get the secret <mainsecret> which contains the connection string value and also update the corresponding Kofax TotalAgility configuration file settings with the secret value.
10.
Similarly, you can update the UpdateConfigAppSettings.ps1
script file and docker run command to get other application settings from AWSsecret by adding new variables similar to $ awsMainSecretName and KTA_AWS_MAINSECRETNAME respectively .
95
Kofax TotalAgility Installation Guide
Import SSL certificate on the container
You can import a custom SSL certificate for use by TotalAgility on a Docker container.
You can import password-protected certificates with a private key. See SSL Support Desk for more information on certificate export.
1.
Create a new folder, such as “HostMachineFolder” on the host machine.
2.
Copy the certificate file, such as CertificateName.pfx to the newly created folder
(HostMachineFolder).
3.
You can pass the certificate password to the container as text or in a file. The file can be passed to the container as a secret (if using Docker compose, Kubernetes, and so on) or as a mapped volume.
To pass password file using mapped volume, do the following: a.
Create new text file, such as password.txt in the HostMachineFolder.
b.
Open the newly created file and enter the certificate’s password in the first line of the file.
c.
Save the file and ensure to that you change the file attribute to hidden.
4.
Create a Docker container using the "docker run" command as documented in previous sections with two additional switches, "-v" and "-e".
a.
-v: Container can access contents of HostMachineFolder via mapped ContainerFolder.
b.
-e: additional environment variables are created to store SSL certificate path
"KTA_SSL_CERT_PATH" and password ("KTA_SSL_CERT_PASSWORD" or password
"KTA_SSL_CERT_PASSWORD_PATH)".
c.
Following are the examples of the "docker run" command with new -v and -e:
For on-premise:
• docker run --env-file "C:\Docker\ TotalAgility TotalAgility
\dockersettings.env" -e SSL_CERT_PASSWORD="password" -e
SSL_CERT_PATH="HostMachineFolder\CertificateName.pfx" -v
"HostMachineFolder:ContainerFolder" -p 5000:443 -d kofax/kta_771
• docker run --env-file "C:\Docker\TotalAgility\dockersettings.env"
-e KTA_SSL_CERT_PASSWORD_PATH="C:\folder\password.txt" -e
KTA_SSL_CERT_PATH="C:\folder\Cert.pfx" -v "C:\folder:C:\folder2" -p
5000:443 -d kofax/kta_771 d.
Replace HostMachineFolder with the actual certificate path on the host machine.
e.
Replace the CertificateName with the actual certificate name.
f.
Replace the ContainerFolder with the actual folderpath and name on the container (folder will be created).
Note Ensure that folder paths or names do not have spaces.
Use Windows authentication with IIS and SQL server
Use GSMA to configure Windows authentication for Docker containers.
96
Kofax TotalAgility Installation Guide
Use Windows authentication with IIS and SQL server
Docker containers cannot join an Active Directory domain. However, when running a container, you can specify that it should use a specific AD Group Managed Service Account (gMSA) for any local
Windows services and IIS Application pool in the container that are configured to run as LocalSystem or
NetworkService accounts.
When running as these accounts in the container, the services and App pool will automatically get the access rights of the gMSA to allow them to use Windows authentication to access other VMs/machines outside of the container.
When setting up a TotalAgility Docker container to use Windows authentication, you must modify the
SilentInstallConfig.xml file to specify LocalSystem as the account to use for all TotalAgility services and IIS
App pool. This account will be used when the container is built.
Ensure the following prerequisites are met:
• Add Docker server, SQL server machine and machines that will use gMSA under required domain controller.
• Add these machines in the Active Directory under "Computer" folder.
• Create a Global Security group, such as " ContainerHostGroupName" in the Active Directory under
"Builtin" folder.
• Add Docker server, SQL server machine or machines that will use gMSA as members to the new group.
Perform the following steps to use Windows authentication with IIS and SQL server.
1.
Create the KDS root key.
This key is used by the KDS service on DCs (along with other information) to generate passwords.
You can generate this key only once per domain.
a.
Login to domain controller and execute the following commands:
Import-module ActiveDirectory
Add-KdsRootKey -EffectiveImmediately b.
Verify your key using the following command:
Get-KdsRootKey
2.
Create a gMSA account.
a.
Login to domain controller and execute the following command:
GMSA account name : containerhost
Domain name: TotalAgilityexample.com
New-ADServiceAccount -Name containerhost -DNSHostName TotalAgilityexample.com
-PrincipalsAllowedToRetrieveManagedPassword "Domain Controllers",
"domain admins", "CN= ContainerHostGroupName,CN=Builtin, DC=
TotalAgilityexample, DC=COM" -KerberosEncryptionType RC4, AES128, AES256 b.
Verify the new gMSA account using the following command: .
Get - ADServiceAccount - Identity containerhost c.
A new gMSA object appears in your domain's Managed Service Account.
97
Kofax TotalAgility Installation Guide
3.
Add gMSA account to the servers you want to use.
a.
Open the Active directory Admin Center and go to Managed service accounts.
b.
Select the gMSA account and click Properties .
c.
Select the security and click Add .
d.
Select the computers where you want to use gMSA such as Docker server and SQL server machine.
e.
Reboot Domain controller for the changes to take effect.
f.
Reboot the computers that will be using gMSA.
4.
Install gMSA Account on servers.
a.
Login to the machine that will be used as Docker server.
b.
If Active Directory features are not available, execute the following command:
Enable-WindowsOptionalFeature -FeatureName ActiveDirectory-Powershell
-online -all c.
To install and test gMSA, execute the following commands:
// check whether you are able to account
Get-ADServiceAccount -Identity containerhost //Name of GMSA
// install on machine
Install-ADServiceAccount -Identity containerhost
// test
Test-AdServiceAccount -Identity containerhost
If the output does not contain any errors, it will look like as follows:
Path :
Online : True
RestartNeeded : False
DistinguishedName : CN=containerhost,CN=Managed Service Accounts, DC=local
Enabled : True
Name: containerhost objectClass : msDs-GroupManagedServiceAccount
ObjectGUID : containerhost$
SamAccountName : containerhost$
SID : S-1-5-21-3914853822-719528391-929614657-1606
UserPrincipalName :
True
5.
Associate Service Principal Name with the gMSA: a.
This step is required for kerberos authentication to work and for automatic login in Chrome and
Internet Explorer browsers. If you skip this step, authentication still works but will always prompt for username/password since it will fallback to NTLM.
GMSA account : containerhost
Domain name: TotalAgilityexample .com
Container host machine: machine1 b.
Login to domain controller and execute the following command: setspn -c -s HTTP/ machine1 TotalAgilityexample \ containerhost setspn -c -s HTTP/ machine1. TotalAgilityexample.com TotalAgilityexample \
containerhost
98
Kofax TotalAgility Installation Guide
6.
To test Active Directory access on the container host, run the following command on the host machine: nltest /parentdomain
At this point, if no errors occurs, the LocalSystem account on the container will be a proxy for the configured gMSA account. Any process run as the LocalSystem principal on the container will appear to be the GMSA principal to all assets on the Active Directory domain.
7.
Generate credential specifications file which must be passed to the Docker during container creation to utilize this service account. Run the following commands to downloads module which will create this file from Microsoft github account and will create a JSON file containing required data.
GMSA account : containerhost
Domain name: TotalAgilityexample.com
Invoke-WebRequest "https://raw.githubusercontent.com/Microsoft/Virtualization-
Documentation/live/windows-server-container-tools/ServiceAccounts/
CredentialSpec.psm1" -UseBasicParsing -OutFile $env:TEMP\cred.psm1
import-module $env:temp\cred.psm1
New-CredentialSpec -Name win -AccountName containerhost
#This will return location and name of JSON file
Get-CredentialSpec
Name Path
---- ---- win C:\ProgramData\docker\CredentialSpecs\win.json
8.
For SQL server configuration to allow gMSA, enter the gMSA account as "containerhost" and domain name as "TotalAgilityexample.com" and run the following SQL commands on your SQL database:
CREATE LOGIN " TotalAgilityexample \containerhost$"
FROM WINDOWS
GO
To create user for all the TotalAgility databases:
CREATE USER containerhost FOR LOGIN " TotalAgilityexample \ containerhost$"
GO
EXEC sp_addrolemember 'db_datareader', containerhost
EXEC sp_addrolemember 'db_datawriter', containerhost
9.
If there are no errors, the LocalSystem account on the container will be a proxy for the configured gMSA account. Any process run as the LocalSystem principal on the container will appear to be the gMSA principal to all assets on the Active Directory domain. To test Active Directory access on the container, run the following command on the container: nltest /parentdomain
Install TotalAgility on a non-standard port
To install TotalAgility on a non-standard port, you must first edit bindings to specify the port number, and update the base address and restart the streaming service.
Edit bindings
1.
Click Start > Run > InetMgr > Sites > Default Web Site .
By default, the Default Web Site is selected.
2.
Right click on the Default Website and click Edit Bindings .
99
Kofax TotalAgility Installation Guide
3.
Select the default port 80 and click Edit .
4.
In the Edit Site Binding window, change the port number to 81 and click OK .
5.
Install Kofax TotalAgility. See
.
6.
Enter the following URL in your browser and change the port number to 81 in the URL to logon.
http://ServerName:81/TotalAgility/forms/GeneralWorkQueue.form
.
Update the base address
You can edit the base address setting either manually or using the Configuration Utility.
Manually
1.
On the TotalAgility installation media, open the Agility.Server.StreamingService.exe.configuration
file available at \\TotalAgilityInstall\Agility.Server.Web\bin> and change the base address section.
< baseAddresses >
<add baseAddress="http://<ServerName>.<DomainName>:
<non default port>/TotalAgility/Services/Sdk/StreamingService.svc" />
</ baseAddresses >
2.
Similarly, change the base address section in the Agility.Server.StreamingService.exe.config file available at \\TotalAgilityInstall\CoreWorkerService> .
< baseAddresses >
<add baseAddress="http://<ServerName>.<DomainName>:
<non default port>/TotalAgility/Services/Core/StreamingService.svc" />
</ baseAddresses >
3.
The streaming service hosts an http server. If the Streaming service and Package streaming service are running under a non-admin account on a non-standard port, you need to reserve a namespace for them. To do so, on the Command Prompt, run the following command using an account that has administrator rights on the local machine:
• For StreamingService.svc:
• For the Web server and Combined Web App server installations: netsh http add urlacl url=http://+:<non default port>/TotalAgility/
Services/Sdk/StreamingService.svc user=%domainuser%
• For the Application server installation: netsh http add urlacl url=http://+:/TotalAgility/Services/Core/
StreamingService.svc user=%domainuser%
• For PackageStreamingService.svc: netsh http add urlacl url=http://+:<non default port>/TotalAgility/
Services/Sdk/PackageStreamingService.svc user=%domainuser%
If the aforementioned URLs are not reserved, the Streaming service will not start when using a nonadmin service account.
Use the Configuration Utility
Run the Configuration utility and update the base address property for the streaming service. The streaming service must be restarted for the change to take effect. Restart the Streaming Service
100
Kofax TotalAgility Installation Guide
Restart the Streaming Service
Once the base address is changed or the command to reserve the namespace is completed, restart the
Streaming service.
Install databases manually
The following procedure describes installing databases manually.
You can either create a single database for Main, Audit and Finished databases or create separate Main,
Audit and Finished databases.
By default, the Document Repository is installed into its own database. However, you can create tables for the document repository within the main TotalAgility database by running the scripts. See
.
Configure MSDTC
Important If the Application Server and databases are installed on the same server, it is not required to start MSDTC.
When you have scaled out (separate) TotalAgility databases such as Main and Archive, you require the
Microsoft Distributed Transaction Coordinator (MSDTC).
By default, the security configuration for the Microsoft Distributed Transaction Coordinator is set to not allow network transactions.
As the MSDTC is responsible for coordinating transactions that span multiple resource managers, such as databases, message queues, and file systems you must configure MSDTC if your databases are split and the TotalAgility application reside on separate servers. In this case, do the following to select the settings:
1.
Navigate to Control Panel > System and Security > Administrative Tools .
2.
Click Component Services .
The Component Services window appears.
3.
In the left panel, under Console Root expand the Component Services, navigate to Computers >
My Computer > Distributed Transaction Coordinator and select Local DTC .
4.
From the Local DTC context menu, select Properties .
5.
In the Local DTC Properties window, click the Security tab.
6.
Under Security Settings, select the checkboxes for Network DTC Access and Enable SNA LU 6.2
Transactions (if JDBC is used).
7.
Select Enable SNA LU 6.2 Transactions if required. Ensure that Microsoft SNA server is installed and SNA resources are correctly configured.
8.
Under Transaction Manager Communication, select the checkboxes for Allow Inbound and Allow
Outbound (configure the desired level of security for authentication).
9.
After the settings are completed, start the Distributed Transaction Coordinator service.
101
Kofax TotalAgility Installation Guide
Start MSDTC manually
To start MSDTC manually, on the Command Prompt window, run the following command: net start msdtc . Alternatively, at Run, type Services.msc and press Enter . Right-click the Distributed Transaction
Coordinator service and click Start .
Note The remote SQL server will also require MSDTC configuration. In addition to the above Security
Settings, select Allow Remote Clients . The Allow Remote Administration setting is optional.
If there are additional network and security rules required for TotalAgility to communicate, there are a number of Microsoft tools that can help you troubleshoot some common issues. These tools are not Kofax products and carry no warranty or liability.
• DTCTester : This tool verifies the transactions between two computers if SQL Server is installed on one computer, using ODBC to verify transaction support against an SQL Server database.
• DTCPing : This tool verifies transaction support between two computers if SQL Server is not installed on either computer. The DTCPing tool must be run on both the client and server computers.
TotalAgility license tables are installed by running the Create_KLS_OnPremise.sql
.
Manually install databases
Perform the following steps to install databases manually.
1.
Ensure that you create the following databases:
• TotalAgility
• Finished Jobs
• Audit
• TotalAgility_Reporting
• TotalAgility_Reporting_Staging
2.
Edit the Initialise_Main.sql script by using the comments in the script. For example, update the details of the user who will log on to TotalAgility initially by editing the following: a.
@NTNAME = ‘INSTALL_NTUSERID’ , where the User Domain and User ID replaces
INSTALL_NTUSERID. For example, ‘DomainName\USERA’ b.
@FULLNAME = ‘INSTALL_FULLNAME’ , where the User name replaces
INSTALL_FULLNAME. For example, ‘USER A’
102
Kofax TotalAgility Installation Guide
3.
Run the scripts in the following order across databases and follow the instructions inside each script.
a.
Main(Create, Initialise)
Run the following scripts on the Main database:
• Create_Main.sql
• Initialise_Main.sql
• Create_Forms.sql
• Initialise_Forms.sql
• Create_KFS.sql
• Initialise_KFS.sql
• LicenseScripts\Create_KLS_OnPremise.sql
b.
Finished Jobs(Create)
Run the following script on the Finished Jobs database (can exist on the Main database):
• Create_Archive.sql
c.
Audit(Create, Intialise)
Run the following scripts on the Audit database (can exist on the Main database):
• Create_Audit.sql
• Initialise_Audit.sql
4.
The following scripts are used for installing reporting databases manually.
• Scripts for creating the Staging database.
• Kofax.Reporting.Analytics.Staging.SQL_TablesCreate.sql
• Kofax.Reporting.Analytics.Staging.SQL_Initialize.sql
• Scripts for creating the Reporting database.
• Kofax.Reporting.Analytics.SQL_TablesCreate.sql
• Kofax.Reporting.Analytics.SQL_Initialize.sql
Note Before running these scripts, verify that a compatible database server is already installed.
The Reporting tables must be in the default schema.
5.
In the Installation wizard, in the Databases window, do the following: a.
Clear the check boxes for Install Databases and Overwrite databases if they exist .
b.
Rename the databases under Database Name to match with the name given while creating databases manually.
Change the name of the Data Layer database to either Repository2012 or the name given while creating the databases.
c.
Click Next . Ensure the installation completes before updating the configuration files.
103
Kofax TotalAgility Installation Guide
6.
You can edit the value of the database connections in the Web.config manually or run the
Configuration Utility available on the installation media.
• Open Web.config
available at \\TotalAgilityInstall\Agility.Server.Web
. In the appSettings section, update the value of the following database connections:
• MainDBConnectionString
• ArchiveDBConnectionString
• AuditDBConnectionString
• ReportingMainDBConnectionString
• ReportingStagingDBConnectionString
Note The database should point to the machine where Kofax TotalAgility is installed.
• Run the Configuration Utility and modify the values of the preceding database connections available on the Common settings tab.
7.
To modify the value of database connections in Agility.Server.Core.WorkerService.exe.config, do either of the following:
• Open Agility.Server.Core.WorkerService.exe.config
available at \\TotalAgilityInstall
\CoreWorkerService and modify the values of following connection strings:
• MainDBConnectionString
• ArchiveDBConnectionString
• AuditDBConnectionString
• ReportingMainDBConnectionString
• ReportingStagingDBConnectionString
Note The database should point to the machine where the Kofax TotalAgility is installed.
• Run the Configuration Utility and modify the values of the preceding connection strings available on the Common settings tab.
8.
To modify the values of database connections in the Agility.Server.StreamingService.exe.config, do either of the following:
• Open Agility.Server.StreamingService.exe.config
available at \\TotalAgilityInstall
\CoreWorkerService and update the following connection strings:
• MainDBConnectionString
• ArchiveDBConnectionString
• AuditDBConnectionString
• ReportingMainDBConnectionString
• ReportingStagingDBConnectionString
Note The database should point to the machine where Kofax TotalAgility is installed.
• Run the Configuration Utility and modify the values of the preceding connection strings available on the Common settings tab.
104
Kofax TotalAgility Installation Guide
9.
To connect TotalAgility to the desired documents database: a.
Go to the TotalAgility Main database > SERVER_DATA table > CEBPM_SETTINGS column.
b.
Open the CEBPM_SETTINGS XML file.
c.
In the <Common Settings> section, update the Data Source value to your computer name,
Integrated Security to True, and the value of the Initial Catalog to the Data Layer Database name.
<Common_Settings>
<ReportingSettings />
<DataLayerConfiguration RepositoryDBConnectionString="; Data
Source=<computer name> ; Initial Catalog = Data Layer
Database ;User ID=;Password=; Integrated Security=True ;Connect
Timeout=30;Encrypt=False;TrustServerCertificate=False"
RepositoryBlobStorageAccountConnectionString="{DATA_LAYER_BLOB_CONNSTRING}"
RepositoryBlobStorageContainerName="{DATA_LAYER_BLOB_CONTAINER}" />
</Common_Settings>
10.
Restart the TotalAgilityCoreWorker service for the change to take affect.
11.
Generate the security key. To generate the key, navigate to System > Settings > System >
General > in the TotalAgility Designer.
Import Artifacts
You must import the standard forms, style sheets and custom assets after installing TotalAgility databases.
Note On upgrading TotalAgility, you must manually import the System maps and standard forms.
You can import all the artifact from WorkspacePackage.zip available at the following location:
\\TotalAgilityInstall\Agility.Server.Web\Packages
Configure TotalAgility for high availability
You can install a second License Server on a different computer and use it as a backup server for Kofax
TotalAgility.
1.
On the TotalAgility installation media, navigate to \\ TotalAgilityInstall > Licensing > Installs .
2.
Click KSALicServerSetup .
The License Server Setup window opens.
3.
Click Next .
4.
In the Destination Folder window, select the default folder ( C:\Program Files (x86)\Kofax
\License Server\ ) for the License Server or click Change to select a different folder.
5.
Click Next and follow the instructions to complete the installation.
105
Kofax TotalAgility Installation Guide
Access TotalAgility through iPad or iPhone
To access TotalAgility through iPad or iPhone, update the Web.config
file. You can use Windows authentication between the Web and Application servers and still use TotalAgility authentication from the client device to the Web server.
1.
Access TotalAgility Web.config
file from the following directory on the Web server: C:\Program
Files\Kofax\otalAgility\Agility.Server.Web\Web.config
.
2.
Search the .config
file for the following: <binding name="BasicHttpBinding_Service" .
3.
Copy the entire block of code, from <binding> to </binding> .
4.
Paste the block under the copied block and rename it to: <binding name= BasicHttpBindingCore_Service .
5.
In the copied binding, ensure HTTP with Windows authentication is enabled. This enables the authentication from the Web server to the Application server.
6.
Navigate to the start of the core end points, search for: <!--START CORE END POINTS --> .
7.
For each core end point replace BasicHttpBinding_Service with
BasicHttpBindingCore_Service .
8.
To use the authentication from the client device to the web server, update the original
BasicHttpBinding_Service binding to use Anonymous authentication and SSL (if required).
9.
Save the Web.config
file.
10.
Log on to TotalAgility ensuring you have been previously added as a TotalAgility user.
Federated Security-Generate a common machine key
When using Federated Security with TotalAgility in a load balance environment, TotalAgility cannot consistently decrypt the encrypted token passed from an Identity Provider using WsFed tokens. This is because, by default, each load balanced server has a unique machine key identifier used for token encryption/decryption.
We recommend that you generate a common machine key and propagate it to all servers in the load balanced environment. For example, if you generate a machine key for the TotalAgility application, the
Web.config file gets automatically updated with the machine key element. The configuration of a machine key can be done at Web Server, Site or Application level.
To generate a machine key, perform the following steps:
1.
Open Internet Information Services(IIS) manager.
2.
Select the TotalAgility application, website or web server from the left panel to generate a machine key.
3.
In Features View , right-click Machine Key , and then click Open Feature .
4.
On the Machine Key page, select an encryption method from the Encryption method drop-down list.
5.
Select a decryption method from the Decryption method drop-down list.
6.
Optionally, configure settings for Validation and Decryption keys.
106
Kofax TotalAgility Installation Guide
7.
In the Actions panel, click Generate Keys , and then click Apply .
When you click apply, the changes are automatically saved in the Web.config file.
To encrypt and decrypt the machine key, see
Encrypt and decrypt the TotalAgility configuration files .
Encrypt and decrypt the TotalAgility configuration files
The TotalAgility configuration files include the DB Connection settings, including sensitive information.
Therefore, we recommend that you encrypt the following TotalAgility files.
• Web.config (Use Microsoft ASP.NET IIS Registration Tool)
• Configuration files of executables (Use the Kofax.CEBPM.EncryptConfig.exe utility)
Note Kofax.CEBPM.EncryptConfig.exe cannot work with Web.config; it can only work with configurations of executables.
Encrypt and decrypt Web.config
1.
Navigate to TotalAgility Web.config located at <Kofax Install location>\TotalAgility
\Agility.Server.Web
.
2.
Use the Microsoft ASP.NET IIS Registration Tool (aspnet_regiis) to encrypt or decrypt any section of the Web.config file. See the Encrpting and Decrypting Configuration sections On the Microsoft website.
At a minimum, encrypt the appSettings section that includes the Database connection information.
Encrypt and decrypt the configuration files of executables
The configuration files of executables that can be encrypted include:
Configuration file name
• Agility.Server.ExportConnector.exe.config
• Agility.Server.StreamingService.exe.config
• Agility.Server.Core.WorkerService.exe.config
• Agility.Server.Core.Executor.exe.config
• Agility.Server.Core.ExportService.exe.config
• Agility.Server.Core.ExportWorker.Host.exe.config
Location
Agility.Server.Web files:
<Kofax Install location>\TotalAgility
\Agility.Server.Web
Core Worker Service files:
<Kofax Install location>\TotalAgility
\CoreWorkerService
• Kofax.CEBPM.Reporting.TAService.exe.config
• Kofax.CEBPM.CPUServer.ServiceHost.exe.config
• KSALicenseService.exe.config
Reporting Server Service file: <Kofax Install location>\TotalAgility\Reporting
Transformation Server Service file: <Kofax Install location>\TotalAgility\Transformation
Server
License Server Service file: <Kofax Install location>\TotalAgility\LicenseServer
107
Kofax TotalAgility Installation Guide
Add the security provider
Add the following security provider in the configuration file before encrypting them:
<configProtectedData>
<providers>
<add useMachineProtection="true"
name="DPAPIProtection"
type="System.Configuration.DpapiProtectedConfigurationProvider,
System.Configuration, Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a" />
<add name="RSAProvider"
type="System.Configuration.RsaProtectedConfigurationProvider,
System.Configuration,
Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a,
processorArchitecture=MSIL"
keyContainerName="CPUServerKeys" useMachineContainer="true" />
</providers>
</configProtectedData>
Use the Kofax.CEBPM.Encryption.exe utility
The Kofax.CEBPM.EncryptConfig.exe (located in the TotalAgility installation_folder) utility encrypts (-enc) or decrypts (-dec) any section of the configuration file.
At a minimum, encrypt the appSettings section as it includes the user ID and password as well as other information. Use the optional -h flag to display help for the command.
The TotalAgility Server supports two encryption methods depending on command line parameters using the Kofax.CEBPM.EncryptConfig.exe utility:
•
•
Use the DPAPI encryption method
Use this utility to encrypt one server at a time because you must decrypt the file on the same machine where it was encrypted.
Run the utility on each TotalAgility Server individually.
1.
Stop the TotalAgility Core Worker Server service.
2.
Navigate to the TotalAgility Core Worker installation directory.
3.
Copy the Kofax.CEBPM.EncryptConfig.exe
to the same folder where
Agility.Server.Core.WorkerService.exe.config resides.
4.
Open a Command Prompt window and run the following command:
Kofax.CEBPM.EncryptConfig.exe -f Agility.Server.Core.WorkerService.exe.config -s
"appSettings" -p DPAPIProtection -enc
Use the RSA encryption method
An algorithm for public key encryption and digital signatures that uses two separate keys. Create a key and encrypt the configuration file on one Server, and export the key to all the other Servers. All the
108
Kofax TotalAgility Installation Guide
TotalAgility Servers with the exported key installed can access the configuration file. Use this method if you have several Servers with the same configuration.
The following instructions differentiate between the source TotalAgility Server where you create the key and the target TotalAgility Servers onto which you import the key.
Prepare the key
Perform these steps on one source TotalAgility Server.
1.
Create the custom RSA key container: a.
Log on to the TotalAgility Server with administrator rights.
b.
Open a command-line window.
c.
Navigate to the .NET Framework version 4.0 directory. For example, enter the following command: cd \WINDOWS\Microsoft.Net\Framework\v4.0.* d.
Run the following command: aspnet_regiis -pc "<KeysFile>" -exp where:
• <KeysFile> is the name of the key file.
• The -exp option makes the key exportable.
2.
Run the following command to grant the TotalAgility Core Worker Server service user permission to read the <KeysFile> RSA container file.
aspnet_regiis -pa <KeysFile> <TotalAgilityserviceuser> where:
• <KeysFile> is the name of the key file you created in Step 1d.
• <TAserviceuser> is the TotalAgility Core Worker Server service user.
3.
Encrypt the file: a.
Log on to the TotalAgility Server as the TotalAgility Core Worker Server service user.
b.
Navigate to the installation directory for the TotalAgility Server and open a command-line window.
c.
Run the following command:
Kofax.CEBPM.EncryptConfig.exe -f
Agility.Server.Core.WorkerService.exe.config -s "appSettings" -p
RSAProvider -enc
This command encrypts the appSettings section of the configuration file. The appSettings section includes the user ID, password and other information.
4.
Export the key by running the following command: aspnet_regiis -px "<KeysFile>" "<c:\keys.xml>" -pri where:
• <KeysFile> is the default keystore keyContainerName.
• <c:\keys.xml> is the path and file name of the exported key file.
109
Kofax TotalAgility Installation Guide
Import the key
Perform these steps on every target TotalAgility Server.
1.
Import the key: a.
Log on to the TotalAgility Server with administrator rights.
b.
Copy the keys.xml file from the source TotalAgility Server to the root C:\ directory of the target
TotalAgility Server.
c.
Open a command-line window.
d.
Run the following command: aspnet_regiis -pi "<KeysFile>" "c:\keys.xml" where:
• <KeysFile> is the default name of the key file.
• <c:\keys.xml> is the path and file name to the imported key file.
e.
Delete the keys.xml because it contains the unprotected private key.
2.
Run the following command to grant the TotalAgility Core Worker Server service user permissions to use the <KeysFile> RSA container file: aspnet_regiis -pa "<KeysFile>" "TotalAgilityserviceuser" where:
• <KeysFile> is the name of the key file you imported in step 1.
• <TotalAgilityserviceuser> is the TotalAgility Core Worker Server service user.
3.
Repeat these steps on all remaining TotalAgility Servers.
Decrypt the configuration file
1.
Stop the TotalAgility Core Worker Server service.
2.
Navigate to the TotalAgility Server installation directory and open a command-line window.
3.
Run the following command:
Kofax.CEBPM.EncryptConfig.exe -f
Agility.Server.Core.WorkerService.exe.config -s "appSettings" -p
DPAPIProtection -dec
Important Repeat the encrypt and decrypt procedures for Export configuration file also.
Encrypt the configuration files in a Docker container
To encrypt the Web.config files and all executable configuration files using "DPAPI", you must add the following to your Docker run command.
-e KTA_CONFIG_ENCRYPTION_PROVIDER_TYPE="DPAPI"
For example, "docker run -d --hostname "opdemo2" --name "opdemo2" -env-file "C: \Docker\TotalAgility\dockersettings.env" -p 5000:80 -e
KTA_CONFIG_ENCRYPTION_PROVIDER_TYPE="DPAPI" kofaxop"
110
Kofax TotalAgility Installation Guide
To encrypt the Web.config files and all executable configuration files using "RSA", you must add the following to your Docker run command.
-e KTA_CONFIG_ENCRYPTION_PROVIDER_TYPE="RSA"
For example, "docker run -d --hostname "opdemo2" --name "opdemo2" -env-file "C: \Docker\TotalAgility\dockersettings.env" -p 5000:80 -e
KTA_CONFIG_ENCRYPTION_PROVIDER_TYPE="RSA" kofaxop"
Edit the TotalAgility configuration settings
After installing TotalAgility, to change or update any parameters, edit the following configuration files available in the installation directory.
• Agility.Server.Core.WorkerService.exe.config
• Agility.Server.Core.ExportService.exe.config
• Web.config
• KSALicenseService.exe.config
You can either edit each of these files separately or run the TotalAgility configuration utility to modify all the settings at one go. The configuration utility is available on the installation media and must be manually copied to your TotalAgility server. See the TotalAgility Configuration Utility Guide .
Update the parameter values
When you initially install the TotalAgility Server, the system stores the configuration settings in a .NET file,
Agility.Server.Core.WorkerService.exe.config. To change the value of any parameters, do the following.
1.
If you encrypted the configuration file after you installed the TotalAgility server, decrypt the file. See
Encrypt and decrypt the TotalAgility configuration files
.
Note If you use RSA encryption, decrypt the configuration file only on the source TotalAgility server where you initially encrypted the file.
2.
Navigate to the installation directory for the TotalAgility server.
3.
Open Agility.Server.Core.WorkerService.exe.config in a text editor.
4.
Locate the following section:
<appSettings>
<add key="KeyNameString" value="which may contain passwords;"/>
</appSettings>
5.
Edit the parameter values as needed.
6.
Save and close the configuration file.
7.
To re-encrypt the configuration file, run the encryption utility.
Note If you use RSA encryption, export the key, and install the encryption key file on any target
TotalAgility servers imported the original encrypted configuration file.
8.
Restart the Kofax TotalAgility Core Worker Server service.
111
Kofax TotalAgility Installation Guide
Update the settings for a license server
When installing TotalAgility, by default, the primary license server is used. If the primary license server fails, you can connect to the backup server post installation manually, or run the Configuration utility.
Manually
After installing TotalAgility, you can update the license server parameters in the KSALicenseService.exe
available in the installation directory.
1.
Stop the Kofax Licenser Server service.
2.
Navigate to the installation directory for the TotalAgility server.
3.
In a text editor, open KSALicenseService.exe.config from the following directory: \\Kofax
\TotalAgility\LicenseServer .
4.
Locate the following section and update the serverID and connectionStrings parameters. By default, serverId value is "1", which means primary license server is connected.
<appSettings>
<!-- Specify "1" for a primary license server or "2" for a backup license
server. -->
<add key="serverId" value="1"/>
</appSettings>
<connectionStrings>
<add name="LicensingDatabase"
connectionString="Server=<machinename>;Trusted_Connection=Yes;Database='TotalAgility';"/
>
</connectionStrings> a.
To connect to the backup license server, modify the serverId value as "2".
b.
Update the LicensingDatabase connection string to point to Main DB for on premise environment.
5.
Save and close the configuration file.
Use the Configuration Utility
Run the Configuration utility and select Backup license server setting on the Licensing tab. See the
Kofax TotalAgility Configuration Utility Guide .
Support export vertical scaling
By default, there is no export instance. An export instance is only spawned if there is an export activity that is ready for export. More export instances are spawned if there are more export activities that are ready for export. You can configure TotalAgility to support multiple export instances on an export server.
1.
Navigate to the installation directory for the TotalAgility Server.
2.
Open Agility.Server.Core.ExportService.exe.config in a text editor.
3.
Locate the <appSettings> section and change the value of MaxExportProcessesNumber as needed. (Default: 0)
<appSettings>
<add key="MaxExportProcessesNumber" value="0"/>
</appSettings>
112
Kofax TotalAgility Installation Guide
Note Maximum number = Round of ((The number of machine processor count) * 1.25)
Maximum number = Round of ((The number of machine processor count) * 1.25)
The formula is only used if MaxExportProcessesNumber is less than or equal to 0. If the number is
>= 1, the export processes count is equal to the defined value (MaxExportProcessesNumber).
Anti-Cross Site Request Forgery (CSRF) measures
Use the following anti-CSRF measures to protect the site against Cross-site Request Forgery attacks.
•
Configure the Anti-CSRF tokens
• Specify the Samesite attribute with value as Strict or Lax in the <hostCookies> tag of the web.config to prevent CSRF attacks. See the Microsoft website for more information.
•
Enable Host prefix for cookies
Anti-Cross Site Request Forgery (CSRF) tokens
A CSRF attack relies on a user being authenticated on a website. The attack usually comes as an email or website hyperlink on which the user clicks while still authenticated. This URL then points back to the user's website and attempts to perform a privileged action (such as add an administrator account) without the user's knowledge. In TotalAgility, the TargetHostName and TargetPortNo settings are added as Anti-CSRF tokens in the Web.config file. The TargetHostName is the fully qualified domain name of the webserver and the TargetPortNo is the website port number. When you provide for these settings, the Anti-CSRF origin and referrer validations are performed on the request URL. If the validation fails, the request will be terminated considering it as a potentially dangerous request.
You can configure the Anti-CSRF tokens in the Web.config manually or using the Configuration Utility.
Manually
1.
Navigate to the installation directory for the TotalAgility server.
2.
In a text editor, open Web.config from the following directory: .
\\TotalAgilityInstall\Agility.Server.Web
3.
Locate the following section and specify the target host name and target port number.
<appSettings>
<add key= “TargetHostName" value="<hostnamegoeshere"/>
<add key= “TargetPortNo” value=”443”
</appSettings>
4.
Save and close the configuration file.
Use the Configuration Utility
Run the Configuration utility and specify the TargetHostName and TargetPortNo settings. See the Kofax
TotalAgility Configuration Utility Guide .
113
Kofax TotalAgility Installation Guide
Enable Host prefix for cookies
Use the "Host Prefix for Cookies", a browser functionality which makes the cookies more secure by prefixing the TotalAgility cookie names with "__HOST-". When a cookie name starts with this flag, it triggers additional browser policy on the cookie in supporting browsers. A __Host--prefixed cookie is only accessible by the same domain it is set on, which means a subdomain can no longer overwrite the cookie value. It also makes a cookie accessible from HTTPS sites only. This protects the cookie even if an attacker uses a forged insecure site to overwrite a secure cookie.
Edit the setting manually or use the Configuration Utility for enabling or disabling the cookies security.
Perform the following steps on the Web or combined Web/Application server.
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall
\Agility.Server.Web
.
2.
Open web.config in a text editor.
3.
Locate the <appSettings> section and make sure the value of "UseHostPrefixForCookies" value="true".
<appSettings>
<add key="UseHostPrefixForCookies" value="true"/>
</appSettings>
Use the Configuration Utility
Run the Configuration Utility and change the Host Prefix for Cookies setting on the Web settings tab as needed.
Configure the wait time for export activities
You can configure the wait time for export activities in seconds so that the Export Service will wait for the configured seconds for new export activities to progress based on the availability of the child export processes.
If all the child export processes are in inactive mode (that is, there are no export activities available),
TotalAgility Export Service will wait for the configured seconds for new export activities to process. If any child export process is in an active mode (that is, any child process is executing the Export activity),
TotalAgility Export Service will instantaneously take new export activities to export without waiting for the configured seconds.
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall
\CoreWorkerService .
2.
Open Agility.Server.Core.ExportService.exe.config in a text editor.
3.
Locate the <appSettings> section and change the value of
"WaitForAvailableExportActivitiesTimeoutInSeconds" as needed. (Default: 30)
<appSettings>
<add key="WaitForAvailableExportActivitiesTimeoutInSeconds" value="30"/>
</appSettings>
114
Kofax TotalAgility Installation Guide
Note The minimum value for WaitForAvailableExportActivitiesTimeoutInSeconds is 1 and maximum value is 600.
You must restart the TotalAgility Export Service for the change to take effect.
Update the settings for manual authentication
Perform the following steps on the Web or combined Web/Application server and Application Server.
Edit the setting manually or use the Configuration Utility for manual authentication.
Web server or combined Web/Application server
Perform the following steps on the Web or combined Web/Application server and Application Server.
Manually
1.
Open the TotalAgility Web.config
file from the following directory: C:\Program Files\Kofax
\TotalAgility\Agility.Server.Web
.
2.
Locate the following bindings: "CustomBinding_CoreService", "BasicHttpBinding_Service" and
"WebHttpBinding_Service" and comment out all the three security mode configurations for manual logon over http.
<!-- The following are the different options for securing the services -->
<!-- All commented out is application manual logon over HTTP -->
<!-- Only one option should be uncommented at a time -->
<!-- Azure should use HTTPS SSL with application logon-->
<!-- On premise default: HTTP with Windows authentication-->
<!-- HTTPS SSL with application logon-->
<!--<security mode="Transport">
<transport clientCredentialType="None"/>
</security>-->
<!-- HTTP with Windows authentication-->
<security mode="TransportCredentialOnly">
<transport clientCredentialType="Windows" />
</security>
<!-- HTTPS SSL with Windows authentication-->
<!--<security mode="Transport">
<transport clientCredentialType="Windows" />
</security>-->
Note In the TotalAgility Web.config file, under the section,
TransformationServerExternalService_Binding , the security mode and transport clientCredentialType should be same as specified in the Transformation Server Web.config file.
Use the Configuration Utility
Run the Configuration Utility and change the mode of authentication on the Web settings tab as needed.
115
Kofax TotalAgility Installation Guide
Application server
Manually
1.
Open the TotalAgility Web.config
file from the following directory: C:\Program Files\Kofax
\TotalAgility\Agility.Server.Web
.
2.
Locate the following bindings, "CustomBinding_CoreService", "BasicHttpBinding_Service" and
"WebHttpBinding_Service" and comment out all the three security mode configurations for manual logon over http.
<!-- The following are the different options for securing the services -->
<!-- All commented out is application manual logon over HTTP -->
<!-- Only one option should be uncommented at a time -->
<!-- Azure should use HTTPS SSL with application logon-->
<!-- On premise default: HTTP with Windows authentication-->
<!-- HTTPS SSL with application logon-->
<!--<security mode="Transport">
<transport clientCredentialType="None"/>
</security>-->
<!-- HTTP with Windows authentication-->
<security mode="TransportCredentialOnly">
<transport clientCredentialType="Windows" />
</security>
<!-- HTTPS SSL with Windows authentication-->
<!--<security mode="Transport">
<transport clientCredentialType="Windows" />
</security>-->
Use the Configuration Utility
Run the Configuration Utility and change the mode of authentication on the Web settings tab as needed.
Update the settings for manual and Windows authentication
When you install TotalAgility, you can choose the logon mode as manual or Windows authentication.
However, post installation, you can switch the logon mode to use both Windows and manual (mixed) authentication by running the Configuration Utility. If the Windows authentication fails, you will be redirected to the manual logon page.
Use mixed authentication on the Web server or combined Web/Application server
Perform the following steps on the Web server or combined Web/Application server to set up mixed authentication (Windows and manual).
1.
Open the TotalAgility Web.config
file from the following directory: C:\Program Files\Kofax
\TotalAgility\Agility.Server.Web
.
2.
Locate the following Bindings: BasicHttpBinding_Service and WebHttpBinding_Service and comment out the security mode configurations for manual logon over http.
3.
Locate the following ClientWindowsService Bindings:
BasicHttpWindowsUserBinding_Service and WebHttpWindowsUserBinding_Service and comment out the security mode configurations for Windows Authentication logon over http.
<!-- The following are the different options for securing the services -->
116
Kofax TotalAgility Installation Guide
<!-- All commented out is application manual logon over HTTP -->
<!-- Only one option should be uncommented at a time -->
<!-- Azure should use HTTPS SSL with application logon-->
<!-- On premise default: HTTP with Windows authentication-->
<!-- HTTPS SSL with application logon-->
<!--<security mode="Transport">
<transport clientCredentialType="None"/>
</security>-->
<!-- HTTP with Windows authentication-->
<security mode="TransportCredentialOnly">
<transport clientCredentialType="Windows" />
</security>
<!-- HTTPS SSL with Windows authentication-->
<!--<security mode="Transport">
<transport clientCredentialType="Windows" />
</security>-->
Use the Configuration Utility
After installing TotalAgility, to use the mixed authentication, run the Configuration Utility and switch the mode of authentication ( HTTP with manual and Windows authentication or HTTPS with manual and Windows authentication ) on the Web settings tab, as needed.
Note To use mixed authentication, you must enable both the Anonymous and Windows Authentication options in the IIS.
Update settings for the TotalAgility linked servers
Edit the setting manually or use the Configuration Utility for manual authentication.
Manually
On installing TotalAgility, the Web.config is updated automatically with machine name / TotalAgility for linked servers. If you want to connect from a public IP Address, you must update the Web.config file.
1.
Open the TotalAgility Web.config
file from the following directory: \\TotalAgilityInstall
\Agility.Server.Web
2.
Locate the following section and replace the IP Address with your machine name.
<add key="TotalAgilityHostNameLive" value = "<ip_address>/TotalAgility" />
<add key="TotalAgilityHostNameDev" value = "<ip_address>/TotalAgility"/>
See the Kofax TotalAgility help for more information.
Use the Configuration Utility
Run the Configuration Utility and update the TotalAgilityHostNameLive key.
Alter the virtual root for the Kofax TotalAgility website
1.
Open the TotalAgility Web.config
file from the following directory: \\TotalAgilityInstall
\Agility.Server.Web
2.
Modify the following configuration keys to alter the virtual root for the Kofax TotalAgility website:
<add key="WebsiteBaseName" value="TotalAgility"/>
117
Kofax TotalAgility Installation Guide
<add key="ProcessDocumentsRootFolder" value="/TotalAgility/documents/process"/
Note The value for the "WebsiteBaseName" should be the name of the virtual directory used within the IIS.
Add custom job thread pools
A job thread performs multiple operations at a time, such as job evaluation, raising an exception job or ingestion through Kofax Import Connector. Multiple operations can lead to bottlenecks in the production systems. For example, when there are thousands of jobs to be archived, ingestion and job evaluation take longer time because the job threads are busy archiving jobs. Adding custom job thread pools, helps in achieving better throughput and prioritizing the background tasks.
You can add custom job thread pools, specify the number of threads in the thread pool and assign the worker task to a thread pool manually or use the Configuration Utility.
Manually
1.
Navigate to the installation directory for the TotalAgility server.
2.
In a text editor, open Agility.Server.Core.WorkerService.exe.config
from the following directory:
\\TotalAgilityInstall\Agility.Server.Web
3.
Locate the following section:
<configSections>
<section name="CoreWorker" type="Agility.Server.Core.Worker.Configuration,
Agility.Server.Core.Worker"/>
</configSections>
4.
Add one or more job thread pools within the CoreWorker section and add worker tasks, as required.
The following is a sample from the configuration file.
Example
<CoreWorker>
<JobThreadPools>
<add Id ="1" Size ="16" WorkerTasks ="ArchiveJobTask, DeleteItemTask,
CreateExceptionTask, CreateJobTask, EvaluateJobTask,
ProcessStateActionTask, IngestSystemTask, CaptureBatchTask "/>
</JobThreadPools>
</CoreWorker>
118
Kofax TotalAgility Installation Guide
Note You must assign the following worker tasks to some thread pool, otherwise, an error message is displayed and the Core Worker Service stops working. You cannot assign the same worker task to more than one thread pool.
• ArchiveJobTask
• EvaluateJob Task
• CreateException Task
• CreateJob Task
• IngestSystem Task
• CaptureBatch Task
• DeleteItem Task
• ProcessStateAction Task
5.
Save and close the configuration file.
6.
Restart the TotalAgility Core Worker service.
Use the Configuration Utility
Run the Configuration utility and add or update the custom job thread pools, specify the number of threads in the thread pool and assign the worker task to a thread pool.
Add a thread pool monitoring interval
When long running automatic activities are processed by the Core Worker, the threads in the automatic activity thread pool are not freed up when the taken activity is reset due to timeout. Configure a thread pool monitoring interval to free up the threads for these long running taken activities to allow other activities to progress once they timeout.
You can configure the thread pool monitoring interval manually or use the Configuration Utility.
Manually
1.
Navigate to the installation directory for the TotalAgility server.
2.
In a text editor, open Agility.Server.Core.WorkerService.exe.config
from the following directory:
\\TotalAgilityInstall\Agility.Server.Web
3.
Locate the following section and add a thread pool monitoring interval (default:60).
<appSettings>
<add key="CoreWorkerThreadPoolMonitoringIntervalInSeconds" value="60"/>
</appSettings>
The default value is 60.
4.
Save and close the configuration file.
5.
Restart the TotalAgility Core Worker service.
119
Kofax TotalAgility Installation Guide
Use the Configuration Utility
Run the Configuration utility and add the thread pool monitoring interval. See the TotalAgility Configuration utility Guide .
Add performance monitoring counters
Use the performance counters to record application states and activities.
The following categories for TotalAgility performance monitoring counters are automatically installed on the target machine when the Core Worker Service and the Export Service are installed:
• TotalAgility Core Worker: Locked Activities
• TotalAgility Core Worker: System Tasks
• TotalAgility Core Worker: Threads
• TotalAgility Core Worker: Worker Tasks
• TotalAgility Export Service
• TotalAgility Child Export Processes
Each category is associated with the performance counters. When the performance monitor is launched, you can select the installed counters and add to the current monitoring session. Each instance is recorded for a performance counter. For example, the Active Threads Per Thread pool performance counter records an instance per thread pool as shown in the image below.
120
Kofax TotalAgility Installation Guide
You can log each performance counter to the TotalAgility log file by enabling the logging function. For more information on performance monitoring counters, see the Kofax TotalAgility Administrator's Guide .
Install the language pack
The languages files are available at the following location in the installation directory:
\\TotalAgilityInstall\Agility.Server.Web
121
Kofax TotalAgility Installation Guide
After installing TotalAgility, import <Language>.zip using the "Import Languages" feature of the TotalAgility menu.
When you change your browser to one of the supported languages, the corresponding translation is displayed.
Note Only the Workspace is localized according to the browser display language after installing the language pack.
Install the .NET Framework language packs
To localize the system error messages from .NET, you must install the .NET Framework language packs on both the Web and Application servers.
You can download the .NET Framework language pack from the Microsoft website.
Access TotalAgility documentation
You can access help online as well as in offline mode.
Online documentation
The product documentation for Kofax TotalAgility 7.9.0 is now available at the following location: https://docshield.kofax.com/Portal/Products/KTA/7.9.0-ud9cfx6hos/KTA.htm
To launch the online help for the installed version of the product, click the Help icon on the application.
Note
• On upgrading to TotalAgility 7.9.0 from an earlier version, to view the TotalAgility Workspace help, you must import the WorkspaceHeader form from the TotalAgility Workspace package.
• When upgrading to TotalAgility 7.9.0 from an earlier version, ensure that the check box for "Import system Workspace package" is selected to view the Workspace help online; otherwise, you must import the WorkspaceHeader form from the TotalAgility Workspace package.
Offline documentation
To access the documentation offline, you can download it from the Kofax Fulfillment Site . For each language, a separate documentation package is available to download as a compressed file, such as
Kofax TotalAgilityDocumentation7.9.0_EN.zip for English or Kofax TotalAgilityDocumentation7.9.0_FR.zip
for French.
The English .zip file includes both help and print folders. The print folder contains all guides, such as installation guide and administrator's guide. The .zip files for other languages contain only the localized files as applicable.
The following procedure describes accessing TotalAgility documentation offline for English.
1.
From the Kofax Fulfillment Site, download the documentation.zip file for the applicable language.
122
Kofax TotalAgility Installation Guide
2.
Extract the contents of the compressed documentation file to your local machine.
3.
On the TotalAgility installation media, inside the Agility.Server.Web\Help folder, create a folder for the desired language. For example, for accessing TotalAgility documentation offline for English, create EN folder as follows:
Note In a distributed environment, perform copying files on the Web server, and the Web.config
changes on the Application and Web servers.
• Copy the contents from Designer folder to:
\\TotalAgilityInstall\Agility.Server.Web\Help\TotalAgility_designer\EN
Note TotalAgility installer creates the TotalAgility_designer and API folders inside the Help folder.
You must manually create other folders such as Workspace and TotalAgilityApps and then copy the contents into the respective folders.
• Copy the contents from Workspace folder to:
\\TotalAgilityInstall\Agility.Server.Web\Help\Workspace\EN
• Copy the contents from WebCaptureControl folder to:
\\TotalAgilityInstall\Agility.Server.Web\Help\WebCaptureControl\EN
• Copy the contents from TransformationDesigner folder to:
<%ProgramData%>\Kofax\Transformation\help\en_US\help
\TransformationDesigner
• Copy the contents from TenantManagementSystem folder to:
\\TotalAgilityInstall\Agility.Server.Web.TenantManagement
\TenantManagement\Help\TenantManagementSystem\EN
• Copy the contents from TotalAgilityApps folder to:
\\TotalAgilityInstall\Agility.Server.Web\Help\TotalAgilityApps\EN
• Copy the contents from ExportConnector folder to:
\\TotalAgilityInstall\Agility.Server.Web\Help\ExportConnector_help\EN
• Copy the contents from the activity (such as DocumentReviewActivity) folder within CaptureClient folder to:
\\TotalAgilityInstall\Agility.Server.Web\Forms\Controls\Capture\Help
\DocumentReviewActivity\EN
• Copy the contents from Devices to:
\\TotalAgilityInstall\Agility.Server.Web\bin\Administrative\Help\Devices
\EN
• Copy the contents from RepositoryBrowser folder to:
\\TotalAgilityInstall\Agility.Server.Web\Help\RepositoryBrowser\EN
• Copy the contents from the SDK_Documentation folder to:
\\TotalAgilityInstall\Agility.Server.Web\Help\API\EN
• Copy the contents from DocumentConverter folder to:
\\Kofax\Document Converter\web\en\WebHelp
• Copy the contents from MessageConnector folder to:
\\Kofax\KIC-ED\MC\web\en\WebHelp
123
Kofax TotalAgility Installation Guide
4.
Navigate to the installation folder and do the following:
• For TotalAgility help and Devices help: a.
Open TotalAgility Web.config in a text editor from the following location:
\\TotalAgilityInstall\Agility.Server.Web
b.
Locate the <appSettings> section and remove http://docshield.kofax.com/
KTA from the key value: <add key="OnlineHelpURL" value="http:// docshield.kofax.com/KTA"/> .
Alternatively, run the Configuration Utility (available from the Installation media at \
\TotalAgilityInstall\Utilities\ConfigurationUtility ) and remove the URL for online help from the OnlinehelpURL setting.
• For Kofax Export Connector help: a.
Open Agility.Server.ExportConnector.exe.config in a text editor from the following location:
\\TotalAgilityInstall\Agility.Server.Web\bin b.
Locate the <appSettings> section and remove http://docshield.kofax.com/
KTA from the key value: <add key="OnlineHelpURL" value="http:// docshield.kofax.com/KTA"/> .
• For Message Connector help: a.
Open configuration.xml in a text editor from the following location:
\\Kofax\KIC-ED\MC\web b.
Locate the <OnlineHelp>1</OnlineHelp> section and replace 1 with 0.
• For Document Converter help: a.
Open configuration.xml in a text editor from the following location:
\\Kofax\Document Converter\web b.
Locate the <OnlineHelp>1</OnlineHelp> section and replace 1 with 0.
5.
Save and close the configuration file.
Clicking the Help icon will launch the help for the installed product.
Run EVRSCheck utility
The EvrsCheck utility helps in testing how an image will look once the eVRS setting is applied to it. The left half of the application window displays the original image and the right half displays the processed image once the setting is applied to it.
1.
Run the EvrsCheck.exe
available at the following location in the TotalAgility Installation folder:
\\TotalAgilityInstall\Utilities\EvrsCheck
The Before and After window opens.
2.
Click Choose and select an image.
The selected image with its metadata appears in the left half of the window. If the selected image is a multi-page image, you can use the "<" and ">" buttons to navigate between pages.
124
Kofax TotalAgility Installation Guide
3.
Copy the desired eVRS setting and paste it into the EVRS Settings box.
The image is processed based on the eVRS settings. The output along with its metadata is displayed in the right half of the window.
Note You can edit the eVRS setting; the image starts reprocessing as you type.
125
Chapter 3
Transformation Server Bundle installation
The Transformation Server Bundle includes:
• Transformation Server
• Transformation Core modules
To install any component, you must install the entire Transformation Server Bundle.
You can install the Transformation Server Bundle when you install TotalAgility, or install the Transformation
Server Bundle separately.
Note
• Before installing the Transformation Server Bundle, it may be necessary to install the USERTrust
Certificate and the DigiCert Assured ID Root CA Certificate in your environment. The installation may fail if these certificates are missing.
• For development environments, install the Transformation Server Bundle where you installed
TotalAgility. For production environments, install the Transformation Server Bundle on a separate computer.
• If you install the Transformation Server or Transformation Designer independent of TotalAgility, make sure the supported version of .NET Framework is already installed on that machine.
• The user who will run the Transformation Server must have "Log on as Service" rights. Also, the user who is running Transformation Server will be used for all communication channels where Windows authentication is used. For example, if Windows authentication is being used for SQL Server, this user must have rights on this server, otherwise Transformation Server does not work.
• After installing the Transformation Server, you can modify the configuration settings by editing the Transformation Server configuration file or by running the configuration utility. See the Kofax
TotalAgility Configuration Utility Guide .
Perform a silent installation
This section describes installing the Transformation Server Bundle silently, independent of TotalAgility.
1.
On the TotalAgility installation media, navigate to \\Transformation Server.
2.
On the Command prompt window, run the following command:
TransformationServerSetup.exe /quiet /log %LogFile% TS_INSTALLLOCATION=
%InstallLocation% TS_SERVICE_ACCOUNT=%WindowsServiceAccount%
TS_SERVICE_PASSWORD=%WindowsServicePassword% TS_USE_SPECIFIC_POOL=
%UseSpecificPool% TS_POOL_NAME=%PoolName% TS_OL_ENABLED=%OLEnabled
% TS_WCF_PORT=%WcfPort% TS_RESERVED_SLOTS=%ReservedSlots%
126
Kofax TotalAgility Installation Guide
TS_OVERRIDE_DEF_SLOTS=%OverrideDefSlots% TS_MAX_SLOTS=%MaxSlots%
TS_ENABLE_SYNC_CALLS=%EnableSyncCalls% TS_SYNCHRONOUS_ONLY=FALSE
TS_STARTSERVICE=TRUE TS_MAIN_DB_CONNECTION_STRING=
%MainDBConnectionString% TS_AUDIT_DB_CONNECTION_STRING=
%AuditDBConnectionString% TS_REPORTING_STAGING_DB_CONNECTION_STRING=
%ReportingStagingDBConnectionString% TS_ARCHIVE_DB_CONNECTION_STRING=
%ArchiveDBConnectionString%
Tip Optionally, call TS_SETUP_CONFIG_FILE int eh installation command. This property requires an absolute path to a configuration file for the installer. The configuration file can have one parameter per line only. Using such a configuration file will prevent the setup.exe from logging sensitive data.
TS_SETUP_CONFIG_FILE example:
TS_INSTALLLOCATION= "<Installation path>\Kofax\TotalAgility\Transformation Server
\"
TS_SERVICE_ACCOUNT=**account name**
TS_SERVICE_PASSWORD=**Password**
TS_SERVER_SERVICE_URL= https://**Name/IP**/TotalAgility/Services/Core/
ServerService.svc
TS_USE_SPECIFIC_POOL=FALSE
TS_POOL_NAME=
TS_OL_ENABLED=TRUE
TS_WCF_PORT=9001
TS_RESERVED_SLOTS=0
TS_OVERRIDE_DEF_SLOTS=
TS_MAX_SLOTS=0
TS_ENABLE_SYNC_CALLS=TRUE
TS_MAIN_DB_CONNECTION_STRING=Server=**Name/
IP**;Trusted_Connection=Yes;Database=**DB Name**;
TS_AUDIT_DB_CONNECTION_STRING=Server=localhost;Trusted_Connection=Yes;
Database=TotalAgility;
TS_ARCHIVE_DB_CONNECTION_STRING=Server=localhost;Trusted_Connection=Yes;
Database=TotalAgility;
TS_REPORTING_STAGING_DB_CONNECTION_STRING=Server=localhost;
Trusted_Connection=Yes;Database=TotalAgility_Reporting_Staging;
TS_STARTSERVICE=TRUE
TS_SYNCHRONOUS_ONLY=false
The parameter names are case-sensitive. If the value of a parameter has spaces, enclose the value in quotation marks.
3.
To ensure that the installation works as expected, perform the following steps: a.
Navigate to <Program Files>/Kofax/ TotalAgility/Agility.Server.Web
and open the Web.config in a text editor.
b.
Locate the TransformationServerExternalService_Binding binding parameter and ensure that the <transport ClientCredentialType> value is set to Windows.
c.
Save and close the web configuration file.
127
Kofax TotalAgility Installation Guide
Perform a standard installation
1.
Ensure that the user who will run the Transformation Server has Log on as Service rights.
2.
Access the Transformation Server Bundle installer from one of the following methods:
• Production systems : Install the Transformation Server Bundle separately from TotalAgility.
Navigate to \\Transformation Server\Transformation Server on the installation media and run one of the following commands:
• To install without creating a log file, run TransformationServerSetup.exe
.
• To install and create a log file, run setup.exe/log <path\install_log.txt> where <path
\install_log.txt> is the path and name of the log file.
• Development systems : If you are installing the Transformation Server Bundle as part of the
TotalAgility installation, the Transformation Server Bundle installer opens automatically.
3.
Click Install .
The system installs any necessary prerequisites.
4.
Click Next .
The Kofax Transformation Server Setup window opens.
5.
Click Next .
6.
In the license agreement window, accept the terms in the License Agreement.
This window is not displayed if the Transformation Server is installed automatically as part of
TotalAgility installation.
7.
Click Next .
The system prompts you for a destination folder for the Transformation Server.
8.
Enter the destination and click Next .
9.
In the Service Account Setup window, enter the credentials for the user who will run the
Transformation Server. These credentials are also used to encrypt sensitive data.
a.
In the Username field, enter the user name. To specify a domain user, enter the user name in the format Domain\User.
b.
Enter and confirm the Password .
c.
Click Next .
The Setting up connection data window opens.
10.
Enter the connection string for the Main, Archive, Audit and Reporting_Staging databases to connect to and authenticate with the databases.
Use the following syntax:
Server=<server address>;Database=TotalAgility;User ID=<user_name>;
Password=<password>;
If installing on split web/app, use the following syntax:
Server=<server name>; Trusted_Connection=yes; Database=<database name>;
Specify the address of the database server and the user name and password to authenticate with database where indicated. Example:
Server=dbserver\dbinstance;Database=TotalAgility;User
ID=dbo_id;Password=dbopassword;
128
Kofax TotalAgility Installation Guide
11.
Click Next .
12.
Specify the connection options to TotalAgility server: a.
To enable the Transformation Server to process online learning tasks, select Enable Online
Learning processing by this Transformation Server instance .
b.
Optionally, select Process activities from specific Transformation Server pool and enter a
Pool name .
Note To select the default pool, select Default Transformation Server Thread Pool .
13.
Click Next .
The Advanced execution options window opens. These options control the slots reserved for incoming high-priority activities.
14.
Select the advanced execution options:
• Enable support for Quick Capture : Select this option to provide the back end service necessary to support the Quick Capture Solution service.
• Enable synchronous calls processing : Select this option to configure the TCP/IP port and the number of reserved processing slots. The default TCP/IP port is 9001, and the number of reserved processing slots is 0.
Note If you are upgrading from version 7.0.0, "Enable synchronous calls processing" is not enabled if the number of reserved processing slots is zero and it is enabled if there are one or more reserved processing slots.
• Override default* number of processing slots : Select this option to specify number of slots other than the default.
15.
Click Next .
The Kofax Transformation Server is now ready to install.
16.
Click Install to install the Transformation Server.
The system displays the installation status and a message when Transformation Server setup is complete.
17.
Click Finish to continue.
The system displays the Transformation Server Bundle setup status and a message when the
Transformation Server Bundle setup is successful.
18.
Click Close to close the success message window.
19.
To ensure that the installation works as expected, perform the following steps: a.
Navigate to <Program Files>/Kofax/ TotalAgility/Agility.Server.Web
and open the Web.config in a text editor.
b.
Locate the TransformationServerExternalService_Binding binding parameter and ensure that the <transport ClientCredentialType> value is set to Windows.
c.
Save and close the web configuration file.
20.
From the Service console, start the Kofax Transformation Server service.
21.
If applicable, restart the anti-virus or firewall applications.
129
Kofax TotalAgility Installation Guide
Encrypt and decrypt the configuration file
The configuration file includes the Transformation Server settings, including sensitive information.
Therefore, we recommend that you encrypt this file. The Transformation Server supports two encryption methods depending on command line parameters:
• DPAPI encryption : Because you must decrypt the file on the same machine where it was encrypted, use this utility to encrypt one server at a time. See
Use Kofax.CEBPM.EncryptConfig.exe
.
• RSA encryption : An algorithm for public key encryption and digital signatures that uses two separate keys. Create a key and encrypt the configuration file on one Transformation Server, and export the key to all the other Transformation Servers. All the Transformation Servers with the exported key installed can access the configuration file. Use this method if you have several Transformation Servers with the same configuration (TAService ID, pool name, and so on). See
.
To decrypt the configuration file, see Decrypt the configuration file
.
Use Kofax.CEBPM.EncryptConfig.exe
The Kofax.CEBPM.EncryptConfig.exe utility encrypts (-enc) or decrypts (-dec) the CPUServer and appSettings sections of the configuration file. The CPUServer section includes the TotalAgility Session ID.
The AppSettings section includes the user ID and password as well as other information. Use the optional
-h flag to display help for the command.
Encrypt a File with Kofax.CEBPM.EncryptConfig.exe
Run the utility on each Transformation Server individually.
1.
Stop the Transformation Server service.
2.
Navigate to the Transformation Server installation directory and open a command Prompt window.
3.
Run the following command:
Kofax.CEBPM.EncryptConfig.exe -f Kofax.CEBPM.CPUServer.ServiceHost.exe.config -s
"appSettings" -p DPAPIProtection -enc
Use RSA encryption
Use RSA encryption to encrypt the configuration file, export the encryption key, and install the encryption key file on multiple Transformation Servers. Use this method if you have several Transformation Servers with the same configuration (TAService ID, pool name, and so on).
The following instructions differentiate between the source Transformation Server where you create the key and the target Transformation Servers onto which you import the key.
130
Kofax TotalAgility Installation Guide
Prepare the key
Perform these steps on one source Transformation Server.
1.
Create the custom RSA key container: a.
Log on to the Transformation Server with administrator rights.
b.
Open a Command Prompt window.
c.
Navigate to the .NET Framework version 4.5 directory. For example, enter the following command: cd \WINDOWS\Microsoft.Net\Framework\v4.5.* d.
Run the following command: aspnet_regiis -pc "<KeysFile>" -exp where:
• <KeysFile> is the name of the key file.
• The -exp option makes the key exportable.
2.
Run the following command to grant the Transformation Server service user permission to read the
<KeysFile> RSA container file.
aspnet_regiis -pa "<KeysFile>" "<TSserviceuser>" where:
• <KeysFile> is the name of the key file you created in Step 1d.
• <TSserviceuser> is the Transformation Server service user.
3.
Encrypt the file: a.
Log on to the Transformation Server as the Transformation Server service user.
b.
Navigate to the installation directory for the Transformation Server and open a Command
Prompt window.
c.
Run the following command:
Kofax.CEBPM.EncryptConfig.exe -f
Kofax.CEBPM.CPUServer.ServiceHost.exe.config -s "appSettings" -p
RSAProvider -enc
This command encrypts the CPUServer and AppSettings sections of the configuration file. The
CPUServer section includes the TotalAgility Session ID. The AppSettings section includes the user ID, password and other information.
4.
Export the key by running the following command: aspnet_regiis -px "<KeysFile>" "<c:\keys.xml>" -pri where:
• <KeysFile> is the default keystore keyContainerName.
• <c:\keys.xml> is the path and file name of the exported key file.
131
Kofax TotalAgility Installation Guide
Import the key
Perform these steps on every target Transformation Server.
1.
Import the key: a.
Log on to the Transformation Server with administrator rights.
b.
Copy the keys.xml file from the source Transformation Server to the root directory of the target
Transformation Server.
c.
Open a Command Prompt window.
d.
Run the following command: aspnet_regiis -pi "<KeysFile>" "c:\keys.xml" where:
• <KeysFile> is the default name of the key file.
• <c:\keys.xml> is the path and file name to the imported key file.
e.
Delete the keys.xml because it contains the unprotected private key.
2.
Run the following command to grant the Transformation Server service user permissions to use the
<KeysFile> RSA container file: aspnet_regiis -pa "<KeysFile>" "TSserviceuser" where:
• <KeysFile> is the name of the key file you imported in step 1.
• <TSserviceuser> is the Transformation Server service user.
3.
Repeat these steps on all remaining Transformation Servers.
Decrypt the configuration file
1.
Stop the Transformation Server service.
2.
Navigate to the Transformation Server installation directory and open a command-line window.
3.
Run the following command:
Kofax.CEBPM.EncryptConfig.exe -f
Kofax.CEBPM.CPUServer.ServiceHost.exe.config -s "appSettings" -p
DPAPIProtection -de c
Edit the configuration file
Modify the Transformation Server configuration file, Kofax.CEBPM.CPUServer.ServiceHost.exe.config
if the system configuration has changed, or when you need to resolve a technical or performance issue.
1.
If you encrypted the configuration file after you installed the Transformation Server, decrypt the file.
See Decrypt the configuration file
.
Note If RSA encryption is used, decrypt the configuration file only on the source Transformation
Server where you initially encrypted the file.
132
Kofax TotalAgility Installation Guide
2.
Navigate to the installation directory for the Transformation Server and locate
Kofax.CEBPM.CPUServer.ServiceHost.exe.config
.
3.
Back up the file and save it in a secure location.
4.
Open the configuration file in a text editor.
5.
To change the system configuration options, modify the keys in the <appSettings> section.
The section contains a list of keys for setting configuration options. The ones that can be modified have comments that describe the setting and supported values, as in this example.
<!-- Maximum number of instances allowed for Executor Process -->
<add key="MaxNumberOfTenantProcesses" value="1"/>
6.
Change the value within the quotation marks to a supported value, as indicated in the comments.
7.
To change how errors are reported in the application event log, which can be viewed in the Event
Viewer, modify the <system.diagnostics> section as follows: a.
Under <switches> , locate the following element:
<add name="TraceLevelSwitch" value="Warning"/>
By default, the value is set to Warning, which reports error and warning messages. Change the value to any of the options listed in the comment to change the type of messages reported.
b.
Under <sharedListeners>, locate the following line:
<add name="CPUServerLogTxt"
type="Kofax.CEBPM.CPUServer.Common.Diagnostics.DateTimeTaggedTraceListener,
Kofax.CEBPM.CPUServer.Common" initializeData="KofaxCPUServerLog.log" >
To specify a different log file or change the format for timestamps , change the value of initializeData as shown in the comments in the file.
8.
Save and close the configuration file.
9.
To re-encrypt the configuration file, run the encryption utility. See
Encrypt and Decrypt the configuration file
.
Note If you used RSA encryption, export the key, and install the encryption key file on any target
Transformation Servers imported the original encrypted configuration file.
10.
Restart the Kofax Transformation Server service.
Install the NLP language packs manually
If the Transformation Designer is installed on a separate server than the Transformation Server Bundle in your solution, then you need to install the Kofax NLP engine language packs on the machine where
Transformation Designer is installed. This is because the Kofax NLP engine language packs are installed by the Transformation Server Bundle only, and these languages are required to use the Kofax NLP functionality in Transformation Designer and in production.
To install the Kofax NLP engine language packs, you need access to the original Kofax TotalAgility installation zip file.
133
Kofax TotalAgility Installation Guide
You can install the Kofax NLP engine language packs by following these steps.
1.
Navigate to the TotalAgility\TransformationServer
\KofaxTransformation_Salience6.4
path inside the extracted Kofax TotalAgility installation zip file.
2.
Double-click on one of the following .MSP
files depending on what languages you are supporting.
• KofaxTransformation_SalienceV6.4.0_LanguageBundle_western-default .
Run to install English, Spanish, Portuguese, French, and German support.
• KofaxTransformation_SalienceV6.4.0_LanguageBundle_western-extended .
Run to install Italian, Romanian, and Dutch support.
• KofaxTransformation_SalienceV6.4.0_LanguageBundle_extended
.
Run this to install Japanese, Chinese, and Korean support.
A Windows Installer window appears and then installs the selected Kofax NLP languages automatically.
The installer window closes when the installation is complete.
3.
Optionally, double-click on another language installer if you want to support additional languages.
Upgrade Transformation Server using silent installation
To upgrade the Transformation Server in silent mode, use the following command, replacing the example content with your own environment.
setup.exe /quiet /Upgrade /log installation.log TS_SERVER_SERVICE_URL=http:// <Server> /
TotalAgility/Services/Core/ServerService.svc TS_INSTALLLOCATION=" <Program Files> \Kofax
\TotalAgility\Transformation Server"
TS_MAIN_DB_CONNECTION_STRING="Server=servername;Database=databasename;User
Id=sa;Password=password" TS_SERVICE_ACCOUNT=serviceAccountName
TS_SERVICE_PASSWORD=password TS_STARTSERVICE=TRUE
Uninstall the Transformation Server
Uninstall Transformation Server depending on how you have installed it.
• When you install Transformation Server as part of Kofax TotalAgility standard installation, uninstalling
TotalAgility will automatically uninstall Transformation Server.
• When you install Transformation Server on a separate system, uninstall the Transformation Server
Bundle from the Control Panel.
• To uninstall in a silent mode, do the following:
• Navigate to the root directory of TransformationServerSetup.exe.
• Run TransformationServerSetup.exe / uninstall / quiet .
The system uninstalls the Transformation Server and automatically creates a log file in the temporary files folder. This log file contains information on errors, if any.
134
Chapter 4
Reporting Server installation
This chapter describes two methods for installing the Kofax Reporting Server:
• Silent installation of Reporting Server independent of TotalAgility
• Standard installation using the installation wizard.
For development environments, install the Reporting Server where you installed TotalAgility. Otherwise, install the Reporting Server on a separate system in the same domain where you installed TotalAgility.
Note If you choose to install the Reporting Server on a separate system in the same domain where you installed TotalAgility, then you must assign the following roles to service account:
• For the Staging database: kfx_staging
• For the data warehouse: kfx_etl, kfx_reader, kfx_advanced_reader
Perform a silent installation
The section describes the silent installation of the Reporting Server, independent of TotalAgility.
See the following table for the silent installation parameters required to install the Reporting Server.
Note Parameter names are case-sensitive.
Parameter
INSTALLLOCATION
WINSERV_ACCOUNT
Default Value
C:\Program Files\Kofax
\TotalAgility\
Reporting Server\ no default
Description
Specify the Reporting Server destination directory.
WINSERV_PASSWORD no default
Enter the name of the user who will run the
Reporting Server. To specify a domain user, enter the user name in the format Domain\User.
Ensure that the account details are correct, as under this account Reporting Server authenticates in all places where Windows authentication is used.
Example, TotalAgility database.
All communication and resource access is run under this account. Therefore, the account under which Reporting Server is running must not be a dummy account.
Enter the Password for the user.
135
Kofax TotalAgility Installation Guide
Parameter
MAIN_DB_CONNECTION
_STRING
AUDIT_DB_CONNECTION_
STRING
REPORTING_STAGING_
DB_CONNECTION_STRING
REPORTING_WORKHOUSE_
DB_CONNECTION_STRING
Default Value no default no default no default no default
Description
Enter the connection string for the Main database.
Example:
"Server=<hostname>;Trusted_Connection=Yes;"
"Database=TotalAgility;"
Enter the connection string for the Audit database.
Enter the connection string for the Reporting
Staging database.
Enter the connection string for the Reporting
Workhouse database.
1.
On the TotalAgility installation media, navigate to \\TotalAgilityInstall\Reporting\
TAReportingService .
2.
Run the following command: msiexec.exe /i Kofax.Reporting.TAService.msi /q WINSERV_ACCOUNT=
%WindowsServiceAccount% WINSERV_PASSWORD=%WindowsServicePassword
% MAIN_DB_CONNECTION_STRING="%MainDBConnectionString%"
INSTALLLOCATION="%InstallLocation%"
AUDIT_DB_CONNECTION_STRING="%AuditDBConnectionString
%" REPORTING_STAGING_DB_CONNECTION_STRING=
"%ReportingStagingDBConnectionString%"
REPORTING_WAREHOUSE_DB_CONNECTION_STRING="%ReportingConnection%"
Perform a standard installation
1.
On the TotalAgility installation media, navigate to TotalAgility > Reporting >
TAReportingService > Kofax.Reporting.TAService.msi
.
The TotalAgility Reporting Server Setup window opens.
2.
Click Next .
3.
In the End-User License Agreement window, accept the terms in the License Agreement and click
Next .
4.
In the Destination Folder window, select the default folder ( C:\Program Files (x86)\Kofax
\TotalAgility\Reporting Server\ ) for the Reporting server or click Change to choose another folder.
5.
Click Next .
6.
In the Service Account Setup window, enter the credentials for the user who will run the Kofax
TotalAgility Reporting Server service: a.
In the Username field, enter the username.
Note To specify a domain user, enter the username in the format Domain\User.
b.
Enter and confirm the Password .
c.
Click Next .
136
Kofax TotalAgility Installation Guide
7.
In the Obtaining TotalAgility Configuration window: a.
Specify TotalAgility Server service URL in the following format: http://<server_name>/
TotalAgility/Services/Core/ServerService.svc
Here <server_name> is the TotalAgility server name.
Note To install Web Service over SSL, use ‘https://’ instead of ‘http://’ in the URL.
b.
In the Main DB connection string box, enter the connection string for the TotalAgility database.
c.
Click Next .
The system downloads the configuration settings.
8.
Click Install to begin the installation.
9.
Click Finish .
Uninstall the Reporting Server
Uninstall the Reporting Server depending on how you have installed it.
• When you install the Reporting Server as part of Kofax TotalAgility standard installation, uninstalling
TotalAgility will automatically uninstall the Reporting Server.
• When you install the Reporting Server on a separate system using the Wizard, uninstall the Reporting
Server from the Control Panel.
• If you install the Reporting Server in a silent mode, you must do the following to uninstall the Reporting
Server in a silent mode:
1.
On the Command Prompt, change the command line to the root directory of the
Kofax.Reporting.TAService.msi
file.
2.
Run msiexec.exe/quiet/x Kofax.Reporting.TAService.msi/L*V"%LogFileName%" .
The system uninstalls the Reporting Server and automatically creates a log file in the temporary files folder. This log file contains information on errors, if any. You can use "msiexec/help"
(Windows installer help) to check options for the installation and logging.
137
Chapter 5
Integrate Microsoft SharePoint with TotalAgility
Set up the SharePoint server and the TotalAgility server for using SharePoint in TotalAgility .
Note The SharePoint integration components should not be installed on the same machine where
TotalAgility is installed.
1.
Navigate to \\SharePointInstallation on the installation media, and double click Setup.exe
.
The system opens the TotalAgility for SharePoint Setup wizard.
2.
Click Next .
The system displays the TotalAgility SharePoint Components window.
3.
Select the TotalAgility SharePoint components to install.
a.
To install the SharePoint web parts, select the TotalAgility SharePoint WebParts check box.
b.
To install the SharePoint web service and event-handler dlls, select the TotalAgility
SharePoint Event-Handling Components check box.
c.
On the list of Website to host TotalAgility SharePoint components , select a website.
Note You must not select the SharePoint related websites.
4.
Click Install .
5.
Update Web.config
to get support event handlers and configure SharePoint site. See Update the
.
Further configure:
•
TotalAgility Web parts in the SharePoint server
•
Microsoft SharePoint Server and TotalAgility to provide fault tolerance
Configure the Application Pool for the SharePoint communicator site
1.
Ensure that SharepointAppPool user should be either Primary or Secondary site collection administrator.
2.
Ensure that this user also resides in TotalAgility.
Note You can get this information from the appropriate SharePoint site.
3.
Configure the same application pool in the SharePoint communicator site.
138
Kofax TotalAgility Installation Guide
Update the Web configuration file
Update Web.config for the TotalAgility components.
To load the assembly from GAC
If you select to add assembly from GAC during installation, then edit the Sharepoint Web.config file with the following:
<system.web>
<compilation>
<assemblies>
<add assembly="Agility.Server.Integration.Sharepoint,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=d86c87abe4a71948" />
</assemblies>
<compilation>
</system.web>
To support event handlers
Note If you copy and paste the code from this guide, correct any incorrect line breaks.
<configSections>
<section name="exceptionHandling" type="Microsoft.Practices.EnterpriseLibrary.
ExceptionHandling.Configuration.ExceptionHandlingSettings,
Microsoft.Practices.EnterpriseLibrary.ExceptionHandling,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" requirePermission="true" />
<section name="loggingConfiguration" type="Microsoft.Practices.EnterpriseLibrary.
Logging.Configuration.LoggingSettings,
Microsoft.Practices.EnterpriseLibrary.Logging,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" requirePermission="true" />
</configSections>
<loggingConfiguration name="" tracingEnabled="true" defaultCategory="General">
<listeners>
<add name="Event Log Listener" type="Microsoft.Practices.EnterpriseLibrary.Logging.
TraceListeners.FormattedEventLogTraceListener,
Microsoft.Practices.EnterpriseLibrary.Logging,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" listenerDataType="Microsoft.Practices.EnterpriseLibrary.
Logging.Configuration.FormattedEventLogTraceListenerData,
Microsoft.Practices.EnterpriseLibrary.Logging,
139
Kofax TotalAgility Installation Guide
Version=5.0.505.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35" source="Total Agility" formatter="Text Formatter" log="" machineName="." traceOutputOptions="None" />
</listeners>
<formatters>
<add type="Microsoft.Practices.EnterpriseLibrary.Logging.
Formatters.TextFormatter,
Microsoft.Practices.EnterpriseLibrary.Logging,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" template="Timestamp: {timestamp}
{newline}
Message: {message}
{newline}
Category: {category}
{newline}
Priority: {priority}
{newline}
EventId: {eventid}
{newline}
Severity: {severity}
{newline}
Title:{title}
{newline}
Machine: {localMachine}
{newline}
App Domain: {localAppDomain}
{newline}
ProcessId: {localProcessId}
{newline}
Process Name: {localProcessName}
{newline}
Thread Name: {threadName}
{newline}
Win32 ThreadId:{win32ThreadId}
{newline}
Extended Properties:
{dictionary({key} - {value}{newline})}" name="Text Formatter" />
</formatters>
<categorySources>
<add switchValue="All" name="General">
<listeners>
<add name="Event Log Listener" />
</listeners>
</add>
</categorySources>
<specialSources>
<allEvents switchValue="All" name="All Events" />
<notProcessed switchValue="All" name="Unprocessed Category" />
<errors switchValue="All" name="Logging Errors & Warnings">
<listeners>
<add name="Event Log Listener" />
</listeners>
</errors>
</specialSources>
</loggingConfiguration>
<exceptionHandling>
<exceptionPolicies>
<add name="Agility Exception Policy">
<exceptionTypes>
<add name="All Exceptions" type="System.Exception, mscorlib,
Version=4.0.0.0,
Culture=neutral,
PublicKeyToken=b77a5c561934e089" postHandlingAction="NotifyRethrow">
<exceptionHandlers>
<add name="Logging Exception Handler" type="Microsoft.Practices.EnterpriseLibrary.
ExceptionHandling.Logging.LoggingExceptionHandler,
Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.Logging,
Version=5.0.505.0,
Culture=neutral,
140
Kofax TotalAgility Installation Guide
PublicKeyToken=31bf3856ad364e35" logCategory="General" eventId="100" severity="Error" title="Total Agility" formatterType="Microsoft.Practices.EnterpriseLibrary.
ExceptionHandling.TextExceptionFormatter,
Microsoft.Practices.EnterpriseLibrary.ExceptionHandling,
Version=5.0.505.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35" priority="0" />
</exceptionHandlers></add>
</exceptionTypes>
</add>
</exceptionPolicies>
</exceptionHandling>
Note SharePoint event handler executes in the context of the user who initiated the action.
For a SharePoint site
Note If you copy and paste the code from this guide, fix the line breaks.
• Update the <system.serviceModel> section:
<system.serviceModel>
<bindings>
<basicHttpBinding>
<binding name="BasicHttpBinding_Service" openTimeout="00:10:00" closeTimeout="00:10:00" sendTimeout="00:10:00" receiveTimeout="00:10:00" allowCookies="true" maxBufferSize="2147483647" maxReceivedMessageSize="2147483647" maxBufferPoolSize="524288">
<readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647" maxArrayLength="2147483647" maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
<security mode="TransportCredentialOnly">
<transport clientCredentialType="None" />
</security>
</binding>
</basicHttpBinding>
</bindings>
<client>
<endpoint name="CoreIntegrationEventServiceEndpoint" binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_Service" contract="Agility.Server.Core.Model.Interfaces.Services.IIntegrationEventService" address="http://[TotaAgility server name or IP Address]/TotalAgility/Services/Core/
IntegrationEventService.svc"/>
</client>
</system.serviceModel>
Replace <TotalAgility server name or IP Address> with the IP Address of TotalAgility.
Note Point the endpoint address to the integration service URL for TotalAgility.
141
Kofax TotalAgility Installation Guide
Configure the TotalAgility Integration with SharePoint using SSL
1.
On the TotalAgility server, perform the following: a.
Add the SharePoint site location and Kofax TotalAgility SharePoint communicator using HTTPS into the Kofax TotalAgility integration module (Home>Integration>SharePoint).
b.
On Kofax TotalAgility server, open the Web.config file, locate the
BasicHttpBinding_SharePointCommunicatorService and set the security mode="Transport"
2.
On SharePoint server, to enable SharePoint events using HTTPS, perform the following: a.
Apply certificate onto SharePoint Server for that particular Sharepoint site.
b.
For the SharePoint site, open the Web.config file, locate the BasicHttpBinding_Service and set the security mode="Transport".
Network authentication for SharePoint and TotalAgility
Configure the network authentication for SharePoint and TotalAgility when they are on the same domain or when they are on different domains.
TotalAgility and SharePoint are on the same domain
1.
Ensure that TotalAgility site has Windows Authentication in Internet Information Services (IIS) and the required SharePoint users are added to the TotalAgility server. Perform the following in the
TotalAgility server: a.
Open Internet Information Services (IIS) Manager .
b.
Click Sites > Default Web Site > TotalAgility.
c.
On the Features View tab, double-click Authentication .
d.
Right-click Windows Authentication and click Providers .
e.
Check if, Negotiate and NTLM are available as providers. If not, add them from the Available
Providers list.
2.
Ensure that TotalAgility SharePoint Communicator site has Windows authentication in the Internet
Information Services (IIS). Perform the following in the SharePoint server: a.
Open Internet Information Services (IIS) Manager .
b.
Click Sites > Default Web Site > TotalAgilitySharepointCommunicator .
c.
On the Features View tab, double-click Authentication .
d.
Right-click Windows Authentication and click Providers .
e.
Check if, Negotiate and NTLM are available as providers. If not, add them from the Available
Providers list.
f.
Ensure that Site App pool is changed to SharePoint site App pool.
142
Kofax TotalAgility Installation Guide
TotalAgility and SharePoint are on different domains
Ensure that TotalAgility and SharePoint domains are trusted. If domains are not trusted, Windows authentication does not work, so it must be disabled and Anonymous authentication must be enabled in
IIS. The web configuration files must also be updated. The steps to modify the web configuration files are given in the sub section.
Perform the following steps in the TotalAgility server and SharePoint server:
1.
Open Internet Information Services (IIS) Manager .
2.
Click Sites > Default Web Site > TotalAgility .
For SharePoint server, click Sites > Default Web Site ?> TotalAgilitySharePointCommunicator .
3.
On the Features View tab, double-click Authentication .
4.
Right-click Windows Authentication and click Disable .
5.
Right-click Anonymous Authentication and click Enable .
Update Web.config
Update the Web.config if TotalAgility and SharePoint are on different domains.
1.
In the Web.config
for TotalAgility, replace <transport clientCredentialType="Windows" /
> with <transport clientCredentialType="None" /> in the following bindings:
• BasicHttpBinding_SharepointCommunicatorService
• BasicHttpBinding_Service
• CustomBinding_CoreService
• WebHttpBinding_Service
2.
In the Web.config
for TotalAgilitySharePointCommunicator site on the SharePoint server, replace <transport clientCredentialType="Windows" /
> with <transport clientCredentialType="None" /> for
BasicHttpBinding_SharepointCommunicatorService binding.
3.
In the Web.config
for SharePoint site ( C:\inetpub\wwwroot\wss\VirtualDirectories
\<site port> ), replace <transport clientCredentialType="Windows" /
> with <transport clientCredentialType="None" /> for
BasicHttpBinding_SharepointCommunicatorService binding.
4.
Save the changes.
Configure the TotalAgility Web parts in the SharePoint server
Configure the SharePoint site that contains the TotalAgility web parts to communicate with TotalAgility using web services or enabling session.
Use the Web Services
1.
Open the Web.config
file.
143
Kofax TotalAgility Installation Guide
2.
Add the following keys:
• <add key="SPPServerName" value="<http or https>://<TA server name><:port>/<TASiteName>"/> . For example, <add key="SPPServerName" value="https://DL-WDEML-32:85/TotalAgility">
• <add key="SystemSessionId" value="<TA System Session Id>"/> . Get the value for the key from System Settings in the Kofax TotalAgility Designer.
Note
• If you do not add the "SPPServerName" key, a message informs you that the Web services communications layer for TotalAgility is not configured. In the key, do not mention the Port if running under port 80.
• If you do not add the "SystemSessionId" key, a message informs you that the System Session Id key is not found.
Enable session
1.
Navigate to the C:\Inetpub\wwwroot\VirtualDirectories\<Port> directory.
Note Get the <Port> from the address bar in Internet Explorer.
2.
Open Web.config and do the following: a.
Uncomment the line, “<add name=”Session”> .
Note If add name ="Session" is not available, add the following code: <add name="Session" type="System.Web.SessionState.SessionStateModule, System.Web, Version=4.0.0.0,
Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" /> b.
Search for the “<pages enableSessionState” tag and change the value of
“enableSessionState” from “false” to “true” .
3.
Save the changes.
Set up the Microsoft SharePoint and TotalAgility servers to provide fault tolerance
Set up the TotalAgility server
1.
Prior to setting up the TotalAgility Server, install the MSMQ support.
a.
Open Server Manager on the SharePoint Server.
b.
Select to add the Message Queuing feature.
c.
Select the Message Queuing Server, Directory Service Integration and HTTP Support.
144
Kofax TotalAgility Installation Guide
2.
Create a physical MSMQ queue on the TotalAgility Server.
a.
Navigate to Computer Management\Message Queuing\Private Queues .
b.
Create a Transactional private queue, TotalAgility/Services/Core/
IntegrationEventService.svc
.
Note Select Transactional when creating the queue.
3.
Enter the following two commands to configure IIS 7 to enable WAS to listen to the message queue, and activate your service when new messages arrive: appcmd set site "Default Web Site" -+bindings.
[protocol='net.msmq',bindingInformation='localhost'] appcmd set app "Default Web Site/TotalAgility" / enabledProtocols:net.msmq,http
4.
Open Web.config located in the TotalAgility\Agility.Server.Web directory on the installation media. For example, C:\Program Files\Kofax\TotalAgility\Agility.Server.Web
.
5.
Add the following msmq binding in the <bindings> section:
<netMsmqBinding>
<binding name="MsmqBindingTransactionalNoSecurity" maxRetryCycles="3" receiveErrorHandling="Move" receiveRetryCount="3" retryCycleDelay="00:01:00">
<security mode="None"/>
</binding>
</netMsmqBinding>
6.
Open Web.config located in the Core directory in your install location (for example, C:\Program
Files\Kofax\TotalAgility\Agility.Server.Web\Services\Core ) and locate for the service tag:
<service
name="Agility.Server.Core.Services.IntegrationEventService"
behaviorConfiguration="Agility.Server.Web.Services.Behavior">
7.
Add the following endpoint below this service tag:
<endpoint address=
"net.msmq://localhost/private/TotalAgility/Services/Core/
IntegrationEventService.svc" binding="netMsmqBinding" bindingConfiguration="MsmqBindingTransactionalNoSecurity" contract=
"Agility.Server.Core.Model.Interfaces.Services.IIntegrationEventService" />
8.
Verify that the Microsoft Windows net.msmq Listener Adapter service is started.
Set up the Microsoft SharePoint server
1.
Open Web.config for a SharePoint site.
2.
Add the following tags under <bindings> section:
<netMsmqBinding>
<binding name="MsmqBindingTransactionalNoSecurity" maxRetryCycles="3" receiveErrorHandling="Move" receiveRetryCount="3" retryCycleDelay="00:30:00">
<security mode="None"/>
</binding>
</netMsmqBinding>
145
Kofax TotalAgility Installation Guide
3.
Add the following tags under <client> section:
<endpoint address=
"net.msmq://<TA_MACHINENAME>/private/TotalAgility/Services/Core/
IntegrationEventService.svc" behaviorConfiguration="MsmqBindingTransactionalTransportSecurity" binding="netMsmqBinding"
bindingConfiguration="MsmqBindingTransactionalNoSecurity" contract="Agility.Server.Core.Model.Interfaces.Services.IIntegrationEventService" name="Agility.Server.Core.Services.IntegrationEventService" />
4.
Remove or comment out the following tag under <appSettings> section:
<add key="SPP_EventHandler_WebServiceURL" value="" />
5.
Replace <TA_MACHINENAME> with the TotalAgility server name.
6.
Save the changes.
146
Chapter 6
Integrate Microsoft Dynamics CRM with
TotalAgility
You can integrate Microsoft Dynamics CRM and Microsoft Dynamics 365 CRM with TotalAgility . To install both, the users must have the administrator rights.
See also:
•
•
Update the Web configuration file for Dynamics CRM
Install Dynamics CRM
Follow the same steps to install Dynamics CRM and Dynamic 365 CRM.
1.
Navigate to \\DynamicsCRMInstall on the installation media, and double-click Setup.exe
.
For Dynamics 365 CRM, navigate to \\Dynamics365CRMInstallation on the installation media, and double-click Dynamics365CRM_Setup.exe
.
The installation wizard appears.
2.
Click Next .
3.
In the CRM Server field, enter the IP address or machine name of the CRM server.
4.
In the CRM Port field, enter the port on which CRM is running.
5.
To enable SSL (Secure Sockets Layer), select Use SSL (default: Clear).
6.
In the Domain field, enter the domain name.
7.
Enter the Username and Password .
8.
Click Finish .
The installation starts and registers Event Handler in CRM and places necessary files in Global
Assembly Cache (GAC).
Update Web.config for Dynamics CRM
Add the following script for the TotalAgility components to support event handlers in Dynamics CRM and
Dynamics 365 CRM:
Note If you copy and paste the code from this guide, correct any incorrect line breaks.
<configSections>
<section name="exceptionHandling"
147
Kofax TotalAgility Installation Guide type="Microsoft.Practices.EnterpriseLibrary.
ExceptionHandling.Configuration.ExceptionHandlingSettings,
Microsoft.Practices.EnterpriseLibrary.ExceptionHandling,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" requirePermission="true" />
<section name="loggingConfiguration" type="Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.LoggingSettings,
Microsoft.Practices.EnterpriseLibrary.Logging,
Version=5.0.505.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35" requirePermission="true" />
</configSections>
<loggingConfiguration name="" tracingEnabled="true" defaultCategory="General">
<listeners>
<add name="Event Log Listener" type="Microsoft.Practices.EnterpriseLibrary.Logging.TraceListeners.
FormattedEventLogTraceListener,
Microsoft.Practices.EnterpriseLibrary.Logging,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" listenerDataType="Microsoft.Practices.EnterpriseLibrary.Logging.
Configuration.FormattedEventLogTraceListenerData,
Microsoft.Practices.EnterpriseLibrary.Logging,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" source="Total Agility" formatter="Text Formatter" log="" machineName="." traceOutputOptions="None" />
</listeners>
<formatters>
<add type="Microsoft.Practices.EnterpriseLibrary.Logging.Formatters.TextFormatter,
Microsoft.Practices.EnterpriseLibrary.Logging,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" template="Timestamp: {timestamp}{newline}
Message: {message}
{newline}
Category: {category}{newline}
Priority:
{priority}{newline}
EventId: {eventid}
{newline}
Severity: {severity}{newline}
Title:
{title}{newline}
Machine: {localMachine}
{newline}
App Domain: {localAppDomain}
{newline}
ProcessId: {localProcessId}
{newline}
Process Name: {localProcessName}
{newline}
Thread Name: {threadName}
{newline}
Win32 ThreadId:{win32ThreadId}
{newline}
Extended Properties:
{dictionary({key} - {value}{newline})}" name="Text Formatter" />
</formatters>
<categorySources>
<add switchValue="All" name="General">
<listeners> <add name="Event Log Listener" />
</listeners>
</add>
</categorySources>
<specialSources>
<allEvents switchValue="All" name="All Events" />
<notProcessed switchValue="All" name="Unprocessed Category" />
<errors switchValue="All" name="Logging Errors & Warnings">
148
Kofax TotalAgility Installation Guide
<listeners> <add name="Event Log Listener" />
</listeners>
</errors>
</specialSources>
</loggingConfiguration>
<exceptionHandling>
<exceptionPolicies>
<add name="Agility Exception Policy">
<exceptionTypes>
<add name="All Exceptions" type="System.Exception, mscorlib,
Version=4.0.0.0,
Culture=neutral,
PublicKeyToken=b77a5c561934e089" postHandlingAction="NotifyRethrow">
<exceptionHandlers>
<add name="Logging Exception Handler" type="Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.
Logging.LoggingExceptionHandler,
Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.Logging,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" logCategory="General" eventId="100" severity="Error"
title="Total Agility" formatterType="Microsoft.Practices.EnterpriseLibrary.
ExceptionHandling.TextExceptionFormatter,
Microsoft.Practices.EnterpriseLibrary.ExceptionHandling,
Version=5.0.505.0,
Culture=neutral,
PublicKeyToken=31bf3856ad364e35" priority="0" />
</exceptionHandlers>
</add>
</exceptionTypes>
</add>
</exceptionPolicies>
</exceptionHandling>
Update Web.config for the CRM virtual directory
<system.serviceModel>
<bindings>
<basicHttpBinding>
<binding name="BasicHttpBinding_Service" openTimeout="00:10:00" closeTimeout="00:10:00"
sendTimeout="00:10:00" receiveTimeout="00:10:00" allowCookies="true" maxBufferSize="2147483647"
maxReceivedMessageSize="2147483647" maxBufferPoolSize="524288">
<readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647"
maxArrayLength="2147483647" maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
<security mode="TransportCredentialOnly">
<transport clientCredentialType="None" />
</security>
</binding>
</basicHttpBinding>
</bindings>
<client>
<endpoint name="CoreIntegrationEventServiceEndpoint" binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_Service"
149
Kofax TotalAgility Installation Guide
contract="Agility.Server.Core.Model.Interfaces.Services.IIntegrationEventService" address="http://<TotaAgility server name or IP Address>/TotalAgility/Services/Core/
IntegrationEventService.svc"/>
</client>
</system.serviceModel>
Note Replace <TotalAgility server name or IP Address> with the IP Address of TotalAgility.
150
Chapter 7
Integrate Microsoft Dynamics AX with
TotalAgility
To install Dynamics AX,
• Users created in TotalAgility must have Deployment Administrator rights.
• If a user does not use the default Deployment Administrator to install the TotalAgility Dynamics AX integration, the user must meet the following conditions:
• Be the system administrator in AX.
• Have full CAL access.
Failure to meet the preceding criteria generates the following error message during installation: "System unable to process request error."
1.
Navigate to \\DynamicsAXInstall on the installation media and double-click Setup.exe
.
The TotalAgility for Dynamics AX Setup wizard appears.
2.
Click Next .
The window displays a list of prerequisite software for Dynamics AX.
Note If the required software is not installed, first install the software and then install Dynamics
AX. If using Dynamics AX 2009, install .NETFramework 3.5. If using Dynamics AX 2012, install .NETFramework 4.0.
3.
Click Next .
The Destination window appears.
4.
Use the information in the following table to specify file paths in the Destination folder:
Destination Folder
DAX website Physical
Location
DAX website URL
DAX Client Physical
Location
DAX Server Physical
Location
Sample Path for Dynamics AX 2009 Sample Path for Dynamics AX 2012
C:\inetpub\wwwroot
\MicrosoftDynamicsAXAif50\
C:\Program Files\Microsoft
Dynamics AX\60\AifWebServices
Default Web Site/
MicrosoftDynamicsAXAif50/
C:\Program Files\Microsoft
Dynamics AX\50\Client\Bin\
C:\Program Files\Microsoft
Dynamics AX\50\Server
\DynamicsAx1\Bin
Default Web Site/
MicrosoftDynamicsAXAif60/
C:\Program Files
(x86)\Microsoft Dynamics AX
\60\Client\Bin
Not Applicable
5.
Click Next .
The Credentials window appears.
6.
Enter your Username and Password to associate with DAX Application pool.
151
Kofax TotalAgility Installation Guide
7.
Click Next .
The system displays the installation status and a summary of installation report when installation is complete.
8.
Click Finish .
Important If you are using 64 bit operating system and Dynamics AX 2009 32 bit application, enable the Application Pool account associated with the DAX Communicator site. In the IIS
Manager, click Application Pools > DAXAppPool > Advanced Settings and set True for Enable 32-Bit Applications.
Create Dynamics AX service reference to the TotalAgility web service
As AOT (Application Object Tree) is in the Development Workspace, ensure to deploy the Development
Workspace to add in references. Otherwise, you cannot integrate TotalAgility with Dynamics AX. See the following URL for instructions: http://msdn.microsoft.com/en-us/library/gg846350.aspx
.
Create Dynamics AX 09 service reference to the TotalAgility web service
1.
Start Dynamics AX 09.
2.
Click AOT (Application Object Tree) and press Ctrl+D .
3.
In the application object tree, Right-click References and select Add service reference .
4.
Complete the Add service reference window with the following information: a.
WSDL URL: Enter the web URL of the DynamicsAxIntegrationService within the Agility IIS web application, for example, http://Server/Agility.Server.Web/Services/SDK/
DynamicsAxIntegrationService.svc
.
b.
.NET code namespace: KtaEventsService .
c.
Reference name: KtaEventsService .
d.
Service description: Description of the service reference.
5.
Click OK .
Create Dynamics AX 12 service reference to the TotalAgility web service
1.
Start Dynamics AX 12.
2.
Click AOT (Application Object Tree) and press Ctrl+Shift+W .
3.
In the application object tree, right-click References and select Add Reference .
4.
Browse to the TotalAgility assembly, KtaEvents.Services.dll which was installed previously. For example,
C:\Program Files (x86)\Microsoft Dynamics AX\60\Client\Bin
5.
Click OK .
152
Kofax TotalAgility Installation Guide
Add a reference in Dynamics AX
Add a reference to the Agility.Server.Integration.Common.dll assembly in Dynamics AX.
In Dynamics AX 09
1.
Right-click References and select Add reference .
The assembly browsing form opens.
2.
Browse to the ...\client\bin directory of the Dynamics AX 09 installation. For example,
C:\Program Files (x86)\Microsoft Dynamics AX\50\Client\Bin)
3.
Select the Agility.Server.Integration.Common.dll
assembly and click OK .
The newly added assembly appears under references.
In Dynamics AX 12
1.
Right-click References and select Add reference .
2.
Browse to the TotalAgility assembly, Agility.Server.Integration.Common.dll, that was installed previously. For example, C:\Program Files (x86)\Microsoft Dynamics AX\60\Client
\Bin .
The newly added assembly appears under references.
3.
Click OK .
Edit the service configuration file for Dynamics AX 12
1.
Browse to the client\bin directory of the Dynamics AX where the WCF service configurations file,
KtaEvents.Services.dll.config was copied by the installer.
2.
Edit the endpoint to point to the valid TotalAgility Service for Dynamics AX notifications ( …Services/
SDK/DynamicsAxIntegrationService.svc
).
Copy files manually
To successfully add a Dynamics AX 2012 R2 site in TotalAgility, you must perform the following steps manually:
1.
Open Microsoft Dynamics AX 2012 and navigate to Dynamics AX server folder.
2.
Copy version 6.2.0 of Microsoft.Dynamics.BusinessConnectorNet.dll and paste it to the bin directory of the DAXCommunicatorService that you install on to the Dynamics AX server.
3.
On your TotalAgility installation media, navigate to \\TotalAgilityInstall\DAXInstallation
\Agility.Server.Integration.DynamicsAx.Web\Dax2012R2 .
4.
Copy Web.config and paste it to the following location on your DAX Server:
<\\Microsoft Dynamics AX\60\AifWebServices\DAXCommunicatorService>
The service uses the 6.2.0 version of the dll from the Web.config.
Note For DAX 2012 R3, the Web.config file needs updated to use 6.3.0 version of
Microsoft.Dynamics.BusinessConnectorNet.dll.
153
Kofax TotalAgility Installation Guide
Import the TotalAgility connector class into Dynamics AX
1.
In the AOT, click Import or press Ctrl+Shift+I.
2.
Click Browse and navigate to the Dynamics AX Setup installation folder (in the Program Files(x86) or Program Files directory). For example,
C:\Program Files\Dynamics AX Setup
3.
Select the XPO class, such as Class_KtaController.xpo.
4.
Click OK to initiate the import or compilation process.
Note Once the class is imported, the Status tab in the compiler output page displays any errors.
Edit database X++ event methods
You can edit the database X++ event methods in the DAX Development Workspace under Classes and
Application folders.
1.
To alter the Application CUD (create, update and delete) class event methods, call the custom class method EventChangeNotifyKtaWebService when a CUD event has been performed within Dynamics
AX.
2.
Edit the Application class methods ( InsertLog , DeleteLog & UpdateLog ) by adding a single line to the appropriate location within each method:
• Insertlog method: new ktaController().EventChangeNotifyKtaWebService("Create", recordInserted, null, conNull(), recordInserted.RecId);
• Deletelog method: new ktaController().EventChangeNotifyKtaWebService("Delete", recordDeleted, null, conNull(), recordDeleted.RecId);
• Updatelog method: new ktaController().EventChangeNotifyKtaWebService("Update", recordOrig, recordUpdated, changedFields, recordUpdated.RecId);
Note The onsite AX Administrator registers the Databaselog events for various AX documents.
For example, if the Customer, SalesOrder and Purchase Requisition documents have the Insert,
Update and Delete events registered against them, and when one of these events execute for one of these documents, TotalAgility is informed through a WCF call.
Register the database log events
1.
Open Microsoft Dynamics AX 2012.
2.
In the left hand panel, expand the configure buttons and select System Administration.
3.
In the System Administration page, under Setup, click Database logsetup. Database log window appears.
4.
Click File > New . Logging Database changes wizard appears where you can add and remove tables and fields from the database log.
154
Kofax TotalAgility Installation Guide
5.
Click Next. Tables and Fields window appears.
6.
Select the Show all tables radio button.
7.
In the Tables and Fields window, under General Ledger, select Customers / Vendor Tables as required and click Next.
8.
Select the type of change (insert, update, delete, or rename) to register in the database log by selecting the appropriate check box for the table.
9.
Click Next. Logging Database changes window appears with the details of the selected tables and fields.
10.
Click Finish .
Verify the Application Pool account
Verify that the Application pool account is using the correct Business Connecter.NET (BC.NET) Windows credentials.
1.
On the Start menu, select All Programs > Accessories and click Run .
2.
Enter inetmgr and click OK .
The IIS Manager appears.
3.
Navigate to Application Pool accounts.
4.
Select the DAXKTA account and verify that the identity is the same as the BC.NET Windows credentials.
5.
If the credentials differ, do the following: a.
On the Actions panel, click Advanced Settings .
b.
Select the identity and click Edit .
6.
Click OK .
The Application Pool Identity window appears.
7.
Click Set .
The Set Credentials window appears.
8.
Enter the user credentials that are associated with the BC.NET account within Dynamics AX. (The
Kofax WCF service uses the BC.NET account to connect to Dynamics AX).
9.
Click OK .
155
Chapter 8
Integrate Micro Focus Content Manager with
TotalAgility
This chapter provides the instructions for integrating Micro Focus Content Manager with TotalAgility
Integration Server.
Prior to installing Content Manager server, install the following software:
• IIS
• .NET Framework 4.6.1
• TotalAgility (optional)
Identify the Content Manager SDK Version
These instructions only apply to Content Manager version below 8.
1.
Navigate to the C:\Program Files\Kofax\TotalAgility\ directory.
2.
Right-click TrimSDKPIA20.dll
and select Properties .
The TrimSDKPIA20.dll properties window appears.
3.
On the properties window, select the Version tab.
The File Version displays the current Content Manager version. For example, 7.3.0.
Note For TRIM SDK 7.3.0 and later, you will require to enter this number in the <assemblyBinding> section of the Web.config (see
Set up the Micro Focus Content Manager server ).
Set up the Micro Focus Content Manager server
To set up the Content Manager server, install and configure TotalagilitytrimCommunicatorService and then configure the event handler in Content Manager system.
Install and configure TotalAgilityTrimCommunicatorService
To install and work with Micro Focus Content Manager with version 9.4 or higher, do the following.
1.
Log on to the Content Manager server with an account with Local Administrator privilege.
2.
Navigate to \\ContentManagerInstallation on the Content Manager installation media, right click on the executable Setup.exe
and select Run as administrator .
The User Account Control window appears.
156
Kofax TotalAgility Installation Guide
3.
Click Yes .
The installation wizard appears.
4.
Click Next .
The setup is ready to install the TotalAgility integration components.
Note
• If the Trim SDK already exists in your system, the Trim SDK Detected checkbox is by selected by default. Click Finish .
• If the Trim SDK does not exist in your system, the Trim SDK Detected checkbox is clear by default and an error message appears. Also, the Finish button is not enabled. To resolve this error, click Cancel and run Install CM_COMComponents_x64.msi from the Content Manager installation media to get the Trim SDK. Rerun the
Micro Focus Content Manager server setup .
5.
Configure the Web configuration file as follows: a.
In C:\Program Files\Kofax\TotalAgility
\TotalAgilityTrimCommunicatorService , open the Web.config
file in the text editor.
b.
Locate the configuration > runtime tag and edit the <assemblyBinding> section as follows:
<assemblyBinding>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity name="TrimSdkPIA20" publicKeyToken="533fc65e30e543fa" />
<bindingRedirect oldVersion="6.2.2.8614" newVersion=" <latest version> " />
</dependentAssembly>
</assemblyBinding>
Replace the <latest version> with the version of TRIM SDK . See
Integrate Content Manager with TotalAgility .
c.
Edit the <appsettings> as follows:
<appSettings>
<add key="TrimDocumentRecordType" value="DocumentRecordType" />
<add key="TrimFolderRecordType" value="FolderRecordType" />
<add key="WorkGroupServerName" value="ServerName" />
157
Kofax TotalAgility Installation Guide
</appSettings>
• Replace the DocumentRecordType with the value taken from the Content Manager server by checking the record type of Document.
• Replace the FolderRecordType with the value taken from the Content Manager server by checking record type of Folder.
• Replace the ServerName with the computer name of the Server.
To identify the computer name of the server, open Windows Explorer , right-click Computer and click Properties . In the Computer name, domain, and workgroup settings group, click
Change Settings . Copy the computer name.
Important When you first install the TotalAgility Micro Focus Content Manager, a
TrimIntegrationAppPool with a local system identity is created. This causes an error if the
Content Manager server is remote.
To resolve this error, you must update the TrimIntegrationAppPool identity to account with
Administrator permission.
Configure the event handler in Content Manager
Configure TotalAgility events for actions in the Content Manager System.
1.
Copy the following DLLs.
• If using Content Manager version below 8, copy the following DLLs to the TRIM binaries directory
(usually c:\Program Files\Hewlett-Packard\HP Records Manager.)
• Agility.Server.Integration.Trim.dll
• Agility.Server.Integration.Model.dll
• Agility.Server.Integration.Common
• If using Content Manager version 8 and above, copy Agility.Server.Integration.Trim.dll
to the
TRIM directory.
2.
For Content Manager to fire events in TotalAgility, register the Agility.Server.Integration.Trim.dll
file using RegAsm ( regasm /codebase Agility.Server.Integration.Trim.dll
).
158
Kofax TotalAgility Installation Guide
3.
To register the dll: a.
Open Content Manager .
b.
Select Tools > Context Administration > External Links .
The Content Manager Context External Links window appears.
c.
Click New Record AddIn .
The Record AddIn Properties window appears.
d.
Enter a Link Name.
e.
In the COM Add-In PROGID field, enter the ProgId,
Agility.Server.Integration.Trim.TrimIntegrationEventHandler
.
f.
Select Add-In supports a multi-threaded environment .
g.
Click OK .
The Content Manager Context External Links window displays the new link.
h.
Select the link and click Properties .
The Record AddIn Properties window appears.
i.
Click the Used By tab.
j.
Check the Document and File Folder under Record list and click OK .
This configures the Event handler on Content Manager.
4.
In the Explorer, find trim.exe.config
file, open it in a text editor and add or replace the following tags:
Note If you cut and paste code from this guide, correct any incorrect line breaks.
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<section name="loggingConfiguration" type="Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.LoggingSettings,
Microsoft.Practices.EnterpriseLibrary.Logging, Version=5.0.505.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35" requirePermission="true" />
<section name="exceptionHandling" type="Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.Configuration.
ExceptionHandlingSettings,
Microsoft.Practices.EnterpriseLibrary.ExceptionHandling,
Version=5.0.505.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
requirePermission="true" />
</configSections>
<exceptionHandling>
<exceptionPolicies>
<add name="Agility Exception Policy">
<exceptionTypes>
<add name="All Exceptions" type="System.Exception, mscorlib, Version=4.0.0.0,
Culture=neutral, PublicKeyToken=b77a5c561934e089"
postHandlingAction="NotifyRethrow">
<exceptionHandlers>
<add name="Logging Exception Handler" type=
"Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.Logging.
LoggingExceptionHandler,
Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.Logging,
Version=5.0.505.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35" logCategory="General" eventId="100" severity="Error" title="Total Agility"
159
Kofax TotalAgility Installation Guide formatterType=
"Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.TextExceptionFormatter,
Microsoft.Practices.EnterpriseLibrary.ExceptionHandling, Version=5.0.505.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35" priority="0" />
</exceptionHandlers>
</add>
</exceptionTypes>
</add>
</exceptionPolicies>
</exceptionHandling>
<system.serviceModel>
<bindings>
<basicHttpBinding>
<binding name="BasicHttpBinding_Service" openTimeout="00:10:00"
closeTimeout="00:10:00" sendTimeout="00:10:00" receiveTimeout="00:10:00" allowCookies="true"
maxBufferSize="2147483647" maxReceivedMessageSize="2147483647" maxBufferPoolSize="524288"> <readerQuotas
maxDepth="2147483647" maxStringContentLength="2147483647" maxArrayLength="2147483647"
maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
<security mode="TransportCredentialOnly">
<transport clientCredentialType="Windows" />
</security>
</binding>
</basicHttpBinding>
</bindings>
<client>
<endpoint name="CoreIntegrationEventServiceEndpoint" binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_Service" contract="Agility.Server.Core.Model.Interfaces.Services.IIntegrationEventService" address="http://<TotaAgility server name or IP Address>/TotalAgility/Services/
Core/IntegrationEventService.svc"/>
</client>
</system.serviceModel>
</configuration>
Note Replace <TotalAgility server name or IP Address> with the IP Address of the TotalAgility server.
160
Chapter 9
Integrate Kofax SignDoc with TotalAgility
This chapter provides the instructions for integrating Kofax SignDoc with TotalAgility.
Set up the Kofax SignDoc server
Configure the Kofax SignDoc server to point to the relevant TotalAgility server to allow callback to occur when the signing is completed. The SignDoc server can be configured per SignDoc account to allow the same SignDoc server to callback to multiple TotalAgility servers.
Refer to the section on integration with TotalAgility in SignDoc documentation to know how to set up the
SignDoc server to point to the TotalAgility server.
161
Chapter 10
KCM Proxy installation on the Web server
This chapter describes three methods for installing the KCM Proxy Web server:
• Silent installation
• Standard installation
• Docker installation
Ensure that the Microsoft plugin, Web Platform Installer is installed before installing the KCM Proxy Web server. You can install the Microsoft Web Platform from the Microsoft website.
Silent installation
1.
On the installation media, navigate to \\KCMProxyInstallation .
2.
Launch a Command Prompt window and run Setup.exe
and enter the KCM Server URL in the following format: http(s)://<CCMServer>:<Portnumber> .
Provide the IP address and port number of the KCM server. The installer updates the Web.config
with KCM server details and enables the proxy rewrite rules on the web server (IIS).
3.
Press Enter .
The KCM Proxy is installed in the silent mode.
The system generates a log file on the desktop which reports errors (if any).
Standard installation
1.
On the installation media, navigate to \\KCMProxyInstallation and double-click Setup.exe
.
The KCM Proxy Configuration window appears.
2.
Enter the KCM Server URL in the following format: http(s)://<CCMServer>:<Portnumber> .
The Web.config file is automatically updated with the KCM Server IP and the Port number.
3.
Click Configure .
4.
Click OK .
Docker installation
While generating the "dockersetting.env" file, if the URL is specified in the "KCM Server URL" setting in the Configuration Utility tool, the same URL is used to install KCM Proxy and configure the deployment in the container.
162
Kofax TotalAgility Installation Guide
Update the KCM Server URL in TotalAgility Web.config
You can manually update the KCM Server URL in TotalAgility Web.config or run the Configuration tool and update the settings before setting up the integration to KCM.
Manually update the KCM Server URL in TotalAgility Web.config
1.
Navigate to the installation directory for the TotalAgility server.
2.
In a text editor, open TotalAgility Web.config
from the following directory:
\\TotalAgilityInstall\Agility.Server.Web
3.
Locate the following section:
<rewrite>
<rules>
<rule name="CCMInteractiveProxy" stopProcessing="true">
<match url="CCM/Proxy/Interactive/(.*)" />
<action type="Rewrite" url="{http://ccmserver:port}/ccm/Interactive/
{R:1}" />
</rule>
<rule name="CCMDesignerProxy" stopProcessing="true">
<match url="CCM/Proxy/Repository/(.*)" />
<action type="Rewrite" url="{http://ccmserver:port}/ccm/Repository/
{R:1}" />
</rule>
<rule name="ComposerUIJavascriptProxyRule" stopProcessing="true">
<match url="CCM/Proxy/ccmcomposerui.js" />
<action type="Rewrite" url="{http://ccmserver:port}/proxy/ ccmcomposerui.js" />
</rule>
<rule name="ComposerUICssProxyRule" stopProcessing="true">
<match url="CCM/Proxy/ccmcomposerui.css" />
<action type="Rewrite" url="{http://ccmserver:port}/proxy/ ccmcomposerui.css" />
</rule>
<rule name="ComposerUIImgProxyRule" stopProcessing="true">
<match url="CCM/Proxy/img/(.*)" />
<action type="Rewrite" url="{http://ccmserver:port}/proxy/img/{R:1}" />
</rule>
<rule name="CCMDesignerStaticProxyRule" stopProcessing="true">
<match url="CCM/Proxy/static/(.*)" />
<action type="Rewrite" url="{http://ccmserver:port}/ccm/static/
{R:1}" />
</rule>
<rule name="ComposerUIFontProxyRule" stopProcessing="true">
<match url="CCM/Proxy/fonts/(.*)" />
<action type="Rewrite" url="http://{ccmserver:port}/proxy/fonts/
{R:1}" />
</rule>
</rules>
4.
Replace the http://<kcmserver>:<port> with the kcmserver URL.
5.
Save and close the configuration file.
163
Kofax TotalAgility Installation Guide
Use the Configuration Utility
Run the Configuration Utility and update the configuration settings. See the Kofax TotalAgility
Configuration Utility Guide . (Navigate to Configuration settings >On-premise >App section).
Install KCM Proxy manually
You can install KCM proxy without using Web platform installer and KCM proxy installer.
1.
Install IIS URL Rewrite 2.0.
2.
Install Microsoft Application Request Routing 2.5 or higher for IIS.
3.
In the IIS Manager, do the following: a.
On server level, double-click Application request routing cache.
b.
Click Server Proxy Settings .
c.
Select Enable Proxy .
d.
Click Apply .
4.
In TotalAgility Web.config, find {http://ccmserver:port} and replace with http:// servername:port where servername is the host name of the KCM machine and port is the port
KCM listed as (default 8081). See the previous section for manually updating the KCM Server URL in
TotalAgility Web.config.
5.
Uncomment the <rewrite> section.
6.
Save and close the configuration file.
164
Chapter 11
Configure HTTPS communication
Configure TotalAgility and Transformation Designer for HTTP communication.
•
Configure TotalAgility for HTTPS communication
•
Configure Transformation Designer for HTTPS communication
Configure TotalAgility for HTTPS communication
Enable SSL (Secure Sockets Layer) communication for the TotalAgility web layer and Kofax TotalAgility
Core Worker to communicate with core services and Transformation Server.
You can enable SSL for TotalAgility at the time of installation. However, if you have not enabled SSL at the time of installation, you can do so post installation by running the Configuration Utility available on the installation media. See the Kofax TotalAgility Configuration Utility Guide .
Note Before changing the bindings in the TotalAgility configuration files, ensure that SSL is enabled for
TotalAgility in the IIS.
Enable SSL for the TotalAgility application in IIS
1.
Open Internet Information Services (IIS) Manager .
2.
Right-click the Default Web Site and click Edit Bindings .
3.
Click Add .
a.
On the Type list, select HTTPS .
b.
On the SSL certificate list, select the certificate.
c.
If installing a separate web server, additionally specify the IP address of the web server, and
Port number.
d.
Click Ok .
4.
Click TotalAgility and click SSL settings on the Features tab.
a.
Select the check box for Require SSL .
b.
Accept the Client certificates.
c.
Click Apply .
Update the TotalAgility configuration files
Update the following configuration files:
• Web.config
165
Kofax TotalAgility Installation Guide
• Agility.Server.Core.WorkerService.exe.config
• Agility.Server.StreamingService.exe.config
Update Web.config
1.
Open Web.config
located at your installed location. The default location is:
C:\Program Files\Kofax\TotalAgility\Agility.Server.Web
2.
In <servicebehaviors> , update the httpsGetEnabled setting as follows:
<serviceBehaviors>
<behavior name="Agility.Server.Web.Services.Behavior">
<serviceMetadata httpGetEnabled="false" httpsGetEnabled="true" />
</serviceBehaviors>
3.
By default <security mode="TransportCredentialOnly"> . If using HTTPS mode, update the
<security> settings as follows:
• If using Windows Authentication, comment out the default Windows authentication section:
<!-- HTTPS SSL with Windows logon-->
<security mode="Transport">
<transport clientCredentialType="Windows"/>
</security>
• If logging on manually, uncomment the HTTPS section:
<!-- HTTPS SSL with application authentication-->
<security mode="Transport">
<transport clientCredentialType="None" />
</security>
4.
Perform the above HTTPS transport authentication for all the bindings:
• BasicHttpBinding_SharepointCommunicatorService
• BasicHttpBinding_TrimCommunicatorService
• BasicHttpBinding_ExchangeNotificationService
• BasicHttpBinding_DynamicsAxCommunicatorService
• BasicHttpBinding_DynamicsAxIntegrationService
• BasicHttpBinding_Service
• CustomBinding_CoreService
• BasicHttpBinding_RemoteLinkedService
• BasicHttpBinding_LicenseServerService
• BasicHttpStreamingBinding_Service
• BasicHttpBinding_DeviceManagerService
• BasicHttpBinding_InsightDataService
• BasicHttpBinding_SigningIntegrationService
• WebHttpBinding_Service
• WebHttpBinding_DeviceManagerService
• WebHttpBinding_SigningIntegrationService
5.
The Secure attribute for sensitive cookies in HTTPS sessions is not set by default. This allows a browser to send these cookies in plain text over an HTTP session. To secure the cookies, uncomment the httpCookies tag.
<httpCookies requireSSL="true"/>
166
Kofax TotalAgility Installation Guide
6.
To connect TotalAgility to a specific SQL server, ensure that "encrypt=true" for the TotalAgility database connection string.
Note Ensure that SSL is enabled and certificates are installed for the SQL server. See the
Microsoft documentation.
If SSL encryption has been turned on globally at the SQL server level using force encryption, you do not need to update the TotalAgility connection strings.
7.
Save the file.
Update Agility.Server.Core.WorkerService.exe.config
1.
Open Core Worker Agility.Server.Core.WorkerService.exe.config
located at your installed location. The default location is:
C:\Program Files\Kofax\TotalAgility\CoreWorkerService
2.
Perform the HTTPS transport authentication for all the bindings:
• BasicHttpBinding_Service
• CustomBinding_CoreService
• BasicHttpBinding_SharepointCommunicatorService
• BasicHttpBinding_TrimCommunicatorService
3.
Save the file.
4.
Restart the TotalAgility CoreWorker service.
Update Agility.Server.StreamingService.exe.config
1.
Open the Agility.Server.StreamingService.exe.config
located at your installed location. The default location is:
• Web server :
C:\ProgramFiles\Kofax\TotalAgility\Agility.Server.Web\bin
\Agility.Server.StreamingService.exe.config
• Application server and combined Web/Application server :
C:\ProgramFiles\Kofax\TotalAgility\CoreWorkerService
\Agility.Server.StreamingService.exe.config
Note Edit the Agility.Server.StreamingService.exe.config for both the Application and Web servers.
2.
In <servicebehaviors> , update the httpsGetEnabled setting as follows:
<serviceBehaviors>
<behavior name="Agility.Server.Web.Services.Behavior">
<serviceMetadata httpGetEnabled="false" httpsGetEnabled="true" />
</serviceBehaviors>
3.
By default, <security mode="TransportCredentialOnly"> . If using HTTPS mode, update the <security> settings (for Windows authentication or logging on manually) as follows:
• <!-- HTTPS SSL with Windows logon-->
<security mode="Transport">
<transport clientCredentialType="None"/>
</security>
167
Kofax TotalAgility Installation Guide
4.
Perform the HTTPS transport authentication for all the bindings as follows:
• WebHttpExportBinding_Service
<binding name="WebHttpExportBinding_Service"> transferMode="StreamedResponse">
<security mode="Transport">
<transport clientCredentialType="None">
</transport>
</security>
</binding>
• WebHttpImportBinding_Service
<binding name="WebHttpImportBinding_Service"> transferMode="StreamedRequest">
<security mode="Transport">
<transport clientCredentialType="None">
</transport>
</security>
</binding>
• BasicHttpStreamingBinding_Service
<binding name="BasicHttpStreamingBinding_Service" transferMode="Streamed"
<security mode="Transport">
<transport clientCredentialType="None">
</transport>
</security>
</binding>
• BasicHttpBinding_Service
<binding name="BasicHttpBinding_Service">
<security mode="Transport">
<transport clientCredentialType="Windows" />
</security>
</binding>
• BasicHttpStreamingBinding_CoreService
<binding name="BasicHttpStreamingBinding_CoreService" transferMode="Streamed"
<binding name="BasicHttpStreamingBinding_CoreService" transferMode="Streamed"
<security mode="Transport">
<transport clientCredentialType="Windows" />
</security>
</binding>
Note The streamed transfer mode causes the Microsoft WCF runtime to enforce some restrictions on security. The Windows authentication is not possible with streamed transfer mode. Therefore, we recommend that you use anonymous authentication. However, TotalAgility always validates the session ID before serving a request.
• CustomBinding_CoreService
<binding name="CustomBinding_CoreService">
<!--
<httpTransport authenticationScheme="Negotiate" for http with windows
authentication
<httpsTransport authenticationScheme="Anonymous" for https with None
authentication
-->
<httpsTransport authenticationScheme="Anonymous" allowCookies="true"
maxBufferSize="2147483647" maxReceivedMessageSize="2147483647"
maxBufferPoolSize="524288" />
</binding>
5.
Change the <baseAddresses> from http to https.
168
Kofax TotalAgility Installation Guide
6.
Save the file.
7.
Restart the TotalAgility Streaming Service to apply the new settings.
Configure the Transformation Designer for HTTPS communication
Update the Kofax Transformation Designer to use SDK SVC accessed via SSL by updating the connection within Kofax Transformation Designer options. For Kofax Transformation Designer, you need to do the following for HTTPS communication:
• Make sure you have installed a certificate that is trusted by the client on the server.
• If the Transformation Designer server is installed on-premise but is not part of a domain, disable
Windows Authentication for BasicHttpBinding_Service and WebHttpBinding_Service.
• Specify the URL for Transformation Designer for HTTPS as follows:
• For Azure: https://<Azure host name>/Services/SDK
• For other configurations: https://<host name>/TotalAgility/Services/SDK
169
Chapter 12
Install TotalAgility License Proxy
TotalAgility License Proxy enables unconnected Scan Workstations and/or other TotalAgility components to get licensing from the TotalAgility Licence server.
We recommend that you install TotalAgility License Proxy on the machine where VRS Elite server is installed. Otherwise, you will need to run the license utility on each workstation and configure the server to point to the proxy machine.
Do not install the Licence Proxy on the same computer as the Licence server (computer running the
'Kofax License Server' service). The Licence Proxy must run on a separate computer, because it needs to route traffic to the licence server. As part of the License Proxy setup, the installer checks the local computer for the TotalAgility License Server, stops the service and sets the startup type to "Disabled".
You can install the License Proxy manually or when installing TotalAgility.
1.
To install manually, on the Installation media, navigate to \\TotalAgilityInstall\ Licensing
\Installs and run Kofax.Licensing.TotalAgility.Proxy.Installer.msi
.
The Kofax TotalAgility License Proxy Setup wizard opens.
2.
Click Next .
3.
In the End-User License Agreement window, accept the terms in the License Agreement and click
Next .
4.
In the Destination Folder window, select the default path ( C:\Program Files (x86)\Kofax
\TotalAgility License Proxy\ ) where the Kofax TotalAgility License Proxy will be installed or click Change to choose another folder.
5.
Click Next .
6.
In the Service account setup window, enter the credentials for the user who will run the TotalAgility
License Server service: a.
In the Username field, enter the user name.
To specify a domain user, enter the user name in the format Domain\User.
b.
Enter and confirm the password.
Note This account must have access to the specified TotalAgility URL. These credentials are used for Kofax License Proxy service.
c.
Click Next .
170
Kofax TotalAgility Installation Guide
7.
In the TotalAgility connection setup window: a.
Enter the URL of the License Server where the configuration settings reside.
Use the following format: http://<server_name>/TotalAgility/Services/Core/
LicenseServerService.svc
where <server_name> is the TotalAgility server name.
Note If using SSL, you must have a trusted, valid certificate.
b.
Enter the System Session ID.
Obtain the Session ID value from the TotalAgility Designer(System Settings>Settings page).
c.
Click Next .
The system downloads the settings.
8.
Click Install to begin installation.
9.
Click Finish .
Once the Kofax TotalAgility License Proxy for VRS Server is installed, you can verify if the proxy is working properly by navigating to C:\Program Files\Kofax\Imgctls\bin\Application and running KSALicenseUtility . If the proxy is configured properly, the license information appears in the Kofax License Utility user interface; otherwise, an error appears. You may need to reconfigure the System Session ID to match with the TotalAgility Server.
Modify the TotalAgility license proxy information
You can modify the TotalAgility license proxy information after the installation, in one of the following ways.
• Run the Kofax.Licensing.TotalAgility.ProxyConfig.exe
typically located at C:\Program
Files (x86)\Kofax\TotalAgility License Proxy\ . For example, if you regenerate the system session ID in TotalAgility, the same session ID must be reflected in the License Proxy configuration.
• Use command line parameters. Replace the parameters with the following values, if needed.
Parameter
/URL
/sessionID
/retrySpan
/silent
Value
TotalAgility URL
System Session ID for the specified user.
Length of time to retry connections to Kofax TotalAgility. Format is that accepted by
TimeSpan.Parse, for instance "00:00:30" represents the default of 30 seconds.
Enables silent mode for configuration utility. User Interface does not appear.
For example, Kofax.Licensing.TotalAgility.TenantProxyConfig /url https:// tenantSpecific /sessionId {66FFD7D5-F618-4BEE-903A-54C151671BC8} /retrySpan:
00:05:00 .
Note When you run the command with any invalid parameters an error message is sent to the standard error file.
171
Kofax TotalAgility Installation Guide
Modify the TotalAgility license proxy information
You can modify the TotalAgility license proxy information after the installation, in one of the following ways.
• Run the Kofax.Licensing.TotalAgility.ProxyConfig.exe
typically located at C:\Program
Files (x86)\Kofax\TotalAgility License Proxy\ . Example: If you regenerate the system session ID in TotalAgility Designer, the same session ID must be reflected in the License Proxy configuration.
• Use command line parameters. Replace the parameters with the following values, if needed.
Parameter
/URL
/sessionID
/retrySpan
/silent
Value
TotalAgility URL
System Session ID for the specified user.
Length of time to retry connections to TotalAgility. Format is that accepted by
TimeSpan.Parse, for instance "00:00:30" represents the default of 30 seconds.
Enables silent mode for configuration utility. User Interface does not appear.
For example, Kofax.Licensing.TotalAgility.TenantProxyConfig /url https:// tenantSpecific /sessionId {66FFD7D5-F618-4BEE-903A-54C151671BC8} /retrySpan:
00:05:00 .
Note When you run the command with any invalid parameters an error message is sent to the standard error file.
172
Chapter 13
Configure VRS Elite for TotalAgility
Install Kofax VRS and configure the VRS license server. Refer to the Kofax VRS Elite Installation Guide for more details.
Kofax VRS Basic or Professional OEM installations
If your scanner includes an OEM version of VRS Basic or Professional, install VRS by running setup.exe
on the scan station. The VRS software is automatically activated based on the attached scanner model.
Standalone installations
If you purchased a standalone VRS license, install VRS by running setup.exe
and select Standalone as the setup type. When prompted, specify the part number (such as VP-P005-0001), product code, and serial number to activate the software.
Note VRS remains activated on the workstation unless you manually deactivate it.
Kofax VRS Elite licensing managed by the TotalAgility License
Server
Use this configuration to manage VRS licenses through the TotalAgility License Server while also enabling
VRS Elite shared profiles and auto profile training data.
This configuration requires installation of the VRS Elite 5.1.2 or higher.
Note This configuration may be convenient if you have a limited number of scanners, however, it does not enable support for shared VRS profiles and training data.
Install VRS Server
1.
Run setup.exe
from the VRS Elite installation media.
2.
When prompted, select Server as the setup type.
173
Kofax TotalAgility Installation Guide
3.
Confirm the TotalAgility license server information.
Note If the VRS Server does not have a direct connection to the TotalAgility license server, you need to install a license proxy.
4.
Complete the steps in the installation wizard.
5.
Use the generated deployment Kofax VRS.msi to install VRS on the scan stations. Refer to the Kofax
VRS Elite Installation Guide for details.
Use Kofax VRS Elite with the TotalAgility Scan Client
After you install VRS Elite, Kofax Software VRS - TWAIN appears in the list of scanners when you scan a document in TotalAgility. See the Totalagility Scan Client help for more information.
174
Chapter 14
Kofax Web Capture Service installation
Install the Kofax Web Capture Service either at the default location or to a custom location.
Install at the default location
1.
When opening a scan-enabled form for the first time, a prompt appears asking you to install the new
Web Capture Service. See Build a Scan Create New Job form in TotalAgility Help .
2.
Click Run .
3.
Select Save As if you want to keep a copy of the msi installer. The msi installer can be used for
Enterprise central deployment scenarios.
4.
Refresh the page once installation completes.
5.
The View and Change Settings icon on the Scan Create New Job form becomes available after page refresh.
6.
The Kofax Web Capture Service icon in the System Tray icons indicates if the service is running.
Install at custom location
For enterprise deployment scenarios where a custom Web Capture service installation location is required, install Web Capture service as follows.
On the Command Prompt, type the following command: msiexec /i Kofax.WebCapture.Installer.msi INSTALLFOLDER=<Installation Folder>
Use the Web Capture Service on multiuser environment
You can use the Web Capture Service on multiuser environments, such as MS Terminal Server and
Citrix. Multiple users can work with Web Capture Service at the same time from different Windows logon sessions.
Use the Web Capture Service on MS Terminal Server
When using a Terminal Server, users can connect to the scan server simultaneously and perform scanning tasks or import files in parallel. The Web Capture Service Host determines who exactly has made the request and forwards the request to the appropriate Web Capture Service Worker. The Web
Capture Service Worker then works with devices and files that are available to the specific user.
175
Kofax TotalAgility Installation Guide
Note The Web Capture Service can only work with scanners attached to a remote Terminal Server; it cannot work with locally connected scanners.
Similarly, for file import, the Web Capture Service provides access to files on a Terminal Server.
Use the Web Capture Service on Citrix
When both the Browser app and Web Capture Service are installed on the Citrix Server, the Web Capture
Service physically runs on a remote Citrix server, while a scanner is connected to the client user’s computer. This works transparently for Web Capture Service when Citrix TWAIN Redirection is enabled.
Note The number of simultaneously active user sessions for one Citrix Server is limited to 50 sessions.
Install the Web Capture Service as Windows Service
To deploy and upgrade the Web Capture Service installed as Windows Service, you must have
Administrator rights.
To install the Web Capture Service as a Windows Service, enable the multiuser support features by using the INSTALLASSERVICE command line option as follows: msiexec /I Kofax.WebCapture.Installer.msi INSTALLASSERVICE=1
The MSI installation package is available in the TotalAgility installation folder at:
\\TotalAgilityInstall\Agility.Server.Web\Forms\Controls\Capture\external
\webcapture
Upgrade the Web Capture Service
To upgrade the Web Capture Service installed as Windows Service, use the same command line parameter that you used for installing the Web Capture Service.
Note You cannot upgrade the Web Capture Service installed as a Windows Service to the standalone version. If you try to do so, the following message appears: This application cannot be installed because you already have Web Capture Service installed as Windows service.
However, you can upgrade from the standalone installation to Windows.
176
Chapter 15
Scan Agent Service installation
The Scan Agent Service is offered through lightweight local agents that can be deployed through an msi file included in the TotalAgility installation media.
You must have sufficient privileges to install system services, otherwise the Scan Agent Service
(ScanAgentService) cannot be installed.
Service account to use for Scan Agent Service :
If TotalAgility is configured to use Windows authentication then Active Directory account must be specified that can authenticate within TotalAgility. Otherwise, the LocalSystem account can be used.
As Scan Agent Service needs access to user profile specific folders (to access scanned images) then service account that is used for Scan Agent Service must have access to different user profiles. This means that this account must have administrative privileges. For example, when Scan Agent Service is installed on terminal server and/or different users (scan operators) use the same computer.
If Scan Agent Service is going to be deployed to end user computer then you may not require administrator privileges. For example, if Scan Agent Service is going to upload images only for a particular user then you can install Scan Agent Service under this user account.
Standard installation
1.
On the installation media, navigate to \\ScanAgentService .
2.
Double-click Kofax.TotalAgility.ScanAgentService.Installer.msi
.
The Kofax TotalAgility Scan Agent Service Setup wizard starts.
3.
Click Next .
4.
In the End-user License Agreement window, select I accept the terms in the License
Agreement .
5.
Click Next .
6.
In the Destination Folder window, either accept the default location where the Scan Agent Service must be installed, or click Change to choose another folder.
7.
Click Next .
8.
In the Service account setup window, specify the logon account (Windows account) for the Kofax
TotalAgility Scan Agent service.
9.
Click Next .
10.
Click Install to begin installation.
Once installed, a local service, "Kofax TotalAgility Scan Agent Service", is created on the workstation.
A companion "Scan Agent Monitor" is available, which can be used to monitor job upload status.
177
Kofax TotalAgility Installation Guide
Scanning with Scan Agent Service
The status bar of the Scan Create New Job form indicates if the session is connected to Scan Agent
Service.
The Scan create new job form offloads actual upload of images to Scan Agent Service. However if image enhancement is enabled, the Scan create new job form performs image processing in a regular way.
Once image processing operation (if any) is done, the "Create Job" button becomes available, even if images have not been completely uploaded to the server. When you click "Create Job", the job appears in the Scan Agent Monitor.
The Scan Agent Monitor can be used to monitor job upload status. The job upload statuses include:
• Pending : Job is being prepared for upload.
• In Progress : Job is currently being uploaded.
• Finished : Job has successfully being uploaded.
• Error : Job encountered an error and has been stopped.
• Paused : Job has been paused.
Depending on the job status, the following actions are available.
• Abort : Aborts and cancels the corresponding job, and prompts you for a TotalAgility user account to cancel the job with.
Note This action uses a separate TotalAgility user session; if “Allow Multiple Logon” is not enabled, the abort action ends any other session using the same user account.
• Pause : Pauses the upload session for the job. You must explicitly resume a paused job.
• Retry : Queues uploading job again if the job encounters an error. This action helps in recovering from an upload error.
• Resume : Resumes a paused job.
• Clear Completed : Removes all uploaded complete jobs from the list.
178
Chapter 16
Launch TotalAgility
1.
Enter the following URL in the browser: http://<TotalAgility server hostname or IP>/TotalAgility/Designer
2.
Enter the login credentials provided during installation.
TotalAgility Designer is launched in the browser.
3.
Alternatively, click Start > All Programs > Kofax TotalAgility > Designer .
Launch TotalAgility Workspace
1.
Enter the following URL in the browser: http://<TotalAgility server hostname or IP>/TotalAgility/Forms
2.
Enter the login credentials provided during installation.
TotalAgility Workspace is launched in the browser.
3.
Alternatively, click Start > All Programs > Kofax TotalAgility > Workspace .
Launch TotalAgility Quick Start
When you install or upgrade Kofax TotalAgility, Quick Start is automatically installed and available on the
Start menu.
1.
Click Start > All Programs > Kofax TotalAgility > Quick Start .
Alternatively, enter the following URL in the browser.
http://<TotalAgility server hostname or IP>/TotalAgility/Designer/#/ quickstart
2.
Enter the login credentials provided during installation.
The Kofax TotalAgility Quick Start landing page appears.
Guidance notes on logon
You can configure a single Kofax TotalAgility web installation using either of the following as these configurations are mutually exclusive:
• Windows Authentication
• Manual Logon
179
Kofax TotalAgility Installation Guide
For example, if an organization requires "manual logon" for external users and "Windows authentication" for internal users, you cannot achieve this with a single web installation. You need two separate web sites, one to use Windows authentication and the other to use Manual logon. You can use the following options to achieve this configuration.
• Two separate web servers where one web server will have a Kofax TotalAgility web installation using
Windows authentication, and another web server will have a Kofax TotalAgility web installation using manual logon (preferred). You can upgrade the servers as they are installed using the Kofax TotalAgility installation program (by the Kofax TotalAgility installation / upgrade program).
• Single web server containing two TotalAgility web sites, where one website is configured to use manual logon and another website configured to use Windows authentication. The administrator setting up this server will install Kofax TotalAgility web installation and then clone the virtual directory.
Note You can upgrade the original Kofax TotalAgility web installation, but not the cloned virtual directory.
180
Chapter 17
Repair the TotalAgility installation
Repairing TotalAgility will only repair the application and not the database.
To repair any TotalAgility product components that are installed incorrectly:
1.
Click Start > All Programs > Kofax TotalAgility and select Uninstall or Repair .
The Repair/Uninstall window opens.
2.
Click Repair and click Next .
The Components To Repair window opens and lists all the components you can repair.
3.
Select the components to repair.
4.
Click Browse and select the installation files.
5.
Click Next .
The Credentials window opens.
6.
Enter the Password or select the Run as System Account check box to choose the system credentials.
7.
Click Next .
The Repair Progress window opens. When the repair is complete, the Repair Complete window opens. The summary report lists the components, servers, applications and services repaired.
8.
Click Finish .
181
Chapter 18
Uninstall TotalAgility
Uninstalling TotalAgility only removes the application and not the database.
Use the installation wizard
1.
Click Start > All Programs > TotalAgility and select Uninstall or Repair TotalAgility .
The Repair/Uninstall window opens.
2.
Select Uninstall and click Next .
3.
Follow the prompts until you are informed that the product is uninstalled, and then click Finish .
The summary report lists the components, servers, applications and services uninstalled.
If any errors occur during uninstallation, you can view them in the TotalAgility log file called
TotalAgilityInstallationErrorLog.txt on your desktop. This log file contains information about any errors.
Use the silent mode
1.
On the Command Prompt, change the command line to the root directory of the Setup.exe file.
2.
Run Setup.exe /Silent /U .
The system uninstalls TotalAgility and automatically creates a log file on your desktop. This log file contains information on errors, if any. The removal of the product is indicated in the event log.
Note Uninstalling TotalAgility in silent mode not only removes the applied fix pack or service pack but also removes the TotalAgility application completely. To reinstall TotalAgility, you must install its base version and then apply any patches.
182
Chapter 19
Upgrade TotalAgility
You can upgrade TotalAgility from 7.0.2, 7.1.0, 7.2.0 (or any interim patches), 7.3.0 (or any interim patches) or 7.4.0 (or any interim patches) or 7.5.0 (or any interim patches) or 7.6.0 (or any interim patches) or 7.7.0 (or any interim patches) to 7.9.0.
Note Before upgrading TotalAgility, ensure TotalAgility App Pool and all the TotalAgility Services are stopped, and the databases are backed up.
You can choose to upgrade only TotalAgility components (such as License Proxy, Transformation
Designer and Transformation Server) and TotalAgility databases
independent of each other or upgrade
TotalAgility components including databases
. See
Upon upgrading, the TotalAgility installer restores the following configuration settings:
• All existing AppSettings
• All existing Security Bindings
• All HTTP URL Rewrites to be done for TotalAgility 7.9.0.
Note After upgrading TotalAgility from versions prior to 7.7.0, you must reconfigure the license server by updating the settings to use the new licensing behavior. See
Update the settings for a license server .
Capture data migration
You can run the capture data migration process when upgrading TotalAgility. During the migration, capture data (such as folders, documents and fields) is transformed from old Data Layer tables into new format and stores in new Data Layer tables. The migration process never writes to existing old DL tables, only reads them. For higher migration throughput, the binary data (which is usually the biggest part of data) does not migrate.
Note When upgrading TotalAgility, there are many live jobs in system. These jobs continue their execution after the upgrade and capture data migration. For any reason if the migration process is failed, the overall TotalAgility upgrade is considered as failed and you must revert database to its previous state.
When running database upgrade with Migration Utility directly on SQL Server, we recommend that you leave enough free memory on the SQL server for better migration performance.
See the following recommendations for faster capture data migration:
• It is highly recommended to have at least 4-6Gb of free memory available before migration is running.
• Make sure that no CPU consuming processes are running on machine where migration is running.
183
Kofax TotalAgility Installation Guide
• If possible, run migration on machine where SQL Server is running.
• If you run migration on SQL Server's machine, make sure that 'Maximum Server Memory' option is reduced to have 50% or more free memory on the machine (database server restart may be needed to free up memory). This can significantly reduce the migration time.
• It is highly recommended to store SQL Server data files on SSD (solid-state drive) disks.
Perform the following steps for capture data migration:
1.
Navigate to TotalAgility Installation media and double-click Setup.exe
.
The User Account control window opens.
2.
Click Next .
3.
In the Kofax TotalAgility Upgrade window, select TotalAgility databases or TotalAgility components including databases .
4.
By default, the system starts the services automatically. To manually start the services after the installation is complete, clear the Automatically start services check box.
5.
To import the Workspace package, select the Import system Workspace package check box.
(Default: Clear)
6.
Click Next .
The Check for updates window prompts with a recommendation to check for the latest updates.
Click either of the following:
• No : Executes the normal installation flow.
• Yes : Redirects to Download updates page and installer exits. (Installer can open text file with instructions on how to download and apply updates)
7.
From the Download updates page, downloads ZIP file containing up-to-date versions of precheck SQL script and Kofax.TotalAgility.CaptureDataMigration.dll. Then run a new utility to apply downloaded updates. After updates are successfully applied, click Next .
8.
In the Credentials window, enter the credentials (password and confirm password) and click Next .
The Installation Review window opens and displays the settings.
9.
Review the settings and click Next to start the installation.
The Installation Progress window displays the following:
• The Data Read progress bar shows how much data has been read so far.
• The Data Migrated progress bar shows how much read data has been written.
• The Finish time ETA progress bar shows the predicted finish time of migration (ETA may change during migration as read/write throughput may change over time).
To cancel the data migration, click Cancel Migration .
Note
• Before running actual migration. TotalAgility installer performs pre-check of documents database.
If database pre-check finds any broken root folders and data cannot be migrated, the Capture
Data Migration summary panel displays the list of errors along with the error description. To ignore the broken folders, select the check box for Ignore broken folders and click Next . The
Kofax TotalAgility Installation Complete with errors window displays the summary.
• If any non-recoverable exception occurs during migration, the upgrade fails.
184
Kofax TotalAgility Installation Guide
10.
If the data migration is success, click Finish in the Kofax TotalAgility Installation Complete window to complete the installation.
If any errors occur during upgrade, TotalAgility creates a log file called Kofax
TotalAgilityInstallErrorLog.txt
in your installation directory. Fix the errors.
If any database script errors occur, TotalAgility creates a log file called
CEBPMDatabaseErrorLog.txt
on your desktop. Fix the errors and run Agility.server.upgrade.exe
.
Capture binary data storage
By default, the capture data is stored in the SQL Server. You can use the preconfigured external cloud data storage services such as Amazon S3 or Windows Azure Blob Storage for saving and processing the capture data. When upgrading TotalAgility On-Premise Multi-Tenancy from previous versions of
TotalAgility to 7.8.0 and higher, the existing SQL Server binary data is not moved to the cloud storage.
Post upgrade, you can change the storage type to Amazon S3 or Windows Azure Blob Storage from the
Capture Cloud Storage tab by running the Configuration Utility. See the Kofax TotalAgility Configuration
Utility Guide .
Upgrade TotalAgility in silent mode
See Upgrade TotalAgility in silent mode
.
Upgrade process
You can choose to upgrade TotalAgility components and databases independent of each other or upgrade
TotalAgility components including databases.
1.
Navigate to TotalAgility Installation media and install a base version of TotalAgility.
2.
Navigate to TotalAgility 7.9.0 Installation media and double-click Setup.exe
.
3.
In the Kofax TotalAgility Upgrade window, you can upgrade the following:
• TotalAgility components
• TotalAgility databases
• TotalAgility components including databases
If any errors occur during upgrade, by default, TotalAgility creates a log file
(KofaxTotalAgilityInstallErrorLog) at the following path on the TotalAgility installation media: \
\TotalAgilityInstall\KofaxTotalAgilityInstallErrorLog . Fix the errors.
Upgrade TotalAgility components
To upgrade TotalAgility components such as License Proxy, TotalAgility Designer and Transformation
Server, perform the following steps.
1.
In the Kofax TotalAgility Upgrade window, select TotalAgility components .
185
Kofax TotalAgility Installation Guide
2.
By default, the services are automatically started. To start services manually, clear the check box for
Automatically start services and click Next .
The Credentials window opens.
3.
Enter the credentials (password and confirm password) and click Next .
The Installation Review window opens. Review the settings and click Next to start the installation.
4.
Click Finish to complete the installation.
If any errors occur during upgrade, by default, TotalAgility creates a log file
(KofaxTotalAgilityInstallErrorLog) at the following path on the TotalAgility installation media: \
\TotalAgilityInstall\KofaxTotalAgilityInstallErrorLog . Fix the errors.
After upgrading TotalAgility components, if you also want to upgrade Kofax TotalAgility databases, do the following: a.
Navigate to TotalAgility Installation media and double-click Setup.exe
.
The Repair/Uninstall/Upgrade Databases window opens.
Note Alternatively, you can select the Upgrade Databases option from the Repair/Uninstall/
Upgrade Databases window by clicking Start > All Programs > Kofax TotalAgility and select
Uninstall or Repair Kofax TotalAgility.
b.
Select Upgrade Databases .
c.
Click Next and follow the instructions.
Upgrade TotalAgility databases
Follow the steps to upgrade only TotalAgility databases.
1.
In the Kofax TotalAgility Upgrade window, select TotalAgility databases .
2.
By default, the services are automatically started. To start services manually, clear the check box for
Automatically start services .
3.
To import the Workspace package, select the check box for Import system Workspace Package and click Next . (Default: Clear)
When upgrading TotalAgility from version lower than 7.8.0 to 7.9.0, clicking Next will display a pop-up
message recommending to check for latest updates to perform capture data migration.
The Credentials window opens.
4.
Enter the credentials (password and confirm password) and click Next .
The Installation Review window opens. Review the settings and click Next to start the installation.
5.
Click Finish to complete the installation.
If any errors occur during upgrade, by default, TotalAgility creates a log file
(KofaxTotalAgilityInstallErrorLog) at the following path on the TotalAgility installation media: \
\TotalAgilityInstall\KofaxTotalAgilityInstallErrorLog . Fix the errors.
Upgrade TotalAgility components including databases
Follow the steps to upgrade TotalAgility components including databases.
1.
In the Kofax TotalAgility Upgrade window, select TotalAgility databases .
2.
By default, the services are automatically started. To start services manually, clear the check box for
Automatically start services .
186
Kofax TotalAgility Installation Guide
3.
To import the Workspace package, select the check box for Import system Workspace Package and click Next . (Default: Clear)
When upgrading TotalAgility from version lower than 7.8.0 to 7.9.0, clicking Next will display a pop-up
message recommending to check for latest updates to perform capture data migration.
The Credentials window opens.
4.
Enter the credentials (password and confirm password) and click Next .
The Installation Review window opens. Review the settings and click Next to start the installation.
5.
Click Finish to complete the installation.
If any errors occur during upgrade, by default, TotalAgility creates a log file
(KofaxTotalAgilityInstallErrorLog) at the following path on the TotalAgility installation media: \
\TotalAgilityInstall\KofaxTotalAgilityInstallErrorLog . Fix the errors.
Check for latest updates to perform capture data migration
When upgrading TotalAgility databases and TotalAgility components including databases from version lower than 7.8.0 to 7.9.0, perform the following steps.
1.
In the Kofax TotalAgility Upgrade window, select TotalAgility databases .
2.
By default, the services are automatically started. To start services manually, clear the check box for
Automatically start services .
3.
To import the Workspace package, select the check box for Import system Workspace Package and click Next .
A pop-up message appears recommending to check for latest updates to perform capture data migration.
4.
Click Yes .
The Installation Review dialog box displays the following link for downloading the precheck updates for capture data migration.
https://edelivery.kofax.com/TotalAgility/7.9.0/MigrationPreCheck.ZIP
5.
Click the link to automatically download the MigrationPreCheck.zip to your local machine.
6.
Click Finish in the Installation Review dialog box.
7.
Run the utility, Agility.Install.ApplyCaptureMigrationUpdates.exe
located at the installation directory to replace the DLLs and script files.
The Capture Migration pop-up appears.
8.
Click Browse and select the Zip file location where the MigrationPreCheck.zip is downloaded and click OK .
The Capture Migration Updates Tool automatically extracts the zip and applies the updates into
TotalAgility installer.
9.
Click OK in the message.
10.
Navigate to TotalAgility 7.9.0 Installation media and double-click Setup.exe
to run the installation again
11.
Click No when prompted to check for the updates to perform capture data migration..
The Credentials window opens.
12.
Enter the credentials and continue with the upgrade.
If any errors occur during upgrade, by default, TotalAgility creates a log file
(KofaxTotalAgilityInstallErrorLog) at the following path on the TotalAgility installation media: \
\TotalAgilityInstall\KofaxTotalAgilityInstallErrorLog . Fix the errors.
187
Kofax TotalAgility Installation Guide
Upgrade TotalAgility databases manually using database scripts
When upgrading TotalAgility from 7.0.2, 7.1.0, 7.2.0, 7.3.0, 7.4.0, 7.5.0, 7.6.0, 7.7.0 or 7.8.0 to TotalAgility
7.9.0, do the following.
Note
• To upgrade the TotalAgility databases manually from version less than or equal to 7.7.0, you must run a special Migration Utility to complete the database upgrade. Please contact Kofax Technical
Support to request a copy of the Migration Utility and the appropriate instructions to complete a manual database upgrade.
• For a clean installation of TotalAgility 7.8.0, the Simulator database and any Simulator related SQL scripts are no longer available. On upgrading TotalAgility to 7.8.0 and higher, the connections to the
Simulator database are automatically removed.
1.
To run scripts manually, go to \\TotalAgilityInstall\DatabaseScripts\SQL Server
\Upgrade Database Scripts .
188
Kofax TotalAgility Installation Guide
2.
Run the conversion scripts (if exist) for all releases and patches starting from the version upgrading from to the version being upgraded to.
Example: If upgrading from 7.2.0.0 to 7.9.0, run the following conversion scripts.
• 7.2.0.0 to 7.2.1.0 Conversion Scripts
• 7.2.1.0 to 7.2.2.1 Conversion Scripts
• 7.2.2.1 to 7.3.0.0 Conversion Scripts
• 7.3.0.0 to 7.3.0.2 Conversion Scripts
• 7.3.0.2 to 7.3.1.0 Conversion Scripts
• 7.3.1.0 to 7.3.1.2 Conversion Scripts
• 7.3.1.2 to 7.4.0.0 Conversion Scripts
• 7.4.0.0 to 7.4.0.1 Conversion Scripts
• 7.4.0.1 to 7.4.1.0 Conversion Scripts
• 7.4.1.0 to 7.4.1.1 Conversion Scripts
• 7.4.1.1 to 7.5.0.0 Conversion Scripts
• 7.5.0.0 to 7.5.0.5 Conversion Scripts
• 7.5.0.5 to 7.5.0.10 Conversion Scripts
• 7.5.0.10 to 7.6.0.0 Conversion Scripts
• 7.6.0.0 to 7.6.0.5 Conversion Scripts
• 7.6.0.5 to 7.7.0.0 Conversion Scripts
• 7.7.0.0 to 7.7.0.1 Conversion Scripts
• 7.7.0.1 to 7.8.0.0 Conversion Scripts
• 7.8.0.0 to 7.9.0.0 Conversion Scripts
Run the scripts in the following order across databases and follow the instructions inside each script.
a.
Convert_Main.sql
on the TotalAgility database.
b.
Convert_Audit.sql
on the Audit database.
c.
Convert_Archive.sql
on the Finished Jobs database.
Note If Audit and Archive databases are maintained with the same name as the TotalAgility database, then run the Convert_Audit.sql
and Convert_Archive.sql
scripts on the
TotalAgility database.
d.
Convert_Forms.sql
on the TotalAgility database.
e.
Convert_KLS_OnPremise.sql
on the TotalAgility database.
f.
Convert_KFS.sql
on the TotalAgility database.
g.
Convert_DataLayer.sql
on the TotalAgility_Documents database.
h.
Run the following conversion scripts for the Reporting databases:
• KofaxReportingAnalytics.SQL_Convert.sql
on the TotalAgility_Reporting database.
• KofaxReportingAnalytics.Staging.SQL_Convert.sql
on the
TotalAgility_Reporting_Staging database.
189
Kofax TotalAgility Installation Guide
If the previous version of TotalAgility, such as TotalAgility 7.0.2 did not include reporting databases, you must first create the TotalAgility_Reporting database and the
TotalAgility_Reporting Staging database and update the Web.config file accordingly.
3.
Navigate to <C:\Program Files\Kofax\TotalAgility\Agility.Server.Web\bin> and open Agility.Installation.Server.Upgrade.exe.config
. In the <appSettings> section, update the value for the following settings.
• <add key="UpgradeFromVersion" value =""/> where the value is the TotalAgility version from which you want to perform an upgrade. For example, if you are upgrading TotalAgility from
7.7.0 to 7.8.0, set the value as follows: <key="UpgradeFromVersion" value ="7.7.0"/> .
• <add key="SystemSessionId" value="" /> . Take the system session ID from the
TotalAgility Designer or from the database.
• <add key="UserName" value="" /> where the user name is the currently logged on user's name.
4.
From the command prompt, run Agility.Installation.Server.Upgrade.exe
by passing the Agility.Installation.Server.Upgrade.exe <ImportWorkspacepackage> as a parameter, such as Agility.Installation.Server.Upgrade.exe false . If you want to import the Workspace package, pass the Agility.Installation.Server.Upgrade.exe
true as a parameter.
5.
Ensure that no error log is created. If any errors occur, a log file called
KofaxUpgradeDatabaseUtilityError.txt
is created on your desktop. Fix those errors and repeat the above steps.
6.
Start the Kofax TotalAgility Core Worker service manually: a.
At Run, type Services.msc
and press Enter .
b.
Right-click Kofax TotalAgility Core Worker and click Start .
Upgrade reporting databases 2.0.2
Run the following scripts to upgrade the Reporting databases 2.0.2 manually:
1.
Run the script from TotalAgilityInstall\DatabaseScripts\SQL Server\Upgrade
Database Scripts \ 7.0.2 -> 7.1.0
.
2.
Run the script from TotalAgilityInstall\DatabaseScripts\SQL Server\Upgrade
Database Scripts\ 7.1.0 -> 7.2.0
.
3.
Run the script from TotalAgilityInstall\DatabaseScripts\SQL Server\Upgrade
Database Scripts\ 7.2.0 -> 7.3.0
.
4.
Run the script from TotalAgilityInstall\DatabaseScripts\SQL Server\Upgrade
Database Scripts\ 7.3.0 -> 7.4.0
.
5.
Run the script from TotalAgilityInstall\DatabaseScripts\SQL Server\Upgrade
Database Scripts\ 7.4.0 -> 7.5.0
.
6.
Run the script from TotalAgilityInstall\DatabaseScripts\SQL Server\Upgrade
Database Scripts\ 7.5.0 -> 7.6.0
.
7.
Run the script from TotalAgilityInstall\DatabaseScripts\SQL Server\Upgrade
Database Scripts\ 7.6.0 -> 7.7.0
.
8.
Run the script from TotalAgilityInstall\DatabaseScripts\SQL Server\Upgrade
Database Scripts\ 7.7.0 -> 7.8.0
.
190
Kofax TotalAgility Installation Guide
9.
Run the script from TotalAgilityInstall\DatabaseScripts\SQL Server\Upgrade
Database Scripts\ 7.8.0 -> 7.9.0
.
Note If you are upgrading from TotalAgility 7.1.0 to 7.9.0 (with Reporting as a part of TotalAgility
7.8.0), ensure that all the Reporting Staging database tables are empty before performing any automatic or manual upgrade.
See also:
•
•
Upgrade TotalAgility in silent mode
Upgrade TotalAgility in silent mode
Before upgrading TotalAgility from version 7.7.0 to 7.9.0 (any upgrade which includes databases, and components including databases) in silent mode, you must click the following link for downloading the precheck updates for capture data migration.
https://edelivery.kofax.com/TotalAgility/7.9.0/MigrationPrecheck.ZIP
After downloading the zip, run the utility Agility.Install.ApplyCaptureMigrationUpdates.exe which is located at the installation directory to replace the DLLs and scripts.
For a silent upgrade of TotalAgility to version 7.9.0, do the following.
1.
Go to the root directory of setup.exe.
2.
Navigate to \\TotalAgilityInstall and open SilentInstallConfig.xml using a text editor.
3.
In SilentInstallConfig.xml, update the following parameters.
Default value Description Parameter
Identity Information
UserName username
Password password
Enter the name of the user who will run
TotalAgility.
Enter the password for the user who will run
TotalAgility.
Install Info
InstallAction upgrade Use this setting to upgrade TotalAgility components including databases.
191
Kofax TotalAgility Installation Guide
Parameter Default value Description upgradeTotalAgilitydatabases Use this setting only if you are upgrading the databases before upgrading TotalAgility components.
Note If you wish to upgrade TotalAgility components before upgrading databases, you must do the following: a.
Open SilentInstallConfig.xml
available at the following location:
\\TotalAgility
Installation Information
\Kofax TotalAgility b.
Update the <InstallAction> section with the following parameter: <InstallAction> =Upg radedatabasesforexistingTotalAgil ity c.
Run Setup.exe /Silent /U from the above mentioned path.
upgradeTotalAgilitycomponents Use this setting to upgrade only TotalAgility components.
DatabaseInformation
IgnoreBrokenFoldersOnUpg rade
RunCaptureMigrationIgnoring
Errors
StartServices
ImportWorkspacepackage false false true false
If broken data is found during migration, the upgrade is failed.
If set to true, ignores broken folders and proceeds with capture data migration when upgrading TotalAgility.
If errors occur during migration, the root folders with broken data will not be migrated.
If set to true, ignores the errors and proceeds with capture data migration.
Starts the services automatically after upgrade installation.
Set to false to start the services manually after upgrade installation.
Set to true to import the Workspace package after upgrade installation.
Note Review the Kofax TotalAgility
Release Notes to import the required updates for the Workspace package.
4.
Open the Command Prompt window as an Administrator and change the command line to the root directory of the Setup.exe file.
192
Kofax TotalAgility Installation Guide
5.
Run Setup.exe /Silent /Upgrade .
Based on the parameters set to true in the silent configuration file, the following items are upgraded automatically:
• Kofax TotalAgility
• Kofax Import Connector (KIC)
• Kofax Transformation Designer
• Utility for Kofax Export Connector
The system generates a log file which reports errors (if any).
The success or failure of installation is indicated in the event log.
6.
Save and close the file.
See also:
•
•
Upgrade Message Connectors instances
If you have installed more than one instance of Message Connector, you must upgrade all the instances of
Message Connector at the time of upgrading TotalAgility. Do the following:
1.
To upgrade the first instance of Message Connector, before upgrading TotalAgility, set the value of ImportService parameter to true in SilentInstallConfig.xml. See
Upgrade TotalAgility in silent mode .
2.
To upgrade the second instance of Message Connector, run the following command on the
Command Prompt:
<\\TotalAgility\KIC\Export\MC\MC.msi> TRANSFORMS=:I02 MSINEWINSTANCE=1
KOFAX="<path>" <options>
Where, <\\TotalAgility\KIC\Export\MC\MC.msi
> is the path of TotalAgility setup folder.
In <path>, specify the upgrade path for second instance of Message Connector. \KIC-ED\MC02 is appended to this path at the time of upgrade.
3.
To upgrade the third instance of Message Connector, run the following command on the Command
Prompt:
<\\TotalAgility\KIC\Export\MC\MC.msi> TRANSFORMS=:I03 MSINEWINSTANCE=1
KOFAX="<path>" <options>
Where, <\\TotalAgility\KIC\Export\MC\MC.msi> is the path of TotalAgility setup folder.
In <path>, specify the upgrade path for third instance of Message Connector. \KIC-ED\MC03 is appended to this path at the time of upgrade.
Note For second and third instances of message Connector, optionally, in <options> use the following command options:
• /qn - silent installation
• /qb - silent installation with elementary user interface (progress bar)
• ALLUSERS=1 - install for all users
193
Chapter 20
Troubleshooting
This section describes the issues you may encounter and their resolution.
TotalAgilityAppPool exists
TotalAgility creates an application pool called TotalAgilityAppPool. Ensure you do not have an existing application pool of the same name as it may cause issues when installing or upgrading.
Download software updates
When downloading an installation package or a service pack from ftp.kofax.com site, please ensure this site is added as a trusted site, otherwise the downloaded file may get corrupted.
Installation failure in IPv4 and IPv6 environment
If SQL server is configured to listen only on IPv6 addresses on a dual-stack (IPV46), client connection attempts using IPv4 address will fail and it may take longer than default timeout, contributed by default
TCP timeout logic during connection establishment handshakes. Even though the subsequent IPv6 connection can succeed immediately, the connection may still fail.
To resolve this issue, disable IPv4 in SQL Server Configuration Manager.
1.
Start SQL Server Configuration Manager .
2.
Open the Properties for the TotalAgility server instance TCP/IP protocol.
3.
Set Listen All to No .
Note This setting allows fine control over which interfaces the TAServerSQLInstance will listen for connections.
4.
Click the IP Address tab.
5.
Set Enabled to No for all entries except for ::1 which is the IPv6 local host address.
6.
Select OK to commit changes and OK at the service restart dialog.
7.
Restart the SQL Server (<TAServerInstance>) service where TAServerInstance is the actual instance used by TotalAgility (for example, Kofax TotalAgility).
194
Kofax TotalAgility Installation Guide
Images not displayed in Workspace after scanning
No images are displayed on Workspace after scanning if you log into machine as non-admin user. The images display normally if you login as admin user.
1.
If you have not installed DosadiLog, the diagnostic logging tool for the WebCapture plugin, please do so now. See the instructions and download link at: http://www.eztwain.com/dosadilog.htm
.
2.
Edit the <system.diagnostics> section of the Web.config file as follows:
Note If you copy and paste the code from this guide, fix the line breaks.
<system.diagnostics>
<!--<sources>
<source name="System.ServiceModel" switchValue="Information, ActivityTracing" propagateActivity="true">
<listeners>
<add name="traceListener" type="System.Diagnostics.XmlWriterTraceListener" initializeData= "c:\log\Traces.svclog" /> </listeners> </source> </sources>-->
<trace autoflush="true">
<listeners> <add name="ThinClientServer" traceOutputOptions="DateTime,ThreadId" type="System.Diagnostics.TextWriterTraceListener" initializeData="c:
\ThinClientServerLog.txt">
<filter type="System.Diagnostics.EventTypeFilter" initializeData="Verbose" /> </ add>
<!--<add type="Microsoft.WindowsAzure.Diagnostics.DiagnosticMonitorTraceListener,
Microsoft.WindowsAzure.Diagnostics, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35" name="AzureDiagnostics">
<filter type="" />
</add>-->
</listeners>
</trace>
</system.diagnostics>
3.
To ensure that non-admin users are able to log in, add the link to Trusted Sites: a.
Go to Internet Options in IE 11.
b.
Click the Security tab.
c.
Click Sites .
d.
Add the domain to the trusted sites, for example, http://<domain>.
Exception during Transformation Designer projects import
An exception is thrown while importing projects using Transformation Designer that connects to a
TotalAgility web service that uses SSL.
1.
If you select to run your server using SSL, make sure the Client certificates option is set to Ignore under SSL Settings.
195
Kofax TotalAgility Installation Guide
2.
If you want to use Client certificates for authentication (Accept or Require), you must set the value for uploadReadAheadSize in IIS. Use either option to adjust this setting:
• In the IIS Manger: a.
Open the Configuration Editor of the TotalAgility site.
b.
In the Section list, expand system.webServer and select serverRuntime .
c.
In the From list, select ApplicationHost.config <location path=’Default Web Site/
Totalgility’/> .
d.
Set an appropriate value in bytes for uploadReadAheadSize .
• Or, modify the IIS main config file: a.
Open the applicationHost.config
file located under C:\Windows\System32\inetsrv
\config\ .
b.
If the <serverRuntime> node does not exist yet, add it below the <security> node within
<system.webServer>.
<location path="Default Web Site">
<system.webServer>
<security>
…
</security>
<serverRuntime uploadReadAheadSize="10485760" />
</system.webServer>
</location> c.
Set an appropriate value in bytes for uploadReadAheadSize .
Search feature not working in TotalAgility help
• The TotalAgility Help Search functionality does not work when Designer is run from Start > All
Programs .
To resolve this issue, add the site as a trusted site in Internet Explorer: Internet Options > Security >
Trusted Sites > Sites
196
Kofax TotalAgility Installation Guide
• The TotalAgility Help Search functionality does not work in Designer and Workspace for Internet
Explorer 9.
To resolve this issue, navigate to Tools > Compatibility Settings in Internet Explorer 9 and clear the following two options:
• Include updated website lists from the Microsoft
• Display intranet sites in Compatibility View
Site location invalid error
SharePoint security issues can occur when the TotalAgilitySharePointCommunicator web service hosted in IIS does not have permission to access the SharePoint site in IIS. This can cause a "Site location is invalid" error when integrating TotalAgility with SharePoint.
To resolve this issue:
1.
Ensure the TotalAgilitySharePointCommunicator web service is running under the same application pool as your SharePoint site. Depending on the security trust level within SharePoint, TotalAgility can cause communication failures between TotalAgilitySharePointCommunicator and SharePoint due to permissions.
2.
Turn off ASP impersonation on the TotalAgilitySharePointCommunicator web service in IIS (if enabled); ASP impersonation is not supported by the SharePoint application pool and may cause permission issues with remote SharePoint and TotalAgility servers.
(405) Method not allowed error
While Installing TotalAgility, the error "(405) Method Not Allowed" may occur.
To resolve the issue, re-register ASP.NET 4.x for IIS.
1.
Open the command prompt.
2.
Navigate to %WINDIR%\Microsoft.NET\Framework\v4.0.30319 .
3.
Execute aspnet_regiis.exe-i .
MimeType error
When trying to access the Tenant Management or TotalAgility websites from the IIS, and the web page does not render with the following error: Cannot add duplicate collection entry of type mimeMap with unique attribute field Extension set to .xap
; this means there are conflicting mime types in two different configuration files (for example, one at the application level and the other at the site level).
To resolve this issue, do either of the following:
1.
Remove one of the two conflicting mimeMap extensions from the configuration files.
2.
If the IIS Administrator needs both the conflicting mime mappings, add the remove tag above the conflicting mimemap.
Example If your application has the following mimemap in the application level configuration file:
<mimeMap fileExtension=".xap" mimeType="application/octet-stream" /> (for example, located at //inetpub/wwwroot/web.config
); if this mimemap creates a conflict with
197
Kofax TotalAgility Installation Guide the same mimemap in the applicationhost.config file, add <remove fileExtension=".xap" /> above the mimemap as follows:
<remove fileExtension=".xap" />
<mimeMap fileExtension=".xap" mimeType="application/octet-stream" /> where .xap is the mime type.
198
advertisement
Key Features
- Perform a silent installation
- Install TotalAgility in a Docker container
- Database Only option
- Upgrade databases
- Install both Web and Application on the same server
- Install on a separate Web or Application server
- Install Real Time Transformation Server
- Install multiple instances of Message Connectors
- Standard installation
- Express installation
Related manuals
Frequently Answers and Questions
Where I can found help with Kofax products?
What is the default installation?
Can I perform a silent installation?
advertisement