Skip to main content

Kofax TotalAgility:Steps to consider prior upgrading to KTA 7.8


I would like to know steps to consider when performing an upgrade to KTA 7.8.   
The KTA 7.8 upgrade requires the Setup.exe to perform the capture migration to the new improved Documents database architecture.  

The setup.exe now has the functionality to upgrade the Databases Only, it is no longer supported to run the scripts manually.
However, they 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. 

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

First some context, the capture migration process can migrate only consistent data. If for some reason folders exist in an inconsistent state (eg SQL failures causing non-existing objects), these folders cannot be migrated and therefore the UI will present the following:

o    List of broken root folder IDs is presented to the user.
o    User is able either stop upgrade (which means the upgrade is failed). New upgrade can be re-started after the database is reverted.
o    Or user can skip these and continue. In this case the found root folders will never be migrated and basically won’t exist in new system.
•    If upgrade is running without UI (silent installation):
o    By default, if broken objects found the upgrade is failed. List of found root folder IDs is dumped to log file.
o    User can provide additional parameter that allows to continue the upgrade regardless found broken folders. In this case, the found root folders will never be migrated and basically won’t exist in new system.

Also, we have found cases where unexpected data existed. In this case, please run the following SQL queries to validate if this type of data exists in your databases:

-- This query counts should be the same.

select count(*) from BinaryData
select count(distinct sqlpath) from binarydata

--This query should not return any document ids. The count return value can be ignored.

select FileId, COUNT(Id) as CountOfDocs from Document
group by FileId

having COUNT(Id) > 1

--This query should not return any rows.

select sqlpath,fileid from BinaryData where sqlpath in
(select sqlpath from BinaryData group by sqlpath having count(*) > 1)

If any of the above queries return unexpected results, please do not proceed any further and raise a Kofax support case so we can review.

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:

    <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" />

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)

<trace autoflush="true" indentsize="4">
<add name="KTALog" type="System.Diagnostics.TextWriterTraceListener" initializeData="c:\temp\UpgadeDatabaseFile.log" />
<remove name="Default" />

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.

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.