Skip to main content

Steps to consider before upgrading to Kofax TotalAgility 7.8 or above

Article # 3035587 - Page views: 51

Article # 3035587 - Page views: 51


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: 


f you click Yes, it will redirect to a link to download the latest version:


Simply, download the and run the \\InstallationMedia\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 prior to upgrading to verify if any 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, or above, 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 \\InstallationMedia\TotalAgilityInstall\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 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">
          <clear />
          <add name="Migration" />
      <source name="Kofax.CEBPM.DataLayer" switchName="TraceLevelSwitch">
          <clear />
          <add name="Migration" />
  1. Within the \\InstallationMedia\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" />

<unity xmlns="">
      <!--KTA Logging - uncomment the below tag to enable logging of method calls-->
      <extension type="Agility.Server.Common.Logging.LogMethodRegistration, Agility.Server.Common, Version=, 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 \\InstallationMedia\TotalAgilityInstall folder.  

If for any reason the upgrade reports an error, please raise a support case and attach the KofaxTotalAgilityInstallErrorLogCEBPMDatabaseErrorLog 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.

*NOTE: From v7.9, the location of the Installation Error logs is defined in \\InstallationMedia\TotalAgilityInstall\Setup.exe.config
By default, it is written to the \\InstallationMedia\TotalAgilityInstall folder

System Recommendations

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.

Level of Complexity 


Applies to  

Product Version Build Environment Hardware
Kofax TotalAgility v7.8 +      



  • Was this article helpful?