Upgrading to a new version of Datacap

Edit online

Upgrade Datacap to a new product version. Upgrade database schemas, upgrade customized Datacap applications and screen panels. Test the new environment and troubleshoot.

Before you begin

  • Review the Software Product Compatibility Reports for supported operating systems, related software, and hardware.
  • Complete all Datacap batches.
  • Close all Taskmaster client applications.
  • Stop the Datacap Server service, Web services, Rulerunner services, Fingerprint services, and Maintenance (NENU) services.
  • Back up existing objects to a temporary location:
    • Administration, Engine, and Fingerprint database tables
    • Custom applications (including any standard applications that you modified)
    • Custom actions
    • RuleRunner configuration files (RuleRunner.xml)
    • The datacap.xml file

About this task

The following tasks provide an upgrade path from any version V8.0.1 and later to any later version. You can upgrade from Taskmaster version V8.0.1 or V8.1 to any Datacap V9.x version. You can upgrade from any Datacap V9.x version to any later Datacap V9.x version.

Restriction: Upgrade from an earlier version to a later version. You cannot upgrade from a later version to an earlier version.

The starting version and ending version can include fix packs but do not require that fix packs are applied.

Test the new Datacap system in a test environment. When you are satisfied with the performance of the test environment, make the test environment your production environment.
Note: Datacap not support calling any of Datacap actions from a custom action.

The following example is used to call any Datacap action in combination with a custom action in a rule in an application in Datacap Studio.

- Rule
-- Function
---- CustomAction1()
---- RecognizeFieldOCR_A()
---- CustomAction2()

Where, CustomAction1() is the set of custom actions to be run before the Datacap action, RecognizeFieldOCR_A() is the Datacap action, and CustomAction2() is the set of custom actions to be run after the Datacap action.

Install the target version of Datacap

Edit online

About this task

For detailed installation information, see Installing.

Procedure

  1. If your target version is V9.0.1 or a later version and your current system has V9.0.0 or an earlier version, you must uninstall the old version.

    If your target version is V9.0.0 or an earlier version, you do not have to uninstall the old version of Datacap. If your version before migration is V9.0.1 or a later version, you do not have to uninstall the old version of Datacap.

    If you install Datacap V9.0.1 or later without uninstalling the V9.0.0 or earlier version, you can repair the system by completing the following task: Repairing your upgraded Datacap system when a required uninstall did not occur: From V9.0.0 or earlier to V9.0.1 or later.

  2. If you install the new Datacap version over an existing Datacap system, you must roll back the old system to all the original modules before you upgrade.
    Original modules are those modules that were installed with your old modification level or interim fix. Test fixes can create issues when you upgrade. If you do not eliminate test fix changes, the new installation might omit required modules.
  3. Install the target version of Datacap, including the target interim fix.
  4. Review the installer log file and confirm that no errors occurred.
    The installer log file is typically in C:\Users\account\AppData\Local\Temp\ or a subfolder.

Configure the environment

Edit online

Procedure

  • Confirm that the user credentials are valid for running Datacap Taskmaster Service.
  • Reconfigure Datacap accounts and groups that are based on your authentication system.
  • Set up sharing and security permissions for users, Datacap folders, and Datacap applications.
  • Confirm FIPS encryption.
    You must have FIPS encryption for password protection when your target version is V8.1.0 or a later version. For more information, see Importing encryption keys to Datacap computers.
    Note: Previously generated encryption keys in the keystore are preserved and need not be generated again.
    Troubleshooting
    Error: Unable to get key from keystore. Encountered when you migrate from V8.x.
    Solution: See technote Key not valid for use in specified state in IBM® Datacap Taskmaster Capture.

Upgrade database schemas

Edit online

About this task

Db2®, Oracle, and SQL databases
Databases schemas are upgraded in V9.0.1, V9.1.5, and V9.1.7. If your upgrade crosses one of those versions, you must upgrade to database schemas that are compatible with the new version of Datacap. If your upgrade does not cross any of those versions, no database upgrade is required.

You can upgrade old Db2, Oracle, or SQL databases to be compatible with the new version of Datacap. Datacap provides scripts that upgrade the schemas of existing databases. For more information, see Upgrading Db2, Oracle, or SQL databases for Datacap applications.

Microsoft Access databases

From V9.0 onward, Datacap provides Microsoft Access databases that contain appropriate schemas for each Datacap version. The Access databases support the Datacap standard, non-customized applications. For standard applications, no database upgrade is required.

For customized applications, you must add your database customizations to a database that is compatible with the new Datacap version. For more information, see Upgrading Microsoft Access database schemas for customized Datacap applications .

Upgrade Datacap applications

Edit online

Procedure

  • Reconfigure connection strings to applications in Datacap Application Manager (where applicable).
  • Use Datacap Application Wizard to convert any customized applications to the target version.
    For more information, see Upgrading customized Datacap applications to run in a new product version.
    Tip: The Application Wizard conversion task might contain erroneous version information. For example, although the task might be labeled "Convert an 8.1 application to a 9.0.1 application", the conversion is from your earlier version to the currently installed version of Datacap.
  • Upgrade compiled rulesets. For more information, see Upgrading compiled rulesets to a new version of Datacap.

Upgrade customized screen panels

Edit online

Procedure

Upgrade customized screen panels
  • If your version before migration is V9.0.0 or later, complete the following task:

    Rebuild Datacap Desktop customized screen panels by using the Datacap Developer Kit (DDK) for the target product version. In some cases code modifications are required.

  • If your version before migration is V8.1 or earlier and your target version is V9.0.0 or later, complete the following task:

    Datacap V9.0.0 and later requires Datacap Desktop screen panels. No utility can automatically convert Batch Pilot panels or DotEdit panels to Datacap Desktop panels. You must manually create custom panels by using the Datacap Developer Kit (DDK) for the target product version. For more information, see Customized panel conversion to Datacap Desktop.

    Troubleshooting
    Issue: When you convert an older framework custom panel to Datacap Desktop, you receive a "file not found exception. For example, in Creating the Datacap Desktop in Microsoft Visual Studio, step 4 ("In the Layout XML field, click Browse and select the XML file that you generated"), you receive the "file not found" exception.
    Solution: Complete the following steps:
    1. In Visual Studio, open the DCDesktopPanels solution that contains the DotEditPanels project.
    2. Set the path to your project by editing the file dotMaster.cs and locate the following line in the file: string sProjectRoot = "";
    3. Update the empty string with the full path to the directory that contains your project and save the file.

    The solution and details for creating Datacap Desktop customized screen panels is in the PDF format Desktop Custom Panels guide in the DDK package.

Datacap Developer Kit (DDK):

Plan and test

Edit online

Procedure

  • Check for issues with customized .NET actions.
    In Datacap Studio, determine whether any customized .NET actions yield errors. If necessary, rebuild and reinstall customized .NET actions.
  • Check for deleted and deprecated actions.
    In Datacap Studio, determine whether any rules or actions that are used by your customized applications are eliminated, renamed, or deprecated in the new version. Modify customized settings as needed.

    IBM Knowledge Center and product readme files typically list eliminated, renamed, and deprecated actions for each version. Consider the eliminated, renamed, and deprecated actions in all versions from your version before migration to your target version.

  • Evaluate Datacap engines to determine optimal processing for your types of documents.
    New features are added to Datacap over time. The optimal engine for processing your types of documents in the Datacap target version might be different from what was optimal in the old version. For more information, see Best Practices for optimal text recognition in IBM Datacap. You can run tests on data with different engines, different settings, and different image enhancement features. Determine find the combination that produces the best results for your documents.

Troubleshooting upgrades

Edit online

The following issues can occur during an upgrade. Possible solutions are provided.

Error: "Could not locate RRX code Barcode_x" when you run Batch Profiler. Noted when migrating from V9.1.3 to V9.1.4.
Solution:
Copy PageID.rrx from the target version of the APT application to the Migrated copy of APT applications that are connected to Oracle/SQL/DB2® databases in the rules folder.
Error when you run a batch: Action execution failed; Type mismatch.
Example:
Error message:
Microsoft VBScript runtime error - Type mismatch.
Cause
Rules are modified in Validations.dll. At the time that the function was created, an action of the same name AllowOnlyChars existed in invoice.rrx & validations.rrx.
Solution:
Create a private function called Characterizations. Modify Invoice and Validations actions to call the private function.
Error: Unable to connect to admin database or engine database.
Explanation:
You attempt to log in by using Taskmaster Web or another Datacap client. You get an error message that you are unable to connect to the admin database or the engine database. 
Solution:
See technote Unable to connect to admin database with IBM Datacap Taskmaster Capture.
Error: Any of the following actions libraries access errors, typically when you update from V8.x:
Could not load file or assembly
Action parameters don't match RRX specification.  
Error retrieving RRX library description: "Couldn't access action library".  
Possible solutions:
In Datacap Studio, the workflow in the Test tab is blank
Solution:

Use DBCopy to copy all data from Microsoft Access database to a new database.

In Application Manager all fields are unavailable. Encountered when you migrate from V8.x.
Possible solutions:
Batches hang or stop before completion due to an out-of-memory condition.
Solution:
Replace Datacap 32-bit actions with Datacap 64-bit actions. 64-bit actions are available in Datacap V9.1.6 and later versions.
Warning 1946.Property ‘{9F4C2855-9F79-4B39-A8D0-E1D42DE1D5F3}, 12' for shortcut 'Datacap Accounts Payable Demo Vendor Tool.lnk' could not be set.
Cause:
The warning can occur if you did not add the APT application in the Custom Setup menu of the Datacap installer. A similar message can occur if you did not add the Medical Claims application during installation. Noted during upgrade from V8.x.
Solution:
Install again and include the APT application.