I would like to know steps to consider when performing an upgrade to KTA 7.8 or above.
The KTA 7.8 or above upgrade now performs capture data migration to the new improved Documents database architecture via the Setup.exe.
The setup.exe now has the functionality to upgrade the Databases Only, and the scripts can be reviewed in the Upgrade Database Scripts folder.
The Agility.Installation.Server.Upgrade.exe existed before 7.8 which had to be manually executed during the manual upgrade approach. Setup.exe now allows customers to perform these tasks automatically on any host (including the SQL server) with the upgrade Databases Only option. This has the added benefit of running locally on the SQL host machine reducing any network latency as it can pipeline large amounts of data from and to the databases.
Note: If you plan on running the upgrade scripts manually, this is not typically recommended as the setup.exe automatically runs the Upgrade.exe and capture data migration.exe executables to initialize data post upgrade scripts. In special conditions, Technical Support can provide the capture data migration executable to allow you run the upgrade scripts manually, however its generally not recommanded and does not ship with the KTA application.
With any upgrade, we recommend fully backing up and restoring the platform databases on a consistent test system prior to validate the data and procedures. This will assist with verifying the upgrade will be successful when upgrading your live system.
Validate found data integrity inconsistencies
The KTA 7.8 R2 or above setup.exe prompts to recommend checking for the latest capture data migration version:
If you click Yes, it will redirect to a link to download the latest version:
Simply, download the MigrationPreCheck.zip and run the \KofaxTotalAgility-7.8.0_R2\TotalAgility\TotalAgilityInstall\Agility.Install.ApplyCaptureMigrationUpdates.exe to replace the dll and script files and run the installation again. This will ensure you have the most updated Capture Migration updates.
Note: It is possible to run the MigrationPreCheck\MigrationPreCheck.sql on your TotalAgility Documents database proir upgrading to verify if data inconsistencies exist.
If the query returns broken binary data results, please do not proceed any further and raise a Kofax support case with the results, so we can review.
Also, we would recommend the capture data clean up task has emptied the PendingDeletes tables (if exist in your version) before upgrading to KTA 7.8, otherwise detached data may linger on the binary table.
Enable extended logging
1. Please enable the migration log using the following diagnostic's section within the 7.8 TotalAgility/setup.exe.config and rerun the DB upgrade,
For Tenant upgrade, please make these changes in the \\TotalAgility\CoreWorkerService\Agility.Server.Core.WorkerService.exe.config:
<trace autoflush="true" />
<!-- trace levels: Off, Critical, Error, Warning, Information, Verbose, ActivityTracing, All
see http://msdn.microsoft.com/en-us/library/ms733025.aspx for additional details -->
<add name="TraceLevelSwitch" value="All" />
<add name="Migration" initializeData="c:\temp\Migration.log" type="System.Diagnostics.TextWriterTraceListener" traceOutputOptions="ThreadId,DateTime" />
<!-- Main Data Layer trace source - contains majority of important log statements -->
<source name="Kofax.TotalAgility.CaptureDataMigration" switchName="TraceLevelSwitch">
<add name="Migration" />
<source name="Kofax.CEBPM.DataLayer" switchName="TraceLevelSwitch">
<add name="Migration" />
2. Within the KofaxTotalAgility-7.8.0\TotalAgility\TotalAgilityInstall\Agility.Server.Web\bin\Agility.Installation.Server.Upgrade.exe.config, add the following section (Verify the listener name is KTALog)
For Tenant upgrade, please make these changes in the \\TotalAgility\Agility.Server.Web.TenantManagement\web.config:
<trace autoflush="true" indentsize="4">
<add name="KTALog" type="System.Diagnostics.TextWriterTraceListener" initializeData="c:\temp\UpgadeDatabaseFile.log" />
<remove name="Default" />
<!--KTA Logging - uncomment the below tag to enable logging of method calls-->
<extension type="Agility.Server.Common.Logging.LogMethodWithIORegistration, Agility.Server.Common, Version=184.108.40.206, Culture=neutral, PublicKeyToken=d86c87abe4a71948" />
<!--Start of Repositories-->
Verify that the folder path for the log location exists. (C:\Temp in this example)
Fully back up and run the upgrade Setup.exe
Fully back up all databases and virtual machines as appropriate prior.
The setup.exe can be found in the KofaxTotalAgility-7.8.0\TotalAgility\TotalAgilityInstall folder. If for any reason the upgrade reports an error, please raise a support case and attach the KofaxTotalAgilityInstallErrorLog, CEBPMDatabaseErrorLog from the desktop of the account running the upgrade. If you have enabled the above extended logging, please also attach the UpgadeDatabaseFile.log and Migration.log.
The more memory the upgrade machine has, the more efficient it will be. The same applies for CPU, the more cores, the more efficient migration can go as it benefits from parallelization of data reading. Minimum system requirements are the same as for the KTA installer. However, if you are upgrading directly on the SQL server, ensure AvailableMemory is below 85% using the SQL maximum server memory property.