Kofax Capture 9 Developer's Guide - FTP Directory Listing

mewstennisΛογισμικό & κατασκευή λογ/κού

4 Νοε 2013 (πριν από 3 χρόνια και 9 μήνες)

258 εμφανίσεις

Kofax
Capture
9
Developer’s Guide
10300940-000
© 1994 - 2010 Kofax, Inc., 15211 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 Kofax’s suppliers.
This product is protected by U.S. Patent No. 6,370,277.
THIS SOFTWARE CONTAINS CONFIDENTIAL INFORMATION AND TRADE SECRETS OF KOFAX,
INC. USE, DISCLOSURE OR REPRODUCTION IS PROHIBITED WITHOUT THE PRIOR EXPRESS
WRITTEN PERMISSION OF KOFAX, INC.
Kofax, the Kofax logo, Kofax Capture, the Kofax Capture Logo, Ascent Capture, the Ascent Capture
logo, and Ascent are trademarks or registered trademarks of Kofax, 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, 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.
Kofax Capture 9 Developer’s Guide
3
Contents
How to Use This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Technical Assistance for Your Kofax Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Why You Would Customize Kofax Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
How to Customize Kofax Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Using the API Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
How to Implement Your Customized Scripts and Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2 Creating Custom Scripts Using SBL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Validation Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Writing a Validation Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
How Validation Scripts are Processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Field Type Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Testing Validation Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Differences Between SBL and Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
About SBL Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Validation Script Return Codes and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Recognition Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Writing a Recognition Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
How Recognition Scripts are Processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Recognition Script Return Codes and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3 Creating Custom Scripts Using VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Creating a Validation Script in VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Choosing the Scripting Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Kofax Capture .NET Scripting API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
VB .NET Project File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Deployment of a VB .NET Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Contents
4
Kofax Capture 9 Developer’s Guide
Publishing Requirements for the Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Sample VB .NET Validation Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Sample Validation Script Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Testing VB .NET Custom Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Error Handling in VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
FatalErrorException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
RejectAndSkipDocumentException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
ValidationErrorException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Creating a Recognition Script in VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Choosing the Scripting Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Kofax Capture .NET Scripting API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Sample VB .NET Recognition Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Field Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Sample VB .NET Field Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4 Creating a Registration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Format for the Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
[Modules] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
[Module Name] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
[Workflow Agents] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
[Workflow Agent Name] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
[Setup Programs] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
[Setup] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
[Menu] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
[Menu Bar] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Example Registration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Example 1: Registering Two Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Example 2: Defining a Menu for the Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Example 3: Defining Context Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Example 4: Defining a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Using the Administration Module to Manage Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Managing Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Registering a Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Viewing Properties for a Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Removing a Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Managing Workflow Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Registering a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Viewing Properties for a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Removing a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Using the Kofax Capture Extension Registration Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Input File [/f {filename}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Output File [/o {filename}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Module Name [/m {module name}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Workflow Agent Name [/w {workflow agent name}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Setup Programs [/x {setup program name}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Runtime Programs [/r {runtime program name}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Unregister [ /u ] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Silent Mode [ /s ] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Contents
Kofax Capture 9 Developer’s Guide
5
Usage [ /? ] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Proper Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Error and Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5 Creating a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Designing a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Implementing the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Writing the Runtime Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Code Project Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Referencing the Kofax Capture API Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Setting the Project Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Workflow Agent Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Workflow Agent Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Inherit the IACWorkflowAgent Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Creating the Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Format of the Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Registering the Workflow Agent from the Administration Module . . . . . . . . . . . . . . . . . . . . . 71
Registering the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Installing and Registering the Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Removing the Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
6 Creating a Setup OCX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Designing the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Writing a Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Code Project Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Example Setup OCX for the Custom Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Setup OCX for the Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Registering a Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Setup OCX Registry Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Menu Registry Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Loading the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Unloading the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Setup OCX Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Enabling Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Context Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Enabling Context Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Main Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Custom Menu Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Enabling/Disabling Custom Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Contents
6
Kofax Capture 9 Developer’s Guide
Batch Class Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Setup OCX Development API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
7 Creating Custom Panels and Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Programming in a High Availability Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
User Interface Design and Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Custom Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Custom Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Scan, Quality Control, Validation, and Verification Tree Node Menus . . . . . . . . . . . . . . . 87
Menus Can Be Added, Removed, and Edited at Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Registry Entries for Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Installing a Custom Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Invoking Kofax Capture Menu Items from a Custom OCX Panel . . . . . . . . . . . . . . . . . . . . . . . 91
Using the Sample Custom Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Registering the Sample Custom Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Example Custom Panel in VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
DelPagePanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
8 Creating a Custom Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
High Availability Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Error Handling Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Typical Development Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Design the Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Create the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Write the Runtime Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Create the Custom Module Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Register the Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Create an Installation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Document Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Using Document Routing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
ChildBatchCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
MoveElementToBatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
BatchCloseWithModuleID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
About Document Routing Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Document GUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Tracking Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Reference Batch ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Unsupported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Using Kofax Transformation Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Using the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Example Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
DeleteEvenPage Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
ProcessNewBatch Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
PageMarkedForDeletion Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
RuntimeSession_BatchAvailable Subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Contents
Kofax Capture 9 Developer’s Guide
7
9 Creating an Export Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Kofax Capture Export Type Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Kofax Capture and the Export Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Requirements for the Export Connector Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Requirements for the Export Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
The ReleaseSetupData and ReleaseData Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Export Connector Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Export Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
COM Servers: In-proc or Out-of-proc? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Registering Your Export Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Scripting in a High Availability Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
10 Deploying Customizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Installing the Customization Deployment Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Setting Up a Customization Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Initiating a Customization Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Viewing Customization Deployment Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Deploying Customizations When Applications Are Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
About the Customization Deployment Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Administrator Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Deployment Service Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
KCN Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
A Custom Module Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Installing the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Registering the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Adding the Sample to the Batch Processing Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Using Batch Manager With a Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Creating a Batch to Open in the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Processing by Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Batch Custom Storage String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
XML Transport Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Corrupt XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Create Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
B Workflow Agent Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Installing the Sample Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Registering the Sample Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Contents
8
Kofax Capture 9 Developer’s Guide
Using the Sample Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Kofax Capture 9 Developer’s Guide
9
How to Use This Guide
Introduction
The Kofax Capture Developer’s 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 Developer’s Guide, Kofax Capture includes the following documentation:
Kofax Capture 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 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 processing, and introduces the
components and major features of Kofax Capture Network Server.
Kofax Capture 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 Developer’s
Guide as a primary resource for customizing Kofax Capture.
To access the API Reference Guide, select Start | Programs | Kofax Capture 9.0 | API Reference
Guide from the taskbar.
How to Use This Guide
10
Kofax Capture 9 Developer’s Guide
Kofax Capture 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 9.0 | Kofax Capture
Help to display the main Help topic for the Help system.

From any Kofax Capture module’s 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.
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.
Technical Assistance for Your Kofax Product
Support for your Kofax product is provided by your primary application support provider, which
is specified as part of the maintenance agreement associated with your purchase. Please contact
your Kofax application support provider for technical assistance.
For more information about your product, visit the Kofax Support pages at www.kofax.com for:

Product information and release news

Access to the Kofax Knowledgebase

Access to the online Case Management System (for eligible customers)

Downloadable product documentation
Before contacting your Kofax application support provider, please gather the following
information where applicable:

Product name, version, and serial number

Log files

Product license

Exact error message(s)

Reproduction scenario
Kofax Capture 9 Developer’s Guide
11
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.
How to Customize Kofax Capture
Kofax Capture supports several tools for creating and writing custom applications and scripts
such as Visual Basic 2008 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 2008 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.
Chapter 1
12
Kofax Capture 9 Developer’s Guide
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.
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 files—AcSetup.htm defines setup information, while AcBatch.htm
defines runtime information. The data is partitioned into elements. Each element describes a
Table 1-1. Kofax Capture API Libraries
Library Name Object and File Names Usage
Kofax
Capture Module
Type Library
AscentCaptureModule
(ACModule.dll)
Used to create custom OCX panels for
Scan, Quality Control, Validation, and
Verification modules.
Kofax Capture
Admin Module
Type Library
AscentCaptureAdminMod
(ACAdMod.dll)
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.
Kofax Capture
Document Access
ACDB
(DBLite.dll)
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
Custom Workflow
Interface
ACWFLib
(ACWFlib.dll)
API used by workflow agents as
batches are closed by modules.
Kofax Capture
Export Type
Library
AscentRelease
(AscRel.dll)
Used to create custom export
connectors.
Kofax Capture
.NET Scripting
Library
ScriptInterface
(ScriptInterface.dll)
Used to create VB .NET custom field,
validation, and recognition scripts.
Overview
Kofax Capture 9 Developer’s Guide
13
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 9, 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.
Refer to these chapters in this guide for detailed instructions for implementing your customized
extensions and scripts.
Chapter 1
14
Kofax Capture 9 Developer’s Guide
Kofax Capture 9 Developer’s Guide
15
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.
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
Chapter 2
16
Kofax Capture 9 Developer’s Guide
seven functions accessible through validation scripts. You can add code to each to perform custom
data validation routines.
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”.
2 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).
3 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.
4 When finished writing your code, compile the script, make corrections if necessary, exit
the editor, and close the Document Validation Script dialog box.
Table 2-1. Validation Script Functions
Function When Called
FmtFieldName 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.
KfxAcmDocument The Kofax Capture Module Document object for the current
document.
KfxDocPostProcess Called after each document is closed.
KfxDocPreProcess Called each time a new document is loaded.
KfxLoadValidation 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.
KfxUnloadValidation Called when a batch is closed.
PostFieldName Called when a validation operator exits a data field. There is a
PostFieldName function for each data field in a document class.
PreFieldName Called each time a validation operator enters a data field. There is a
PreFieldName function for each data field in a document class.
Creating Custom Scripts Using SBL
Kofax Capture 9 Developer’s Guide
17
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.
2 For each document in the batch, Validation or Verification sets the document-level
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.
3 For each index field in the document, Validation or Verification sets the field-level
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.
4 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.
5 The FmtFieldName functions are called for all index fields (except the one getting the
focus) whenever the data in an index field changes.
6 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.
7 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.
Chapter 2
18
Kofax Capture 9 Developer’s Guide
Figure 2-1. Processing Flow for a Validation Script
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 From the Administration module’s Definitions panel, select the Field Types tab.
2 Right-click on a field type and click “Field Macro.” The Field Macro dialog box will
display.
3 Provide a name for the macro (the default name is the same as the field type).
4 Click either “Create” (for a new macro) or “Edit” (for an existing macro).
5 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.
6 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.
Creating Custom Scripts Using SBL
Kofax Capture 9 Developer’s Guide
19
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.
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.
Chapter 2
20
Kofax Capture 9 Developer’s Guide
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.
Creating Custom Scripts Using SBL
Kofax Capture 9 Developer’s Guide
21
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”).

It’s error-free. The operator chooses from a list, so there’s 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.
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
Chapter 2
22
Kofax Capture 9 Developer’s Guide
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 don’t 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.
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.
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"
This code sets up an
array of strings that
provides the list values
for the dialog box to
display. The array is
called DepArray.
Begin Dialog DepartmentName 6,6,181,92
OkButton 124,20,50,14
CancelButton 124,37,50,14
ListBox 6,22,113,65,DepArray(),.ListBox1
Text 6,7,65,10, “Department Name:”
End Dialog
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.
Dim DepRecord As DepName
Dialog DepRecord
This code defines a
dialog box record and
displays the dialog
box.
KfxDepartment_Name=DepArray(DepRecord.Listbox1)
This code retrieves the
selected item from the
list.
Creating Custom Scripts Using SBL
Kofax Capture 9 Developer’s Guide
23
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 Value Definition
FatalError -1 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.
NoError 0 Indicates a successful operation. If this is returned
from a PostFieldName function, the Validation or
Verification module advances to the next field.
NoOperation 3 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.
RejectAndSkipDocument -4 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.
SaveAndSkipDocument
1
1 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
Chapter 2
24
Kofax Capture 9 Developer’s Guide
1 Care should be taken when using these, as no validation will be performed.
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.
Table 2-3. Validation Script System Variables
System Variable Definition
AlreadyProcessed A parameter of the KfxDocPreProcess function that
indicates whether the document is being processed for
the first time or has already been processed.
DataAccepted A parameter of the KfxDocPostProcess function that
indicates whether the operator accepted or rejected the
data.
EnteredValue A parameter of the PostFieldName function that contains
the data entered by the validation operator.
ID A parameter of the KfxDocPreProcess and
KfxDocPostProcess functions that indicates the
document ID of the current document.
KfxBatchClassId The hexadecimal ID of the current batch class.
KfxBatchID The hexadecimal ID of the current batch.
KfxBatchName The name of the current batch.
KfxClassName The name of the current document class.
KfxCLFieldName Contains the confidence level of the current field if it was
filled in via OCR, ICR, OMR, or bar code recognition.
KfxDocClassId The hexadecimal ID of the current document class.
KfxErrorMessage The error message displayed when either FatalError,
RejectAndSkipField, or RejectAndSkipDocument are
returned from any function.
KfxFieldName Contains the value of the data in the current field.
KfxLoadAllProcessedValues 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.”
Table 2-2. Validation Script Return Codes (continued)
Return Code Value Definition
Creating Custom Scripts Using SBL
Kofax Capture 9 Developer’s Guide
25
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
KfxOperation Indicates whether the script is being called by the
Validation module (“index”) or the Verification module
(“verify”).
KfxPageFile The filename of the image currently being displayed.
MaxLength A parameter of the PostFieldName function that indicates
the maximum allowed length of the field (for CHAR and
VARCHAR field types).
NumberOfDocsInBatch A parameter of the KfxLoadValidation function that
indicates the number of documents (not pages) in the
current batch.
NumberOfPages A parameter of the KfxDocPreProcess function that
indicates the number of pages in the current document.
VerifyBatch A parameter of the KfxLoadValidation function that
indicates whether the batch is being processed by the
Validation module or the Verification module.
Table 2-3. Validation Script System Variables (continued)
System Variable Definition
Chapter 2
26
Kofax Capture 9 Developer’s Guide
handling code. There are a total of four functions accessible using recognition scripts, as shown in
Table 2-4.
Writing a recognition script is a straightforward procedure. To write a recognition script, follow
these steps:
1 In the Administration module, select Scripts | Recognition.
2 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).
3 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.
4 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.
2 For each zone of that recognition type in the batch, Recognition Server sets the script’s
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.
3 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.
4 The script remains in memory until the batch is closed. When the batch is closed,
Recognition Server calls the script’s KfxUnload function. You can use this function to
release any resources allocated for the script.
Table 2-4. Recognition Script Functions
Function When Called
KfxLoad 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.
KfxPreRecognition Called before each zone snippet is processed.
KfxPostRecognition Called after each zone snippet is processed.
KfxUnload Called for all recognition scripts when the batch is closed.
Creating Custom Scripts Using SBL
Kofax Capture 9 Developer’s Guide
27
Figure 2-4 illustrates the general flow for processing a recognition script.
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 Definition
FatalError Indicates a fatal error. The batch is set to an error state.
NoError 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.
SaveAndSkipOperation Similar to NoError, but skips the Kofax recognition. Example:
KfxPreRecognition = SaveAndSkipOperation
Table 2-6. Recognition Script System Variables
System Variable Definition
KfxConfidence 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.
Chapter 2
28
Kofax Capture 9 Developer’s Guide
KfxImageFile 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.
KfxRegistrationHorizBMU 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).
KfxRegistrationVertBMU 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).
KfxSearchText The search text is the expected search string set in the
Administration module for a separation, form identification, or
registration zone.
KfxValue 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.
Table 2-6. Recognition Script System Variables (continued)
System Variable Definition
Kofax Capture 9 Developer’s Guide
29
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 2008 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.
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 2010 Express Edition

Microsoft Visual Studio 2010 Standard Edition

Microsoft Visual Studio 2010 Professional Edition

Microsoft Visual Basic 2008 Express Edition

Microsoft Visual Studio 2008 Standard Edition

Microsoft Visual Studio 2008 Professional Edition

Microsoft Visual Basic 2005 Express Edition

Microsoft Visual Studio 2005 Standard Edition

Microsoft Visual Studio 2005 Professional Edition
Chapter 3
30
Kofax Capture 9 Developer’s Guide
For Microsoft Visual Basic 2010, 2008, and 2005, you will also need Microsoft .NET Framework 3.5
runtime installed in your development environment. If not already installed, the .NET 3.5 runtime
is installed either by Kofax Capture or by Visual Studio 2008.
Note Microsoft Visual Basic Express Edition is a free download from the Microsoft Web site.
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 script’s 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.
 To create a document validation script with VB .NET
1 From the Scripts menu, select Document Validation. The Document Validation Script
dialog box will display.
2 In the Document classes list, select the document class for which you want to create a
script.
3 In the Scripting language list, select a scripting language to create the script. In this case,
select VB .NET.
4 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.
Creating Custom Scripts Using VB .NET
Kofax Capture 9 Developer’s Guide
31
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.
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 35
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.
Table 3-1. Validation Script Events
Events When Called
BatchLoading Called when a batch is opened.
BatchUnloading Called when a batch is closed.
DocumentPreProcessing Called each time a new document is opened.
DocumentPostProcessing Called after each document is closed.
PreDocumentEventArgs This class represents the event arguments for the
DocumentValidationScript.DocumentPreProcessing event.
PostDocumentEventArgs This class represents the event arguments for the
DocumentValidationScript.DocumentPostProcessing event.
Chapter 3
32
Kofax Capture 9 Developer’s Guide
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 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 From the Start menu, select Program | Kofax Capture 9.0 | Administration.
2 Select the document class SampleScript.
3 From the Scripts menu, select Document Validation.
4 From the Document Validation Script dialog box that appears, choose SampleScript from
the Document classes list.
5 Choose VB .NET from the Scripting language list.
6 Click Create.
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 FieldPostProcessing event and the next two are helper functions.
Creating Custom Scripts Using VB .NET
Kofax Capture 9 Developer’s Guide
33
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 System
Imports System.Collections.Generic
Imports System.Text
Imports Kofax.AscentCapture.Scripting
Imports 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 SSN_FieldPostProcessing( _
ByVal sender As Object, ByVal e As _
Kofax.AscentCapture.Scripting.PostFieldEventArgs) _
Handles SSN.FieldPostProcessing
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
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
Chapter 3
34
Kofax Capture 9 Developer’s Guide
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
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 Express Edition. It is only supported in Visual Studio.
 The following is a typical process for testing and debugging a VB .NET document
validation script:
1 A user with administrator rights creates a VB .NET document validation script in the
Administration module and publishes a batch class.
2 A batch is created and processed through the Validation module.
3 The VB .NET script project is opened in Visual Studio.
4 Break points are set in the script, and changes are made to the script as desired.
Creating Custom Scripts Using VB .NET
Kofax Capture 9 Developer’s Guide
35
5 The validation script is run from Visual Studio, and the debugger stops at the first break
point.
6 Testing and debugging can continue until you are satisfied with the script.
7 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.
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.
Chapter 3
36
Kofax Capture 9 Developer’s Guide
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.
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