KofaxCapture 8 0 Dev Guide

KOFAX
Capture
Developers Guide
10300626-000 Rev A
1994 - 2008 Kofax Image Products, Inc., 16245 Laguna Canyon Road, Irvine, California 92618, U.S.A. All rights reserved. Use is subject to license terms. Third-party software is copyrighted and licensed from Kofaxs suppliers. This product includes software developed by the Apache Software Foundation (http://www.apache.org/). This product is protected by U.S. Patent No. 6,370,277. THIS SOFTWARE CONTAINS CONFIDENTIAL INFORMATION AND TRADE SECRETS OF KOFAX IMAGE PRODUCTS, INC. USE, DISCLOSURE OR REPRODUCTION IS PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF KOFAX IMAGE PRODUCTS, INC. Kofax Image Products, Kofax, the Kofax logo, VirtualReScan, the VRS VirtualReScan logo, and VRS are trademarks or registered trademarks of Kofax Image Products, Inc. in the U.S. and other countries. All other trademarks are the trademarks or registered trademarks of their respective owners. U.S. Government Rights Commercial software. Government users are subject to the Kofax Image Products, Inc. standard license agreement and applicable provisions of the FAR and its supplements. You agree that you do not intend to and will not, directly or indirectly, export or transmit the Software or related documentation and technical data to any country to which such export or transmission is restricted by any applicable U.S. regulation or statute, without the prior written consent, if required, of the Bureau of Export Administration of the U.S. Department of Commerce, or such other governmental entity as may have jurisdiction over such export or transmission. You represent and warrant that you are not located in, under the control of, or a national or resident of any such country. DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
Contents
How to Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi Kofax Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Why You Would Customize Kofax Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Customize Kofax Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the API Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Implement Your Customized Scripts and Modules . . . . . . . . . . . . . . . . . . 1 1 2 2 3 3
Creating Custom Scripts Using SBL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Validation Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Writing a Validation Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 How Validation Scripts are Processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Field Type Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Testing Validation Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Differences Between SBL and Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 About SBL Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Validation Script Return Codes and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Recognition Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing a Recognition Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Recognition Scripts are Processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recognition Script Return Codes and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 19 20 21
Creating Custom Scripts Using VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Kofax Capture 8 Developers Guide
iii
Contents
Creating a Validation Script in VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Choosing the Scripting Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Kofax Capture .NET Scripting API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 VB .NET Project File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Deployment of a VB .NET Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Publishing Requirements for the Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Sample VB .NET Validation Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Sample Validation Script Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Testing VB .NET Custom Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Error Handling in VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 FatalErrorException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 RejectAndSkipDocumentException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 ValidationErrorException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Creating a Recognition Script in VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Choosing the Scripting Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Kofax Capture .NET Scripting API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Sample VB .NET Recognition Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Field Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Sample VB .NET Field Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4 Creating a Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Format for the Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 [Modules] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 [Module Name] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 [Workflow Agents] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 [Workflow Agent Name] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 [Setup Programs] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 [Setup] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 [Menu] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 [Menu Bar] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Example Registration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Example 1: Registering Two Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . 52 Example 2: Defining a Menu for the Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . 53 Example 3: Defining Context Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Example 4: Defining a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Using the Administration Module to Manage Extensions . . . . . . . . . . . . . . . . . . . . . . . 58 Managing Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Registering a Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Viewing Properties for a Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Removing a Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
iv
Contents
Managing Workflow Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Properties for a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Kofax Capture Extension Registration Utility . . . . . . . . . . . . . . . . . . . . . . . . Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input File [/f {filename}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Output File [/o {filename}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module Name [/m {module name}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow Agent Name [/w {workflow agent name}] . . . . . . . . . . . . . . . . . . Setup Programs [/x {setup program name}] . . . . . . . . . . . . . . . . . . . . . . . . . . . Runtime Programs [/r {runtime program name}] . . . . . . . . . . . . . . . . . . . . . . Unregister [ /u ] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Silent Mode [ /s ] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage [ /? ] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Proper Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error and Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
64 64 66 68 69 69 70 70 70 70 71 71 71 71 72 72 72 72 73
Creating a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Designing a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Implementing the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Writing the Runtime Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Code Project Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing the Kofax Capture API Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Project Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow Agent Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow Agent Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inherit the IACWorkflowAgent Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 77 77 78 78 78 79
Creating the Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Format of the Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Registering the Workflow Agent from the Administration Module . . . . . . . . . . 85 Registering the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Installing and Registering the Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Removing the Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 6 Creating a Setup OCX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Contents
Designing the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Writing a Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Code Project Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Example Setup OCX for the Custom Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . 90 Setup OCX for the Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Registering a Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Setup OCX Registry Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Menu Registry Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Loading the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Unloading the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Setup OCX Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Enabling Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Context Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Enabling Context Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Main Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Custom Menu Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Enabling/Disabling Custom Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Batch Class Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Setup OCX Development API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 7 Creating Custom Panels and Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Programming in a High Availability Environment . . . . . . . . . . . . . . . . . . . . . . . . 112 User Interface Design and Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Custom Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Custom Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Scan, Quality Control, Validation, and Verification Tree Node Menus . . . 115 Menus Can Be Added, Removed, and Edited at Runtime . . . . . . . . . . . . . . 115 Registry Entries for Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Installing a Custom Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Invoking Kofax Capture Menu Items from a Custom OCX Panel . . . . . . . . . . . 121 Using the Sample Custom Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Registering the Sample Custom Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Example Custom Panel in VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
vi
Contents
DelPagePanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 8 Creating a Custom Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . High Availability Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error Handling Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Typical Development Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Design the Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Write the Runtime Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create the Custom Module Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . Register the Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create an Installation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DeleteEvenPage Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ProcessNewBatch Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PageMarkedForDeletion Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RuntimeSession_BatchAvailable Subroutine . . . . . . . . . . . . . . . . . . . . . . . . . 9 129 129 129 130 132 132 132 133 133 134 134 134 134 136 138 139
Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Creating a Release Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Kofax Capture Release Type Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Kofax Capture and the Release Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements for the Release Setup Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements for the Release Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The ReleaseSetupData and ReleaseData Objects . . . . . . . . . . . . . . . . . . . . . . . . . . Release Setup Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Release Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COM Servers: In-proc or Out-of-proc? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering Your Release Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scripting in a High Availability Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 142 143 144 145 145 146 147 149
Custom Module Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Installing the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Registering the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
vii
Contents
Adding the Sample to the Batch Processing Workflow . . . . . . . . . . . . . . . . . . . . . . . . 155 Using Batch Manager With a Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Creating a Batch to Open in the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . 158 Processing by Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Batch Custom Storage String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 XML Transport Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Corrupt XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Create Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 B Workflow Agent Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169 Installing the Sample Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Registering the Sample Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Using the Sample Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 C Sample Import Controller Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 General Preparations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Kofax Capture Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Visual Basic 6.0 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Visual Studio 2005 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 The Example Import Controller Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 Visual Basic Code for the Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Basic Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Program Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Declare Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Load Main Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Get Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Make Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Make Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Development API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
viii
How to Use This Guide
Introduction
The Kofax Capture Developers Guide provides information for customizing your Kofax Capture installation. This guide includes instructions for the following: Writing custom validation, recognition, and field scripts Creating and registering custom extensions such as custom modules, custom panels, workflow agents, and setup OCXs Using the Kofax Capture API Library to create the custom extensions Several custom script and extension examples are provided throughout this guide. This guide assumes that you have an understanding of the Kofax Capture product and a working knowledge of an object-oriented development tool such as Visual Studio.
Related Documentation
In addition to the Developers Guide, Kofax Capture includes the following documentation: Kofax Capture 8 Installation Guide The installation guide provides instructions for installing Kofax Capture and Kofax Capture Network Server. In addition, it contains information about planning your installation, certified operating systems and other system requirements, and important installation notes. Kofax Capture 8 Getting Started Guide This guide introduces the various modules and utilities provided with Kofax Capture, describes basic concepts about document/data capture and Kofax Capture
ix
processing, and introduces the components and major features of Kofax Capture Network Server. Kofax Capture 8 API Reference Guide This guide is an online reference that provides the details of each API library needed to customize Kofax Capture. The API Reference Guide is designed to be used with the Kofax Capture Developers Guide as a primary resource for customizing Kofax Capture. To access the API Reference Guide, select Start | Programs | Kofax Capture 8.0 | API Reference Guide from the taskbar. Kofax Capture 8 Online Help Kofax Capture online Help provides online assistance for system administrators and operators alike. You can access online Help as follows: From the Windows taskbar: Select Start | Programs | Kofax Capture 8.0 | Kofax Capture Help to display the main Help topic for the Help system. From any Kofax Capture modules toolbar or menu bar: Click the Help button from the toolbar, or select Help | Kofax Capture Help Topics from the menu bar to display the main Help topic for the module. From any dialog box: Click the Help button or press F1 to display context sensitive information for the dialog box. Quick Reference Cards The set of quick reference cards provides abbreviated steps for performing common tasks for several Kofax Capture modules. Release Notes Late-breaking product information is available from release notes. You should read the release notes carefully, as they contain information that may not be included in other Kofax Capture documentation.
Training
Kofax offers both classroom and computer-based training that will help you make the most of your Kofax Capture solution. Visit the Kofax Web site at www.kofax.com for complete details about the available training options and schedules.
Kofax Technical Support

For additional technical information about Kofax products, visit the Kofax Web site at www.kofax.com and select an appropriate option from the Support menu. The Kofax Support pages provide product-specific information, such as current revision levels, the latest drivers and software patches, online documentation and user manuals, updates to product release notes (if any), technical tips, and an extensive searchable knowledgebase. The Kofax Web site also contains information that describes support options for Kofax products. Please review the site for details about the available support options. If you need to contact Kofax Technical Support, please have the following information available: Kofax Capture software version Kofax Capture Network Server software version Operating system and service pack version Network and client configuration Copies of your error log files Scanner make and model Scanner engine (board) type Special/custom configuration or integration information
xi
xii
Chapter 1
Overview
Introduction
The Kofax Capture Developer's Guide contains information about customizing your Kofax Capture installation and provides answers to the following questions: Why would you want to customize Kofax Capture? How do you customize Kofax Capture? How do you implement your customized scripts and modules? This guide assumes that you have a good understanding of Kofax Capture, Visual Basic or Visual Studio, and COM interface tools.
Why You Would Customize Kofax Capture

Kofax Capture provides the solution to your business needs for converting forms and data to a more useful electronic medium for data processing and archiving. However, you may also want to customize a Kofax Capture process for a specific business task. Some reasons to customize Kofax Capture are: To streamline or bypass unnecessary processes. For example, there may be no need to validate index data if the accuracy of the data exceeds a specified accuracy threshold defined by your business policy. To assert additional processes. To customize the user interface for your business environment. For example, a validation operator would need to have access to only certain functions or processes. Because Kofax Capture is modular (comprised of the Administration, Scan, Validation, Verification, Quality Control modules, and so on) you can customize a specific module for forms processing using the provided Kofax Capture API libraries.
Chapter 1
How to Customize Kofax Capture

Kofax Capture supports several tools for creating and writing custom applications and scripts such as Visual Basic 6.0, Visual Basic 2005 Express Edition, C++, C#, and Softbridge Basic Language (SBL). SBL is a legacy software product that will continue to be supported by Kofax Capture for creating custom macros and scripts, but you are encouraged to use Visual Basic 2005 Express Edition for creating custom scripts. API libraries, which are documented in the Kofax Capture API Reference Guide, are available for you to create custom Kofax Capture extensions. Using the API Libraries Kofax Capture includes several API libraries that you can use to customize Kofax Capture features or behavior. Details on these libraries are provided in the Kofax Capture API Reference Guide and in many topics in the online Help. The Library Name column in the following table shows the library as it will be displayed in the Visual Basic References dialog box. The Object and File Names column shows the library as it will be displayed in the Visual Basic Object Browser, followed in parenthesis by the name of library file.
Table 1-1. Kofax Capture API Libraries Library Name Kofax Capture Module Type Library Kofax Capture Admin Module Type Library Object and File Names AscentCaptureModule (ACModule.dll) AscentCaptureAdminMod (ACAdMod.dll) Usage Used to create custom OCX panels for Scan, Quality Control, Validation, and Verification modules. Used to create custom OCX panels for the Administration module or Setup OCXs for Custom Modules. Can also be used to create Setup OCXs for Workflow Agents. Used by custom modules to access batches. Also called DBLite library. Kofax Capture Optimized Custom Module API DBLiteOpt (DBLiteOpt.dll) Used to get information about an open batch (runtime and setup data). Used in lieu of ExportXML from DBLite, quicker when a subset of data is needed. Used with the DBLite library.
Kofax Capture Document Access
ACDB (DBLite.dll)
Overview
Table 1-1. Kofax Capture API Libraries (continued) Library Name Kofax Capture Custom Workflow Interface Kofax Capture Release Type Library Kofax Capture .NET Scripting Library Object and File Names ACWFLib (ACWFlib.dll) AscentRelease (AscRel.dll) ScriptInterface (ScriptInterface.dll) Used to create VB .NET custom field, validation, and recognition scripts. Usage API used by workflow agents as batches are closed by modules. Used to create custom release scripts.
Additional Resources Files that define the data layout used when accessing Kofax Capture data through custom modules and workflow agents are provided. Both mechanisms utilize identical data layouts. These data layout files (AcBatch.htm, AcDocs.htm, and AcSetup.htm ) are installed with Kofax Capture in your Kofax Capture installation folder. The data layout is split into two filesAcSetup.htm defines setup information, while AcBatch.htm defines runtime information. The data is partitioned into elements. Each element describes a specific kind of object and includes attributes and subelements. Attributes are properties that describe an element. AcDocs.htm is a subset of AcBatch.htm, and contains only the portion of AcBatch that relates to the document structure. Note Prior to Kofax Capture 8, the product was named Ascent Capture. Although the product name in most of the documentation has been changed, there remain instances of the prior product name in some code snippets, filenames, sample applications, API references, or when referring to prior versions of Kofax Capture.
How to Implement Your Customized Scripts and Modules

Each chapter that provides instructions for creating custom extensions, such as custom modules, panels, workflow agents, and setup OCXs includes implementation information.
Chapter 1
Refer to these chapters in this guide for detailed instructions for implementing your customized extensions and scripts.
Chapter 2
Creating Custom Scripts Using SBL
Introduction
You can customize the way Kofax Capture processes batches by adding scripts to your batch classes. You can write the following types of scripts: Validation scripts validate data in the Kofax Capture Validation and Verification modules. For example, you can write a validation script that does a database query to verify that an index field was entered correctly. Some common validation tasks can be done with the database validation feature. This eliminates the need to create scripts for simple database query functions. Recognition scripts modify data in the Recognition Server module. For example, you can write a recognition script that retrieves zone snippets from each image in a batch and extracts data from them using a custom OCR engine. Validation scripts and recognition scripts can be written in either Visual Basic .NET or with the Softbridge Basic Language (SBL), the scripting language incorporated into Kofax Capture. This chapter focuses on SBL as the tool with which to create custom scripts. Writing scripts using Visual Basic .NET is described in Chapter 3 Creating Custom Scripts Using VB .NET.
Chapter 2
Validation Scripts
The Validation and Verification modules in Kofax Capture have the ability to automatically execute validation scripts for every data field in a document class. These scripts are written using an embedded macro language called the Softbridge Basic Language (SBL), a full-featured language similar to Visual Basic. Note You can also use folder validation scripts to add custom processing or enhance or replace the default folder validation provided by Kofax Capture. Folder validation scripts are nearly identical to the document validation scripts described below. Important differences are noted in the Kofax Capture online Help.
Writing a Validation Script

Validation scripts are written and managed from the Administration module. Separate scripts can be written for each document class you have defined, and each script consists of a set of event handler functions that are initially blank except for some default error handling code. There are seven functions accessible through validation scripts. You can add code to each to perform custom data validation routines.
Table 2-1. Validation Script Functions Function FmtFieldName When Called Called for all data fields whenever the data in any field changes. It affects only the way the data is displayed, not the data itself. There is a FmtFieldName function for each data field in a document class. The Kofax Capture Module Document object for the current document. Called after each document is closed. Called each time a new document is loaded. Called when a batch is first loaded in the Validation or Verification module. If a batch has multiple document classes, the function is called once per document class the first time a document class is processed. Called when a batch is closed. Called when a validation operator exits a data field. There is a PostFieldName function for each data field in a document class.
KfxAcmDocument KfxDocPostProcess KfxDocPreProcess KfxLoadValidation
KfxUnloadValidation PostFieldName
Table 2-1. Validation Script Functions (continued) Function PreFieldName When Called Called each time a validation operator enters a data field. There is a PreFieldName function for each data field in a document class.
Writing a validation script is a straightforward procedure. To write a validation script, follow these steps: 1 From the Batch tab in the Administration module, right-click on the document class for which you want to implement a validation script. Click on Document Validation Script. In the Document Validation Script dialog box, select SBL from the Scripting language list. Click either the Create button (for a new script) or the Edit button (for an existing script). The built-in SBL macro editor is displayed with default code already supplied. You can add your own code to any of the functions contained in the script. When finished writing your code, compile the script, make corrections if necessary, exit the editor, and close the Document Validation Script dialog box.
Chapter 2
How Validation Scripts are Processed

The Validation or Verification module loads a validation script the first time it encounters a document of a particular class in the batch. In most cases, the script remains loaded until the batch is closed. (If document sorting is enabled and batch editing is disabled, the script is unloaded when a document of a different document class is processed, and reloaded/unloaded as necessary.) The following describes the typical validation script function sequence: 1 The Validation or Verification module sets the batch-level variables (variables, such as ValidationError, that apply to an entire batch rather than a document or field) and calls the KfxLoadValidation function. You can use this function to allocate resources or perform any other initialization needed for the script. For each document in the batch, Validation or Verification sets the documentlevel variables (variables, such as RejectandSkipDocument, that apply to an entire document) and calls the KfxDocPreProcess function. You can use this function to set up any initialization needed to process the document. For each index field in the document, Validation or Verification sets the fieldlevel variables (variables, such as SaveandSkipField, that apply to individual index fields) and calls the PreFieldName function. You can use this function to supply a default value for the index field or to display a dialog box with options for the field. When the operator leaves the field, Validation or Verification calls the PostFieldName function. You can use this function to do any type of validation required for the index field. The FmtFieldName functions are called for all index fields (except the one getting the focus) whenever the data in an index field changes. After the last index field in the document is processed, Validation or Verification calls the KfxDocPostProcess function. You can use this function to do any final processing for the document, although you no longer have access to the index field data. When the script is unloaded, Validation or Verification calls the KfxUnloadValidation function. You can use this function to release any resources allocated for the script. The general flow for processing a validation script is shown in Figure 2-1. Consult the online Help available from the Administration module for details on certain exceptions to this flow.
5 6
Figure 2-1. Processing Flow for a Validation Script
Chapter 2
Field Type Macros

Although it is possible to write code directly into the PreFieldName and PostFieldName functions in the validation script, you also have the option of using field type macros instead. You use the Kofax Capture Administration module to create field type macros. To write a field type macro 1 2 3 4 5 From the Administration modules Definitions panel, select the Field Types tab. Right-click on a field type and click Field Macro. The Field Macro dialog box will display. Provide a name for the macro (the default name is the same as the field type). Click either Create (for a new macro) or Edit (for an existing macro). The SBL editor is displayed, but only three field functions are accessible (Pre_KFX_FieldName, Post_Kfx_FieldName, and Fmt_Kfx_FieldName) for the field you have chosen. Edit the functions as desired, and then exit the editor. There is no need to compile the macro unless you want to check the syntax of your code.
The next time you create a validation script that contains this field, the code you wrote for the field type macro will be automatically copied into the validation script. You can then compile the validation script as usual. Note that a field type macro itself is never executed. It is merely a template that is copied into a validation script. Only validation scripts are executed during actual processing. The advantage of writing a field type macro is that the code is automatically reused whenever you create a document class that contains a field of the specified type. For example, if you have a telephone number formatting function, you could create a field type called Phone Number and then write a field type macro that performs the formatting. From that point forward, any time you create a document class that contains a field of the Phone Number type, the formatting function will be automatically copied into the validation script. Instead of cutting-and-pasting from another script, all you have to do is open the new validation script and compile it.
10
Testing Validation Scripts

You should always test validation scripts before using them in production. Here are a few tips: While developing your script, make sure the SBL Editor/Debugger Console window is visible (select a document class and click Edit in the Validation Script dialog box). This window has the functionality of both the Visual Basic Immediate window and the Visual C++ Output window: the compiler displays results (including any error messages) in this window and you can display text in this window using the SBL print function. To quickly test your code without running a batch through Validation, add a Sub Main function at the end of your validation script with a call to the function you want to test. For example, if you want to test the PreFieldName function of a field called FirstName, you would write:
Sub Main() Result = PreFirstName() ***Additional code goes here*** End sub
The Main function will be executed when you run the script (select File | Run from the menu bar), and you can return results using a MsgBox function or any other mechanism you desire. All of the functions in validation scripts include error handling. If an unhandled error occurs, the function returns the FatalError value. When you are developing a custom script, you should comment the On Error Goto Failure statement so you can examine any runtime errors generated by your code. Be sure to restore the default error handling when you are finished with the script so that Validation or Verification can properly handle any unexpected errors that occur during batch processing. To test your script under real conditions, compile the script and publish your batch class. Create a test batch and process it through the Validation or Verification module. If you need to make changes and test again, delete the batch without saving the validation data, and then edit your script from the Administration module. Recompile your script, publish your batch class, and create another test batch to process through the Validation or Verification module. Repeat this process until you get the desired results.
11
Chapter 2
Differences Between SBL and Visual Basic

SBL is similar to Visual Basic and Visual Basic for Applications (VBA). Most of the Visual Basic functions and procedures have SBL equivalents, often with the same names and arguments. Here are some key differences between SBL and Visual Basic: Variable and function declarations. All variables and functions must be declared before they are referenced. If you want to include function definitions at the end of a code module, they must be forward declared for the compiler to resolve the references. Variable scope. SBL offers local variables and module-level variables (both declared using Dim) and global variables (declared using Global). A local variable is accessible only within the function in which it is declared. A module-level variable is accessible only by functions in the script in which it is declared. It is similar to a Private variable in Visual Basic. A global variable is accessible by any function in any loaded script. It is similar to a Global variable in Visual Basic, but note that a global variable must be declared in every SBL code module that accesses it. External function declarations. External functions must be declared in every module that calls them. Dialog boxes. SBL scripts are not associated with a form or dialog box, but SBL has a dialog editor you can use to create a dialog box to display from a script function. The dialog editor creates a dialog box definition, which is inserted into your script. To send or retrieve data to/from a dialog box, attach script variables to controls on the dialog box. The implementation is similar to that used by Word Basic in Microsoft Word.
About SBL Dialog Boxes

Softbridge Basic includes a dialog editor that allows you to create and display custom dialog boxes within your scripts. All SBL dialog boxes are modal. Dialog boxes can return values to the script, so you can use a dialog box to display a list of selections for an index field. You create custom dialog boxes using the SBL Dialog Editor. This program allows you to name and position controls on a dialog box form. The editor creates a dialog box definition record, which is inserted into the script.
12
Figure 2-2. The SBL Dialog Editor
For example, if you have an index field that gets filled in with a department name, and there are only seven departments to choose from, it might be convenient to simply display a list and allow the operator to choose an item from the list. This has two advantages: The operator has less typing to do. This is especially handy if the department names are fairly lengthy (Parks and Recreation Department). Its error-free. The operator chooses from a list, so theres no chance of mistakes. You can display a dialog box from any function in a script. When the user closes the dialog box, the script can determine the selections made by the user. If you need to enable or disable controls on the dialog box as the user works with it, you can create a dialog box function to handle user selections. To create a dialog box, click on the Edit | Dialog menu item in the SBL Dialog Editor. The SBL Dialog Editor allows you to create dialog boxes that contain list boxes, command buttons, radio buttons, check boxes, and other standard Windows controls. When you are finished creating the dialog box, exit the editor and the template for the dialog box is inserted into your class script at the current cursor position.
13
Chapter 2
Creating the dialog box in Figure 2-2 is straightforward. The dialog editor automatically creates the template code within the validation script, taking only a few more lines of code to display the dialog box. The code excerpt in Figure 2-3 shows what needs to be done.
Function PreDepartment_Name() As Integer On Error GoTo Failure Dim DepArray(4) As String DepArray(0) = "Parks & Recreation Department" DepArray(1) = "Mayor's Office" DepArray(2) = "Beaches and Roads" DepArray(3) = "Water and Power" Begin Dialog DepartmentName 6,6,181,92 OkButton ListBox Text End Dialog Dim DepRecord As DepName Dialog DepRecord 124,20,50,14 124,37,50,14 6,22,113,65,DepArray(),.ListBox1 CancelButton This code sets up an array of strings that provides the list values for the dialog box to display. The array is called DepArray. This is the dialog template code that was inserted by the SBL Dialog Editor. The only modification is to insert the variable name (DepArray) into the template. This code defines a dialog box record and displays the dialog box. This code retrieves the selected item from the list.
6,7,65,10, Department Name:
KfxDepartment_Name=DepArray(DepRecord.Listbox1)
Figure 2-3. Example of the SBL Dialog Editor
Note that for the purposes of this example, the dialog box selections are defined statically within the script. You dont need scripting to do something this simple (you can just specify a set of values when you define the field type). Yet an SBL list box is a good solution if you want to do something more complex, such as dynamically populating the list based on a database query.
14
Keep the following in mind as you create dialog boxes: If you need to modify an existing dialog box, simply highlight the template code and start the dialog editor. The dialog box defined by the template is displayed in the dialog editor. The size and position of the dialog box within the module are defined on the first line (Begin Dialog) of the dialog template code. You can edit this code directly or you can change it dynamically within the dialog editor. For more details on creating dialog boxes, consult the Softbridge Help files. Note You can achieve results similar to those described above by providing known values for your field type. This is done with the Values tab in the Field Type Properties dialog box in the Administration module.
Validation Script Return Codes and Variables

Validation scripts have access to a variety of return codes and system variables. Table 2-2 lists return codes; Table 2-3 lists system variables.
Table 2-2. Validation Script Return Codes Return Code FatalError Value -1 Definition Indicates a fatal error. The batch is immediately terminated and the batch status is set to Error. Validation or Verification module changes the batch status to Error, displays a message box with the KfxErrorMessage string, and closes. Indicates a successful operation. If this is returned from a PostFieldName function, the Validation or Verification module advances to the next field. Return this value from a PreFieldName or PostFieldName function to call the default processing for an index field after the custom processing in the script.
NoError
NoOperation
15
Chapter 2
Table 2-2. Validation Script Return Codes (continued) Return Code RejectAndSkipDocument Value -4 Definition Return this value from KfxDocPreProcess, KfxDocPostProcess, PreFieldName, or PostFieldName function to reject the active document and advance to the next document. The PreFieldName and PostFieldName functions for any unvalidated fields in the document are skipped; however, the KfxDocPostProcess function is called. Indicates that all data fields should be saved and the Validation or Verification module should advance to the next document. It is typically used in order to automatically skip a document that does not need to be validated by an operator (for example, because the confidence level of all the fields is high). The Pre and Post functions for all remaining fields are not called, but the KfxDocPostProcess function is called. Example: KfxDocPreProcess = SaveAndSkipDocument SaveAndSkipField 1 2 When returned from the PreFieldName function, causes the Validation or Verification module to save data for the current field and advance to the next field (as if the Tab key had been pressed). The PreFieldName processing is skipped, but the PostFieldName function is called. Example: PreFieldName = SaveAndSkipField ValidationError -3 Indicates that the script encountered an error. An error message will display and the Validation or Verification module will not advance to the next field. Example: PostDepartment_Name = ValidationError ValidationErrorNoMsg -2 Same as above, but no error message is displayed.
SaveAndSkipDocument 1
Care should be taken when using these, as no validation will be performed.
16
Table 2-3. Validation Script System Variables System Variable AlreadyProcessed Definition A parameter of the KfxDocPreProcess function that indicates whether the document is being processed for the first time or has already been processed. A parameter of the KfxDocPostProcess function that indicates whether the operator accepted or rejected the data. A parameter of the PostFieldName function that contains the data entered by the validation operator. A parameter of the KfxDocPreProcess and KfxDocPostProcess functions that indicates the document ID of the current document. The hexadecimal ID of the current batch class. The hexadecimal ID of the current batch. The name of the current batch. The name of the current document class. Contains the confidence level of the current field if it was filled in via OCR, ICR, OMR, or bar code recognition. The hexadecimal ID of the current document class. The error message displayed when either FatalError, RejectAndSkipField, or RejectAndSkipDocument are returned from any function. Contains the value of the data in the current field. Indicates whether the KfxDocPreProcess and KfxDocPostProcess functions should be called for documents that have already been processed (for example, if a batch is suspended halfway through and then reloaded). The default is No. Indicates whether the script is being called by the Validation module (index) or the Verification module (verify). The filename of the image currently being displayed.
DataAccepted
EnteredValue ID
KfxBatchClassId KfxBatchID KfxBatchName KfxClassName KfxCLFieldName KfxDocClassId KfxErrorMessage
KfxFieldName KfxLoadAllProcessedValues
KfxOperation
KfxPageFile
17
Chapter 2
Table 2-3. Validation Script System Variables (continued) System Variable MaxLength Definition A parameter of the PostFieldName function that indicates the maximum allowed length of the field (for CHAR and VARCHAR field types). A parameter of the KfxLoadValidation function that indicates the number of documents (not pages) in the current batch. A parameter of the KfxDocPreProcess function that indicates the number of pages in the current document. A parameter of the KfxLoadValidation function that indicates whether the batch is being processed by the Validation module or the Verification module.
NumberOfDocsInBatch
NumberOfPages VerifyBatch
18
Recognition Scripts
Recognition scripts are similar in many ways to validation scripts. Both are written using the Softbridge Basic Language and both are based on a set of event handler functions to which you can add your own custom code. The primary difference is that recognition scripts run in the Recognition Server module and have access to different functions and different system variables. Some common uses of recognition scripts include the following: Replacing a Kofax Capture recognition engine. Recognition scripts have access to zone snippets (small cutouts of an image that represent a zone being processed) and they can process the zone snippets in a custom engine. Modifying the processing of a Kofax recognition engine. For example, you can provide a list of possible choices and add pattern matching. Performing offline processing. Since the Recognition Server module is unattended, it is a good place to perform time-intensive validation procedures (such as querying a remote database over a slow connection).
Writing a Recognition Script

Like validation scripts, recognition scripts are written and managed from the Administration module. You can write a recognition script for each recognition profile that you have created, and each script consists of a set of functions that are initially blank except for some default error handling code. There are a total of four functions accessible using recognition scripts, as shown in Table 2-4.
Table 2-4. Recognition Script Functions Function KfxLoad When Called Called the first time a zone is encountered of the specified recognition type. KfxLoad is called once per batch for each recognition profile that contains a recognition script. Called before each zone snippet is processed. Called after each zone snippet is processed. Called for all recognition scripts when the batch is closed.
KfxPreRecognition KfxPostRecognition KfxUnload
Writing a recognition script is a straightforward procedure. To write a recognition script, follow these steps:
19
Chapter 2
1 2
In the Administration module, select Scripts | Recognition. In the Recognition Script dialog box, choose the recognition profile for which you wish to write a script. It should be the one associated with the zone you want to manipulate. Click the Create button (for new scripts) or the Edit button (for existing scripts). The built-in SBL macro editor is displayed with default code already supplied. You can add your own code to any of the functions contained in the script. When finished writing your code, compile the script, exit the editor, and close the Recognition Script dialog box.
How Recognition Scripts are Processed

When a batch is processed through the Recognition Server module, the following recognition script function sequence occurs: 1 Recognition Server calls the KfxLoad function the first time it encounters a zone of that recognition type in the batch. You can use this function to allocate resources or perform any other initialization needed for the script. For each zone of that recognition type in the batch, Recognition Server sets the scripts KfxImageFile variable to the filename of the temporary image file containing the zone and calls the KfxPreRecognition function. You can use this function to submit the image to another recognition engine and/or cancel the default recognition processing. Unless you use the KfxPreRecognition function to cancel the default recognition, Recognition Server then submits the image to the Kofax recognition engine. After recognition is completed, Recognition Server sets the script variables to the results from the recognition engine and calls the KfxPostRecognition function. You can use this function to compare results from different engines or do any additional validation of the results. After processing this function, Recognition Server saves the data in the script variables to the Kofax Capture database. The script remains in memory until the batch is closed. When the batch is closed, Recognition Server calls the scripts KfxUnload function. You can use this function to release any resources allocated for the script.
Figure 2-4 illustrates the general flow for processing a recognition script.
20
Figure 2-4. Processing Flow for a Recognition Script
Recognition Script Return Codes and Variables

Recognition scripts have access to a variety of return codes and system variables. Table 2-5 lists return codes; Table 2-6 lists system variables.
Table 2-5. Recognition Script Return Codes Return Code FatalError NoError Definition Indicates a fatal error. The batch is set to an error state. Indicates a successful operation. If this is returned from the KfxPreRecognition function, Kofax recognition will be performed next, followed by the KfxPostRecognition function. If this is returned from the KfxPostRecognition function, the Recognition Server module advances to the next field. Similar to NoError, but skips the Kofax recognition. Example: KfxPreRecognition = SaveAndSkipOperation
SaveAndSkipOperation
21
Chapter 2
Table 2-6. Recognition Script System Variables System Variable KfxConfidence Definition The confidence level of the recognition engine. It is an integer between 0-100, with 100 being the highest confidence. If you perform recognition with a custom engine, you are responsible for setting this value. The filename of the zone snippet currently being processed. Image processing has already been performed by the time the script gets access to this file. Note that this is a temporary file and is read-only; attempting to modify the file may have unpredictable consequences. This can be used to retrieve and/or modify the horizontal registration offsets returned by the default engine. These variables define the offset of the lower-left pixel for the first character in the search text found in the zone. The offsets are defined from the upper-left of the zone and are in 1/1200ths of an inch (BMUs). This can be used to retrieve and/or modify the vertical registration offsets returned by the default engine. These variables define the offset of the lower-left pixel for the first character in the search text found in the zone. The offsets are defined from the upper-left of the zone and are in 1/1200ths of an inch (BMUs). The search text is the expected search string set in the Administration module for a separation, form identification, or registration zone. The current recognized value. It is null in the KfxPreRecognition function and is overwritten in the KfxPostRecognition function by the Kofax recognition engine unless SaveAndSkipOperation is returned in the KfxPreRecognition function. It can be modified if desired in the KfxPostRecognition function.
KfxImageFile
KfxRegistrationHorizBMU
KfxRegistrationVertBMU
KfxSearchText
KfxValue
22
Chapter 3
Creating Custom Scripts Using VB .NET
Introduction
Scripts are small programs used to perform specific tasks for associated Kofax Capture modules. Through the Scripts menu item of the Administration module, you can choose the kind of script you want to create and the language you want to create it with. This chapter focuses on creating custom scripts using Microsoft Visual Basic 2005 Express Edition as the script programming language. The advantage of writing scripts in VB .NET and the Microsoft Visual Studio development environment is that Unicode is supported, which is essential for supporting multi-byte character sets. There is also a large knowledge base for the Visual Studio development environment should you need additional coding assistance. You should be familiar with programming concepts and the VB .NET programming language and development environment for writing custom scripts. You can create the following kinds of custom scripts in VB .NET: Field scripts validate data in index fields. For example, your field script can validate that data meets the criteria for a particular field type. Validation scripts validate data in the Kofax Capture Validation and Verification modules. For example, you can write a validation script that queries a database to verify that data for an index field matches the entered data. Document and folder validation scripts can be used to perform validation on document class index fields and folder index fields, respectively. Recognition scripts validate or modify data on results from the Recognition Server module. For example, you can write a recognition script that retrieves zone snippets from each image in a batch and determines if the zone meets a specific acceptance criteria.
23
Chapter 3
Software Requirements
To create a custom script in VB .NET, one of the following development environments must be installed on your system: Microsoft Visual Basic 2005 Express Edition Microsoft Visual Studio 2005 Standard Edition Microsoft Visual Studio 2005 Professional Edition You will also need the .NET Framework 2.0 installed in your development environment. If it is not already installed, the .NET Framework 2.0 can be installed through either Kofax Capture or by Visual Studio 2005. Note Microsoft Visual Basic 2005 Express Edition is a free download from the Microsoft Web site. It is not included in the Kofax Capture Installation CD.
Creating a Validation Script in VB .NET

Validation scripts are useful for verifying that data meets specific formatting criteria or for validating database information for fields of a document class. You can perform these checks prior to and after document processing (that is, DocumentPreProcessing and DocumentPostProcessing events). In this topic, you will learn How to choose the kind of custom script you want to create using VB .NET The objects, methods, and properties that are available for use from the Kofax Capture .NET Scripting API The VB .NET project location for your script The deployment of the scripts Visual Basic project Publishing requirements for the script Additionally, a sample Validation script written in VB .NET is provided.
Choosing the Scripting Language

Although it is possible to create a custom script outside of Kofax Capture using a supported Visual Studio environment, the typical method of creating a custom script is from the Scripts menu of the Kofax Capture Administration module. A document class, for which the document validation script processes, must exist.
24
To create a document validation script with VB .NET 1 2 3 4 From the Scripts menu, select Document Validation. The Document Validation Script dialog box will display. In the Document classes list, select the document class for which you want to create a script. In the Scripting language list, select a scripting language to create the script. In this case, select VB .NET. Click Create. A VB .NET project is created for the script and opens in the code editor of your .NET application. Add your code to create your custom script.
Kofax Capture .NET Scripting API

Your document validation script project will have access to the events and properties of the Kofax Capture .NET Scripting library. Each script can consist of several events and event handlers. The index fields that exist for the document class selected are included in the script code shell. DocumentValidationScript Class The DocumentValidationScript class contains the events that are available for use in a validation script. You add code for a selected event to perform a custom data validation routine. The following events, event arguments, and their associated properties can be used.
Table 3-1. Validation Script Events Events When Called
BatchLoading BatchUnloading DocumentPreProcessing DocumentPostProcessing PreDocumentEventArgs
Called when a batch is opened. Called when a batch is closed. Called each time a new document is opened. Called after each document is closed. This class represents the event arguments for the DocumentValidationScript.DocumentPreProcessing event. This class represents the event arguments for the DocumentValidationScript.DocumentPostProcessing event.
PostDocumentEventArgs
25
Chapter 3
Exceptions To signal an error state, the VB .NET script can throw an exception during event handling. Three types of exceptions are available: FatalErrorException RejectAndSkipDocumentException ValidationErrorException For details about each event, event arguments, and properties, refer to the Kofax Capture API Reference Guide. For more information about exceptions, refer to Error Handling in VB .NET on page 32
VB .NET Project File Location

The file name assigned to the script is shown in the title bar of the programming product. The default location for each project is a numeric folder name under the "~AdminDB\Scripts" folder. The default location of the AdminDB folder for a client/ server installation is: \\<MachineName>\CaptureSV The default location of the AdminDB folder for a standalone installation is: C:\Documents and Settings\All Users\Application Data\Kofax\Capture Note Validation of a batch field and batch totals through VB .NET scripting is not supported. However, batch fields are exposed through the Batch object, which can be accessed from the parameter of the event handler. You must compile your script and publish your batch class before your script can be used in batches. Your script cannot be applied to a batch created before the new publication date. In addition, you must republish if you make changes to your script.
Deployment of a VB .NET Project

VB .NET scripts have a folder of source files and a folder of executables. The entire VB .NET script project is deployed to the Local\Scripts folder before the Validation or Recognition module is launched for either a standalone or remote/central site environment. The VB .NET script is opened each time a batch is opened (if the script is not already present) and a new script ID folder is created for a published batch class. VB .NET
26
scripts can include field scripts, which are executed when there is no document/ folder validation script. Batches using VB .NET scripts are deployed automatically on standalone workstations and on Kofax Capture Network Server remote sites through synchronization by the Remote Synchronization Agent. Scripts are downloaded when the remote site synchronizes with the central site.
Publishing Requirements for the Script

A VB .NET script must be compiled before it can be published. Otherwise, an error occurs. The publish check is performed only on a newly created VB .NET script. The publish check is not performed on updated or changed scripts, and it is the responsibility of the script developer to recompile scripts as needed. Also, a publish check is not performed on VB .NET scripts for imported and exported batch classes.
Sample VB .NET Validation Script

This section describes how to create a sample VB .NET document validation script and add some custom code to it. The sample will use a document class named SampleScript, which contains the fields ClientName and SSN. The VB .NET document validation script is created as outlined in the section Choosing the Scripting Language. Start the Kofax Capture Administration Module: 1 2 3 From the Start menu, select Program | Kofax Capture 8.0 | Administration. Select the document class SampleScript. From the Scripts menu, select Document Validation.
27
Chapter 3
Figure 3-1. Selecting the Document Validation Script from the Script Menu
4 5 6
From the Document Validation Script dialog box that appears, choose SampleScript from the Document classes list. Choose VB .NET from the Scripting language list. Click Create.
Figure 3-2. Document Validation Script Dialog Box
A VB .NET project is created and the code shell opens in the code editor.
Sample Validation Script Code

Next, we will add code that compares and validates a social security number field from a scanned document to a social security number that is already in the database for that client. The first function of the code is the Post Processing event and the next two are helper functions.
28
After you have added the following code, compile the script. When the script successfully compiles, publish the batch class by right-clicking the batch class and selecting Publish.
Imports Imports Imports Imports Imports System System.Collections.Generic System.Text Kofax.AscentCapture.Scripting Kofax.AscentCaptureModule
Imports System.Data.SqlClient
Namespace SampleScript Public Class SampleScript Inherits DocumentValidationScript <IndexFieldVariableAttribute("ClientName")> _ Dim WithEvents ClientName As FieldScript <IndexFieldVariableAttribute("SSN")> _ Dim WithEvents SSN As FieldScript Private Sub SampleScript_DocumentPostProcessing( _ ByVal sender As Object, ByVal e As _ Kofax.AscentCapture.Scripting.PostDocumentEventArgs) _ Handles Me.DocumentPostProcessing Dim oConnection As IDbConnection oConnection = OpenDatabaseConnection() Try oConnection.Open() If (Not FindSsnInDatabase(oConnection, _ SSN.IndexField.Value)) Then Throw New _ Kofax.AscentCapture.Scripting.ValidationErrorException _ ("SSN missing from the database.", SSN.IndexField) End If Finally oConnection.Close() End Try End Sub
29
Chapter 3
Private Function OpenDatabaseConnection() As IDbConnection Dim oConnectionStringBuilder As SqlConnectionStringBuilder oConnectionStringBuilder = New SqlConnectionStringBuilder() oConnectionStringBuilder.DataSource = "DBServer00\SQL2005" _ '*** server name oConnectionStringBuilder.UserID = "User1" '*** user name oConnectionStringBuilder.Password = "abc123" '*** password oConnectionStringBuilder.InitialCatalog = "SocialSecurityDB" _ '*** database name Dim oConnection As SqlConnection oConnection = New SqlConnection oConnection.ConnectionString = oConnectionStringBuilder.ConnectionString Return oConnection End Function
Private Function FindSsnInDatabase( _ ByVal oConnection As IDbConnection, _ ByVal strSsn As String) As Boolean Dim oCommand As IDbCommand oCommand = oConnection.CreateCommand() '*** The database has a Customers table with a column for SSN oCommand.CommandText = String.Format("SELECT SSN FROM _ Customers WHERE SSN=N'{0}'", strSsn) oCommand.CommandType = CommandType.Text Dim oReader As IDataReader oReader = oCommand.ExecuteReader() Dim bFound As Boolean bFound = oReader.Read() oReader.Close() Return bFound End Function End Class End Namespace
30
Testing VB .NET Custom Scripts

A VB .NET custom validation script can be tested and debugged without republishing the associated batch class. However, the batch class (with one or more associated VB .NET scripts) must have been previously published and a batch must be ready to be processed. When a VB .NET script is tested, the script in the Administration module is loaded instead of the published script. In this case, the VB .NET script that is being debugged is the unpublished copy. However, the batch class and script must be republished before changes can take effect. Note The ability to debug and modify the VB .NET script without republishing the batch class is not supported in Visual Basic 2005 Express Edition. It is only supported in Visual Studio 2005. The following is a typical process for testing and debugging a VB .NET document validation script: 1 2 3 4 5 6 7 A user with administrator rights creates a VB .NET document validation script in the Administration module and publishes a batch class. A batch is created and processed through the Validation module. The VB .NET script project is opened in Visual Studio. Break points are set in the script, and changes are made to the script as desired. The validation script is run from Visual Studio, and the debugger stops at the first break point. Testing and debugging can continue until you are satisfied with the script. The script is compiled, and the batch is published.
Note When debugging a Validation script in VB .NET, if you stop the debugger while a batch is open, the validation process is terminated and the batch is left in an In progress state. It may take time for the batch to return to the Ready state.
31
Chapter 3
Error Handling in VB .NET

A VB .NET script uses an exception during event handling to signal an error state. The Kofax Capture .NET Scripting API provides the following exceptions: FatalErrorException RejectAndSkipDocumentException ValidationErrorException
FatalErrorException
This exception is used to signal a fatal error and can be used in validation, recognition, and field scripts. When this exception is thrown, the error message is displayed in Validation or Verification, or logged in the Recognition Server. The batch is set to an error state and sent to Quality Control. Example
Throw New FatalErrorException("Missing validation resource")
RejectAndSkipDocumentException
This exception is used by the validation script to reject and skip a document, and to advance to the next document. This exception is thrown in document validation scripts only. The FieldScript.FieldPreProcessing and FieldScript.FieldPostProcessing events for any unvalidated fields in the document are skipped. However, the DocumentValidationScript.DocumentPostProcessing event is called. Example
Throw New RejectAndSkipDocumentException("Document does not have the correct format")
ValidationErrorException
This exception is used to signal a validation error and is to be thrown in validation scripts only. It is treated as a fatal error if the Recognition Server receives this exception.
32
There are two versions for this exception: ValidationErrorException (ErrMsg) ValidationErrorException (ErrMsg, IndexField) ValidationErrorException (ErrMsg) If this version is used, then the error message is displayed in the status bar of the Validation or Verification module and will not advance to the next field. The focus remains on the last field that is being validated. Example
Throw New ValidationErrorException()
ValidationErrorException (ErrMsg, IndexField) This version is similar to the prior version for ValidationErrorException except that it allows the developer to set the focus on a particular field. IndexField specifies the field to get the focus. If the field does not exist or is null, then the last field that is being evaluated gets the focus. For example, if cross-field validation is being performed in the DocumentValidationScript.DocumentPostProcessing event and a computation routine determines that the third field does not match the sum of the first and second fields, then an exception is thrown with the third field getting the focus. Example
Throw New ValidationErrorException("Sum does not match",oIndexField)
Note If ErrrorMsg is empty, then the default error message is displayed. Refer to the Kofax Capture API Reference Guide for details about the syntax and parameters for these exception classes.
33
Chapter 3
Creating a Recognition Script in VB .NET

Recognition scripts are useful for processing zone snippets with a custom recognition engine, modifying the process of a Kofax recognition engine, or performing an offline recognition process. In this section, you will learn How to choose the VB .NET as the scripting language for the recognition script. The objects, methods, and properties that are available for use from the Kofax Capture .NET Scripting API. The VB .NET project location of your script, the script deployment, and publishing requirements are the same as those for validation scripts.
Choosing the Scripting Language

Although it is possible to create a custom script outside of Kofax Capture using a supported Visual Studio environment, the typical method for creating a custom script is from the Scripts menu of the Kofax Capture Administration module. A recognition profile for which the custom recognition script processes must exist. To create a recognition script with VB .NET 1 2 3 4 From the Scripts menu, select Recognition. The Recognition Script dialog box will display. In the Recognition profiles list, choose the recognition profile for which you want to create a script. In the Scripting language list, select a scripting language to create the script. In this case, select VB .NET. Click Create.
A VB .NET project is created for the script and opens in the code editor of your .NET application. You add your code to create your custom script.
Kofax Capture .NET Scripting API

Your recognition script project will have access to the events and properties of the Kofax Capture .NET Scripting library. Each script can consist of several events and event handlers.
34
RecognitionScript Class The RecognitionScript class contains the events that are available for use in a recognition script. You add code for a selected event to perform a custom recognition routine. The following events, event arguments, and their associated properties can be used
Table 3-2. Recognition Script Events Events When Called
BatchLoading BatchUnloading RecognitionPreProcessing RecognitionPostProcessing PreRecognitionEventArgs PostRecognitionEventArgs
Called when a batch is opened. Called when a batch is closed. Called before each zone snippet is processed. Called after each zone snippet is processed. This class represents the event arguments for the RecognitionScript.RecognitionPreProcessing event. This class represents the event arguments for the RecognitionScript.RecognitionPostProcessing event.
Exceptions To signal an error state, the VB .NET script can throw an exception during event handling. Three types of exceptions are available: FatalErrorException RejectAndSkipDocumentException ValidationErrorException For details about each event, event arguments, and properties, refer to the Kofax Capture API Reference Guide. For more information about exceptions, refer to Error Handling in VB .NET on page 32.
Sample VB .NET Recognition Script

The following recognition script demonstrates how to set recognition criteria to enhance a field that may display poorly. The confidence level is set to 75%. If the
35
Chapter 3
confidence level for the field falls below 75%, the document is sent to the Quality Control module.
Private Sub ConfidenceScript_RecognitionPostProcessing( _ ByVal sender As Object, ByVal e As _ Kofax.AscentCapture.Scripting.PostRecognitionEventArgs) _ Handles Me.RecognitionPostProcessing If (e.Confidence < 75) Then Throw New Kofax.AscentCapture.Scripting.FatalErrorException _ ("Confidence value was less than 75 percent.") End If End Sub
36
Field Script
A field script is a small program that can contain variables and functions needed for validating an index field with an associated field type. A field script is invoked when there is no document validation script for a document class, and the field script can be referenced in other custom scripts for documents. A field script can have only one script language defined, either VB .NET or SBL; however, it is possible to have a combination of VB .NET field scripts and SBL field macros for index fields of the same document class. The following exceptions are enforced: If an index field of the same field type is defined in a batch, then the VB .NET field script is called. If a document class (with a custom SBL validation script) includes a field based on a field type with an SBL field type macro and another field based on a field type with a VB .NET field script, then all of the scripts are run. That is, the SBL validation script, SBL field type macros, and VB .NET field scripts are executed. If a document class (with a custom VB .NET validation script) includes a field based on a field type with an SBL field type macro and another field based on a field type with a VB .NET field script, then only the VB .NET validation script and the VB .NET field scripts are executed. The SBL field type macros are not run. A field script can contain field formatting functions and event arguments associated with each event:
Table 3-3. Field Script Events Events When Called Called for every field as every other field is exited. Allows the display of a field to differ from the stored value. Called as the field is entered. Set e.SaveAndSkipField = True to save the field and move to the next field. Called as the field is exited. Set e.SaveAndSkipDocument = True to save the field and move to the next document. This class represents the event arguments for the FieldScript.FieldFormatting event.
FieldFormatting
FieldPreProcessing FieldPostProcessing FormatFieldEventArgs
37
Chapter 3
Table 3-3. Field Script Events Events When Called This class represents the event arguments for the FieldScript.FieldPreProcessing event. This class represents the event arguments for the FieldScript.FieldPostProcessing event.
PreFieldEventArgs PostFieldEventArgs
For details about each event, event arguments, and properties, refer to the Kofax Capture API Reference Guide.
Sample VB .NET Field Script

When you create a new field script, a new class is derived from the FieldScript class of the Kofax Capture .NET Scripting API. The name of the class is based on the field type name (all non-alphanumeric characters of the class name are replaced with underscore characters). The name of the class can be changed; however, the changed name is not automatically updated in the generated field script. The following is an example of a field script that changes all mixed case letters of a particular field to upper case letters for reading clarity.
Private Sub UppercaseField20_FieldFormatting( _ ByVal sender As Object, _ ByVal e As Kofax.AscentCapture.Scripting.FormatFieldEventArgs)_ Handles Me.FieldFormatting '*** Convert the string to upper case. Dim strUpperCase As String strUpperCase = IndexField.Value.ToUpper() '*** Set the value to the uppercase string. IndexField.Value = strUpperCase End Sub
38
Chapter 4
Creating a Registration File
Introduction
Custom extensions (custom modules, setup OCX programs, and workflow agents) must be registered with Kofax Capture before they can be used. The registration process is necessary so that Kofax Capture recognizes the custom extension as valid. Custom extension registration is a two-part process that requires you to do the following: Set up a registration file (.aex file) that defines the property settings for the custom extension. Refer to Format for the Registration File on page 40 for more information about the registration file. Register the custom extension using one of the following: The Administration module. For details, see Using the Administration Module to Manage Extensions on page 58. Kofax Capture Extension Registration Utility, which is run from a command line. For details, see Using the Kofax Capture Extension Registration Utility on page 69. Prior to registration, the custom extension registration file (the executable or DLL file), and the optional setup OCX must be saved to the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin). Note Release scripts and runtime OCXs cannot be registered using the methods described in this chapter. For more information on release scripts, see Chapter 9 Creating a Release Script. For more information on runtime OCXs see Chapter 7 Creating Custom Panels and Applications.
39
Chapter 4
Format for the Registration File

The format for the registration (.aex) file is similar to that of a standard Windows .ini file. Refer to Example Registration Files on page 52 for examples of registration files. Registration files offer you great flexibility. You can have a single file that contains information for all your custom modules, workflow agents, or setup OCXs. Alternatively you can have separate files for each custom extension. If you have a custom module or a workflow agent that requires a setup OCX, you must put the setup OCX information in the same registration file as the extension that uses it. The registration file can contain sections as described below.
[Modules] Section
To register one or more custom modules, the .aex file must contain a header section labeled [Modules] that lists the display name of each custom module defined in the file. Custom module display names cannot exceed 32 characters. Note Items listed in the [Modules] section can be registered with the Custom Module Manager available from the Administration module. Alternatively, they can be registered with the Kofax Capture Extension Registration Utility (RegAscEx.exe) available from the Kofax Capture Bin folder.
[Module Name] Section

For each custom module listed in the [Modules] section, the .aex file must include a corresponding [Module Name] section (labeled with the custom module name) that includes the property settings required to register the module. Each [Module Name] section can include the keys listed below. Note that some of the keys are required. If a required key is missing, an error will occur during registration.
Table 4-1. [Module Name] Section Keys Key Description Description Description of the purpose of the custom module. The description displays in the Queues tab of the Create Batch Class and Batch Class Properties dialog boxes for the selected module. Maximum length is 250 characters. Required Yes
40
Kofax Capture Developers Guide
Table 4-1. [Module Name] Section Keys (continued) Key Follow Description Indicates the processing function that the custom module function must follow in the batch class workflow. The following values are valid for the Follow key: Scan (default value) Document Separation Form Identification Automatic Index Validation Verification Custom modules are not allowed to follow the Release module. Note that to specify proper queue ordering, you can set values for Follow and/or Precede or set a value for Function. If you specify a value for Follow or Precede, do not set a value for Function. If you do, errors will occur when you attempt to register a custom module. Function Specifies the function to be performed by the custom module. The defined function is used to perform publish checks and to ensure proper queue ordering. One or more of the following functions may be specified, delimited by semicolons. Document Separation Page Registration Form Identification Automatic Index Validation Verification Full Text OCR Quality Control Other (default value) Note that to specify proper queue ordering, you can set a value for Function or set values for the Follow and/or Precede keys. If you specify a value for Function, do not set Follow or Precede. If you do, errors will occur when you attempt to register the custom module. No Required No
41
Chapter 4
Table 4-1. [Module Name] Section Keys (continued) Key IconFile Description Path to a file containing the icon associated with the module name. A semicolon and the numeric index of the desired icon in the file may optionally follow the path. If this property is not specified, the default icon for the RuntimeProgram file is used. If no icon is found in either file, the module name will display without an icon. Maximum length for the icon file and path is 250 characters. Unique identifier for a custom module. Used to synchronize information about custom modules when data is exported and imported between databases. Maximum length is 250 characters. This identifier must be unique across both custom modules and workflow agents. Precede Indicates the processing function that the custom module function must precede in the batch class workflow. These Precede key values are valid: Document Separation Form Identification Automatic Index Validation Verification Full Text OCR Release (default value) Custom modules are not allowed to precede the Scan module. Note that to specify proper queue ordering, you can set values for Follow and/or Precede OR set a value for Function. If you specify a value for Follow or Precede, do not set a value for Function. If you do, errors will occur when you attempt to register a custom module. Runtime Command Line Specifies command line parameters that must be passed to the custom modules runtime program when it is invoked from Batch Manager. Maximum length is 250 characters. No No Required No
ModuleID
Yes
42
Table 4-1. [Module Name] Section Keys (continued) Key Runtime Program Description The runtime executable for the custom module. This executable will be invoked when a batch in the ready state is selected in Batch Manager. Maximum length is 250 characters. The executable must exist in the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin) for each workstation that will use it. SetupProgram Specifies a [Setup] Section within the .aex file that defines the properties of the setup module for a custom module. The name of this section will also be the display name of the custom module. Maximum length is 250 characters. Refer to [Setup] Section on page 49 for more information about defining [Setup] sections. Specifies whether the custom module supports nonimage files (eDocuments). Setting this key to True enables non-image file support for the custom module. Setting this key to False or omitting the key disables non-image file support for the custom module. No Required Yes
SupportsNon ImageFiles
No
SupportsTable Specifies whether the customization supports tables. Fields Setting this key to True enables table support for the customization. Setting this key to False disables table support for the customization. If not specified, the default setting is False. SuppressBatch Specifies whether the custom standard module Contents includes the Batch Contents panel. Setting this key to True removes the panel. Setting this key to False, or omitting the key, causes the Batch Contents panel to be available. This key applies only to custom standard modules. SuppressBatch Specifies whether the custom standard module Filters includes the Batch Filter toolbar. Setting this key to True removes the toolbar. Setting this key to False, or omitting the key, causes the Batch Filters toolbar to be available. This key applies only to custom standard modules.
No
No
No
43
Chapter 4
Table 4-1. [Module Name] Section Keys (continued) Key Description Required No
SuppressBatch Specifies whether the custom standard module Navigation includes the Batch Navigation toolbar. Setting this key to True removes the toolbar. Setting this key to False, or omitting the key, causes the Batch Navigation toolbar to be available. This key applies only to custom standard modules. SuppressBatch Specifies whether the custom standard module Thumbnails includes the Batch Thumbnails panel. Setting this key to True removes the panel. Setting this key to False, or omitting the key, causes the Batch Thumbnails panel to be available. This key applies only to custom standard modules. SuppressBatch Specifies whether the custom standard module Tools includes the Batch Tools toolbar. Setting this key to True removes the toolbar. Setting this key to False, or omitting the key, causes the Batch Tools toolbar to be available. This key applies only to custom standard modules. Suppress ImageTools Specifies whether the custom standard module includes the Image Tools toolbar. Setting this key to True removes the panel. Setting this key to False, or omitting the key, causes the Image Tools toolbar to be available. This key applies only to custom standard modules. Suppress ImageViewer Specifies whether the custom standard module displays the Kofax Capture Image Viewer. Setting this key to True hides the image viewer. Setting this key to False, or omitting the key, causes the image viewer to be visible. Kofax This key applies only to custom standard modules. Suppress Notes Specifies whether the custom standard module includes the Notes panel. Setting this key to True removes the panel. Setting this key to False, or omitting the key, causes the Notes to be available. This key applies only to custom standard modules.
No
No
No
No
No
44
Table 4-1. [Module Name] Section Keys (continued) Key SuppressScan Controls Description Specifies whether the custom standard module includes the Scan Controls panel. Setting this key to True removes the panel. Setting this key to False, or omitting the key, causes the Scan Controls Panel to be available. This key applies only to custom standard modules. UsesExtended Recognition Info In order to enable communications between custom modules, the Recognition Server is able to generate the extended recognition data in the form of an XML string. By default, the Recognition Server does not output this XML data unless a custom module is registered that indicates a desire to use this it. This is because the extended recognition data could be very large and have a significant impact on performance and/or disk space. If a batch class contains any custom module with this flag set to true, then extended recognition information is generated in the Recognition Server. For Example:
[Sample] RuntimeProgram=CMSample.EXE ModuleID=Kofax.Sample Description=This Sample module supports non-image files Version=1.0 UsesExtendedRecognitionInfo=True
Required No
No
The default, if this value is not provided, is False. A document-based custom storage string, named Kofax.AC.ExtendedRecognitionInfo is used for the storage of extended recognition data. The Recognition Server generates values for the this custom storage string whenever it produces an index field value result that was generated by the Kofax High Performance OCR Zonal, Kofax High Performance ICR Zonal, or the Kofax Advanced OCR Zonal engines, and a custom module has registered itself as using extended recognition information.
45
Chapter 4
Table 4-1. [Module Name] Section Keys (continued) Key UsesExtended Recognition Info (continued) Description Required
Index Fields whose values are assigned by other means No (such as OMR, or Kofax OCR) do not cause the generation of ExtIndexField elements within the string. The Recognition Server updates only those ExtIndexField elements where the corresponding index field value is updated. Note The Kofax.AC.ExtendedRecognitionInfo custom storage string is never cleared, even when the index value is changed.
Version
Custom module version number assigned by the developer. If this property is not specified, no version number will display.
No
[Workflow Agents] Section

To register one or more workflow agents, the .aex file must contain a header section labeled [Workflow Agents] that lists the display name of each workflow agent. Workflow agent display names cannot exceed 32 characters. Note Items listed in the [Workflow Agents] section can be registered with the Workflow Agent Manager available from the Administration module. Alternatively, they can be registered with the Kofax Capture Extension Registration Utility (RegAscEx.exe) available from the Kofax Capture Bin folder.
46
[Workflow Agent Name] Section

For each workflow agent listed in the [Workflow Agents] section, the .aex file must include a corresponding [Workflow Agent Name] section (labeled with the workflow agent name) that includes the property settings required to register the agent. Each [Workflow Agent Name] section can include the keys listed below. Note that some of the keys are required. If a required key is missing, an error will occur during registration.
Table 4-2. [Workflow Agent Name] Section Keys Key Description Description Description of the purpose of the workflow agent. Maximum length is 250 characters. Specifies a [Setup] Section within the .aex file that defines the properties of the setup program for a workflow agent. Maximum length is 250 characters. Workflow agent version number assigned by the developer. If this property is not specified, no version number will display. This is the .dll that contains the Workflow Agent runtime COM server. This value indicates a unique identifier for the Workflow Agent. Maximum length is 250 characters. This identifier must be unique across both Workflow Agents and Custom Modules. WorkflowAgentProgID This is the runtime COM ProgID of the Workflow Agent. Yes Required Yes
SetupProgram
No
Version
No
WorkflowAgentFile WorkflowAgentID
Yes Yes
47
Chapter 4
Table 4-2. [Workflow Agent Name] Section Keys (continued) Key WorkflowAgentSkipIfCantLoad Description By default, the system places the batch in error if it cannot load the runtime COM server on a particular station. However, with this flag set, the system will not place the batch in error if the Workflow Agent does not exist, instead continuing with the default batch workflow. To set this flag, include WorkflowAgentSkipIfCantLoad=true in the .aex file. Required No
[Setup Programs] Section

To register one or more setup OCXs, the .aex file must contain a [Setup Programs] section that lists the names of all [Setup] sections defined in the file. Refer to [Setup] Section on page 49 for more information about defining [Setup] sections. If a setup program is listed in [Setup Programs], but not defined in its own [Setup] section, an error will occur during registration. Note Items listed in the [Setup Programs] section must be registered with the Kofax Capture Extension Registration Utility (RegAscEx.exe) available from the Kofax Capture Bin folder. They cannot be registered from the Administration module.
48
[Setup] Section
For each item listed in the [Setup Programs], [Module Name], or [Workflow Agent Name] sections, the .aex file must include a corresponding [Setup] section (labeled with the item name) that defines the setup program. Each [Setup] section can include the keys listed below. Note that some of the keys are required. If a required key is missing, an error will occur during registration.
Table 4-3. [Setup] Section Keys Key BatchClassMenus Description Names one or more [Menu] sections in the .aex file that define the menu items to be added to the context menu for batch class nodes. Multiple items must be delimited by semicolons. The name of the section is also the internal name of the menu (passed to the OCX on ActionEvents). Maximum length is 250 characters. Same as BatchClassMenus, except that it defines menu items to add to the context menu for document class nodes. Same as BatchClassMenus, except that it defines the menu items to add to the context menu for field type nodes. Same as BatchClassMenus, except that it defines the menu items to add to the context menu for form identification zone nodes. Same as BatchClassMenus, except that it defines menu items to add to the context menu for form type nodes. Same as BatchClassMenus, except that it defines the menu items to add to the context menu for index group zone nodes. Required No
DocumentClassMenus
No
FieldTypeMenus
No
FormIdZoneMenus
No
FormTypeMenus
No
IndexGroupMemberZoneMenus
No
IndexGroupMemberZonesMenus Same as BatchClassMenus, except that it defines the menu items to add to the context menu for index group zone collection nodes.
No
49
Chapter 4
Table 4-3. [Setup] Section Keys (continued) Key IndexZoneMenus Description Same as BatchClassMenus, except that it defines menu items to add to the context menu for index zone nodes. Same as BatchClassMenus, except that it defines the menu items to add to the context menu for index zone collection nodes. The initial horizontal size of the panel in screen resolution pixels. The default is 50. The initial vertical size of the panel in screen resolution pixels. The default is 50. Names one [Menu Bar] section that defines the menu to add to the main menu bar. Multiple items are not allowed. Maximum length is 250 characters. The minimum horizontal size of the panel when undocked in screen resolution pixels. The default is 50. The minimum vertical size of the panel when undocked in screen resolution pixels. The default is 50. Path, including the file name, of the Setup OCX file. Maximum length is 250 characters. If there is no path, <Kofax Capture installation folder>\Bin will be used. PageLevelBarcodeMenus Same as BatchClassMenus, except that it defines the menu items to add to the context menu for page level bar code nodes. Same as BatchClassMenus, except that it defines the menu items to add to the context menu for page level bar code collection nodes. No Required No
IndexZonesMenus
No
InitSizeX InitSizeY MenuBarMenu
No No No
MinSizeX
No
MinSizeY
No
OCXFile
Yes
PageLevelBarcodesMenus
No
50
Table 4-3. [Setup] Section Keys (continued) Key ProgID Description The COM program ID of the module specified with the OCXFile key. Maximum length is 250 characters. Same as BatchClassMenus, except that it defines the menu items to add to the context menu for registration zone nodes. Same as BatchClassMenus, except that it defines the menu items to add to the context menu for registration zone collection nodes. Same as BatchClassMenus, except that it defines the menu items to add to the context menu for sample page nodes. Same as BatchClassMenus, except that it defines the menu items to add to the context menu for separation zone nodes. A value of 1 indicates visible; 0 indicates invisible. If set to 0, the panel will not be initially displayed and the DisplayName will not appear under the Toolbar menu. The default is 1. This key is ignored when registering a custom module from the command line. Required Yes
RegistrationZoneMenus
No
RegistrationZonesMenus
No
SamplePageMenus
No
SeparationZoneMenus
No
Visible
No
[Menu] Section
A [Menu] section defines the text for a menu item listed in [Menu Bar] and [Setup] sections. A [Menu] section has one required key. If the key is missing, an error will occur during registration.
Table 4-4. [Menu] Section Key Key MenuText Description Display text for the menu item. Required Yes
51
Chapter 4
[Menu Bar] Section

For each menu bar menu listed in a [Setup] section, the .aex file must include a corresponding [Menu Bar] section (labeled with the menu bar menu name) that defines the menu. Each [Menu Bar] section must contain the keys listed below. Note that all keys are required. If a key is missing, an error will occur during registration.
Table 4-5. [Menu Bar] Section Keys Key MenuBarText Menus Description Display text for the menu. Names one or more [Menu] sections that define the menu items to be added to this menu. Multiple items are delimited by semicolons. The name of the section is also the internal name of the menu (passed to the OCX on ActionEvents). Maximum length is 250 characters. Required Yes Yes
Example Registration Files

This section contains several examples that show the file structure for registration files. Example 1: Registering Two Custom Modules The example registration file shown below specifies two custom modules: ABC Image Cleanup and XYZ Index. ABC Image Cleanup does not have a custom setup module, but XYZ Index does. The XYZ Index batch class context menu has two custom menu items: XYZ Properties and XYZ Reset to Default. The main menu bar has a custom menu item, XYZ Index, with two menu items: XYZ Item 1 and XYZ Item 2. Comments are shown in bold text and are not part of the registration file.
[Modules] - Modules Section ABC Image Cleanup XYZ Index [ABC Image Cleanup] - Module Name Section ModuleID=ABC.ImageCleanup Version=1.0 RuntimeProgram=ABCImage.exe Description=The ABC Image Cleanup module performs image enhancement [XYZ Index] - Module Name Section ModuleID=XYZ.Index
52
IconFile=XYZ.ico RuntimeProgram=XYZIndex.exe RuntimeCommandline=/k SetupProgram=XYZ Setup Description=The XYZ Index module automatically gathers index data Function=Automatic Index [XYZ Setup] - Setup Section OCXFile=XYZSetup.ocx ProgID=XYZCorp.IndexSetup InitSizeX=200 InitSizeY=100 Visible=1 BatchClassMenus=XYZ Batch Menu 1;XYZ Batch Menu 2 MenuBarMenu=XYZ Menu Bar [XYZ Batch Menu 1] - Menu Section MenuText=XYZ Properties [XYZ Batch Menu 2] - Menu Section MenuText=XYZ Reset to Default [XYZ Menu Bar] - Menu Bar Section MenuText=XYZ Index Menus=XYZ Bar Menu1;XYZ Bar Menu 2 [XYZ Bar Menu 1] - Menu Section MenuText=XYZ Item 1 [XYZ Bar Menu 2] - Menu Section MenuText=XYZ Item 2
Example 2: Defining a Menu for the Menu Bar The following custom module registration file (.aex file) defines one menu for the main menu bar, including the name of the menu and two menu items as shown below:
Figure 4-1. Custom Menu for Menu Bar
Comments are shown in bold text and are not part of the registration file.
53
Chapter 4
[Setup Programs] - Setup Programs Section Sample Setup [Sample Setup] - Setup Section OCXFile=c:\SmpSetUp.ocx ProgID=SampleSetUp.SmpSetUp Visible=1 MinSizeX=50 MinSizeY=50 InitSizeX=432 InitSizeY=351 MenuBarMenu=XYZ Menu Bar [XYZ Menu Bar] - Menu Bar Section MenuBarText=XYZ Index Menus=XYZ Bar Menu 1;XYZ Bar Menu 2 [XYZ Bar Menu 1] - Menu Section MenuText=XYZ menu item 1 [XYZ Bar Menu 2] - Menu Section MenuText=XYZ menu item 2
Note The above example requires that SmpSetUp.ocx be located in the C:\ folder.
Example 3: Defining Context Menu Items The following custom module registration file defines custom context menu items for nodes in the tree view available from the Administration module as shown below.
Figure 4-2. Custom Context Menus
54
[Setup Programs] - Setup Programs Section Sample Setup [Sample Setup] - Setup Section OCXFile=c:\SmpSetUp.ocx ProgID=SampleSetUp.SmpSetUp Visible=1 MinSizeX=50 MinSizeY=50 InitSizeX=432 InitSizeY=351 MenuBarMenu=XYZ Menu Bar BatchClassMenus=BatchClass 1 DocumentClassMenus=DocClass 1 FormTypeMenus=FormType 1 SamplePageMenus=SamplePage 1 SeparationZoneMenus=Separation 1 RegistrationZoneMenus=RegZone 1 IndexZoneMenus=IndexZone 1 FormIdZoneMenus=FormId 1 FieldTypeMenus=FieldType 1 PageLevelBarcodeMenus=PLB 1 IndexZonesMenus=Index Zones 1 PageLevelBarcodesMenus=PLBs 1 RegistrationZonesMenus=Regzones 1 IndexGroupMemberZoneMenus=GroupMember 1 IndexGroupMemberZonesMenus=GroupParent 1 [XYZ Menu Bar] - Menu Bar Section MenuBarText=XYZ Index Menus=XYZ Bar Menu 1;XYZ Bar Menu 2 [XYZ Bar Menu 1] - Menu Section MenuText=XYZ menu item 1 [XYZ Bar Menu 2] - Menu Section MenuText=XYZ menu item 2 [BatchClass 1] - Menu Section MenuText=I show up on the &BatchClass tree node [DocClass 1] - Menu Section MenuText=I show up on the &DocClass tree node [FormType 1] - Menu Section MenuText=I show up on the &FormType tree node [SamplePage 1] - Menu Section MenuText=I show up on the &SamplePage tree node [Separation 1] - Menu Section MenuText=I show up on the Separation &Zones tree node
55
Chapter 4
[RegZone 1] - Menu Section MenuText=I show up on the &Reg Zone tree node [IndexZone 1] - Menu Section MenuText=I show up on the &Index Zone tree node [FormId 1] - Menu Section MenuText=I show up on the Form&Id tree node [FieldType 1] - Menu Section MenuText=I show up on the &FieldType tree node [PLB 1] - Menu Section MenuText=I show up on the Pa&ge level bar code tree node [Index Zones 1] - Menu Section MenuText=I show up on the &Index Zones tree node [PLBs 1] - Menu Section MenuText=I show up on the Page level bar code pare&nt tree node [Regzones 1] - Menu Section MenuText=I show up on the Regzon&es tree node [GroupParent 1] - Menu Section MenuText=I show up on the Group&Parent tree node [GroupMember 1] - Menu Section MenuText=I show up on the Group&Member tree node
Example 4: Defining a Workflow Agent The following workflow agent registration file defines a workflow agent with a custom context menu item available from the Administration module as shown below.
56
Figure 4-3. Sample Workflow Agent in Context Menu
[Workflow Agents] Workflow Agents Section Validation Workflow Agent [Validation Workflow Agent] Workflow Agent Name Section WorkflowAgentID=Kofax.AgentWithOCX WorkflowAgentProgID=WFAgent.SampleWorkflowAgent WorkflowAgentFile=WFAgent.dll Description=This sample workflow agent is combined with a setup OCX. Version=7.5 SupportsNonImageFiles=True SetupProgram=Workflow Agent Setup [Workflow Agent Setup] Setup Section OCXFile=SampleWorkflowOcx.ocx ProgID=SampleWorkflowOcx.SampleWorkflow Visible=0 MinSizeX=300 MinSizeY=150 BatchClassMenus=Workflow Agent Test Menu [Workflow Agent Test Menu] - Menu Section MenuText=Validation &Workflow Properties...
57
Chapter 4
Using the Administration Module to Manage Extensions

You can use the Administration module to register custom modules and workflow agents. You can also use the command line registration utility, which is explained in Using the Kofax Capture Extension Registration Utility on page 69. Note You cannot use the Administration module to register setup OCXs, you must use the Kofax Capture Extension Registration Utility.
Managing Custom Modules

The following procedures cover registering and removing custom modules. Registering a Custom Module Before registration, make sure that you have placed the following files in the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin): Setup OCX for the custom extension (optional) Executable for the custom extension Registration (.aex) file for the custom extension To register a custom module with the Custom Module Manager 1 2 Start the Administration module. From the Tools menu, select Custom Module Manager. a The Custom Module Manager dialog box will display.
Figure 4-4. Custom Module Manager Dialog Box
58
3 4
From the Custom Module Manager dialog box, click the Add button. From the Open dialog box, browse to Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin) and select the .aex file associated with the custom module you want to register.
Figure 4-5. Custom Module Registration Files
Click Open. The custom module(s) listed in the [Modules] section of the .aex file will display in the Custom Modules dialog box.
Figure 4-6. Custom Modules Dialog Box
Select the name of the module(s) you want to register and click Install. A confirmation message will appear to inform you when the registration is successful.
59
Chapter 4
Click OK to clear the message, and then click Close to exit the Custom Modules dialog box. The name of the newly registered module(s) will appear in the Custom Module Manager dialog box. Also, the newly registered custom module will be added to the list of Available Queues in the Queues tab of the Create Batch Class and Batch Class Properties dialog boxes.
Figure 4-7. Registered Module in Custom Module Manager Dialog Box
Viewing Properties for a Custom Module The Custom Module Properties and Workflow Agent Properties dialog boxes list all of the registered settings for the selected application. The settings are based on the information defined in the .aex file for the custom extension. The properties are listed for reference purposes only; you cannot edit them. To view properties for a custom module 1 From the Custom Module Manager dialog box, choose a custom module and click the Properties button. The Custom Module Properties dialog box will display. From the General tab, you can view information that describes the custom module.
60
Figure 4-8. Custom Module Properties Dialog Box - General Tab
Click the Programs tab. From this tab, you can view the location of the runtime file for the module, along with the location of the optional setup program.
61
Chapter 4
Figure 4-9. Custom Module Properties Dialog Box - Programs Tab
Click the Advanced tab. From this tab, you can view the functions defined for the custom module. The Advanced tab also lists the valid processing order that is allowed for the custom module function. The Follow entry lists the processing function that the custom module function must follow. The Precede entry lists the function that the custom module must precede. The selections for Follow/
62
Precede affect the valid order that is allowed for the custom module on the Queues tab of the Create Batch Class and Batch Class Properties dialog boxes.
Figure 4-10. Custom Module Properties Dialog Box - Advanced Tab
Removing a Custom Module You can use the Administration module to remove or unregister a custom module from Kofax Capture. Before removing the custom module, you must ensure that it is not used in any published batch class. Otherwise, Kofax Capture will prevent you from removing it. To remove a custom module 1 Start the Administration module.
63
Chapter 4
From the Tools menu, select Custom Module Manager. The Custom Module Manager dialog box will display.
Figure 4-11. Removing a Custom Module
3 4
Select the name of the custom module to be removed. Click Remove. If the selected custom module is not used in any published batch class, it will be cleared from the list. The Custom Module Manager will not allow you to remove a custom module that is used by any batch classes. Click Close.
Managing Workflow Agents

The following procedures cover registering and removing workflow agents. Registering a Workflow Agent Before registration, make sure that you have placed the following files in Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin:) Setup OCX for the custom extension (optional) Executable for the custom extension Registration (.aex) file for the custom extension To register a workflow agent with the Workflow Agent Manager 1 Start the Administration module.
64
From the Tools menu, select Workflow Agent Manager. The Workflow Agent Manager dialog box will display.
Figure 4-12. Workflow Agent Manager Dialog Box
3 4
From the Workflow Agent Manager dialog box, click the Add button. From the Open dialog box, browse to the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin) and select the .aex file associated with the workflow agent you want to register.
Figure 4-13. Workflow Agent Registration File
Click Open. The workflow agent(s) listed in the [Workflow Agents] section of the .aex file will display in the Workflow Agents dialog box.
65
Chapter 4
Figure 4-14. Workflow Agents Dialog Box
Select the name of the workflow agent(s) you want to register and click Install. A confirmation message will appear to inform you when the registration is successful. Click OK to clear the message, and then click Close to exit the Workflow Agents dialog box. The name of the newly registered agent(s) will appear in the Workflow Agents Manager dialog box. Also, the newly registered workflow agent will be added to the list of workflow agents available from the Queues tab of the Create Batch Class and Batch Class Properties dialog boxes.
Viewing Properties for a Workflow Agent The Workflow Agent Properties dialog boxes list all of the registered settings for the selected workflow agent. The settings are based on the information defined in the .aex file. The properties are listed for reference purposes only; you cannot edit them. To view properties for a workflow agent 1 From the Workflow Agent Manager dialog box, choose a workflow agent and click the Properties button.
66
The Workflow Agent Properties dialog box will display. From the General tab, you can view information that describes the workflow agent.
Figure 4-15. Workflow Agent Properties Dialog Box - General Tab
Click the Programs tab. From this tab, you can view the location of the runtime file for the module, along with the location of the optional setup program.
Figure 4-16. Workflow Agent Properties Dialog Box - Programs Tab
67
Chapter 4
Removing a Workflow Agent You can use the Administration module to remove or unregister a workflow agent from Kofax Capture. Before removing the workflow agent, you must ensure that it is not used in any published batch class. Otherwise, Kofax Capture will prevent you from removing it. To remove a workflow agent 1 2 Start the Administration module. From the Tools menu, select Workflow Agent Manager. The Workflow Agent Manager dialog box will display.
Figure 4-17. Removing a Workflow Agent
3 4 5
Select the name of the workflow agent to be removed. Click Remove. If the selected workflow agent is not used in any published batch class, it will be cleared from the list. Click Close.
68
Using the Kofax Capture Extension Registration Utility

The Kofax Capture Extension Registration Utility (RegAscEx.exe) is a standalone console application that registers and unregisters custom modules, workflow agents, and setup OCXs. For custom modules and workflow agents, this utility is an alternative to the dialog boxes that are available from the Administration module. With the registration utility, you also can incorporate the registration process into the custom extension installation program. RegAscEx.exe resides in the Kofax Capture Bin folder. You can find this utility in <Kofax Capture installation folder>\Bin. This utility can be used to register: Custom modules Custom modules with setup OCXs Setup OCXs Workflow agents Workflow agents with setup OCXs The registration utility has no graphical user interface, and is controlled completely via command line parameters. Prior to registration, the .aex file, executable file, and the optional setup OCX must be saved to the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin). Note The Visible key available for [Setup] sections is ignored if you register a custom extension with this utility prior to running the Administration module. This happens because the Administration module hides the custom panel if it is launched after you register the custom panel. If you launch the Administration module prior to using the command line to register the custom module, the custom module should display as expected.
Command Line Parameters

The utility supports several command line parameters to specify which custom extensions are to be registered or unregistered, an output file, and silent mode operation. If any invalid or incomplete parameters are specified, you will be prompted with the correct usage, as shown in Figure 4-18.
69
Chapter 4
Input File [/f {filename}] You must specify an .aex file that contains the registration settings for one or more custom extensions to be registered or unregistered in the Kofax Capture database. The /f flag is followed by the .aex filename, as in the following examples:
RegAscEx /f custom.aex RegAscEx /f SetupOCX.aex
(for a custom module and/or workflow agent) (for a setup program)
Every custom extension defined in the specified file will be processed. Status messages will be displayed to the console for each application registered or unregistered. Refer to Format for the Registration File on page 40 for more information about the .aex file. Output File [/o {filename}] You may optionally specify an output file where all messages and statuses will be recorded. The messages are output to the file and to the default display of the console. The /o flag is followed by the output filename, as in the following example:
RegAscEx /f custom.aex /o output.log
Module Name [/m {module name}] You may optionally specify a single custom module from the input file that should be registered or unregistered. Only the specified custom module will be processed, rather than the default behavior of processing all custom modules in the input file. The /m flag is followed by the custom module name enclosed in quotation marks, as in the following example:
RegAscEx /f custom.aex /m XYZ Image Processing
Workflow Agent Name [/w {workflow agent name}] You may optionally specify a single workflow agent from the input file that should be registered or unregistered. Only the specified workflow agent will be processed, rather than the default behavior of processing all Kofax Capture extensions in the input file. The /w flag is followed by the workflow agent name enclosed in quotation marks, as in the following example:
RegAscEx /f ACWflowAgnt.aex /w Validation Workflow Agent
70
Setup Programs [/x {setup program name}] You may optionally specify a single setup program from the input file that should be registered or unregistered. Only the specified setup program will be processed, rather than the default behavior of processing all Kofax Capture extensions in the input file. The /x flag is followed by the setup program name enclosed in quotation marks, as in the following example:
RegAscEx /f SetupOCX.aex /x Setup OCX
Runtime Programs [/r {runtime program name}] You may optionally specify a single runtime program from the input file that should be registered or unregistered. Only the specified runtime program will be processed, rather than the default behavior of processing all Kofax Capture extensions in the input file. The /r flag is followed by the runtime program name enclosed in quotation marks, as in the following example:
RegAscEx /f RuntimeOCX.aex /r Runtime OCX
Unregister [ /u ] You may optionally use the /u flag to unregister one or more custom modules in the Kofax Capture database, as in the following example:
RegAscEx /f custom.aex /u
If the /m parameter is also used, only the specified custom module will be unregistered. If the /w parameter is also used, only the specified workflow agent will be unregistered. If the /x parameter is also used, only the specified setup program will be unregistered. Otherwise, all custom extensions specified in the .aex file will be unregistered. If any batch class is using a custom extension, the application cannot be unregistered. A warning message will be displayed, as follows:
<Application Name> is being used by the following batch classes and cannot
be removed.
This message will be followed by a list of up to 10 batch classes that use the custom extension. If more than 10 batch classes are detected, the first nine will be listed, followed by the phrase and more. Silent Mode [ /s ] You may request that the registration utility operate without generating any output messages to the console by adding the /s command line parameter, as in the following example:
71
Chapter 4
RegAscEx /f custom.aex /s
If an output file is specified using the /o parameter, that file will still be generated with all output messages. Usage [ /? ] The /? parameter displays the proper usage of the registration utility to the console. It defines each of the supported command line parameters and provides an example for formatting the command line. For example, you can use the following to display information about proper usage:
RegAscEx /?
Input
The exact format of the .aex file is documented in Format for the Registration File on page 40. The file contains a header section that lists the name of each custom extension to be defined. Subsequent sections itemize the properties for each custom extension to be registered. The Kofax Capture Extension Registration Utility verifies the values for the properties that are required in the .aex file.
Output
This section contains messages that may be displayed by the Kofax Capture Extension Registration Utility. The following examples assume that silent mode operation (using the /s command line parameter) has not been specified. Console messages will also appear in the output file if they are specified using the /o command line parameter. Proper Usage If you call the Kofax Capture Extension Registration Utility with the /? parameter or specify an invalid command line parameter, the valid parameter information will be displayed, as shown in Figure 4-18.
72
Figure 4-18. Kofax Capture Extension Registration Utility Output
Error and Warning Messages If the utility fails to register or unregister a custom extension, an error or warning message is displayed to explain the problem. If an invalid parameter is specified or a required parameter is missing, the proper usage prompt is also displayed.
73
Chapter 4
74
Chapter 5
Creating a Workflow Agent
Introduction
A workflow agent is a custom application that you can create to examine and modify batch data, change the routing of a batch, restrict access to a batch in certain modules, and obtain the status of a batch. Workflow agents are attached at the batch class level and invoked whenever a batch is closed from a module. This chapter describes how you can create, install, and register a workflow agent to customize your Kofax Capture process. An example workflow agent written in Visual Basic .NET is provided later in this chapter. In this chapter you will learn to: Design a workflow agent Implement an optional setup OCX for the workflow agent Write the runtime module using Visual Basic .NET Create the workflow agent registration file Install and register the workflow agent Remove the workflow agent
Designing a Workflow Agent

The purpose of a custom workflow agent for an assigned batch class is to modify the typical processing of a batch in Kofax Capture. When designing the workflow agent, consider the following questions: What is the purpose of the workflow agent? What functions should be performed by the workflow agent to carry out its purpose? Will an administrator need to have configuration options? (If so, a setup OCX will be needed.)
75
Chapter 5
Avoid implementing a runtime user interface with your workflow agent as most purposes of the workflow agent will be for automatic operations or may be used in a module that is running as a service.
Implementing the Setup OCX

A setup OCX for the workflow agent is optional, but if your workflow agent requires configuration prior to running, a setup OCX should be considered. When creating the setup OCX, consider What the setup OCX interface will look like Where the configuration settings will be stored How the workflow agent is configured The setup OCX will provide the configuration properties for the workflow agent through the Administration module and can be displayed through toolbars, panels, or context menus. These properties will be available only for batch classes that are assigned the workflow agent. Refer to Chapter 6 Creating a Setup OCX for more information about coding a custom setup OCX.
Writing the Runtime Module

Now that youve determined the purpose of your custom workflow agent and defined its functions and goals, you are ready to code your application. The example workflow agent provided later in this chapter is written in Visual Basic .NET. You can write a workflow agent using any of the following supported programming languages and development environments: Microsoft Visual Basic 6.0 with Service Pack 6 Microsoft Visual C++ 6.0 with Service Pack 6 Microsoft Visual C# .NET 2005 Microsoft Visual Basic 2005 Express Edition Microsoft Visual Studio 2005 Standard Edition Microsoft Visual Studio 2005 Professional Edition You will also need the .NET Framework 2.0 installed in your development environment. If it is not already installed, the .NET Framework 2.0 is installed by either Kofax Capture or Visual Studio 2005.
76
Code Project Settings

When generating your Visual Basic project, the following must be set: The workflow agent must be a registered COM server. The code project must reference the Kofax Capture Custom Workflow Library (ACWFLib.dll). The code project must reference the Kofax Capture .NET Interop library (in this case, Kofax.ACWFLib.Interop.dll) Project properties should have the following check boxes selected Unattended execution Retained in memory The workflow agent COM class must implement the IACWorkFlowAgent interface. The workflow agent application named DeletePageWFA is used as an example later in this chapter, and sections of the code that performs certain functions are described. This example application: Ensures that only even-numbered pages are deleted. If odd-numbered pages are marked for deletion, the batch is sent to Quality Control. References a setup OCX, which adds a new menu item to the Batch Class context menu. This menu item will enable the administrator to specify whether or not the workflow agent will check for even-numbered page deletion. The example code for the setup OCX is provided and described in Chapter 6 Creating a Setup OCX. Referencing the Kofax Capture API Libraries The example custom workflow agent will use the objects, methods, and properties defined in the following API libraries: Kofax Capture Custom Workflow Interface (ACWFLib.dll) Kofax Capture Optimized Custom Module API (DBLiteOpt.dll) Set your Visual Basic project to reference these libraries. For more information about the Kofax Capture Workflow Library (ACWFLib.dll) and the Kofax Capture Optimized Custom Module API (DBLiteOpt.dll), refer to the Kofax Capture API Reference Guide in the Kofax Capture Documentation CD or access the guide by selecting Start | Programs | Kofax Capture 8.0 | API Reference Guide.
77
Chapter 5
Setting the Project Properties Set your Visual Basic project properties to Unattended Execution Retained in Memory
Workflow Agent Example

The example workflow agent is part of a more comprehensive example that includes a custom workflow agent, custom setup OCX for the workflow agent, custom panel, and custom module. The comprehensive example 1 2 3 4 Uses a workflow agent setup OCX that enables the administrator to decide whether even-numbered pages are to be removed for a specified batch class. Has a batch for the batch class created and scanned. Provides a custom panel that the operator uses to mark even-numbered pages for deletion. Has the workflow agent check the pages of the batch for odd-numbered pages that were incorrectly marked for deletion. These incorrectly marked pages are reset, and a page note is added indicating that the page should not have been marked for deletion. Runs the custom module, which deletes the even-numbered pages that are marked for deletion. Displays the Quality Control module, which shows that the pages were reset.
5 6
The code for the example workflow agent is provided in this section; however, the code for the setup OCX, custom panel, and the custom module are provided and described in Chapter 6 Creating a Setup OCX, Chapter 7 Creating Custom Panels and Applications, and Chapter 8 Creating a Custom Module, respectively. Workflow Agent Program The purpose of the example custom workflow agent is to ensure that only evennumbered pages are marked for deletion. Odd-numbered pages that are marked for deletion are reset, sent to Quality Control, and flagged with a page note indicating that the page is not to be deleted. The workflow agent application (DeletePageWFA) includes the major functions outlined below.
78
Inherit the IACWorkflowAgent Interface Make sure that you have the line of code in your custom application that implements the IACWorkflowAgent interface. This line of code (shown in bold below) should be placed near the beginning of the DeletePageWFA application.
Imports Kofax.ACWFLib Imports Kofax.DBLiteOpt Public Class Agent Implements Kofax.ACWFLib.IACWorkflowAgent Private m_oSetupDataElement As ACDataElement Private m_strBatchClassName As String
ProcessWorkflow Function The ProcessWorkflow function is the main method for the custom workflow agent. This subroutine is called whenever a batch is closed, rejected, or suspended. This implementation of the ProcessWorkflow function performs several functions: Checks if the batch is leaving the Scan module Extracts the runtime and setup data information Iterates through the pages and checks whether the page that is marked for deletion should indeed be deleted (that is, it is an even-numbered page) Check if the Batch is Leaving the Scan Module The ProcessWorkflow function checks if the batch is leaving the Scan module. If it isnt, the subroutine is exited. A check is also made whether the batch is being suspended or if the batch is in error. If so, the subroutine is exited. Extract the Runtime and Setup Data A segment of the code extracts data from the following elements in preparation for reading each item: Setup ACDataElement Runtime ACDataElement Batch ACDataElement BatchClass ACDataElement Pages ACDataElement
79
Chapter 5
Iterate Through the Documents A segment of the code Determines whether the pages should be checked. (That is, was the Delete Even Page Setup menu item selected from the setup OCX context menu for the batch?) Cycles through each page and increments the page count. The ProcessWorkflow function code segment follows:
Public Sub ProcessWorkflow(ByRef oWorkflowData As _ Kofax.ACWFLib.ACWorkflowData) Implements _ Kofax.ACWFLib._IACWorkflowAgent.ProcessWorkflow '*** Let's make sure we are leaving Scan If oWorkflowData.CurrentModule.Name = "Scan" Then '*** Extract the Runtime DataElement Dim oRTElem As ACDataElement oRTElem = oWorkflowData.ExtractRuntimeACDataElement(0) '*** Extract the Setup DataElement m_oSetupDataElement = _ oWorkflowData.ExtractSetupACDataElement(0) '*** Get the Batch element Dim oBatchElem As ACDataElement oBatchElem = oRTElem.FindChildElementByName("Batch") '*** Set the Batch Class Name m_strBatchClassName = _ oBatchElem.AttributeValue("BatchClassName") '*** Get the Pages elem Dim oPagesElem As ACDataElement oPagesElem = oBatchElem.FindChildElementByName("Pages") '*** Keep track of the Page count Dim lngPageCount As Long = 0 '*** Check if we should check the pages If IsCheckPagesEnabled() Then '*** Iterate through each Page element
80
Dim oPageElem As ACDataElement For Each oPageElem In _ oPagesElem.FindChildElementsByName("Page") '*** Increment the Page count lngPageCount = lngPageCount + 1 '*** Check the page to make sure it should be deleted CheckPage(oPageElem, lngPageCount) Next oPageElem End If End If End Sub
IsCheckPagesEnabled Function The IsCheckPagesEnabled function determines whether the workflow agent should look for pages that were marked for deletion that was set through the setup OCX. That is, did the administrator select the Flag Page for Deletion option from the Batch Class context menu? This Boolean value is stored in the Batch Class custom storage string.
Private Function IsCheckPagesEnabled() As Boolean Try '*** Get the BatchClasses element Dim oBatchClassesElem As ACDataElement oBatchClassesElem = _ m_oSetupDataElement.FindChildElementByName("BatchClasses") '*** Get the BatchClass element Dim oBatchClassElem As ACDataElement oBatchClassElem = _ oBatchClassesElem.FindChildElementByAttribute("BatchClass", _ "Name", m_strBatchClassName) '*** Get the BatchClassCustomStorageStrings Dim oBatchClassCSSs As ACDataElement
81
Chapter 5
oBatchClassCSSs = _ oBatchClassElem.FindChildElementByName _ ("BatchClassCustomStorage Strings") '*** Get the CheckEvenPageDelete custom storage string Dim oCheckEvenPageCSS As ACDataElement oCheckEvenPageCSS = _ oBatchClassCSSs.FindChildElementByAttribute _ ("BatchClassCustomStorageString", "Name", _ "CheckEvenPageDelete") '*** Make sure we have a reference If Not oCheckEvenPageCSS Is Nothing Then '*** Check the value Return (oCheckEvenPageCSS.AttributeValue("Value") = "True") End If Catch ex As Exception '*** Just return false Return False End Try End Function
CheckPage Subroutine The CheckPage subroutine checks if a page is odd-numbered and marked for deletion. If it is, the value is reset to False, and a page note is added to indicate that the page should not be deleted because it is an odd-numbered page. Compile the entire workflow agent code and register it as instructed in the next section.
Private Sub CheckPage(ByRef oPageElem As ACDataElement, _ ByVal lngPageNumber As Long) '*** Check if this is an odd page If (lngPageNumber Mod 2) = 1 Then '*** Check if we have the DeletePage CSS
82
Dim oDeletePageCSS As ACDataElement oDeletePageCSS = oPageElem.FindChildElementByName _ ("PageCustomStorageStrings").FindChildElementByAttribute _ ("PageCustomStorageString", "Name", "DeletePage") '*** Make sure we have a reference If Not oDeletePageCSS Is Nothing Then '*** We don't want to delete odd pages. Clear the value. oDeletePageCSS.AttributeValue("Value") = "False" '*** Set the Page Note to say that we reset the flag oPageElem.AttributeValue("Note") = "The DeletePage flag _ was reset...you're not supposed to do that!" End If End If End Sub
83
Chapter 5
Creating the Registration File

A workflow agent must be registered with Kofax Capture before it can be used. Once registered, the workflow agent is recognized as valid for a processing queue and can be attached to any Kofax Capture batch class. The workflow agent registration is a two-part process that requires you to do the following: Set up a workflow agent registration (.aex) file that defines the property settings for the workflow agent Save the registration file and the optional setup OCX to the <Kofax Capture installation folder>\Bin folder. Register the workflow agent through one of the following: The Administration module The Kofax Capture Extention Registration Utility Note If you are customizing Kofax Capture under the Windows Vista operating system, you must have Administrator privileges in order to install files to the Kofax Capture installation folder.
Format of the Registration File

The format for the registration (.aex) file is similar to that of a standard Windows .ini file. If you have a workflow agent that uses a setup OCX, you must put the setup OCX information in the same registration file as the extension that uses it. The following is the registration file (DeletePageWFA.aex) for the example workflow agent program.
[Workflow Agents] Delete Page Workflow Agent [Delete Page Workflow Agent] WorkflowAgentID=KPSG.DeletePageWFA WorkflowAgentProgID=DeletePageWFA.Agent WorkflowAgentFile=DeletePageWFA.dll Description=This workflow agent makes sure that odd pages are not deleted. Version=8.0 SupportsNonImageFiles=True SetupProgram=Delete Even Page Setup
84
[Delete Even Page Setup] OCXFile=DeleteEvenPageSetup.dll ProgID=DeleteEvenPageSetup.SetupControl Visible=0
The registration file (DeletePageWFA.aex) contains: A list of workflow agents (identified under the heading [Workflow Agents]) The workflow agent name (identified under the heading [Delete Page Workflow Agent]) and the following information Workflow ID ProgID of the workflow agent Library (.dll) file name The setup OCX for the workflow agent (identified under the heading [Delete Even Page Setup]) and the following information Setup OCX file name ProgID of the setup OCX For more information about the registration file, read Chapter 4 Creating a Registration File.
Registering the Workflow Agent from the Administration Module

To register the workflow agent from the Administration module 1 2 3 From the Administration modules menu bar, select Tools | Workflow Agent Manager. The Workflow Agent Manager dialog box will display. From the Workflow Agent Manager dialog box, click Add. From the Open dialog box, browse to the <Kofax Capture installation folder>\Bin folder and select the .aex file associated with the workflow agent you want to register. Click Open. The workflow agent listed in the Workflow Agents section of the .aex file will display in the Workflow Agents dialog box. Select the name of the workflow agent you want to register and click Install. A confirmation message will display when the registration is successful. Click OK to clear the confirmation message, and then click Close to exit the Workflow Agent Manager dialog box.
4 5 6
85
Chapter 5
Note The newly-registered workflow agent will also be added to the list of workflow agents available from the Workflow Agents tab of the Create Batch Class and Batch Class Properties dialog boxes.
Registering the Setup OCX

Having a setup OCX for your workflow agent is optional; however, if a setup OCX is implemented, it must be registered before it can be used. To register a setup OCX that is associated with a custom extension 1 Copy the setup OCX, custom extension files, and registration (.aex) file to the <Kofax Capture installation folder>\Bin folder on each workstation that runs the Administration module or the custom extension. Register the setup OCX with the Custom Module Manager or Workflow Agent Manager available from the Administration module. (Alternatively, you can use the Kofax Capture Extension Registration Utility.)
To register a setup OCX that is not associated with a custom extension 1 2 3 Copy the registration (.aex) file to the <Kofax Capture installation folder>\Bin folder Copy the setup OCX to the location specified by the .aex file. Register the setup OCX with the Kofax Capture Extension Registration Utility by typing the following in the Run command line:
RegAscEx /f <registration_file_name.aex>
Installing and Registering the Workflow Agent

This section provides instructions for installing and registering a workflow agent. Before registration, make sure that you have placed the following files in the <Kofax Capture installation folder>\Bin folder. Note If you are customizing Kofax Capture under the Windows Vista operating system, you must have Administrator privileges in order to install files to the Kofax Capture installation folder.
86
To install and register the workflow agent 1 2 3 4 5 6 From Administration modules menu bar, select Tools | Workflow Agent Manager. Browse to the .aex file for the custom workflow agent, select the file, and click Open. From the Workflow Agents dialog box, select the workflow agent and click Install. The Registration complete message is displayed if the registration was successful. Click OK. The workflow agent is displayed in the Workflow Agent Manager dialog box. Click Close. From the Batch Class Properties - Workflow Agent tab, select the desired workflow agent and click Add. The workflow agent is added to the Selected Workflow Agents list. Click OK to save your changes and exit the Batch Class Properties dialog box.
Removing the Workflow Agent

You can use the Administration module to remove or unregister a workflow agent from Kofax Capture. Before removing the workflow agent, you must ensure that it is not used in any published batch class. Otherwise, Kofax Capture will prevent you from removing it. To remove a workflow agent 1 2 3 4 From Administration modules menu bar, select Tools | Workflow Agent Manager. The Workflow Agent Manager dialog box will display. Select the name of the workflow agent to be removed. Click Remove. If the selected workflow agent is not used in any published batch class, it will be cleared from the list. Click Close.
87
Chapter 5
88
Chapter 6
Creating a Setup OCX
Introduction
You can implement a setup OCX to customize batch class setup options. With a setup OCX, you can define custom menus, configuration settings, and publish checks. This chapter describes how to design, create, and register a setup OCX, how a setup OCX is loaded and unloaded with the Administration module, and the behavior of setup OCX panels and menus. An example setup OCX associated with the custom workflow agent described in Chapter 5 Creating a Workflow Agent is provided and its functionality described later in this chapter.
Designing the Setup OCX

Determine whether a setup OCX is necessary for your custom extension. A setup OCX can be associated with a custom extension (such as a custom module or custom workflow agent), or designed without a custom extension: A setup OCX with an associated custom module allows you to customize the batch class set up process for batch classes that contain the custom module as part of their workflow. The user interface and menu items defined in the setup OCX are available only for batch classes that contain the custom module. A setup OCX with an associated workflow agent allows you to create custom user interfaces that you can use to configure any runtime parameters that the workflow agent may require. The user interface and menu items defined in the setup OCX are available only for batch classes that contain the workflow agent. A setup OCX without an associated custom extension allows you to customize the batch class set up process for all batch classes. Items defined in the setup OCX are available for all batch classes.
89
Chapter 6
While it is possible to use the standard configuration settings and publish checks available from the Administration module with a custom extension, it is likely that you will want to use a custom setup OCX.
Writing a Setup OCX

The supported programming languages and development environment for creating a setup OCX are the same as with workflow agents. See the topic Writing the Runtime Module on page 76 for the supported development environments. The example setup OCX that is provided in this chapter is written in VB .NET and is associated with the example workflow agent provided in Chapter 5 Creating a Workflow Agent. The example setup OCX is part of the comprehensive example for this guide. The example setup OCX will provide the configuration properties for the workflow agent, and will be available through a context menu for a batch class through the Administration module. Details about the example setup OCX is provided later in this chapter in Example Setup OCX for the Custom Workflow Agent on page 90.
Code Project Settings

To generate the VB. NET project for the setup OCX, ensure that the following libraries are referenced in your Visual Basic project: Kofax Capture Admin Module Type Library (ACAdMod.dll) Kofax Capture .NET Interop libraries (in this case, Kofax.AscentCaptureAdminMod.Interop.dll)
Example Setup OCX for the Custom Workflow Agent

The example setup OCX is part of the comprehensive custom extension example. This setup OCX for the custom workflow agent, which is described in Chapter 5 Creating a Workflow Agent, enables the administrator to determine whether a check for evennumbered page deletion is to be enforced and to configure that option through the Batch Class context menu.
90
Setup OCX for the Workflow Agent

The workflow agent setup OCX (DeleteEvenPageSetup) is written in VB .NET. This custom setup OCX consists of the following code: SetupControl is the control code that handles Kofax Capture events and triggers the the setup OCX and setup dialog. SetupForm is the code for the Delete Even Page Setup dialog, which is displayed when the Delete Even Page Setup is selected from the context menu of the Batch Class. It allows the administrator to enable the workflow agent to check for even-numbered page deletion. Figure 6-1 is the context menu for the Batch Class that is associated with the workflow agent setup OCX.
Figure 6-1. Delete Even Page Setup Option Provided Through the Setup OCX Context Menu
Figure 6-2 is the dialog box that displays when the DeleteEvenPage option is chosen from the context menu of the Batch Class. The setup OCX generates the context menu.
91
Chapter 6
Figure 6-2. Delete Even Page Setup Dialog Box
The code segments are listed below. SetupControl

Public Class SetupControl Inherits System.Windows.Forms.UserControl #Region " Windows Form Designer generated code " '***This segment of code, which is generated by VB .NET for the '***form, is not included here. #End Region Private Const cm_strDEPSetup As String = "DEPSetup" Private Const cm_strDEPSetupText As String = "Delete Even Page _ Setup" '*** Reference to the AdminApplication object Private m_oAdminApplication As _ Kofax.AscentCaptureAdminMod.AdminApplication Public WriteOnly Property Application() As _ Kofax.AscentCaptureAdminMod.AdminApplication Set(ByVal Value As _ Kofax.AscentCaptureAdminMod.AdminApplication) '*** Cache the object m_oAdminApplication = Value '*** Initialize the menu InitializeMenu() End Set End Property
92
Public Sub ActionEvent(ByVal nEventNumber As Integer, ByRef _ oArgument As Object, ByRef nCancel As Integer) '*** Check the event number If nEventNumber = _ Kofax.AscentCaptureAdminMod.KfxOcxEvent.KfxOcxEventMenuClicked _ Then '*** Check the menu text If CStr(oArgument) = cm_strDEPSetup Then '*** Show the Setup Dialog Dim oSetupForm As SetupForm = New SetupForm '*** Call the Setup Function oSetupForm.ShowSetupDialog(m_oAdminApplication.ActiveBatchClass) '*** Unload the Form oSetupForm = Nothing End If End If End Sub Private Sub InitializeMenu() m_oAdminApplication.AddMenu(cm_strDEPSetup, _ cm_strDEPSetupText, "BatchClass") End Sub End Class
SetupForm
Imports Kofax.AscentCaptureAdminMod Public Class SetupForm Inherits System.Windows.Forms.Form
93
Chapter 6
#Region " Windows Form Designer generated code " '***This segment of code, which is generated by VB .NET for the '***form, is not included here. #End Region Private Const cm_strCheckEvenPageDeleteCSS As String = _ "CheckEvenPageDelete" Private m_blnCheckEvenPageDelete As Boolean Private m_oBatchClass As BatchClass Public Sub ShowSetupDialog(ByRef oBatchClass As BatchClass) '*** Cache the reference m_oBatchClass = oBatchClass '*** Initialize the form chkCheckPages.Checked = IsCheckEvenPageEnabled() '*** Show the dialog (modal) Me.ShowDialog() '*** Save the settings Call SetEvenPageEnabled(chkCheckPages.Checked) End Sub Private Function IsCheckEvenPageEnabled() As Boolean '*** Check the BatchClassCustomStorageString IsCheckEvenPageEnabled = _ GetBatchClassCSSSafe(cm_strCheckEvenPageDeleteCSS) = "True" End Function Private Sub SetEvenPageEnabled(ByVal blnEnabled As Boolean) '*** Set the value m_oBatchClass.CustomStorageString _ (cm_strCheckEvenPageDeleteCSS) = IIf(blnEnabled, "True", "False") End Sub
94
Private Function GetBatchClassCSSSafe(ByVal strName _ As String) As String On Error GoTo trap GetBatchClassCSSSafe = _ m_oBatchClass.CustomStorageString(strName) Exit Function trap: GetBatchClassCSSSafe = "" End Function Private Sub cmdOK_Click() '*** Simply hide the form Me.Hide() End Sub End Class
95
Chapter 6
Registering a Setup OCX

Follow the procedures below to register your setup OCX. To register a setup OCX that is associated with a custom extension 1 Copy the setup OCX, custom extension files, and registration (.aex) file to the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin) on each workstation that runs the Administration module and/or the custom extension. Register the setup OCX with the Custom Module Manager or Workflow Agent Manager available from the Administration module. Alternatively, you can use the Kofax Capture Extension Registration utility.
To register a setup OCX that is not associated with a custom extension 1 2 3 Copy the registration (.aex) file to the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin). Copy the setup OCX to the location specified by the .aex file. Register the setup OCX with the Kofax Capture Extension Registration utility.
Refer to Chapter 4 Creating a Registration File, for details about creating the registration (.aex) file and using the Kofax Capture Extension Registration utility. Note If you are customizing Kofax Capture under the Windows Vista operating system, you must have Administrator privileges in order to install files to the Kofax Capture installation folder. Because the example setup OCX is associated with a workflow agent, the registration file for the workflow agent is also used to register the setup OCX. Note the listing of the OCX file and ProgID in the workflow agent registration file in Format of the Registration File on page 84.
Setup OCX Registry Entries

After a setup OCX is installed on a client computer, registry keys must be created on that computer to inform the Administration module how the OCX is loaded, and what menus should be created. Registry keys that define the Administrative module setup OCX are automatically created under the following path during the registration process:
96
HKEY_LOCAL_MACHINE\Software\Kofax Image Products\Ascent Capture\3.0\Ascent Capture Administration\User Panels\
Note The registry key path reference to \Ascent Capture\3.0 is intentional. The setup OCX registry key values are listed in Table 6-1.
Table 6-1. Setup OCX Registry Key Values Value DisplayName Required? Yes Type String Description The display name of the panel. This name is displayed under the View | Toolbars menu, and it also appears when the panel is undocked. The Visible value determines whether or not the DisplayName appears under the View | Toolbars menu. The initial horizontal size of the panel in screen resolution pixels. The default is 50. The initial vertical size of the panel in screen resolution pixels. The default is 50. Minimum horizontal size of the panel when undocked in screen resolution pixels. The default is 50. Minimum vertical size of the panel when undocked in screen resolution pixels. The default is 50. The COM ProgID of the OCX. 0 (zero) indicates the setup OCX is used by a custom extension; 1 indicates the setup OCX is not used by a custom extension. The default is 0. 1 indicates visible, 0 (zero) indicates not visible. If set to 0, the panel will not be initially displayed and the DisplayName will not appear under the Toolbar menu. The default is 1.
InitSizeX InitSizeY MinSizeX
No No No
DWORD DWORD DWORD
MinSizeY
No
DWORD
ProgID Type
Yes Yes
String DWORD
Visible
No
DWORD
97
Chapter 6
If any of the required registry values are omitted when the Administration module attempts to load a setup OCX, the following error is reported:
User defined OCX {User Defined Key} contains an invalid registry value for {Value Name}.
Where: {User Defined Key} is the registry key under User Panels causing the error. {Value Name} is the name of the key value that was omitted. The application will shut down in this case. If any of the DWORD values are out of range, the Administration module will report the following error:
{Value Name} for user defined OCX {DisplayName} is out of range.
Where: {Value Name} is the name of the value. {DisplayName} is the value data for the DisplayName value. The value is ignored, and program execution will continue. If a registry key is properly constructed, but the OCX cannot be loaded for some reason, the Administration module will report the following error:
Unable to create user defined OCX {DisplayName}({Details}).
Where: {DisplayName} is the value data for the DisplayName value. {Details} indicates the error number or error description.
Menu Registry Keys

Each panel registry key should have a key entitled Menus under it. The keys registered under Menus define the menus for that OCX. Keys defined directly under Menus dictate the location of a menu item. The following key names are valid.
98
To add a menu item to a tree node: BatchClass DocumentClass FieldType FormIdZone FormType IndexGroupMemberZone IndexGroupZoneCollection IndexZone PageLevelBarcode PageLevelBarcodeCollection RegistrationZone RegistrationZoneCollection SamplePage SeparationZone To add a menu to the main frame menu: MenuBar Menu items are created by adding keys under the keys that are listed above. The name of the key is the internal name for that menu item. Also, you can specify the value listed in Table 6-2.
Table 6-2. Menu Registry Key Value Value Text Required? Yes Type String Description The display name of the menu item.
If this value is omitted, the menu item will not be added. The MenuBar key is a special case, such that it requires the value listed in Table 6-3. If this value is omitted, the menu will not be displayed.
Table 6-3. MenuBar Registry Key Value Value Text Required? Yes Type String Description The display name of the menu.
99
Chapter 6
Loading the Setup OCX

A setup OCX is loaded with the Administration module as follows: If the setup OCX is associated with a custom extension, the OCX is loaded: When the Administration module is launched, and if the setup OCX has been registered. While the Administration module is running, if the setup OCX is registered from the Administration module. If the setup OCX is registered with the Kofax Capture Extension Registration utility, the setup OCX will load the next time the Administration module is launched. If the setup OCX is not associated with a custom extension, the OCX is loaded: When the Administration module is launched, if the setup OCX has been registered. A setup OCX that is not associated with a custom extension must be registered with the Kofax Capture Extension Registration utility. If you register the setup OCX while the Administration module is running, the setup OCX will load the next time the Administration module is launched. Note Refer to Chapter 4 Creating a Registration File, for more information about registering custom extensions and setup OCXs. The first time the setup OCX is loaded, it appears undocked with other display characteristics as defined in the registry settings for the OCX. When a setup OCX is loaded again, it assumes the same location, size, docking status, and visibility used in the previous instance of the Administration module. For details, see Setup OCX Registry Entries on page 96. Note that if your setup OCX is associated with a custom extension, and the setup OCX files are not available in the Kofax Capture Bin folder when the Administration module launches, a message specifying the name of the custom module that must be registered is displayed. You are prompted to open the Custom Module Manager to register the setup OCX. If this kind of message displays, make certain that your setup OCX is installed to <Kofax Capture installation folder>\Bin. Then, click OK to register the missing setup OCX. Note Setup OCXs that are not associated with a custom extension must reside in the location specified in the .aex file used for registration.
100
Unloading the Setup OCX

A setup OCX is unloaded from the Administration module as follows: If the setup OCX is associated with a custom extension, the OCX is unloaded: When the Administration module is shut down While the Administration module is running, if the custom extension is unregistered from within the Administration module If the setup OCX is not associated with a custom extension, the OCX is unloaded when the Administration module is shut down. When a setup OCX is unloaded, its panel and all associated menus are removed from the Administration module.
Setup OCX Panels

At the discretion of the setup OCX developer, the Administration module can display a panel for each setup OCX. This panel may be resized and moved just like any other panel.
Enabling Panels
Setup OCX panels are enabled as follows: If the setup OCX is associated with a custom extension, the panel is enabled when both of the following are true: The Batch class tab of the Definitions panel is active. The current selection is either a batch class with the custom extension in its workflow, or a component of such a batch class. If the setup OCX is not associated with a custom extension, the panel is enabled when the Administration module is launched. Notice that in Figure 6-3, the custom setup panel is enabled. For this case, the setup OCX is associated with a custom module, and a batch class that contains that custom module is selected from the Batch class tab of the Definitions panel.
101
Chapter 6
Figure 6-3. Custom Module Setup Panel - Enabled State
When a panel is disabled, the panel itself remains visible, but the user interface elements of the setup OCX are hidden, as shown in Figure 6-4. In this figure, the setup OCX is associated with a custom module. However, the batch class that contains the custom module is not selected from the Batch class tab of the Definitions panel.
102
Figure 6-4. Custom Module Setup Panel - Disabled State
103
Chapter 6
Context Menus
A setup OCX may add one or more menu items to the context menus available from the nodes in the Batch class Definitions panel available in the Administration module. All of the custom menu items will be grouped together via separator bars (see Figure 6-5). The menus can be added programmatically, or they can be specified in the .aex file required for custom extension registration. Selecting one of these menu items sends an ActionEvent to the OCX, identifying the particular menu selected. Refer to Chapter 4 Creating a Registration File, for more information about registering custom extensions.
Enabling Context Menu Items

The behavior of the context menu items defined with a setup OCX are as follows: If the setup OCX is associated with a custom extension, the menu items are enabled and disabled when both of the following are true. (When a menu item is disabled, it is grayed.) The Batch class tab of the Definitions panel is active. The current selection is either a batch class with the custom extension, or a component of such a batch class. If the setup OCX is not associated with a custom extension, the menu items are always enabled. Figure 6-5 shows a context menu displayed by right-clicking a batch class name. For this case, the setup OCX is associated with a custom module, and a batch class that
104
contains the custom module is selected from the Batch class tab of the Definitions panel.
Figure 6-5. Custom Module Setup Tree Node Menu
105
Chapter 6
When setup OCX menu items are disabled, they are grayed. Figure 6-6 shows the custom menu items in a disabled state.
Figure 6-6. Setup OCX Menu Item in Disabled State
106
Main Menu Bar

A setup OCX can add one or more menus to the Administration module main menu bar, and define menu items for the menu. Custom menus always precede the Help menu, which is a standard menu item on the Administration module main menu bar. Selecting one of the custom menu items sends an ActionEvent to the setup OCX, identifying the particular menu item selected.
Custom Menu Names

Custom menu names defined by a setup OCX must be different from the standard menu names provided on the Administration module main menu bar. If you attempt to create a custom menu with the same name as an existing menu, the following error will occur when the setup OCX is loaded:
Cannot create {DisplayName} menu for the user-defined queue setup module {ProgID}.
Where: {DisplayName} is the display name of the frame menu to be added. {ProgID} is the COM prog ID for the OCX. For this case, the menu will not be added, but program execution will continue.
Enabling/Disabling Custom Menu Items

Custom menus added to the main menu bar by a setup OCX are always enabled. However, the behavior of the menu items for the custom menu are as follows: If the setup OCX is associated with a custom extension, the menu items are enabled when both of the following are true: The Batch class tab of the Definitions panel is active. The current selection is either a batch class with the custom extension, or a component of such a batch class. If the setup OCX is not associated with a custom extension, the menu items are always enabled. Figure 6-7 shows the custom menu added to the Administration module menu bar. Notice that the custom menu precedes the Help menu. For this case, the setup OCX that defines the custom menu is associated with a custom extension, and the batch
107
Chapter 6
class that contains the custom extension is selected from the Batch class tab of the Definitions panel.
Figure 6-7. Custom Menu with Menu Items - Enabled
In contrast, review Figure 6-8. For this case, the setup OCX is associated with a custom extension. However, the batch class that contains the custom extension is not selected. The main menu name Sample Index is available, but the menu items associated with it are grayed.
Figure 6-8. Custom Menu with Menu Items - Disabled
108
Toolbars
Each panel created by a setup OCX will be listed on the menu that appears when you select View | Toolbars. Clicking on this menu item will show or hide the panel, depending on its current state. Custom extension items are inserted before the status bar item on the View | Toolbars menu. Note A panel being shown or hidden has nothing to do with it being enabled or disabled. It is possible to show a panel that is disabled. When a disabled panel is shown, the panel elements are not displayed. It is possible to specify in the registry settings that a panel will always be hidden (see Visible key value in the table that appears in Setup OCX Registry Entries on page 96). In that case, that panel will always be omitted from the Toolbars menu.
Batch Class Publishing

A setup OCX can define publish checks to be used by the Administration module when batch classes are published. Note the following: If the setup OCX is associated with a custom extension, the publish checks defined by the OCX are used when batch classes that contain the custom extension are published. If the setup OCX is not associated with a custom extension, the publish checks are used when any batch class is published. No new user elements for publishing can be exposed with a setup OCX; however, changes to the publishing functionality can be defined. When a batch class is published, each queue performs its own publish checks, according to the queue order listed in the workflow. For example, if the workflow includes a custom extension that uses custom property settings, they are published along with the other property settings for the batch class. Any warnings associated with the custom extension are displayed in the Results list when you publish the batch class. If all publish checks succeed, the batch class is published. When a batch class is published, the custom properties for each custom extension are also published. If you change any custom properties, they are not reflected in the batch class until you publish it again.
109
Chapter 6
Setup OCX Development API

The complete API for the Kofax Capture Admin Module Type Library is documented in the Kofax Capture API Reference Guide. To access the Kofax Capture Admin Module Type Library 1 2 Select Start | Programs | Kofax Capture 8.0 | API Reference Guide from the Windows Start menu. When the API Reference Guide opens in a new browser window, click on the Kofax Capture Admin Module Type Library entry in the Table of Contents.
The Kofax Capture API Reference Guide documents the properties and methods in the Kofax Capture Admin Module Type Library. These properties and methods are associated with setup OCX applications. All properties and methods are defined using Visual Basic syntax.
110
Chapter 7
Creating Custom Panels and Applications
Introduction
With the Kofax Capture Module Type Library, you can add the following custom elements to the Scan, Quality Control, Validation, and/or Verification modules: Custom panels. You can add up to 20 custom panels to a standard Kofax Capture module. Each panel must be developed as an OCX. You can use different panels for each module to be customized. Custom menu items. In conjunction with a custom panel, you can implement custom menu items. In addition, by taking advantage of the extended features of the Kofax Capture Module Type Library, you can create standalone custom applications that act as input scripts. This feature (Import Controller) supports virtually any type of custom import application you might care to create. More information about the Import Controller and an example for its use is provided in Appendix C Sample Import Controller Program. These custom applications can be run from command lines and can also have their own interfaces that are entirely separate from Kofax Capture. These choices are entirely up to you. This chapter describes the following: User interface design and behavior Custom applications An example custom panel associated with the custom module described in Chapter 8 Creating a Custom Module is described later in this chapter.
111
Chapter 7
Programming in a High Availability Environment

When customizing Kofax Capture in a high availability environment, you should observe the error handling guidelines found in High Availability Environments on page 129. These will help ensure that your applications take full advantage of Kofax Captures high availability features. For more information on high availability, refer to the Kofax Capture Installation Guide.
User Interface Design and Behavior

The following sections describe the user interface design and behavior of custom panels and menu items, which may be added to the Scan, Quality Control, Validation, and/or Verification modules. Each panel contains a user-defined OCX.
Custom Panels
A sample custom panel in the Validation module is shown in Figure 7-1.
Figure 7-1. Custom Panel Sample in the Validation Module
112
The user OCX is contained completely within a new user interface panel. This panel may be resized and moved just like any standard panel. The OCX panel sends resizing events to the child OCX whenever the panel itself is resized. The OCX may display any desired graphical objects on the panel. The outside edge of the panel (about 4 pixels) is used for panel operations (listed below). Any panel clicks outside this margin area are passed to the OCX. If the OCX obtains focus, then keyboard events are also sent to it. Standard panels and new OCX panels support the following operations: Saving the panels size, state (floating/docked), and position between application invocations. Clicking and dragging on the top edge of a panel causes the panel to move to a new location on the frame. If the panel is dragged off the frame, then it becomes a distinct, floating window. Double-clicking on the top edge of a docked panel changes that panel into a floating window. (Double-clicking the top edge of the panel toggles between a docked/undocked state.) Resizing a floating window. The panel has a minimum size (which is 50,50 for default panels). Hiding a floating window by clicking its Close box. The panel can be restored by selecting it from the View | Toolbars menu. Dragging a floating window back to the frame to redock the panel to the frame. Note The OCX cannot programmatically resize its parent window. A panel may receive several resize events just after creation. An initial resize of size 0,0 occurs when the OCX is first built. Windows may send other events, depending on the screen resolution configuration. Any changes to data made by the OCX (field content, field data, reject flag, note information) are reflected by all standard Kofax Capture controls, including the image viewer(s), the tree view, the data entry panel, and the thumbnail view. Note the following: Panels without windows: A visible flag in the registry will determine if a panel is displayed in the toolbar list. If a panel is not visible, it will never appear in the toolbar list. The OCX has an API called ShowWindow(), which will allow it to display itself.
113
Chapter 7
If the panel has the visible flag = 0 in the registry, it will not appear in the toolbar list. It can still be displayed via menu selections. If the panel is visible when the application closes, it will be visible when the application opens. As a workaround, dont display the panel. Instead, the OCX can display a modal dialog box. Or, you can hide the panel after opening the application. Panels hidden by the OCX: The application API allows the panel to hide/ show itself. Development Environment A custom panel must be defined as an OCX created in Visual Basic 6. An OCX created in another version of Visual Basic or another development environment may work. However, the custom panel OCX feature has been tested with Visual Basic 6.
Custom Menus
The Toolbars menu (available from the View menu or a Toolbar context menu) contains a new entry that allows hiding/showing the user panel. The User Panel Name on the menu is configurable, and it always appears immediately above the status bar item on the Toolbars menu, as shown in Figure 7-2.
Figure 7-2. Custom Panel Name on the Toolbars Menu
In addition, each OCX can add a menu to the menu bar. The menu is inserted on the menu bar before the Help menu. The name of the new menu must be different from any existing menu bar text. Duplicates will not be added. If you attempt to add duplicate text, an error will be generated.
114
The menu bar text and menu items can be read from the registry. The registry supports one menu bar per panel. Multiple menu bars may be defined programmatically. When more than one OCX (user-defined panel) exist in the registry, they are added in the order they are loaded. The registry alphabetizes its entries. If added programmatically, the menus are inserted before the Help menu in the order that the panels are loaded, as shown in Figure 7-3.
Figure 7-3. Example of OCX Menu Order
Menu items as shown above (Show Me, Hide Me, and Show Dialog) can be defined as part of your OCX. For an example, see the sample OCX provided in your installation folder. Refer to Using the Sample Custom Panel on page 122 for more information about installing and registering the samples. Scan, Quality Control, Validation, and Verification Tree Node Menus Each OCX may add one or more items to the tree nodes displayed in the Batch Contents panel. The menu text, accelerator, and tree nodes are specified in the registry or can be added programmatically. Selecting one of these menu items sends an action event to the OCX. The action event identifies the menu item selected. Note The OCX developer is responsible for accelerator key uniqueness.
Menus Can Be Added, Removed, and Edited at Runtime The AddMenu() API allows the addition of menu items by the OCX while loading or running. A ShowMenu() API allows a user-defined menu item to be shown or hidden. Refer to the Kofax Capture API Reference Guide for details about AddMenu() and ShowMenu(). If all items under a menu bar title are hidden, the menu bar is removed.
115
Chapter 7
Registry Entries for Menus Each user-defined panel will have a Menus key under it. The Menus key will have subkeys for each menu that allows the insertion of menu items. Each menu will have a name and properties. Currently, the only property is the menu text. Table 7-1 describes the Menus registry keys.
Table 7-1. Registry Keys Key Entries Menus Batch Document MenuBar Page Description This key indicates that menus will follow. The locations are under the menus. Locations for menus to appear. The example code below shows the menu location names.
'*** Possible locations for user-defined '*** menus for Scan, Quality Control, '*** Validation, and Verification m_RuntimeMenuLocationKeys(0) = MenuBar m_RuntimeMenuLocationKeys(1) = Batch m_RuntimeMenuLocationKeys(2) = Document m_RuntimeMenuLocationKeys(3) = Page
The MenuBar contains one additional text key from the MenuBar to identify the text displayed on the frame. Batch Menu Sel Menu event text, supplied by the developer. This is the text that will be returned to the OCX when the menu item is selected. This text is passed back as part of the MenuClicked() action event. Text is the non-localized value that contains the text to be displayed. This contains the accelerator key (& on the P).
Text &Pick me
For example, Menubar: &Sample OCX is the menu bar text added from a registry entry. A second menu bar entry &OCXTest was added by calling AddMenu() within the OCX.
Figure 7-4. Menu Bar Text Added from a Registry Entry
116
The MenuBar entry contains one string value. This is the menu text for the menu bar with the accelerator on it. Multiple menu bar items can be added programmatically using AddMenu(). Note The OCX developer is responsible for accelerator key uniqueness.
Installing a Custom Panel

To install a custom panel, the OCX must be copied and registered on each client computer. The OCX file need not reside in any specific folder location. Also, any required customer DLLs must be installed (if necessary). Note Custom panels are not included as part of the standard Kofax Capture installation. However, sample custom panels are available in your Kofax Capture installation folder (a Visual Basic 6 sample is located at Source\Samples\StdCust, and a VB.NET sample is located at Source\VB.Net Samples\StdCust). For more information, see Using the Sample Custom Panel on page 122. Next, some registry entries (on each client computer) must be created under the following path: HKEY_LOCAL_MACHINE\Software\Kofax Image Products\Ascent Capture\3.0\{module name}\User Panels\{User-Defined-Key}\ The local machine area is utilized since such configuration is more likely to be based on the computer than on the user. The {module name} must be replaced with one of the following names: Kofax Capture Scan Kofax Capture Quality Control Kofax Capture Validation Kofax Capture Verification Note Although you may be working with a later Kofax Capture installation, notice that the registry entry is created under a path that intentionally includes a reference to 3.0. Within the User Panels path, the {User-defined Key} key is any valid registry key. If more than 20 keys exist in this folder, then subsequent keys are ignored.
117
Chapter 7
As shown in Table 7-2, the following values may be defined for the {User-defined Key}.
Table 7-2. {User-Defined Key} Values Value DisplayName Required? Yes Value Type String Notes The name may appear in the title bar of the undocked panel or in the toolbars list. The toolbars list is available from the View menu or by right-clicking on an empty area of the control bars under the menu. Currently, this menu always contains the name of a userdefined OCX and the end user is allowed to turn the panel on and off. The OCX has no control over this functionality. The Visible value setting determines whether or not the panel name appears in the toolbars list. The initial horizontal OCX size in screen resolution pixels. The default is 50. The initial vertical OCX size in screen resolution pixels. The default is 50. The minimum undocked horizontal OCX size in screen resolution pixels. The default is 50. The minimum undocked vertical OCX size in screen resolution pixels. The default is 50. The COM program ID of the OCX.
InitSizeX InitSizeY MinSizeX

1
No No No
DWORD DWORD DWORD
MinSizeY ProgID
No Yes
DWORD String
118
Table 7-2. {User-Defined Key} Values (continued) Value ReplacesIndex FieldsPanel Required? No Value Type Notes This applies to the Validation and Verification modules only. When enabled, the Index Fields panel and its View, Toolbars, and Index Fields menu items are hidden. Additionally, its context menu will not show the Index Fields menu item. When an eDocument is displayed the internal Windows Explorer panel takes focus after displaying the eDocument. If the OCX has registered itself as ReplacesIndexFieldsPanel, then it will receive a new event (KfxOcxEventResetFocus) indicating that focus has been returned to the OCX. In such cases, Kofax Capture gives focus to the outer OCX panel. However, you may want to set focus to some subcontrol. To do this, catch the new event and set focus as desired. Only one OCX can register itself as ReplacesIndexFieldsPanel. Note that the panel works best when docked. Visible No DWORD Determines if the panel is displayed in the toolbars list. If the panel is not visible, it can still be displayed via menu selections. Defaults to 1 (visible); 0 is not visible.
The minimum size parameters affect only the undocked minimum size. There is no support for minimum docked size.
119
Chapter 7
Figure 7-5. Registry Values for the {User-Defined Key}
The initial docking location is always at the upper left of the client area. If any of the required values are missing, then the application displays the following error message and then shuts down:
User-defined OCX {User-defined Key} contains any invalid registry values for {Key Name}.
Because the OCX is an integral part of the application, the user is not allowed to run the application unless the OCX is properly set up. If absolutely necessary, the user may completely remove the OCX registry key and the software will run. However, this is not recommended as invalid data may occur (assuming the OCX is performing the necessary tasks). If any size parameter is out of range, the following message displays:
{parameter} for user-defined OCX {DisplayName} is out of range.
The {parameter} string is one of the values shown in Table 7-2. If all parameters are read and valid, but the OCX cannot be created for some reason, the following message is displayed:
Unable to create user-defined OCX {DisplayName} ({details})
Where: {details} indicates the error number and/or description.
120
Invoking Kofax Capture Menu Items from a Custom OCX Panel

You can use a custom OCX panel to invoke Kofax Capture menu items in the Administration, Scan, Quality Control, Validation, and Verification modules through the SelectMenuItem function.
Table 7-3. SelectMenuItem Function Function SelectMenuItem Arguments Returns: Boolean Parameters: lResourceID [ByVal; Long] bSendImmediate [ByVal Optional Default to FALSE] Description Sends a selected menu item to a Kofax Capture module. Resource ID of menu item.
If successful, SelectMenuItem returns a nonzero value. In the case of an unexpected system error, it returns a value of zero. SelectMenuItem will throw an error if any of the following are true: You specify an invalid resource ID for the menu item The item is currently grayed in the target module You execute an exit menu item immediately (bSendImmediate is True) The application is busy The bSendImmediate parameter is optional, and it can be set to True or False. If True, bSendImmediate invokes the Windows API call SendMessage, which executes the menu command instantly and fails if the module is processing another event. If False, bSendImmediate invokes the Windows API call PostMessage, which posts the menu command so it is executed when other events are completed. The following sample passes a menu item from a custom OCX to the Scan module. The menu item shown here displays the last page in a batch.
Private SubScanStopped() Dim bResult As Boolean Dim lMenuResourceNumber As Long Dim bSendImmediate as Boolean bResult=False On Error GoTo MenuSelectError: lMenuResourceNumber=AscentCaptureModule.KfxScanMenuPageLast bSendImmediate=False
121
Chapter 7
bResult=m_oApp.SelectMenuItem(lMenuResourceNumber, _ bSendImmediate) Exit Sub MenuSelectError: MsgBox Unable to select menu: & Err.Description End Sub
In the following code, the OCX Menu Selection invokes the About Kofax Capture menu selection in the Administration module.
Dim bSendImmediate As Boolean bSendImmediate=False Display the about box bResult=m_oApp.SelectMenuItem _ (AscentCaptureAdminMod.KfxAdminMenuHelpAboutAscentCapture, bSendImmediate)
In the above example, KfxAdminMenuHelpAboutAscentCapture is the item for the Administration modules About Kofax Capture menu item. A separate set of menu items is available for each Kofax Capture module.
Using the Sample Custom Panel

A sample custom panel is provided as part of your Kofax Capture installation. The samples are installed to the following folders: Visual Basic 6: <Kofax Capture installation folder>\Source\Samples\StdCust Visual Basic .NET: <Kofax Capture installation folder>\Source\VB.Net Samples\StdCust Two subfolders are included: OCXPanel (or OCXPanel.NET) - This folder contains Visual Basic source code for a sample OCX. OCXReg (or OCXReg.NET) - This folder contains Visual Basic source code for a sample registration utility. The source code in the preceding folders was created in Visual Basic 6 and Visual Basic.NET. The sample OCX is provided to give you an example of a simple custom OCX. The sample registration utility demonstrates the type of utility you might provide to customers for installing and registering your sample OCX for use with Kofax Capture.
122
Registering the Sample Custom Panel Custom panel registration is a two-part process, requiring you to do the following: Use a utility (such as the sample utility provided in your OCXReg folder) to register the custom sample panel with Kofax Capture. For COM components, use RegSvr32.exe to register a custom panel in the Windows Registry. For .NET components, use RegAsm.exe to register a .NET custom panel for COM Interop with the Windows Registry and the .NET Framework. Kofax Capture Registration This section explains how to use the sample registration utility to register the sample OCX panel for use with Kofax Capture. To register the sample custom panel 1 2 Browse to the OCXReg folder, which contains the sample registration utility. Double-click on the file PanelReg.exe to start the User Panel Registration Tool, shown in Figure 7-6.
Figure 7-6. Registering a Custom Panel
At Modules, select the check box for each module in which you want to enable the sample OCX panel. Select the check box for each module listed: Scan, Quality Control, Validation, and Verification. At ProgID (for the VB .NET sample), replace the default SampleOCX.SampleUserControl with Kofax.SampleUserControl.
123
Chapter 7
5 6
For demonstration purposes, you do not need to change the other default settings. Click Save.
Windows Registration In addition to the Kofax Capture registration, you need to register the custom panel in the Windows Registry. To register a custom panel OCX in the Windows Registry 1 2 From the Windows Start menu, select Run. From the Run dialog box, type the following:
<path1>RegSvr32.exe <path2>Ocxname.ocx
Where: <path1> is the full path to the RegSvr32 application. <path2> is the full path to Ocxname.ocx. Ocxname.ocx is the name of your custom panel OCX. To register the sample custom panel 1 2 From the Windows Start menu, select Run. From the Run dialog box, browse to the OCXPanel folder included in your Kofax Capture installation and type the following:
<path1>RegSvr32.exe <path2>Smpleocx.ocx
Where: <path1> is the full path to the RegSvr32 application. <path2> is the full path to Smpleocx.ocx. Smpleocx.ocx is the name of the sample custom panel OCX provided with Kofax Capture. To register the sample .NET custom panel 1 2 From the Windows Start menu, select Run. From the Run dialog box, type the following:
<path1>RegAsm.exe <path2>OCXname.dll /tlb
Where: <path1> is the full path to the .NET Framework, usually for .NET Framework 2.0: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\
124
<path2> is the full path to OCXname.dll. OCXname.dll is the name of the sample .NET custom panel OCX provided with Kofax Capture. Viewing the Custom Panel After the registration process, the custom panel is available in each module for which it was registered with Kofax Capture. For details about typical custom panel behavior, see User Interface Design and Behavior on page 112.
Example Custom Panel in VB .NET

The following example custom panel named DelPagePanel has no user interface but enables an operator to flag a page for deletion. This custom panel uses a context menu accessible from a batch to mark pages for deletion. When you right-click the page that you want deleted, the following context menu is displayed. It enables you to mark the page for deletion.
Figure 7-7. Flag Page for Deletion Option Provided Through the Custom Panel Context Menu
The following is the code for the custom panel (DelPagePanel).
125
Chapter 7
DelPagePanel
Imports Kofax.AscentCaptureModule Public Class DelPagePanel Inherits System.Windows.Forms.UserControl #Region " Windows Form Designer generated code " <This segment of code was removed--it is generated by VB .NET for the form> #End Region #Region "*** Private Member Data/Constants" Private Const cm_strDeletePageMenu As String = "DeletePageMenu" Private Const cm_strDeletePageMenuText As String = "Flag Page _ for Deletion" Private Const cm_strPageCSSName As String = "DeletePage" '*** Application object Private m_oApplication As Kofax.AscentCaptureModule.Application #End Region #Region "*** Public Properties/Methods" Public Property Application() As _ Kofax.AscentCaptureModule.Application Get Return m_oApplication End Get Set(ByVal Value As Kofax.AscentCaptureModule.Application) m_oApplication = Value '*** Initialize Menus InitializeMenus() End Set End Property Public Sub ActionEvent(ByVal nEventNumber As Integer, ByRef _ oArgument As Object, ByRef nCancel As Integer) If nEventNumber = KfxOcxEvent.KfxOcxEventMenuClicked Then
126
'*** Make sure we got the right menu If CStr(oArgument) = cm_strDeletePageMenu Then '*** Flag the page for deletion by setting the Page _ Custom Storage String m_oApplication.ActiveBatch.ActivePage.CustomStorageString _ (cm_strPageCSSName) = "True" End If End If End Sub #End Region #Region "*** Private Methods" Private Sub InitializeMenus() '*** Add a menu for deleting the page m_oApplication.AddMenu(cm_strDeletePageMenu, _ cm_strDeletePageMenuText, "Page") End Sub #End Region End Class
127
Chapter 7
128
Chapter 8
Creating a Custom Module
Introduction
Custom modules can be created to perform tasks such as document separation, page registration, form identification, automatic or manual indexing, verification, or full text OCR. Custom modules can also perform unique functions suited to your business needs. For example, you might want to write a custom OCR module that uses an engine other than the engines provided with Kofax Capture. Or, the custom module might perform a special type of image processing, such as bar code recognition on color images or form identification using a custom algorithm. This chapter gives you an overview of the development process for creating a custom module for Kofax Capture. An example custom module, which is part of the comprehensive example of a custom workflow agent, setup OCX, and custom panel is also provided in this chapter.
Custom Modules
You can implement a custom module alongside the standard set of Kofax Capture processing modules, or you can use it to replace a standard module. Once you create the custom module, it must be registered for use with Kofax Capture and added to the batch class workflow (which must include the standard Scan module to introduce a batch into the Kofax Capture processing environment, as well as the standard Release module as the final processing module).
High Availability Environments

When customizing Kofax Capture in a high availability environment, you should observe the following error handling guidelines. These will help ensure that your applications take full advantage of Kofax Captures high availability features. For more information on high availability, refer to the Kofax Capture Installation Guide.
129
Chapter 8
Error Handling Guidelines Any component of a highly available system is subject to failure at any time. To meet high availability requirements, you should design your Kofax Capture customizations to detect and recover from errors during operations that require access to a remote computer. These errors can be grouped into the following categories: Database Operations Any customization that accesses a database on another computer may encounter errors. If the customization accesses a database that is on a cluster server, then during a failover the database will be off-line for a short period of time. Database errors can occur due to a variety of issues including, but not limited to, intermittent network failures and cluster failover. To ensure high availability, your application must check for errors on every database operation. If an error occurs, the application must reconnect to the database and retry the operation if necessary. Note that even if there is an error, it is possible that the database operation succeeded but that a network failure prevented the successful result from reaching your application. Therefore, if it is important that the failed operation be executed exactly once, you must determine if it succeeded or failed in order to know if the operation should be retried. Since it takes a period of time for the database to failover, applications should continue to retry for at least 2 minutes. File System Operations Any customization that accesses files on another computer may encounter errors. If the customization accesses a file system that is on a cluster server, then during a failover, the file system will be off-line for a short period of time. File access errors can occur due to a variety of issues including, but not limited to, intermittent network failures, contention, and cluster failover. To ensure high availability, your application must check for errors on every file operation. If an error occurs, it must retry the operation. Note that when an operation returns an error, it is possible that the file operation started, but did not complete. Therefore, when retrying, you must take care to determine if the same parameters can be used or if the failed operation changed the state of the system. Since it takes a period of time for the file system to failover, applications should continue to retry for at least 2 minutes.
130
Client / Server Operations Any customization that accesses a third-party server application on another computer may encounter errors. The client/server application might be cluster-aware and be deployed on the cluster server, or it may provide some other mechanism to make the server highly available. In any case, it is up to the client/server application utilized by the Kofax Capture customization to provide high availability in some way. Third-Party Operations Any third-party function utilized by a Kofax Capture customization might access a remote computer. To ensure high availability, your application must check for errors after every function call. If an error occurs, the application must determine if a retry is needed.
Sample Applications
A custom module example named DeleteEvenPage, which is part of the comprehensive VB .NET example, is used to demonstrate the design and implementation of a custom module. The code for this custom module is provided later in this chapter. Kofax Capture also ships with a sample custom module that is provided as part of your Kofax Capture installation. Visual Basic 6 program is in the folder <Kofax Capture installation folder>\Source\Samples\CustMod\Generic Visual Basic .NET program is in the folder <Kofax Capture installation folder>\Source\VB.NET Samples\CustMod\Generic.NET The folder contains the files necessary to register a custom module named Sample. The sample gives a generic example of a custom module, which you can install and register for demonstration purposes. For details about the sample custom module, see Appendix A Custom Module Sample.
131
Chapter 8
Typical Development Tasks

The typical custom extension development process includes the tasks outlined in this section. You may decide to perform some tasks in a different order. Design the custom extension Configure the setup OCX to store properties and add publish checks Write the runtime application (use Kofax Capture Document Access API library elements to create an application to interact with Kofax Capture) Create the custom extension registration file Register the custom extension Create the installation program
Design the Custom Module

As with any development project, the success of the custom module implementation process requires careful planning and analysis. Before starting any development, consider how your custom module will augment the standard Kofax Capture functionality. For example, be sure to take into account the characteristics of the forms you expect to process with the custom module. Then decide whether you want to make the custom module available in addition to, or in place of, existing Kofax Capture functions. Additionally, you need to determine if it would be appropriate to add custom configuration settings to support the new functionality. Then decide where (menus or user interface panels) it would be appropriate to make the custom settings available to the user. You should produce specifications that define the design, functionality, and scope for the custom extension.
Create the Setup OCX

You will probably want to develop a setup OCX in the Administration module to store configuration properties and publish checks associated with the custom extension. The setup OCX is optional, because you could potentially use the standard Kofax Capture settings. For example, if you developed a custom module to replace the standard Validation module, you might be able to use the standard settings and publish checks. However, it is likely that most custom extensions will require unique configuration properties and publish checks. For details, see Chapter 6 Creating a Setup OCX.
132
Write the Runtime Application

Use the Kofax Capture Document Access API library to integrate the application into your Kofax Capture installation. You can present a list of batches to the user, or you can opt to have the custom module automatically process batches as they become available. Develop the custom module to meet your specifications. Kofax Capture Document Access also allows XML batch information to pass between Kofax Capture and the custom module. As the custom module receives a batch, it performs the custom function(s), and then sends the batch back to Kofax Capture. Note Your XML transport files need to follow the format required for compatibility with Kofax Capture. Sample Document Type Definition (DTD) files required for custom module XML files are provided with Kofax Capture and are installed with the program.
Create the Custom Module Registration File

You must create a registration file that defines the property settings for the custom module. The file must be in place before you register the custom module. The following is the registration file (DeleteEvenPage.aex) for the example custom module:
[Modules] Delete Even Page CM [Delete Even Page CM] RuntimeProgram=DeleteEvenPage.exe ModuleID=DeleteEvenPage.exe Description=This module deletes even pages...a very useful tool Version=8.0 SupportsTableFields=True SupportsNonImageFiles=True
The registration file (DeleteEvenPage.aex) contains: The name of the custom module (identified under the heading [Modules]) The custom module name (identified under the heading [Delete Even Page CM]) Runtime executable for the custom module Module ID
133
Chapter 8
ProgID of the custom module For more information about the registration file, read Chapter 4 Creating a Registration File.
Register the Custom Module

Once the registration file is in place, you register the custom module so that Kofax Capture will recognize it. After registration, you can also test the setup OCX to verify its validity. For details on registering custom extensions, see Chapter 4 Creating a Registration File. After registration, you can add the custom extension to the batch class so you can test it. Once you are satisfied with the preliminary tests, you can proceed to create an installation program.
Create an Installation Program

If you plan to distribute the custom module, you will need to write a program to add the application to your Kofax Capture installation. If desired, you can incorporate the registration process into the installation program. You will need to install the custom extension setup OCX, custom extension runtime, and registration file to the <Kofax Capture installation folder>\Bin folder for every workstation where you want the custom extension to be available. If desired, you can add a custom extension icon to the Kofax Capture program group.
Example Custom Module

The example program named DeleteEvenPage is an unattended module that is designed to run after the Scan module. It checks that the pages marked for deletion are removed from the batch. The following is the code for the custom module named DeleteEvenPage. This class definition makes up the blueprint for the custom module. In the Initialize function, we log into Kofax Capture and cache the appropriate data structures. DeleteEvenPage Module
Imports Kofax.DBLite Imports Kofax.DBLiteOpt Imports System.Threading
134
Public Class Driver '*** Reference to the Login object rivate m_oLogin As Kofax.DBLite.Login *** Reference to the RuntimeSession object Private WithEvents m_oRuntimeSession As _ Kofax.DBLite.RuntimeSession '*** Reference to the Active Batch Private m_oActiveBatch As Kofax.DBLite.Batch '*** Create a mutex to protect calls to ProcessBatch Private m_oMutex As Threading.Mutex '*** We will fire this event when we want to log something to _ the window Public Event StatusMessage(ByVal Message As String) Public Sub Initialize() Try '*** Initialize the Mutex m_oMutex = New Threading.Mutex '*** Create the Login object m_oLogin = New Kofax.DBLite.LoginClass '*** Log into Kofax Capture m_oLogin.Login() '*** Set the App name and version m_oLogin.ApplicationName = "DeleteEventPage CM" m_oLogin.Version = "1.0" '*** Validate the User m_oLogin.ValidateUser("DeleteEvenPage.exe", True) RaiseEvent StatusMessage("Logged into Kofax Capture") '*** Cache the Runtime Session m_oRuntimeSession = m_oLogin.RuntimeSession
135
Chapter 8
Catch ex As Exception RaiseEvent StatusMessage("An error occurred: " & ex.Message) End Try End Sub
ProcessNewBatch Function The ProcessNewBatch function attempts to open the next available batch for this module. If it is able to open a batch, the batch is processed by deleting those pages that were marked for deletion by the Scan operator.
'*** This function returns True if we successfully process a Batch. '*** Otherwise, we will return False (ie. No Batches Available) Private Function ProcessNewBatch() As Boolean Try '*** Get the new Batch m_oActiveBatch = m_oRuntimeSession.NextBatchGet( _ m_oLogin.ProcessID, _ KfxDbFilter.KfxDbFilterOnProcess _ Or KfxDbFilter.KfxDbFilterOnStates _ Or KfxDbFilter.KfxDbSortOnPriorityDescending, _ KfxDbState.KfxDbBatchReady _ Or KfxDbState.KfxDbBatchSuspended) '*** Make sure we have a reference If Not m_oActiveBatch Is Nothing Then RaiseEvent StatusMessage("Opened Batch: " & m_oActiveBatch.Name) '*** Extract the RuntimeDataElement Dim oRuntimeDataElement As ACDataElement oRuntimeDataElement = m_oActiveBatch.ExtractRuntimeACDataElement(0) '*** Get the Batch element Dim oBatchElem As ACDataElement = oRuntimeDataElement.FindChildElementByName("Batch")
136
'*** Get the Pages element Dim oPagesElem As ACDataElement = oBatchElem.FindChildElementByName("Pages") '*** Keep track of the Page Count Dim lngCount As Long = 0 '*** Iterate through the Page elements Dim oPageElem As ACDataElement For Each oPageElem In oPagesElem.FindChildElementsByName("Page") '*** Increment our counter lngCount = lngCount + 1 '*** Check if we should delete this page If PageMarkedForDeletion(oPageElem) Then '*** Delete it! oPageElem.Delete() RaiseEvent StatusMessage("Deleted Page " & lngCount) End If Next '*** Close the Batch m_oActiveBatch.BatchClose(KfxDbState.KfxDbBatchReady, _ KfxDbQueue.KfxDbQueueNext, 0, "") '*** Return success ProcessNewBatch = True Else RaiseEvent StatusMessage("No batches for me available.") '*** Return false so we fall back into polling/waiting for _ signal ProcessNewBatch = False
137
Chapter 8
End If Catch ex As Exception RaiseEvent StatusMessage("An error occurred: " & ex.Message) '*** If we have a reference to the Batch object, close _ in error If Not m_oActiveBatch Is Nothing Then m_oActiveBatch.BatchClose(KfxDbState.KfxDbBatchError, _ KfxDbQueue.KfxDbQueueException, 1000, ex.Message) End If End Try End Function
PageMarkedForDeletion Function The PageMarkedForDeletion function returns a flag that indicates that the Scan operator selected the page to be deleted. This flag is stored in a page-level custom storage string file.
Private Function PageMarkedForDeletion(ByRef oPageElem As _ ACDataElement) As Boolean '*** Get the Page Custom Storage Strings Dim oPageCSSs As ACDataElement oPageCSSs = _ oPageElem.FindChildElementByName("PageCustomStorageStrings") '*** Get the Page Custom Storage String by element Dim oPageDeleteCSS As ACDataElement oPageDeleteCSS = _ oPageCSSs.FindChildElementByAttribute _ ("PageCustomStorageString", "Name", "DeletePage") '*** Make sure we have a reference If Not oPageDeleteCSS Is Nothing Then '*** Check the value If oPageDeleteCSS.AttributeValue("Value") = "True" Then PageMarkedForDeletion = True Exit Function
138
End If End If End Function
RuntimeSession_BatchAvailable Subroutine This function handles the BatchAvailable event from Kofax Capture. This handler attempts to process as many batches as possible. A mutex is implemented to ensure that this logic is processed by only one thread at a time.
Private Sub m_oRuntimeSession_BatchAvailable() Handles _ m_oRuntimeSession.BatchAvailable '*** Lock access to this call m_oMutex.WaitOne() Try '*** Process a new Batch While ProcessNewBatch() RaiseEvent StatusMessage("Process Batch Completed") End While Catch ex As Exception RaiseEvent StatusMessage("An error occurred: " & ex.Message) Finally '*** Release the mutex m_oMutex.ReleaseMutex() End Try End Sub End Class
139
Chapter 8
140
Chapter 9
Creating a Release Script
Introduction
Release is the process of exporting images and data to long-term storage after all Kofax Capture processing is finished. A release script consists of two COM components that configure and execute this process. These two components could be in one or two .dll or .exe files. Kofax Capture includes two standard release scripts: A database release script that releases document index data to a Microsoft Access 97/2002 or an ODBC-compliant database. Source code for this release script is installed to your <Kofax Capture installation folder>\Source\Release\Database folder. A text release script that releases document index data to an ASCII text file. Source code for this release script is installed to the <Kofax Capture installation folder>\Source\ Release\Text folder. Both of these scripts release images, full text OCR files, and PDF files to the standard file system. These release scripts were written in Microsoft Visual Basic 6.0. The source code for these release scripts is installed with Kofax Capture. If you need to release document index data or files to other sources, you can modify one of the supplied scripts, you can create an entirely new one, or you can purchase one from Kofax or other third party entities. Note that a wide variety of release scripts are available from Kofax for popular applications developed by Documentum, FileNet, Hummingbird, IBM, and others. Contact your Certified Solutions Provider for details on availability. Release scripts are typically written in Visual Basic, but they can also be written with any tool that supports the development of COM servers.
141
Chapter 9
Kofax Capture Release Type Library

The complete release script API library is documented in the Kofax Capture API Reference Guide. To access the Kofax Capture Release Type Library 1 2 Select Start | Programs | Kofax Capture 8.0 | API Reference Guide from the Windows Start menu. When the API Reference Guide opens in a new browser window, click on the Kofax Capture Release Type Library entry in the Table of Contents.
Kofax Capture and the Release Process

The Kofax Capture Administration module manages the Release Setup process. It loads the release setup script when the system administrator selects a release script for a document class/batch class pair. The release setup script must implement the KfxReleaseSetupScript COM interface that the Administration module requires. Similarly, the Kofax Capture Release module manages the Release process. It loads the appropriate release script when the batch enters the Release Queue. The release script must implement the KfxReleaseScript COM interface that the Release module requires. The Database and the Text release scripts include the KfxReleaseSetupScript and KfxReleaseScript COM components in the ActiveX DLL. When writing a release script, there are two basic functions you must provide: Release setup, which is the user interface for configuring the release process within the Administration module. The release setup portion of the release script is called by the Administration module when the user selects a release script to configure. Release, which performs the actual export of images and data to long-term storage. The release portion of the release script is called by the Release module when it is releasing batches.
Requirements for the Release Setup Script

The release setup script component must define the KfxReleaseSetupScript COM interface.
142
The KfxReleaseSetupScript interface must include the following: One public object variable declared as ReleaseSetupData. The Administration module uses this variable to expose and update release configuration for the document class. Four methods called OpenScript, RunUI, ActionEvent, and CloseScript, which the Administration program calls to perform the various stages of the release setup process. When you use the Administration program to select and configure a release script for the first time, it loads the release setup script and does the following: 1 Fills in the document class properties in the ReleaseSetupData variable. These properties include the available document class index fields, batch class fields, and image file formats. Calls the OpenScript method. You should use this method to perform any initialization required for the script. Calls the RunUI method. You should use this method to load a form or dialog box that allows the user to configure the release process. For example, the database release script displays a form that allows setup of database links, image formats, file folders, and so forth. When the user is finished with setup, you store the users choices in the ReleaseSetupData variable and call the ReleaseSetupData.Apply method to save them permanently to the Kofax Capture database. Calls the CloseScript method after the RunUI method is completed and the script is about to be unloaded. You should use this method to perform any cleanup required for the script.
2 3
If you make a change to the document class after the initial release setup process, the Administration program performs the same series of steps as before, with one exception: instead of calling the RunUI method, it calls the ActionEvent method with a set of parameters that indicate why it is being called. You should use this method to determine whether the change in the document class requires a change in the release setup process. For example, if a new index field is added, you might want to call the RunUI method to provide an opportunity to save this new data in the external database.
Requirements for the Release Script

The Release module uses a COM interface called KfxReleaseScript to communicate with the release script. The standard Text and Database release scripts define this interface in the Release.cls code module.
143
Chapter 9
The KfxReleaseScript interface must include the following: One public object variable declared as ReleaseData. The Release module uses this variable to expose release data for the release process. Three methods called OpenScript, ReleaseDoc, and CloseScript, which the Release module calls to perform the various stages of the release process. When a batch containing documents of a given class enters the Release module, it loads the release script and does the following: 1 2 3 Fills in the general batch class and document class properties in the ReleaseData variable. Calls the OpenScript method. You should use this method to perform any initialization required for the script. Fills in the properties specific to the first document to be released in the ReleaseData variable and calls the ReleaseDoc method for the document. You should use this method to save the document data in the external database and copy the image files and full text OCR files to the selected release folders. Repeats the process described in Step 3 for each remaining document to be released. Calls the CloseScript method after the last ReleaseDoc method is completed and the script is about to be unloaded. You should use this method to perform any cleanup required for the script.
4 5
Note that you cannot provide your own user interface for the release process. The Release module has its own user interface. The various methods listed above provide data to update the Release module user interface as documents and batches complete the release process. The release process is designed to run unattended.
The ReleaseSetupData and ReleaseData Objects

Both database release script and text release script support a wide variety of features and both contain a long list of functions and subroutines. These functions are documented in the Kofax Capture API Reference Guide. However, writing a release script is not actually as complex as you may think. Most of the required work is confined to specific locations in the script. The code involves use of the methods and properties for the ReleaseSetupData and ReleaseData objects. Understanding these two objects is the key to writing a release script.
144
Release Setup Script There are only two places in the release setup script where you have to write a substantial amount of code: The RunUI event should load a form that presents a user interface. This form can be as simple or as complex as you wish. When the user clicks OK to finish release setup, you must save the users settings in the Kofax Capture database. To do this, you must set up a links collection that specifies which index fields should be released and then copy other settings as necessary into the ReleaseSetupData object. When this is finished, call the Apply method to save your changes. ReleaseSetupData Object The ReleaseSetupData object is a top-level object used by both the Kofax Capture Administration module and the release setup script to define the release process for a document class. Some properties of this object are set up by the Administration module when the ReleaseSetupData object is created. For example, the available batch fields, index fields, image types, and storage types are set when the script is loaded. The properties set up by the Administration module are read-only. The script must set the properties that identify the external data repository and the target release folders. It must also set the properties that establish the links between the available data fields and the fields or columns in the external data repository that will receive the document data during the subsequent release process. The properties will be available to the release script. Refer to the Kofax Capture API Reference Guide for details on the specific properties and methods available in the ReleaseSetupData object. Release Script There is only one place in the release script where you need to write a significant amount of code. The ReleaseDoc method is called every time the Release module is ready to release a new document. To release a document, you need to add code to this method that calls the following methods: 1 2 ReleaseData.ImageFiles.Copy copies the images to a location specified by the ReleaseData object. ReleaseData.TextFiles.Copy copies the full text OCR files (if any) to a location specified by the ReleaseData object.
145
Chapter 9
The index data must be released last. The ReleaseData.Values collection contains values for all the index fields that you specified in the links collection during release setup, but there is no method provided for releasing index data, since the process varies widely from script to script. You are responsible for writing the proper code to release your index data to the appropriate repository. 3 ReleaseData.CopyKofaxPDFFile copies the PDF file that belongs to a document into the release PDF path that is defined during release setup.
The amount of code you write depends on how complex your release procedure is, and you are not limited to using the methods described above. For example, if you want to recalculate the destination of every image file based on a custom requirement of your own, you are free to do it. If the destination is a folder, you can then place the new folder into the ReleaseData object and call the Copy method, or if the destination is something else (perhaps a BLOB field in a database) you can ignore the copy method and copy the file yourself. Its completely up to you. ReleaseData Object The ReleaseData object is a top-level object used by both the Kofax Capture Release module and the release script to access the batch and document class information and perform the actual document release. All of the properties of this object are set up by the Release module. The properties that are common to all documents in the batch are set up when the ReleaseData object is initialized. Properties specific to an individual document are set up before the Release module calls the ReleaseDoc method for that document. The script must use the ReleaseDoc method to read the properties and save the index data and related document information in the external data repository. Then, the script must copy the image files, any Kofax PDF files, and any full text OCR files to the target file system. Refer to the Kofax Capture API Reference Guide for details on the specific properties and methods available in the ReleaseData object.
COM Servers: In-proc or Out-of-proc?

Release scripts can be developed using any language and tool that can create COM components. If you are working with a 32-bit development environment, COM components for both release setup and release can be designed as in-process servers (ActiveX DLLs) or as out-of-process servers (ActiveX EXEs).
146
Registering Your Release Script

After completing your release script, you must register it. Registration is a two-part process. To register a release script 1 2 3 4 5 6 7 Create an .inf file for your release script. In the Administration module, click on Tools | Release Script Manager. From the Release Script Manager dialog box, select the script you want to register. Click Add and then browse to your.inf file. Click Open. Select the script you want to use. Click Install. Click OK, and your release script is registered. Close the open dialog boxes to complete the process.
The .inf file, which should be located in the same folder as your compiled release script, has a format similar to that of an .ini file. A sample .inf file is shown below:
[Scripts] Custom Script [Custom Script] SetupModule=Custom.dll SetupProgID=Custom.kfxreleasesetupscript SetupVersion=1.0 ReleaseModule=Custom.dll ReleaseProgID=Custom.kfxreleasescript ReleaseVersion=1.0 SupportsNonImageFiles=True RemainLoaded=True SupportsKofaxPDF=True SupportsOriginalFileName=True SupportsMultipleInstances=False
147
Chapter 9
The .inf file must contain a [Scripts] section that includes the name (up to 255 characters) of each script you are registering. For each entry in the [Scripts] section, there must be a corresponding section with the entries listed in Table 9-1.
Table 9-1. Inf File Entries Inf File Entry ReleaseModule ReleaseProgID Description Name of the compiled .exe or .dll containing the release COM component. Name of the release script COM component. The name is created using the Visual Basic Project Name for the .exe or .dll and the name of the class module for the release script component. Version number assigned to the release script COM component. If True, the release script will remain loaded until processing is complete. Name of the compiled .exe or .dll containing the release setup COM component. Name of the release setup script COM component. The name is created using the Visual Basic Project Name for the .exe or .dll and the name of the class module for the release setup script component. Version number assigned to the release setup script COM component. If True, the release script will support the output of Kofax PDF files. If True, the release script will support eDocuments (non-image files).
ReleaseVersion RemainLoaded SetupModule SetupProgID
SetupVersion SupportsKofaxPDF SupportsNonImageFiles
SupportsOriginalFileName If True, the release script will support the use of the original name of the file. SupportsMultipleInstances If True, the release script supports multiple instances of the Release service. Note that the Multiple Instance Support feature is only available for Kofax Capture Enterprise users.
148
Scripting in a High Availability Environment

When writing scripts for Kofax Capture in a high availability environment, you should observe the error handling guidelines found in High Availability Environments on page 129. These will help ensure that your applications take full advantage of Kofax Captures high availability features. For more information on high availability, refer to the Kofax Capture Installation Guide.
149
Chapter 9
150
Appendix A
Custom Module Sample
Introduction
This appendix walks you through the process of installing, registering, and launching the sample custom module provided in your Kofax Capture product. This generic sample module is intended to demonstrate some simple options for opening and closing a batch. The sample module does not perform any batch processing functions. Visual Basic 6 program is in the folder <Kofax Capture installation folder>\Source\Samples\CustMod\Generic Visual Basic .NET program is in the folder <Kofax Capture installation folder>\Source\VB.NET Samples\CustMod\Generic.NET The folder contains the files necessary to register a custom module named Sample. The sample gives a generic example of a custom module, which you can install and register for demonstration purposes.
151
Appendix A
Installing the Sample Custom Module

This section explains how to install the files required to register and run the sample custom module. To install the sample custom module files 1 2 Start Windows Explorer and browse to the <Kofax Capture installation folder>\Source\Samples\CustMod\Generic folder. Display the contents of the Generic folder, which contains the items shown in Figure A-1.
Figure A-1. Contents of the CustMod Folder
Copy the following files from the CustMod folder to your Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin): CMSample.aex CMSample.exe
Note If you are customizing Kofax Capture under the Windows Vista operating system, you must have Administrator privileges in order to install files to the Kofax Capture installation folder.
152
Registering the Sample Custom Module

This section explains how to use the Custom Module Manager to register the sample custom module, so you can use it as an Kofax Capture processing queue. Note You can also register custom modules with the Kofax Capture Extension Registration Utility, which is explained in Chapter 4 Creating a Registration File. To register the sample custom module 1 2 3 From the Administration modules menu bar, select Tools | Custom Module Manager. The Custom Module Manager dialog box will display. From the Custom Module Manager dialog box, click Add. The Open dialog box will display. From the Open dialog box, browse to the Bin folder, select CMSample.aex, and click Open. The Custom Modules dialog box will display.
Figure A-2. Selecting the Registration File
4 5
From the Custom Modules dialog box, select Sample and click Install. A message will appear to confirm that the registration process is complete. Click OK to clear the confirmation message.
153
Appendix A
Click Close to exit the Custom Modules dialog box. The name of the newly registered custom module Sample will appear in the Custom Module Manager dialog box, as shown in Figure A-3.
Figure A-3. Registered Sample Custom Module
You can now view the properties for the registered custom module sample. The properties are defined in the registration file (CMSample.aex), which you copied earlier to the Kofax Capture Bin folder. For detailed information about the format for the registration file, see Chapter 4 Creating a Registration File. 7 8 9 Click the Properties button to open the Custom Module Properties | Advanced tab. Notice that the properties are read-only. Click the Programs and Advanced tabs to familiarize yourself with the other properties for the sample custom module, and then click Close. Click Close again from the Custom Module Manager dialog box.
154
Adding the Sample to the Batch Processing Workflow

Once a custom module is successfully registered, it will be available for selection as a batch class processing queue from the Create Batch Class and Batch Class Properties dialog boxes as shown below.
Figure A-4. Custom Module in List of Available Queues
You can select it as a processing queue for a batch class, just like any other processing queue. Just select the custom module from the list of Available Queues and click Add. When you move the custom module to the list of Selected Queues, it will be inserted according to the valid processing order, according to its processing function. The valid processing order is defined by the Follow and Precede entries that appear on the Custom Module Properties | Advanced tab (see the preceding section). For example, the Sample custom module is defined to follow Scan and precede Release. Therefore, you can move it to any position within the list of Selected Queues after Scan and before Release.
155
Appendix A
Figure A-5. Adding a Custom Module to the Batch Class Workflow
When you publish the batch class with the custom module in its workflow, check the results log on the Publish dialog box. Be sure that no errors or warnings are associated with the custom module. To add the sample custom module to the batch class workflow 1 2 From the Administration module, create or open a batch class for which you want to include the sample custom module in the workflow. Select the batch class name from the Definitions panel and right-click to open the Properties | Queues tab. Notice that Sample appears in the list of Available Queues. Ensure that Scan appears on the Selected Queues list, and then add Sample to the list. Click OK to close the dialog box. Publish the batch class.
3 4
156
Using Batch Manager With a Custom Module

From Batch Manager, you can view the status of any batch, including a batch that includes a custom module in its workflow. If desired, you can launch the custom module and process the batch from Batch Manager.
Figure A-6. Viewing the Status of a Batch from Batch Manager
In addition, the custom module is available from the list queues for batches that have the custom module defined as part of their workflow. If desired, you can redirect a batch to a custom module from Batch Manager.
Figure A-7. Custom Module in List of Queues from Batch Manager
157
Appendix A
Creating a Batch to Open in the Sample Custom Module

This section explains how to create a batch that will be routed to the sample custom module. To create and open a batch 1 2 3 Start the Scan module and create a batch based on the batch class you published. Scan the batch and close it. Start the sample module in one of the following ways: Double-click CMSample.exe from the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin). Start Batch Manager, select the batch that is ready to open in the sample custom module, and select Process Batch from the File menu. The Sample custom module starts and appears on the desktop, as shown in Figure A-8. If you use Batch Manager to start the custom module, the options for opening a batch are slightly different, as shown in Figure A-9.
Figure A-8. Starting the Sample Custom Module
158
Figure A-9. Starting the Sample Custom Module from Batch Manager
If desired, select the Include Setup Data check box to import the batch class setup data along with the batch data. The setup data includes information about the batch class properties, including release scripts, image cleanup, recognition profiles, and more. For this demonstration, the setup data includes the standard administrative data. Your implementation will probably include a setup OCX to provide batch class configuration settings and publish checks associated with a custom module. Select By Batch as the process mode. For information about the By Document process mode, see Processing by Document on page 160. If you launched the sample from Batch Manager, click Open Batch # (where # is the incremental batch identification number) to open the batch. If you did not launch the sample from Batch Manager, do one of the following: Click Open Next Batch to open the next available batch. Click Select Batch to display the Open Batch dialog box, from which you can select the desired batch, as shown in Figure A-10, and click OK.
5 6
159
Appendix A
Figure A-10. Open Batch Dialog Box Launched from Sample Custom Module
Processing by Document
The previous section explained how to open a batch in the Sample custom module using the By Batch process mode. You can also process a batch with the By Document process mode. This mode allows you to open a specific range of documents in a batch, rather than the entire batch. To enable the By Document process mode 1 In the Scan module, create a batch as described in Creating a Batch to Open in the Sample Custom Module on page 158. Be sure that the batch includes documents. Start the sample custom module as described in Creating a Batch to Open in the Sample Custom Module on page 158. When the sample module dialog box displays, select By Document as the process mode and select the Include Setup data check box. Select the option to open the batch.
2 3 4
160
Figure A-11. Setting Options for Processing by Document
At Open documents, select a range of documents to process in the sample custom module. Note If the batch has no documents, the options for selecting and opening a range of documents are grayed on the dialog box.
161
Appendix A
Figure A-12. Selecting a Document Range
6 7 8 9
Click the Open Documents button. Under Process Documents, click Copy XML or Corrupt XML. For more information, see XML Transport Files on page 163. Click Close Documents. Under Process Batch, click Copy XML or Corrupt XML.
10 Click Close Batch.
162
Batch Custom Storage String

The fields in the Batch Custom Storage String area can be used to read or write the batch custom storage string when a batch is opened. If the batch is closed, you can only read the value. To test this capability, use the following procedure. To set the Batch Custom Storage string 1 2 3 4 From Batch Manager, process a batch that uses the CMSample custom module. Open the batch using the Sample dialog box, using the Open Batch n button. Type a Name and a Value in the appropriate fields. Click Set. The name and value will be set in the batch.
To get the Batch Custom Storage string 1 2 3 4 From Batch Manager, process a batch that uses the CMSample custom module. Open the batch using the Sample dialog box, using the Open Batch n button. Type the name of the batch custom storage string in the name field. Click Get. The value will display.
XML Transport Files

XML transport files are used to relay batch class (setup/administration) and batch (runtime) information between Kofax Capture and the custom module. For example, the sample custom module uses a runtime XML file called RTExport.xml to list Kofax Capture database information that the custom module uses. When batch information is imported back to the database after processing in the custom module, another XML file called RTImport.xml is used. Any modifications that you make to the XML format are validated by Kofax Capture to ensure compatibility. The sample module uses the standard Kofax Capture configuration settings. You will probably implement a setup OCX to define additional custom configuration and property settings associated with custom module functionality. The configuration information is relayed between Kofax Capture and the custom module via files called SUExport.xml and SUImport.xml.
163
Appendix A
Once the batch is open, the following files are generated in the Documents and Settings\All Users\Application Data\Kofax\Capture\Local\Kofax. Sample folder: RtExport.xml: Contains Kofax Capture database information related to the current batch. When the By Batch process mode is enabled, RtExport.xml includes data related to all the documents in the batch. When the By Document process mode is enabled, a separate file (DcExport.xml) is generated with the document information. SuExport.xml: Contains configuration settings and publish checks associated with the custom module. This file is generated if you selected the Include Setup data check box before opening the batch. DcExport.xml: Contains Kofax Capture database information related to selected documents in the batch. This file is generated only if you select the By Document process mode.
Figure A-13. XML Export Files for the Sample Batch
A set of Document Type Definition (DTD) files are also generated. The DTD files list the required XML format that Kofax Capture requires: AcBatch.dtd, AcDocs.dtd, and AcSetup.dtd. (The AcDocs.dtd file is generated only if you opened the batch in the By Document mode.) The .dtd files appear in the Kofax Capture installation folder, as shown in Figure A-14. If you want to examine these DTD files in detail, you can open them in any text editor.
164
Figure A-14. DTD Files for the Sample Batch
To copy the XML files back to Kofax Capture 1 Click the Copy XML button. Notice that additional import files are generated in the Kofax.Sample folder: DcImport.xml, RtImport.xml, and SuImport.xml. These files are used to import batch information to Kofax Capture from the sample module.
Figure A-15. XML Import Files Added for the Sample Batch
If desired, you can select a state (Ready, Suspended, Error) in which the batch should be closed, as shown in Figure A-16.
165
Appendix A
Figure A-16. Closing a Batch in Error
Click the Close Batch button. The batch is routed to the next module in the Kofax Capture workflow, unless it is suspended or closed in error.
Corrupt XML Even if the XML format is technically valid and well-formed, the content may not be compatible with Kofax Capture. The Sample custom module includes a mechanism to demonstrate the effect of XML content that is incompatible with Kofax Capture. You can click the Corrupt XML button to intentionally insert an incompatible text string in one of the XML import files. If you are processing in the By Document mode, you can click the Corrupt XML button to insert an incompatible text string in the DcImport.xml file. If you are processing in the By Batch mode, you can click the Corrupt XML button to insert a similar string in the RtImport.xml file. When you select Corrupt XML, the batch will be suspended when you close it. A message will display with text explaining that the error is related to the import process, the KofaxCaptureRuntime root element, and the first batch element.
166
When the XML format is not compatible with Kofax Capture, the batch will not be routed to the next queue in the Kofax Capture processing workflow.
Create Page
The Create Page button allows you to create a page or a new document. To create a page or a document, the Process mode must be set to by Batch. Clicking the Create Page button adds a new page to the XML file. If Create page in new document is selected, a document and page will be added to the XML file. You can open the RtImport.xml file in the Kofax.Sample folder to see the added lines.
167
Appendix A
168
Appendix B
Workflow Agent Sample
Introduction
This appendix walks you through the process of installing, registering, and using the sample workflow agent provided in your Kofax Capture product package. The name of this sample is Validation Workflow Agent. A workflow agent is a custom application that has the ability to examine and modify batch data, as well as change the routing (next module) and status for the batch. Workflow agents are invoked whenever a batch is closed from any module. Workflow agents consist of a runtime module and optional setup program. Prior to using a workflow agent, you must write the necessary code, and then register the agent. You can find the sample workflow agent application on your Kofax Capture CD in the Kofax\Capture\Source\Samples\Workflow\WFSample folder. This folder contains a Visual Basic 6 Project for both a Workflow Agent and Setup OCX. This folder also contains a compiled version of this Project, and the associated sample Kofax Capture Registration File (.aex). A .NET version of the same sample can be found in the Kofax\Capture\Source\VB.Net Samples\Workflow\WFSample.NET folder. The sample supports a setup OCX that adds a new menu item (Validation Workflow Properties) to the Batch Class context menu. At runtime, the Validation Workflow Agent skips validation for a document if all index fields in that document are automatically recognized with at least a user specified confidence level. You can specify the confidence level with extensions added by the Workflow Agent setup OCX. If all the documents in a batch meet the confidence level, the Validation module (and Verification module, if applicable) is skipped.
169
Appendix B
Note Workflow agents are very similar to custom modules, and the dialog boxes for registering workflow agents are nearly identical to those for custom modules.
Installing the Sample Workflow Agent

This section explains how to install the files required to register and run the sample workflow agent. Note If you are customizing Kofax Capture under the Windows Vista operating system, you must have Administrator privileges in order to install files to the Kofax Capture installation folder. To install the sample workflow agent files 1 2 Start Windows Explorer and browse to the Kofax\Capture\Source\Samples\Workflow\WFSample folder. Display the contents of the WFSample folder, which contains the items shown in Figure B-1.
Figure B-1. Contents of the WFSample Folder
170
Copy the following files from the WFSample folder to your Kofax Capture Bin folder (Kofax Capture installation folder>\Bin): WorkflowAgentWithOCX.aex SampleWorkflowOcx.ocx WFAgent.dll
Registering the Sample Workflow Agent

This section explains how to use the Workflow Agent Manager to register the sample workflow agent, so you can use it in Kofax Capture. Note You can also register workflow agents with the Kofax Capture Extension Registration Utility. To register the sample workflow agent 1 From the Kofax Capture Administration modules menu, select Tools | Workflow Agent Manager. The Workflow Agent Manager dialog box will display. From the Workflow Agent Manager dialog box, click Add. The Open dialog box will display.
Figure B-2. Selecting the Registration File
171
Appendix B
From the Open dialog box, browse to the Bin folder, select WorkflowAgentWithOCX.aex, and click Open. The Workflow Agents dialog box will display.
Figure B-3. Sample Workflow Agent to be Registered
From the Workflow Agents dialog box, select Validation Workflow Agent and click Install. A message will appear to confirm that the registration process is complete. Click OK to clear the confirmation message. Click Close to exit the Workflow Agents dialog box. The name of the newly registered workflow agent Validation Workflow Agent will display in the Workflow Agent Manager dialog box, as shown in Figure B-4.
5 6
Figure B-4. Registered Sample Workflow Agent
You can now view the properties for the registered workflow agent. The properties are defined in the registration file (WorkflowAgentWithOCX.aex), which you copied earlier to the Kofax Capture Bin folder (Kofax Capture installation folder>\Bin). For detailed information about the format for the registration file, see Chapter 7 Custom Extension Registration. 7 Click the Properties button to open the Workflow Agents Properties dialog box - General tab.
172
8 9
Click the General and Programs tabs to familiarize yourself with the other properties for the sample workflow agent, and then click Close. Click Close again from the Workflow Agent Manager dialog box.
Using the Sample Workflow Agent

This section explains how to use the sample workflow agent in a batch class. To use the sample workflow agent 1 2 3 4 From the Administration module, create or open a batch class for which you want to include the sample workflow agent. Select the batch class name from the Definitions panel and right-click to open the Batch Class Properties dialog box - Queues tab. Ensure that Scan, Validation and other modules as appropriate appear on the Selected Queues list. From the Batch Class Properties dialog box - Workflow Agents tab , select Validation Workflow Agent and click Add to move it to the Selected Workflow Agents list.
173
Appendix B
Figure B-5. Selecting the Sample Workflow Agent
5 6
Click OK to close the Batch Class Properties dialog box From the Definitions panel, right-click to display the context menu. Select Validation Workflow Properties. The Validation Workflow Properties dialog box will display.
174
Figure B-6. Selecting Validation Workflow Properties
Select Skip validation if the confidence for all fields is at least.
Figure B-7. Validation Workflow Properties
Move the slider to the desired confidence level. If the confidence level for all the documents in your batch meets or exceeds this setting, the Validation module (and Verification module if it is part of the batch class) will be skipped. Click OK.
10 Publish the batch class.
175
Appendix B
176
Appendix C
Sample Import Controller Program
Introduction
In addition to all the capabilities described in the earlier chapters, you can also take advantage of the Kofax Capture Module Type Library to write custom import applications. The Import Controller feature is an API that allows you to develop applications that import documents into Kofax Capture. This API provides an extensive set of objects, properties, and methods that facilitate the development of quite sophisticated and feature rich programs. Documents are normally created in the Scan module, by either using a scanner or importing already existing files. Although the XML Import Connector feature can create batches by using special import files, this API greatly expands the power and flexibility that can be applied to creating batches programmatically. This appendix contains an example custom import application. It will show you how to write a Microsoft Visual Basic application that creates a batch and imports image files into a document. While this is just a simple example (that is not intended for actual use), it does demonstrate the capabilities available to programmers.
General Preparations
Before you actually begin creating an application, you need to perform some general setup tasks. In order to have an application create batches and documents, you must have index fields, document classes, form types, and batch classes already set up and published in Kofax Capture. All this is done in the Kofax Capture Administration module. See the Kofax Capture Getting Started Guide for specifics on using this module. In addition, when starting a new project in Visual Basic, you need to ensure that the Kofax Capture API is available to your project.
177
Appendix C
Kofax Capture Setup The discussion in this section assumes that you have imported and published LESSON_1.cab. This file is shipped with Kofax Capture, and placed in the <Kofax Capture installation folder>\Tutorial folder. To use the example application 1 2 3 Be sure that user profiles are not enabled. Import LESSON_1.cab. Change the Required property for the Site ID batch field to False. Note This example does not support required batch fields. 4 Publish the batch class.
If you are unsure how to perform any of these steps, refer to your Kofax Capture online Help, or the relevant sections in your Kofax Capture documentation. Visual Basic 6.0 Setup This section assumes you have a working knowledge of Visual Basic and its interface. The Visual Basic project must first be set up to reference the Kofax Capture Module Type library. Kofax Capture must already be installed on your system. To setup the references in Visual Basic: 1 2 3 4 5 6 Start Visual Basic. The New Project dialog box appears. Make sure the New tab is selected. Make sure Standard EXE is selected. Click Open. Visual Basic creates a new project. Save and Name the project. Select Project | References. The References dialog box opens.
178
Figure C-1. Visual Basic References Dialog Box
Scroll down the list of references until you find Kofax Capture Module Type Library. Select the check box. Note Do not confuse this reference with the Kofax Capture Admin Module Type Library. The names are similar, and it is easy to select the wrong library.
Click OK. The References dialog box closes, and Visual Basic is now ready for your application.
That completes setting up Visual Basic. This must be done for each application you create that requires access to the Import Controller API. Visual Studio 2005 Setup This section assumes you have a working knowledge of Visual Studio 2005 and its interface. The Visual Basic project must first be set up to reference the Kofax Capture Module Type library. Kofax Capture must already be installed on your system. To setup the references in Visual Basic 1 2 Start Visual Studio 2005. Click the New Project link on the Start Page, or select File | New | Project from the main menu.
179
Appendix C
3 4 5 6 7 8
In the New Project dialog box, make sure Visual Basic Projects and Windows Application are selected, and choose a location to save the project. Click OK. When the new project opens, select Project | Add Reference. From the Add Reference dialog box, click Browse. Browse to the location of your Kofax Capture installation, then choose the <Kofax Capture installation folder>\Bin folder. Select the file Kofax.AscentCaptureModule.Interop.dll, then click OK. Click OK in the Add Reference dialog box. Select the new reference in the Solution Explorer. Make sure the Copy Local property is set to False.
That completes setting up Visual Basic. This must be done for each application you create that requires access to the Import Controller API. Note Do not distribute Kofax.AscentCaptureModule.Interop.dll with the application.
The Example Import Controller Program

Now that everything has been set up, lets look at the actual example application. As mentioned earlier, this example is not intended for real-world use. It has deliberately been kept simple in order to illustrate the essential concepts of accessing the API. This application presents an interface so that the user can provide some values to Kofax Capture. This example application is limited in several ways. You must provide the data in a specific order. There is only minimal error checking. You may see some additional error messages provided by Visual Basic components or by the API. These restrictions keep the application simple and easy to understand. The focus is on basic concepts, not exercising every object, method, and property in the API. Simple.exe can be run from the Simple subfolder of the Kofax Capture installations folder, as indicated by the following path. <Kofax Capture installation folder>\Source\Samples\InpScrpt\Simple
180
The first thing the application does is log into the Kofax Capture database. This takes several seconds, so a screen appears asking the user to wait. When the main interface screen appears, notice that only the Create Batch and Quit buttons are enabled. In addition, the application has picked up the Order Forms batch class that has been published in Kofax Capture.
Figure C-2. Main Screen
First, we will name and then create a batch. In this case, the batch is called Sample Batch, but you can enter any name you like so long as it is 32 characters or less. The screen now looks like this.
Figure C-3. Screen with Batch Name
Next, select a batch class. In this case, there is only one, but the drop-down list will contain all published batch classes.
181
Appendix C
Click Create Batch to create Sample Batch. After the batch has been created, you will see a message similar to the following:
Figure C-4. Created batch message
Click OK to close the message box. After creating the batch, the application examines the batch class and lists the available form types. These are presented in the Select Form Type field, which is now enabled.
Figure C-5. Screen with Form Types
After selecting the form, click the Get Page button. This button displays the Select Image File dialog box. This standard Windows browser is provided with Visual Basic. In this case, NWest_1.tif will be added to the document. The page imported here should match the layout of the sample pages used in the batch class.
182
Figure C-6. Selecting a Page
Finally, it is possible to use the Create Document button, which is now enabled.
Figure C-7. Screen Now Ready to Make Batch
After clicking the Create Document button, our application summarizes the results. Click OK to proceed.
183
Appendix C
Figure C-8. Example Application Document Summary Message
Click Quit to exit the sample application. Now, it is possible to see the new batch in the Batch Manager.
Figure C-9. The Batch in the Batch Manager
Visual Basic Code for the Example Application

The above discussion should give you a good understanding of how this example application looks to a user. In the next few pages, well look at the code for this application. Much of the program consists of standard Visual Basic tasks. These tasks are not discussed here, however the comments in the code will help you understand them. Basic Structure Structurally, this application contains two forms. PlsWait (the please wait screen) Simple (the main screen) The details for these forms are not provided here. If you want to make this application as an exercise, feel free to design your own user interface, just remember to match the names of your controls to those used here. Program Header The code begins with some standard comments followed by the Option Explicit statement.
184
Figure C-10. Program Header
Declare Variables The following variables are at the heart of this example application. Each of them defines an object in terms of objects within the Kofax Capture Module Type Library that you referenced earlier. Details for these objects (as well as properties and methods) are provided in the tables later in this chapter.
Figure C-11. Program Variables
185
Appendix C
Load Main Form This section checks for published batch classes, performs a few initialization chores, and loads the main form. Note In this example, null strings are used for the User ID and password. If user profiles are enabled, you should supply the actual ID and password.
Figure C-12. Program Main Form
186
Get Page This subroutine is run when the Get Page button is clicked.
Figure C-13. Program Get Page Routine
187
Appendix C
Make Batch This subroutine is run when the Create Batch button is clicked.
Figure C-14. Program Make Batch Routine
188
Make Document This subroutine is run when the Create Document button is clicked.
Figure C-15. Program Make Document Routine
189
Appendix C
Quit Finally, this subroutine ends the application when the Quit button is clicked.
Figure C-16. Quit Program Routine
190
Development API
The complete API for the Kofax Capture Module Type Library is documented in the Kofax Capture API Reference Guide. To access the Kofax Capture Module Type Library 1 2 Select Start | Programs | Kofax Capture 8.0 | API Reference Guide from the Windows Start menu. When the API Reference Guide opens in a new browser window, click on the Kofax Capture Module Type Library entry in the Table of Contents.
The Kofax Capture API Reference Guide documents all the properties and methods available in the Kofax Capture Module Type Library. These properties and methods are associated with setup OCX and custom import applications. All properties and methods are defined using Visual Basic syntax. Note Custom import applications can make use of any object, property, or method exposed by the API, but custom panels and menus will not likely find much use for some of the extensions.
191
Appendix C
192
Index
A
Aex file example, 52 format, 40 Menu Bar section, 52 Menu section, 51 ModuleName section, 40 Modules section, 40 Setup Programs section, 48 Setup section, 49 Workflow Agent Name section, 47 Workflow Agents section, 46 API library ACAdMod.dll, 2 ACModule.dll, 2 ACWFlib.dll, 3 AscRel.dll, 3 DBLite.dll, 2 DBLiteOpt.dll, 2 Kofax Capture .NET Scripting Library, 3 Kofax Capture Custom Workflow Interface, 3 Kofax Capture Document Access, 2 Kofax Capture Module Type Library, 2 Kofax Capture Optimized Custom Module API, 2 Kofax Capture Release Type Library, 3 ScriptInterface.dll, 3 setup OCX development, 110 example import controller program code, 184 import controller, 177 Kofax Capture setup, 178 Visual Basic setup, 178 Visual Basic.NET setup, 179 Custom extension registration command line parameters, 69 Custom extensions development tasks, 132 installation, 134 menu items, 104 menus, 107 publish checks, 109 registration, 133 runtime executable, 133 setup OCX, 132 toolbars, 109 Custom menus, 111, 115 Custom modules properties, 60 registering with Administration module, 58 removing, 63 Custom panels, 111 development environment, 114 installing, 117 menus, 114 registration, 117, 123 sample, 112, 122 user interface design, 112 visible flag, 113 Custom scripts, SBL recognition, 19 validation, 6 Custom scripts, VB .NET field, 23 recognition, 23 software requirements, 24
C
COM servers, 146 Command line parameters custom extension registration, 69 Custom applications example import controller program, 180
193
Index
testing, 31 validation, 23 customizing software needed for, 2
for custom panels, 114
O
OCX custom extension setup, 132 OCX panels custom, 111 standard, 113
D
Data layout files AcBatch.htm, 3 AcDocs.htm, 3 AcSetup.htm, 3 Development API Kofax Capture Admin Module Type Library, 110 Kofax Capture Release Type Library, 142 Development environment custom panels, 114 Docking location custom panels, 120
P
Panels, custom see Custom panels Publish checks custom extensions, 109
R
Recognition scripts, SBL, 5 about, 19 functions, 19 process, 20 return codes, 21 system variables, 22 writing, 19 RegAsm.exe, 123 Registration custom extensions, 133 custom module sample, 153 custom panels, 123 file format for custom extensions, 40 release scripts, 147 workflow agent sample, 171 workflow agents, 64 Registration file See Aex file Registry entries custom menus, 116 keys, 116 Registry keys custom extension setup OCX, 96 menu, 98 RegSvr32.exe, 123, 124 Related documentation, ix Release scripts, 145 API library, 142 process, 142 registration, 147
E
Error DWORD values, 98 registry keys, 98
K
Kofax Capture .NET Scripting API, 25, 34 Kofax Capture .NET Scripting Library, 3 Kofax Capture Admin Module Type Library, 2, 110 Kofax Capture Custom Workflow Interface, 3 Kofax Capture Document Access, 2 Kofax Capture Module Type Library, 2, 111 Kofax Capture Optimized Custom Module API, 2 Kofax Capture Release Type Library, 3, 142 Kofax technical support, xi Kofax training, xi Kofax Web site, xi
M
Managing extensions Administration module, 58 Menus custom, 111 custom extensions, 104, 107
194
Index
requirements, 143 setup, 142 source for standard scripts, 141 standard, 141 Release setup script, 145 requirements, 142 ReleaseData object, 144 ReleaseSetupData object, 144 Removing custom module, 63 workflow agent, 68
S
Sample custom panel, 122 registration, 123 SBL Editor/Debugger, 10 Scripts, custom SBL about, 5 recognition, 5 Softbridge Basic Language, 5 validation, 5, 6 Separator menu bars, 104 Setup OCX, 132 custom panel, 101 designing, 89 development APIs, 110 loading, 100 registry keys, 96 unloading, 101 workflow agent example, 90 writing, 90 Setup panel, 101 Softbridge Basic Language (SBL) dialog boxes, 12 vs Visual Basic, 12
about, 6 field macros, 10 functions, 6 process, 8, 9 return codes, 15 system variables, 15 testing, 11 writing, 6 Validation scripts, VB .NET creating, 24, 34 sample, 27, 35 Visual Basic vs. Softbridge Basic Language (SBL), 12
W
Workflow agent designing, 75 properties, 66 registering with Administration module, 64 removing, 68 runtime module, 76 setup OCX, 76 VB .NET code project settings, 77 Workflow agent sample installing, 170 registering, 171 using, 173
X
XML files, 133, 163, 165, 166 XML transport files DcExport.xml, 164 RtExport.xml, 164 SuExport.xml, 164
T
Technical support, xi Toolbars custom extensions, 109 Training, xi
V
Validation scripts, SBL, 5
195
Index
196

KofaxCapture 8 0 Dev Guide

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

KofaxCapture 8 0 Dev Guide

Загружено:

Авторское право:

Доступные форматы

KOFAX

Kofax Capture 8 Developers Guide

Kofax Capture 8 Developers Guide

Kofax Capture 8 Developers Guide

Kofax Capture 8 Developers Guide

Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Kofax Capture 8 Developers Guide

Kofax Capture 8 Developers Guide

How to Use This Guide

Kofax Capture 8 Developers Guide

How to Use This Guide

Kofax Capture 8 Developers Guide

How to Use This Guide

Kofax Technical Support

Kofax Capture 8 Developers Guide

How to Use This Guide

Kofax Capture 8 Developers Guide

Why You Would Customize Kofax Capture

Kofax Capture 8 Developers Guide

How to Customize Kofax Capture

Kofax Capture Document Access

Kofax Capture 8 Developers Guide

How to Implement Your Customized Scripts and Modules

Kofax Capture 8 Developers Guide

Kofax Capture 8 Developers Guide

Creating Custom Scripts Using SBL

Kofax Capture 8 Developers Guide

Writing a Validation Script

KfxAcmDocument KfxDocPostProcess KfxDocPreProcess KfxLoadValidation

Kofax Capture 8 Developers Guide

Creating Custom Scripts Using SBL

Kofax Capture 8 Developers Guide

How Validation Scripts are Processed

Kofax Capture 8 Developers Guide

Creating Custom Scripts Using SBL

Figure 2-1. Processing Flow for a Validation Script

Kofax Capture 8 Developers Guide

Field Type Macros

Kofax Capture 8 Developers Guide

Creating Custom Scripts Using SBL

Testing Validation Scripts

Kofax Capture 8 Developers Guide

Differences Between SBL and Visual Basic

About SBL Dialog Boxes

Kofax Capture 8 Developers Guide

Creating Custom Scripts Using SBL

Figure 2-2. The SBL Dialog Editor

Kofax Capture 8 Developers Guide

6,7,65,10, Department Name:

Figure 2-3. Example of the SBL Dialog Editor

Kofax Capture 8 Developers Guide

Creating Custom Scripts Using SBL

Validation Script Return Codes and Variables

Kofax Capture 8 Developers Guide

Care should be taken when using these, as no validation will be performed.

Kofax Capture 8 Developers Guide

Creating Custom Scripts Using SBL

KfxBatchClassId KfxBatchID KfxBatchName KfxClassName KfxCLFieldName KfxDocClassId KfxErrorMessage

Kofax Capture 8 Developers Guide

Kofax Capture 8 Developers Guide

Creating Custom Scripts Using SBL

Writing a Recognition Script

KfxPreRecognition KfxPostRecognition KfxUnload