Ko Fax Capture Developers Guide

KofaxCapture 10.0 Developer’s Guide August 1, 2011 © 1994 - 2011 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. Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Getting Help for Kofax Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Why You Would Customize Kofax Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 How to Customize Kofax Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Using the API Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Customizing with the Fluent UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 How to Implement Your Customized Scripts and Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 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 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Validation Script Return Codes and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Recognition Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Writing a Recognition Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Creating a Recognition Script Using VB .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 How Recognition Scripts are Processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Recognition Script Return Codes and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Using a Recognition Script for Testing Your Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 10 Developer’s Guide 3 . . . . . . . . . . . . . . . . . . . . .NET Project . . . . . . . . . . . . . . . . . . . . .NET . . . . . . 40 4 Creating a Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Example 1: Registering Two Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 [Menu] Section . . . . . . . . . . . . . . . . . . . . . . . 38 Example Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Creating a Recognition Script in VB . . . . . . . . 55 Removing a Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 RejectAndSkipDocumentException .NET Scripting API . . . . . 37 Debugging Your Settings with a VB . . . . . . . . . . . 55 Managing Workflow Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Example 4: Defining a Workflow Agent . . . . . . . . . . . . . 46 [Setup Programs] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 VB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .NET Custom Scripts . . . . . . . . . . . . . . . . . 50 Example 2: Defining a Tab for the Ribbon . . . . 38 Sample VB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Viewing Properties for a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 [Setup] Section . . . . . . . . . . . . 41 [Module Name] Section . . . . . . . . . . . . . 39 Field Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Deployment of a VB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 4 Kofax Capture 10 Developer’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . .NET Recognition Script . . . . . . . . . . .NET Validation Script . . . . . . . . . 42 [Workflow Agents] Section . . . . . . . . . . . . . . . . . . . . . 57 Input File [/f {filename}] . . . . . .NET Field Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Using the Kofax Capture Extension Registration Utility . . . . . . . . . . . . .Contents Kofax Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Testing VB . . . . . . . . . . . . . . . . . 32 Publishing Requirements for the Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 [Modules] Section . . . . 38 Removing a Recognition Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Example 3: Defining Context Menu Items . . . . . . 41 Format for the Registration File . . . . . . . . . . . . . . . . . . . . . . . .NET Project File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Registering a Workflow Agent . . . . . . . . . . . . . 53 Using the Administration Module to Manage Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Registering a Custom Module . . . . . . . . . . . . . . . . . . . 54 Managing Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 [Workflow Agent Name] Section . . . . . . . . . . . . . . . . . . . . . . . . . 35 ValidationErrorException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Error Handling in VB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 [Menu Bar] Section . . . . . . . . 56 Removing a Workflow Agent . . . . . . . . . . . 36 Kofax Capture . . 32 Sample VB . . . . . . . . . . . . . . . . . . . . . . 49 Example Registration Files . . . . . . . . . . . . . . . . . . 41 Introduction . 32 Sample Validation Script Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Output File [/o {filename}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Viewing Properties for a Custom Module . . . . . . . . . . . . . . . . . . . . . 39 Sample VB . . . . . . . . . .NET Recognition Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .NET Scripting API . . . . . . . . . . . 35 FatalErrorException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Choosing the Scripting Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Unloading the Setup OCX . . . . . . 59 Silent Mode [ /s ] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Context Menus . . . . . . . . . . . . 61 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Designing the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Writing a Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Format of the Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Implementing the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Setup Programs [/x {setup program name}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Loading the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Kofax Capture 10 Developer’s Guide 5 . . . . . . . . . . . . . . . . 70 6 Creating a Setup OCX. . . . . . . . . . . 58 Workflow Agent Name [/w {workflow agent name}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Contents Module Name [/m {module name}] . . . . . . . . . . . . . . . . . . . . 63 Setting the Project Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Enabling Context Menu Items . . . . . . . . . . . . . . . . . . . . . . . . 69 Installing and Registering the Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Inherit the IACWorkflowAgent Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Removing the Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . 59 Usage [ /? ] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Tab Registry Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Registering the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Setup OCX Panels . . . 68 Registering the Workflow Agent from the Administration Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Referencing the Kofax Capture API Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Registering a Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Code Project Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Input . . . . . . . . . . . . . . . 72 Setup OCX for the Workflow Agent . . . . . . . . . . . . . . . . . . 58 Runtime Programs [/r {runtime program name}] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Error and Warning Messages . . . . . . . . . . . . . . . . . . . . . . 58 Unregister [ /u ] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Output . . . . . . . . . . . . . 75 Setup OCX Registry Entries . . . . . . . . . . 64 Creating the Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Proper Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Enabling Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Writing the Runtime Module . . . . . . . . . . 71 Code Project Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Introduction . . . . . . . . . . . . . . . . . . 63 Workflow Agent Program . . . . . . . . . . . . . . . . . . 60 5 Creating a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Workflow Agent Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Example Setup OCX for the Custom Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Designing a Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Registry Entries for Tabs . . . . . . . . . . . . . . . . . . . 97 Design the Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Create the Custom Module Registration File . . . . . . . . . . . . . . . . . . . . 81 Panels . . . . . . . . . . 99 ChildBatchCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Custom Tab Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Custom Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Tabs Can Be Added. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Custom Modules . . . . . . . . . . . . . . . . 89 Using the Sample Custom Panel . . . . . 96 Typical Development Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Setup OCX Development API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Enabling/Disabling Custom Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Themes in the Fluent UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Error Handling Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . Quality Control. . . . . . . . . . . 91 Example Custom Panel in VB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 DelPagePanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Document GUID . . . . . . . . . . . . . . . . . . . . . 101 Using Kofax Transformation Modules . . . . 100 BatchCloseWithModuleID . . . . . . . . . . . . . . . . . . . . . . . 98 Create an Installation Program . . . . . . . . . . . . . . . . . . 83 User Interface Design and Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . and Verification Tree Node (Context) Menus . . . . . . . . . . . . . . . . . . . . . . . 101 6 Kofax Capture 10 Developer’s Guide . . . . . . . . . 97 Write the Runtime Application . . . . . . . . . . . . . . . . . . . and Edited at Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Custom Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 MoveElementToBatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Sample Applications . . . . . . . . . . 90 Registering the Sample Custom Panel . . . . . 100 About Document Routing Features . . . . . . . . . . . 98 Register the Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Tracking Statistics . . . . . . . . . . . . . . . . . . . . 95 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Using Document Routing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Create the Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Custom Panels in the Fluent UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Batch Class Publishing . . . . . . . . . . . . . . . . . . . . . . 93 8 Creating a Custom Module. . . . . .Contents Ribbon Bar . . . . . . . . 86 Invoking Kofax Capture Commands from a Custom OCX Panel . . . . . . . 83 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Scan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Reference Batch ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Document Routing . . . . . . . 95 High Availability Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 7 Creating Custom Panels and Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Installing a Custom Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Unsupported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Programming in a High Availability Environment . . . . . . . . . . . . . . . . . . . . 124 Adding the Sample to the Batch Processing Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Example Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Administrator Actions . . . . . . . . . . . . . . . . . 118 About the Customization Deployment Process . . . . . . . . . . . . . . . . . 122 Kofax Capture Document Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Status . . . . . . . 123 Setup OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 ProcessNewBatch Function . 109 The ReleaseSetupData and ReleaseData Objects . . . . . . . . . . . . . . 107 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . 119 KCN Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 RuntimeSession_BatchAvailable Subroutine . . . . . . . . . 114 Setting Up a Customization Deployment . . . . . . . . . . . . . . . . . . . . . . 110 COM Servers: In-proc or Out-of-proc? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Installing the Customization Deployment Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Registering the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Development Environment . . . . . . . . . . . . . . . . . . . 102 DeleteEvenPage Module . . . . . . . . . . . . . . . . . . . . . . 103 PageMarkedForDeletion Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Runtime Executable . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Initiating a Customization Deployment . . . . . . . . . . . 105 9 Creating an Export Connector . . . . . . . . . . . . . .Contents Using the Sample Custom Module . . . . . . . . . . . 112 10 Deploying Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Export Connector Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Kofax Capture Export Type Library . . . . . . . . . . . . . . . . . 121 Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 A Custom Module Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Using Batch Manager With a Custom Module . . . . . . . . 110 Export Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Registering Your Export Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Introduction . . . . . . . . . . . . . . . . 124 Installing the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Requirements for the Export Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Kofax Capture and the Export Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Deploying Customizations When Applications Are Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Viewing Customization Deployment Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Kofax Capture 10 Developer’s Guide 7 . . 108 Requirements for the Export Connector Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Kofax Capture Optimized Custom Module API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Deployment Service Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Scripting in a High Availability Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Batch Custom Storage String . . . . . . . . . . . . . . . . . 132 Using the Sample Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 XML Transport Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 B Workflow Agent Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Index. . . . . . . . 128 Create Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 8 Kofax Capture 10 Developer’s Guide . . . . . . . . . . . 126 Processing by Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Contents Creating a Batch to Open in the Sample Custom Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Corrupt XML . . . . . . 131 Registering the Sample Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Installing the Sample Workflow Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . as they contain information that may not be included in other Kofax Capture documentation. recognition. it contains information about planning your installation. This guide includes instructions for the following: Writing custom validation. workflow agents.0 | API Reference Guide from the taskbar. select Start | Programs | Kofax Capture 10. Kofax Capture Online Help Kofax Capture online Help provides online assistance for system administrators and operators. Related Documentation In addition to the Developer’s Guide. certified operating systems and other system requirements. and field scripts Creating and registering custom extensions such as custom modules. Kofax Capture includes the following documentation: Kofax Capture Installation Guide The installation guide provides instructions for installing Kofax Capture and Kofax Capture Network Server. custom panels. The API Reference Guide is designed to be used with the Kofax Capture Developer’s Guide as a primary resource for customizing Kofax Capture. 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. To access the API Reference Guide. Kofax Capture API Reference Guide This guide is an online reference that provides the details of each API library needed to customize Kofax Capture. Release Notes Late-breaking product information is available from release notes. You should read the release notes carefully. 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.Preface Introduction The Kofax Capture Developer’s Guide provides information for customizing your Kofax Capture installation. In addition. Kofax Capture 10 Developer’s Guide 9 . and important installation notes. you must have a valid Support Agreement with an authorized Kofax Reseller/Partner or with Kofax directly. To optimize your use of the portal.Preface Training Kofax offers both classroom and computer-based training that will help you make the most of your Kofax Capture solution. and to research possible solutions to current issues. Access to the Kofax Customer Portal (for eligible customers) Click CAPTURE: SUPPORT INTERACTIONS and log in. Downloadable product documentation Click Documentation and select a product name and version. Visit the Kofax Web site at www.com for complete details about the available training options and schedules. Information about the support commitment for Kofax products Click Options and select Kofax Support Commitment. Access to support tools Click Tools and select the tool to use. To access some resources. Use these tools to find answers to questions that you have.com/support for Access to product knowledge bases Click CAPTURE: SUPPORT KNOWLEDGE.kofax.kofax. go to the Kofax Customer Portal login page and click the link to open the Guide to the Kofax Support Portal. what to do before contacting the support team. 10 Kofax Capture 10 Developer’s Guide . and what information to collect before opening a case. Getting Help for Kofax Products Kofax regularly updates the Kofax Support site with the latest information about Kofax products. The guide describes how to access the portal. Go to www. Product information and release news Click Product and select a product name and version. to learn about new functionality. how to open a new case or view an open case. 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. Visual Basic or Visual Studio. API libraries. C++. To assert additional processes. are available for you to create custom Kofax Capture extensions. Because Kofax Capture is modular (comprised of the Administration. 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. which are documented in the Kofax Capture API Reference Guide. For example. Some reasons to customize Kofax Capture are: To streamline or bypass unnecessary processes. Verification. and Softbridge Basic Language (SBL). and COM interface tools. Quality Control modules. Kofax Capture 10 Developer’s Guide 11 . Validation. For example. a validation operator would need to have access to only certain functions or processes. However. you may also want to customize a Kofax Capture process for a specific business task. 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. 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. C#.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. Scan. and so on) you can customize a specific module for forms processing using the provided Kofax Capture API libraries. To customize the user interface for your business environment. NET Scripting Library Object and File Names AscentCaptureModule (ACModule.dll) ACWFLib (ACWFlib. Used in lieu of ExportXML from DBLite.dll) Used to create VB .dll) Usage Used to create custom OCX panels for Scan. The Object and File Names column shows the library as it will be displayed in the Visual Basic Object Browser.NET custom field.Chapter 1 Using the API Libraries Kofax Capture includes several API libraries that you can use to customize Kofax Capture features or behavior. and commands. Used by custom modules to access batches. Used with the DBLite library. tabs.dll) ScriptInterface (ScriptInterface. API used by workflow agents as batches are closed by modules. The Fluent UI is characterized by the use of ribbons. Details on these libraries are provided in the Kofax Capture API Reference Guide and in many topics in the online Help. Can also be used to create Setup OCXs for Workflow Agents. Also called DBLite library. groups. Table 1-1. quicker when a subset of data is needed. Customizing with the Fluent UI Some Kofax Capture modules have a user interface. validation. Used to get information about an open batch (runtime and setup data). Quality Control. 12 Kofax Capture 10 Developer’s Guide . Used to create custom export connectors. Kofax Capture API Libraries Library Name Kofax Capture Module Type Library Kofax Capture Admin Module Type Library Kofax Capture Document Access Kofax Capture Optimized Custom Module API Kofax Capture Custom Workflow Interface Kofax Capture Export Type Library Kofax Capture . and Verification modules. called the Fluent UI. and recognition scripts. The Library Name column in the following table shows the library as it will be displayed in the Visual Basic References window.dll) AscentRelease (AscRel. which are unchanged from prior interface approaches. Validation. similar to that found in recent versions of Microsoft Office. Used to create custom OCX panels for the Administration module or Setup OCXs for Custom Modules. ACDB (DBLite.dll) DBLiteOpt (DBLiteOpt. See the Kofax Capture Help for more information on the Kofax Capture implementation of the Fluent UI.dll) AscentCaptureAdminMod (ACAdMod. The Fluent UI also supports right-click (context) menus. followed in parenthesis by the name of library file. behavior and syntax of the SelectMenuItem method are unchanged.Overview The following table shows differences between legacy terminology and the Fluent UI. strMenuBarText parameters specify the label that appears on the tab. Kofax Capture 10 Developer’s Guide 13 . Several new methods have been added that directly support the capabilities of the Fluent UI. It is strongly suggested that when updating or creating new customizations. When using older (unmodified) customizations. and AcSetup. As another example.htm. the description. The tabs typically appear at the top of the Ribbon. a group called “Menu Items” is automatically created. Note that unless a method or other API element is specifically restricted to context menus. However. the Paste command may open to show several options for pasting content.htm. AcDocs. menu text/menu item command Commands can have downward pointing arrows that reveal a window with additional related commands. To maintain backwards compatibility. In the context of the Fluent UI. For example. Groups perform a function similar to divider bars in menus. its documented functionality may apply to either the Fluent UI or a context menu (depending on the context of the application code). Additional Resources Files that define the data layout used when accessing Kofax Capture data through custom modules and workflow agents are provided. the names and behaviors and documentation of existing methods and other API and customization elements are unchanged. These data layout files (AcBatch. For example. it causes the command (menu item) with the specified resource ID to be triggered. Both mechanisms utilize identical data layouts. these new methods be employed. The command label is determined by the strMenuText parameter. the strGroupName parameter specifies the text to be used for the group name. See the Kofax Capture API Reference Guide for more information.htm ) are installed with Kofax Capture in your Kofax Capture installation folder. in the AddMenuEx method. A tab may have many groups. the ShowMenu method shows or hides a tab in the Ribbon. but there is no programmatic mapping from a menu based interface to groups. In a Ribbon tab. group A “group” is an organizing container for commands (menu items) and belongs to a tab. Legacy and Context Menu menubar menubar text /menu Fluent UI Ribbon tab Comments An application window can have only one Ribbon. strMenuText parameters specify the label that appears on the command button. Table 1-2. it causes the menu item with the specified resource ID to be triggered. In a context menu. the strMenuBarText parameter specifies the label on the tab. sample applications. while AcBatch. How to Implement Your Customized Scripts and Modules Each chapter that provides instructions for creating custom extensions.htm defines runtime information. API references. filenames. Note Prior to Kofax Capture 9. 14 Kofax Capture 10 Developer’s Guide .htm. Each element describes a specific kind of object and includes attributes and subelements. such as custom modules. Although the product name in most of the documentation has been changed. or when referring to prior versions of Kofax Capture. and contains only the portion of AcBatch that relates to the document structure. panels. The data is partitioned into elements. workflow agents. there remain instances of the prior product name in some code snippets.htm defines setup information. Refer to these chapters in this guide for detailed instructions for implementing your customized extensions and scripts. AcDocs.Chapter 1 The data layout is split into two files—AcSetup. Attributes are properties that describe an element.htm is a subset of AcBatch. and setup OCXs includes implementation information. the product was named Ascent Capture. Writing a Validation Script Validation scripts are written and managed from the Administration module. This chapter focuses on SBL as the tool with which to create custom scripts.NET is described in Chapter 3 – Creating Custom Scripts Using VB . and each script consists of a set of event handler functions that are initially blank except for some default error handling code. Folder validation scripts are nearly identical to the document validation scripts described below. the scripting language incorporated into Kofax Capture. Writing scripts using Visual Basic . 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 recognition script that retrieves zone snippets from each image in a batch and extracts data from them using a custom OCR engine. This eliminates the need to create scripts for simple database query functions. Important differences are noted in the Kofax Capture online Help. Validation scripts and recognition scripts can be written in either Visual Basic . 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.Chapter 2 Creating Custom Scripts Using SBL Introduction You can customize the way Kofax Capture processes batches by adding scripts to your batch classes. There are Kofax Capture 10 Developer’s Guide 15 . Note You can also use folder validation scripts to add custom processing or enhance or replace the default folder validation provided by Kofax Capture. Separate scripts can be written for each document class you have defined. For example.NET or with the Softbridge Basic Language (SBL). you can write a validation script that does a database query to verify that an index field was entered correctly. a full-featured language similar to Visual Basic.NET. These scripts may be written using an embedded macro language called the Softbridge Basic Language (SBL). Some common validation tasks can be done with the database validation feature. Recognition scripts modify data in the Recognition Server module. There is a FmtFieldName function for each data field in a document class. There is a PreFieldName function for each data field in a document class. You can add code to each to perform custom data validation routines. the function is called once per document class the first time a document class is processed. and close the Document Validation Script window. right-click on the document class for which you want to implement a validation script. There is a PostFieldName function for each data field in a document class. make corrections if necessary. When finished writing your code. Called when a batch is closed. compile the script. Called each time a new document is loaded. select SBL from the Scripting language list. Called when a validation operator exits a data field. Table 2-1. The built-in SBL macro editor is displayed with default code already supplied. If a batch has multiple document classes. follow these steps: 1 2 3 4 From the Batch tab in the Administration module. exit the editor. not the data itself.Chapter 2 seven functions accessible through validation scripts. It affects only the way the data is displayed. Click on “Document Validation Script”. KfxAcmDocument KfxDocPostProcess KfxDocPreProcess KfxLoadValidation KfxUnloadValidation PostFieldName PreFieldName Writing a validation script is a straightforward procedure. 16 Kofax Capture 10 Developer’s Guide . You can add your own code to any of the functions contained in the script. Called when a batch is first loaded in the Validation or Verification module. In the Document Validation Script window. The Kofax Capture Module Document object for the current document. To write a validation script. Validation Script Functions Function FmtFieldName When Called Called for all data fields whenever the data in any field changes. Called after each document is closed. Click either the Create button (for a new script) or the Edit button (for an existing script). Called each time a validation operator enters a data field. that apply to an entire document) and calls the KfxDocPreProcess function. Consult the online Help available from the Administration module for details on certain exceptions to this flow. You can use this function to supply a default value for the index field or to display a window with options for the field. You can use this function to set up any initialization needed to process the document. although you no longer have access to the index field data. 2 3 4 5 6 7 Kofax Capture 10 Developer’s Guide 17 .) The following describes the “typical” validation script function sequence: 1 The Validation or Verification module sets the batch-level variables (variables. The general flow for processing a validation script is shown in Figure 2-1. that apply to individual index fields) and calls the PreFieldName function. Validation or Verification calls the KfxUnloadValidation function. and reloaded/unloaded as necessary. that apply to an entire batch rather than a document or field) and calls the KfxLoadValidation function. such as RejectandSkipDocument. the script remains loaded until the batch is closed. For each index field in the document. You can use this function to release any resources allocated for the script. such as SaveandSkipField. When the script is unloaded. When the operator leaves the field. You can use this function to allocate resources or perform any other initialization needed for the script. You can use this function to do any final processing for the document. The FmtFieldName functions are called for all index fields (except the one getting the focus) whenever the data in an index field changes. Validation or Verification sets the document-level variables (variables. For each document in the batch. (If document sorting is enabled and batch editing is disabled. Validation or Verification sets the field-level variables (variables. Validation or Verification calls the PostFieldName function. After the last index field in the document is processed. such as ValidationError. In most cases. Validation or Verification calls the KfxDocPostProcess function. You can use this function to do any type of validation required for the index field. the script is unloaded when a document of a different document class is processed.Creating Custom Scripts Using SBL 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. The SBL editor is displayed. but only three field functions are accessible (Pre_KFX_FieldName. Post_Kfx_FieldName. There is no need to compile the macro unless you want to check the syntax of your code. select the Field Types tab. you also have the option of using field type macros instead. Click either “Create” (for a new macro) or “Edit” (for an existing macro). 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. Provide a name for the macro (the default name is the same as the field type). To write a field type macro 1 2 3 4 5 From the Administration module’s Definitions panel. and Fmt_Kfx_FieldName) for the field you have chosen.” The Field Macro window will display. Edit the functions as desired. and then exit the editor. 6 18 Kofax Capture 10 Developer’s Guide . You use the Kofax Capture Administration module to create field type macros. Right-click on a field type and click “Field Macro.Chapter 2 Figure 2-1. To test your script under real conditions. publish your batch class. If an unhandled error occurs. For example. Create a test batch and process it through the Validation or Verification module. compile the script and publish your batch class. make sure the SBL Editor/Debugger Console window is visible (select a document class and click Edit in the Validation Script window). It is merely a template that is copied into a validation script. add a Sub Main function at the end of your validation script with a call to the function you want to test. you should comment the “On Error Goto Failure” statement so you can examine any runtime errors generated by your code. delete the batch without saving the validation data. 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. and you can return results using a MsgBox function or any other mechanism you desire. Only validation scripts are executed during actual processing. Repeat this process until you get the desired results. you could create a field type called “Phone Number” and then write a field type macro that performs the formatting. From that point forward. the code you wrote for the field type macro will be automatically copied into the validation script. Kofax Capture 10 Developer’s Guide 19 . if you want to test the PreFieldName function of a field called FirstName. Testing Validation Scripts You should always test validation scripts before using them in production. and create another test batch to process through the Validation or Verification module. Here are a few tips: While developing your script. 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. and then edit your script from the Administration module. For example. Instead of cutting-and-pasting from another script. When you are developing a custom script. All of the functions in validation scripts include error handling.Creating Custom Scripts Using SBL The next time you create a validation script that contains this field. you would write: Sub Main() Result = PreFirstName() ***Additional code goes here*** End sub The Main function will be executed when you run the script. If you need to make changes and test again. Note that a field type macro itself is never executed. the formatting function will be automatically copied into the validation script. To quickly test your code without running a batch through Validation. You can then compile the validation script as usual. if you have a telephone number formatting function. all you have to do is open the new validation script and compile it. the function returns the FatalError value. Recompile your script. 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. any time you create a document class that contains a field of the Phone Number type. SBL offers local variables and module-level variables (both declared using “Dim”) and global variables (declared using “Global”). The window editor creates a window definition. which is inserted into the script. often with the same names and arguments. External functions must be declared in every module that calls them. A module-level variable is accessible only by functions in the script in which it is declared. radio 20 Kofax Capture 10 Developer’s Guide . so there’s no chance of mistakes. You can display a window from any function in a script. To send or retrieve data to/from a window. they must be forward declared for the compiler to resolve the references. you can create a window function to handle user selections. All SBL windows are modal. click on the Edit | Dialog menu item in the SBL window editor. This program allows you to name and position controls on a window form. When the user closes the window. Windows can return values to the script. For example. To create a window. Here are some key differences between SBL and Visual Basic: Variable and function declarations. The implementation is similar to that used by Word Basic in Microsoft Word. Variable scope. This has two advantages: The operator has less typing to do. so you can use a window to display a list of selections for an index field. A local variable is accessible only within the function in which it is declared. The SBL window editor allows you to create windows that contain list boxes. It’s error-free. Windows. but note that a global variable must be declared in every SBL code module that accesses it. and there are only seven departments to choose from. the script can determine the selections made by the user. but SBL has a window editor you can use to create a window to display from a script function. It is similar to a Private variable in Visual Basic.Chapter 2 Differences Between SBL and Visual Basic SBL is similar to Visual Basic and Visual Basic for Applications (VBA). It is similar to a Global variable in Visual Basic. it might be convenient to simply display a list and allow the operator to choose an item from the list. command buttons. 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. attach script variables to controls on the window. The operator chooses from a list. External function declarations. You create custom windows using the SBL Dialog Editor (window editor). Most of the Visual Basic functions and procedures have SBL equivalents. About SBL Windows Softbridge Basic includes a window editor that allows you to create and display custom windows within your scripts. If you need to enable or disable controls on the window as the user works with it. which is inserted into your script. A global variable is accessible by any function in any loaded script. SBL scripts are not associated with a form or window. if you have an index field that gets filled in with a department name. This is especially handy if the department names are fairly lengthy (“Parks and Recreation Department”). The editor creates a window definition record. Example of the SBL Dialog Editor Note that for the purposes of this example. 6.181.92 OkButton ListBox Text End Dialog Dim DepRecord As DepartmentName Dialog DepRecord KfxDepartment_Name=DepArray(DepRecord. simply highlight the template code and start the editor. The array is called DepArray. This is done with the Values tab in the Field Type Properties window in the Administration module. Kofax Capture 10 Developer’s Guide 21 .DepArray(). the window selections are defined statically within the script.Creating Custom Scripts Using SBL buttons.50.6. such as dynamically populating the list based on a database query. 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.20. exit the editor and the template for the window is inserted into your class script at the current cursor position. The window defined by the template is displayed in the editor. When you are finished creating the window.. Yet an SBL list box is a good solution if you want to do something more complex. This code retrieves the selected item from the list.113.14 124. For more details on creating windows. taking only a few more lines of code to display the window.14 6.7. You can edit this code directly or you can change it dynamically within the editor. check boxes. Note You can achieve results similar to those described above by providing known values for your field type.10. The code excerpt in Figure 2-2 shows what needs to be done. Keep the following in mind as you create windows: If you need to modify an existing window. The size and position of the window within the module are defined on the first line (Begin Dialog…) of the template code. consult the Softbridge Help files. 124. Creating the window is straightforward. The window editor automatically creates the template code within the validation script. and other standard Windows controls. You don’t need scripting to do something this simple (you can just specify a set of values when you define the field type). The only modification is to insert the variable name (DepArray) into the template.37.50.ListBox1 CancelButton This is the template code that was inserted by the SBL window editor.65. This code sets up an array of strings that provides the list values for the window to display.22.Listbox1) This code defines a window record and displays the window. “Department Name:” Figure 2-2.65. The PreFieldName and PostFieldName functions for any unvalidated fields in the document are skipped. Example: KfxDocPreProcess = SaveAndSkipDocument SaveAndSkipField 1 2 When returned from the PreFieldName function. Return this value from KfxDocPreProcess. displays a message box with the KfxErrorMessage string. If this is returned from a PostFieldName function. the KfxDocPostProcess function is called. Table 2-2. The Pre and Post functions for all remaining fields are not called. An error message will display and the Validation or Verification module will not advance to the next field. Table 2-2 lists return codes. The PreFieldName processing is skipped. PreFieldName. however. Example: PostDepartment_Name = ValidationError ValidationErrorNoMsg -2 Same as above. 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. the Validation or Verification module advances to the next field. Example: PreFieldName = SaveAndSkipField ValidationError -3 Indicates that the script encountered an error. 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). Indicates that all data fields should be saved and the Validation or Verification module should advance to the next document. KfxDocPostProcess. It is typically used in order to automatically skip a document that does not need to be validated by an operator (for example. but no error message is displayed. NoError 0 NoOperation 3 RejectAndSkipDocument -4 SaveAndSkipDocument 1 1 22 Kofax Capture 10 Developer’s Guide . because the confidence level of all the fields is high). but the PostFieldName function is called. The batch is immediately terminated and the batch status is set to Error. but the KfxDocPostProcess function is called. and closes. Validation or Verification module changes the batch status to Error.Chapter 2 Validation Script Return Codes and Variables Validation scripts have access to a variety of return codes and system variables. Indicates a successful operation. Validation Script Return Codes Return Code FatalError Value -1 Definition Indicates a fatal error. Table 2-3 lists system variables. or PostFieldName function to reject the active document and advance to the next document. as no validation will be performed. Contains the value of the data in the current field. The name of the current document class. The hexadecimal ID of the current document class. The error message displayed when either FatalError. A parameter of the KfxDocPostProcess function that indicates whether the operator accepted or rejected the data. A parameter of the KfxLoadValidation function that indicates the number of documents (not pages) in the current batch. A parameter of the KfxLoadValidation function that indicates whether the batch is being processed by the Validation module or the Verification module. Indicates whether the KfxDocPreProcess and KfxDocPostProcess functions should be called for documents that have already been processed (for example.Creating Custom Scripts Using SBL 1 Care should be taken when using these. The hexadecimal ID of the current batch class. DataAccepted EnteredValue ID KfxBatchClassId KfxBatchID KfxBatchName KfxClassName KfxCLFieldName KfxDocClassId KfxErrorMessage KfxFieldName KfxLoadAllProcessedValues KfxOperation KfxPageFile MaxLength NumberOfDocsInBatch NumberOfPages VerifyBatch Kofax Capture 10 Developer’s Guide 23 . A parameter of the KfxDocPreProcess function that indicates the number of pages in the current document. 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. Contains the confidence level of the current field if it was filled in via OCR. RejectAndSkipField. The hexadecimal ID of the current batch.” Indicates whether the script is being called by the Validation module (“index”) or the Verification module (“verify”). The default is “No. OMR. The filename of the image currently being displayed. A parameter of the KfxDocPreProcess and KfxDocPostProcess functions that indicates the document ID of the current document. if a batch is suspended halfway through and then reloaded). A parameter of the PostFieldName function that indicates the maximum allowed length of the field (for CHAR and VARCHAR field types). ICR. or RejectAndSkipDocument are returned from any function. The name of the current batch. or bar code recognition. Table 2-3. A parameter of the PostFieldName function that contains the data entered by the validation operator. In the Recognition Script window. you can provide a list of possible choices and add pattern matching. KfxLoad is called once per batch for each recognition profile that contains a recognition script. Called after each zone snippet is processed. compile the script. The primary difference is that recognition scripts run in the Recognition Server module and have access to different functions and different system variables. recognition scripts are written and managed from the Administration module. Table 2-4. There are a total of four functions accessible using recognition scripts. it is a good place to perform time-intensive validation procedures (such as querying a remote database over a slow connection). The built-in SBL macro editor is displayed with default code already supplied. Some common uses of recognition scripts include the following: Replacing a Kofax Capture recognition engine. exit the editor. To write a recognition script. Writing a Recognition Script Like validation scripts. 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. choose the recognition profile for which you wish to write a script. and each script consists of a set of functions that are initially blank except for some default error handling code. Modifying the processing of a Kofax recognition engine. follow these steps: 1 2 In the Administration module. It should be the one associated with the zone you want to manipulate. Performing offline processing. Recognition Script Functions Function KfxLoad When Called Called the first time a zone is encountered of the specified recognition type. Since the Recognition Server module is unattended. For example. When finished writing your code. in the Recognition group. on the Tools tab. Called for all recognition scripts when the batch is closed. click Scripts. 3 4 24 Kofax Capture 10 Developer’s Guide . and close the Recognition Script window. 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. as shown in Table 2-4.Chapter 2 Recognition Scripts Recognition scripts are similar in many ways to validation scripts. Click the Create button (for new scripts) or the Edit button (for existing scripts). KfxPreRecognition KfxPostRecognition KfxUnload Writing a recognition script is a straightforward procedure. You can write a recognition script for each recognition profile that you have created. You can add your own code to any of the functions contained in the script. Called before each zone snippet is processed. The Recognition Script window will display. Recognition Server then submits the image to the Kofax recognition engine. select VB . RecognitionPostProcessing Event. You can use this function to allocate resources or perform any other initialization needed for the script. After recognition is completed. VB . 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. Recognition Server sets the script variables to the results from the recognition engine and calls the KfxPostRecognition function. To create a recognition script 1 2 3 4 5 On the Tools tab. Click Create. There are a total of four events accessible for recognition scripts. This event is called when a batch is opened.NET code editor. Your script cannot be applied to a batch created before the new publication date. BatchLoading Event. and each script can consist of several events. as described below. Unless you use the KfxPreRecognition function to cancel the default recognition. RecognitionPreProcessing Event. In the Scripting language box. compile the script. When finished writing your code. This event is called after each zone snippet is processed. In addition. click Scripts. select the scripting language. Recognition Server sets the script’s KfxImageFile variable to the filename of the temporary image file containing the zone and calls the KfxPreRecognition function.NET You can use the Kofax Capture Administration module to create a recognition script. Note You must compile your script and publish your batch class before your script can be used in batches. In the Recognition profiles list. form identification zones. select the custom recognition profile for which you want to create a script.NET. This event is called before each zone snippet is processed. You can use this 2 3 Kofax Capture 10 Developer’s Guide 25 . You can use this function to submit the image to another recognition engine and/or cancel the default recognition processing. The filename assigned to the script is shown in the title bar. exit the editor. In this case. For each zone of that recognition type in the batch. How Recognition Scripts are Processed When a batch is processed through the Recognition Server module. You cannot create scripts for full text OCR or page-level form identification profiles. or index zones. This event is called when a batch is closed. in the Recognition group.NET recognition scripts can be created for separator zones.Creating Custom Scripts Using SBL Creating a Recognition Script Using VB . A new script is created and displayed in the VB . you must republish if you make changes to your script. You can write a recognition script for each recognition profile that you have created. Note You can create scripts only for customized recognition profiles. and close the Recognition Script window. BatchUnloading Event. Chapter 2 function to compare results from different engines or do any additional validation of the results. followed by the KfxPostRecognition function. Table 2-6 lists system variables. Figure 2-3. Indicates a successful operation. Table 2-5 lists return codes. Recognition Script Return Codes Return Code FatalError NoError Definition Indicates a fatal error. Recognition Server calls the script’s KfxUnload function. Similar to NoError. Figure 2-3 illustrates the general flow for processing a recognition script. If this is returned from the KfxPreRecognition function. Recognition Server saves the data in the script variables to the Kofax Capture database. After processing this function. Table 2-5. Kofax recognition will be performed next. If this is returned from the KfxPostRecognition function. 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. Example: KfxPreRecognition = SaveAndSkipOperation SaveAndSkipOperation 26 Kofax Capture 10 Developer’s Guide . but skips the Kofax recognition. 4 The script remains in memory until the batch is closed. You can use this function to release any resources allocated for the script. When the batch is closed. the Recognition Server module advances to the next field. The batch is set to an error state. or registration zone. form identification. These variables define the offset of the lower-left pixel for the first character in the search text found in the zone. 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. These variables define the offset of the lower-left pixel for the first character in the search text found in the zone. Add code to the PostRecognition functions to pause the recognition procedure so you can examine the temporary image file and the recognition results for your zone. The current recognized value. The search text is the expected search string set in the Administration module for a separation. Recognition Script System Variables System Variable KfxConfidence Definition The confidence level of the recognition engine. The best way to do this is to add a message box that displays the name of the image file and the results returned by the recognition engine: MsgBox "Zone image file = " & KfxImageFile & _ " Value = " & KfxValue & _ " Confidence = " & KfxConfidence When you process a batch of documents. Kofax Capture 10 Developer’s Guide 27 . with 100 being the highest confidence. To use the recognition script to test your settings 1 2 3 4 If you haven’t already done so. attempting to modify the file may have unpredictable consequences. This can be used to retrieve and/or modify the vertical registration offsets returned by the default engine. It can be modified if desired in the KfxPostRecognition function. This can be used to retrieve and/or modify the horizontal registration offsets returned by the default engine. Uncomment the KfxImageFile variable in the script. You can use a . Note that this is a temporary file and is read-only. Create a recognition script for this profile. The offsets are defined from the upper-left of the zone and are in 1/1200ths of an inch (BMUs). It is an integer between 0100. The filename of the zone snippet currently being processed.tif image viewer to examine the temporary image file and see the results.Creating Custom Scripts Using SBL Table 2-6. KfxImageFile KfxRegistrationHorizBMU KfxRegistrationVertBMU KfxSearchText KfxValue Using a Recognition Script for Testing Your Settings You can use a recognition script to examine the zones and see the results of your image cleanup and recognition settings. Recognition Server will display the message box after it processes the zone. you are responsible for setting this value. The offsets are defined from the upper-left of the zone and are in 1/1200ths of an inch (BMUs). create a custom recognition profile for your settings. If you perform recognition with a custom engine. Image processing has already been performed by the time the script gets access to this file. or when you want to test pages as you are scanning them. and when you only have a few samples you need to test.Chapter 2 Note QuickZones is suitable for checking your settings when you already have some document samples scanned in and saved. 28 Kofax Capture 10 Developer’s Guide . Use a recognition script when you need to test many samples. 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 Kofax Capture 10 Developer’s Guide 29 . For example.Chapter 3 Creating Custom Scripts Using VB .NET. Document and folder validation scripts can be used to perform validation on document class index fields and folder index fields. You can create the following kinds of custom scripts in VB . Recognition scripts validate or modify data on results from the Recognition Server module. your field script can validate that data meets the criteria for a particular field type. 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. There is also a large knowledge base for the Visual Studio development environment should you need additional coding assistance. For example. For example. In the Administration module. you can choose the kind of script you want to create and the language you want to create it with. You should be familiar with programming concepts and the VB .NET Introduction Scripts are small programs used to perform specific tasks for associated Kofax Capture modules. which is essential for supporting multi-byte character sets. Software Requirements To create a custom script in VB . you can write a validation script that queries a database to verify that data for an index field matches the entered data. This chapter focuses on creating custom scripts using Microsoft Visual Basic 2008 Express Edition as the script programming language. Validation scripts validate data in the Kofax Capture Validation and Verification modules.NET: Field scripts validate data in index fields. respectively.NET and the Microsoft Visual Studio development environment is that Unicode is supported. The advantage of writing scripts in VB .NET programming language and development environment for writing custom scripts. In this topic. You can perform these checks prior to and after document processing (that is. for which the document validation script processes. a sample Validation script written in VB .NET project is created for the script and opens in the code editor of your . you will learn How to choose the kind of custom script you want to create using VB . 2008. select the document class for which you want to create a script. Kofax Capture . select a scripting language to create the script. In the Scripting language list. To create a document validation script with VB .5 runtime is installed either by Kofax Capture or by Visual Studio 2008.NET The objects.NET application.NET Scripting API Your document validation script project will have access to the events and properties of the Kofax Capture . in the Document Class group. methods. If not already installed. the typical method of creating a custom script is from Kofax Capture Administration module. A VB . must exist.NET.NET project location for your script The deployment of the script’s Visual Basic project Publishing requirements for the script Additionally. The index fields that exist for the document class selected are included in the script code shell.5 runtime installed in your development environment. The Validation Script window will display. click Validation Script. Choosing the Scripting Language Although it is possible to create a custom script outside of Kofax Capture using a supported Visual Studio environment. Add your code to create your custom script. DocumentPreProcessing and DocumentPostProcessing events). and properties that are available for use from the Kofax Capture . select VB . In the Document classes list. 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.Chapter 3 For Microsoft Visual Basic 2010. and 2005. Each script can consist of several events and event handlers.NET 3.NET 1 2 3 4 On the Home tab. the . In this case. Note Microsoft Visual Basic Express Edition is a free download from the Microsoft Web site. 30 Kofax Capture 10 Developer’s Guide .NET is provided.NET Scripting library. Click Create.NET Scripting API The VB . you will also need Microsoft . A document class.NET Framework 3. and their associated properties can be used. the VB . The following events. refer to Error Handling in VB . This class represents the event arguments for the DocumentValidationScript.NET DocumentValidationScript Class The DocumentValidationScript class contains the events that are available for use in a validation script.Creating Custom Scripts Using VB . Validation Script Events Events BatchLoading BatchUnloading DocumentPreProcessing DocumentPostProcessing PreDocumentEventArgs PostDocumentEventArgs When Called Called when a batch is opened.DocumentPostProcessing event. 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 Project File Location The file name assigned to the script is shown in the title bar of the programming product. and properties. However. The default location for each project is a numeric folder name under the "~AdminDB\Scripts" folder. You must compile your script and publish your batch class before your script can be used in batches.DocumentPreProcessing event. Table 3-1. you must republish if you make changes to your script. This class represents the event arguments for the DocumentValidationScript. event arguments. Three types of exceptions are available: FatalErrorException RejectAndSkipDocumentException ValidationErrorException For details about each event. Kofax Capture 10 Developer’s Guide 31 . For more information about exceptions. event arguments.NET on page 35 VB . refer to the Kofax Capture API Reference Guide. You add code for a selected event to perform a custom data validation routine. which can be accessed from the parameter of the event handler. Exceptions To signal an error state.NET script can throw an exception during event handling. Your script cannot be applied to a batch created before the new publication date. Called after each document is closed. batch fields are exposed through the Batch object. In addition.NET scripting is not supported. Called when a batch is closed. Called each time a new document is opened. Choose VB . Scripts are downloaded when the remote site synchronizes with the central site. The publish check is performed only on a newly created VB . Publishing Requirements for the Script A VB . select Program | Kofax Capture 10. The entire VB .” Start the Kofax Capture Administration Module: 1 2 3 4 5 6 From the Start menu.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.NET Validation Script This section describes how to create a sample VB . a publish check is not performed on VB . in the Document Class group. VB . Click Create. an error occurs. Sample VB . which are executed when there is no document/folder validation script.NET from the Scripting language list. From the Document Validation Script window that appears. click Validation Script.NET Project VB .NET script must be compiled before it can be published. The publish check is not performed on updated or changed scripts. Sample Validation Script Code Next.NET scripts for imported and exported batch classes. The VB . which contains the fields ClientName and SSN.NET project is created and the code shell opens in the code editor. A VB . 32 Kofax Capture 10 Developer’s Guide .0 | Administration. and it is the responsibility of the script developer to recompile scripts as needed. The VB .NET scripts are deployed automatically on standalone workstations and on Kofax Capture Network Server remote sites through synchronization by the Remote Synchronization Agent. choose SampleScript from the Document classes list. The first function of the code is the FieldPostProcessing event and the next two are helper functions. Also. Otherwise.NET scripts have a folder of source files and a folder of executables.NET script.NET document validation script and add some custom code to it. Select the document class SampleScript. 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.Chapter 3 Deployment of a VB .NET scripts can include field scripts.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. On the Home tab.NET document validation script is created as outlined in the section “Choosing the Scripting Language. The sample will use a document class named SampleScript. Batches using VB . Generic System. Imports Imports Imports Imports Imports System System.IndexField.FieldPostProcessing Dim oConnection As IDbConnection oConnection = OpenDatabaseConnection() Try oConnection.UserID = "User1" '*** user name oConnectionStringBuilder. compile the script.AscentCapture.NET After you have added the following code. _ SSN.AscentCapture.ValidationErrorException _ ("SSN missing from the database.Scripting Kofax.InitialCatalog = "SocialSecurityDB" _ '*** database name Dim oConnection As SqlConnection Kofax Capture 10 Developer’s Guide 33 .Scripting. ByVal e As _ Kofax.Scripting.IndexField) End If Finally oConnection.Text Kofax.Collections.Close() End Try End Sub Private Function OpenDatabaseConnection() As IDbConnection Dim oConnectionStringBuilder As SqlConnectionStringBuilder oConnectionStringBuilder = New SqlConnectionStringBuilder() oConnectionStringBuilder.DataSource = "DBServer00\SQL2005" _ '*** server name oConnectionStringBuilder.Data.Value)) Then Throw New _ Kofax.PostFieldEventArgs) _ Handles SSN. SSN.AscentCapture.".Creating Custom Scripts Using VB . publish the batch class by right-clicking the batch class and selecting Publish.Open() If (Not FindSsnInDatabase(oConnection.Password = "abc123" '*** password oConnectionStringBuilder.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.AscentCaptureModule Imports System. When the script successfully compiles. Break points are set in the script. the script in the Administration module is loaded instead of the published script. A batch is created and processed through the Validation module. However.CommandType = CommandType. It is only supported in Visual Studio. Note The ability to debug and modify the VB .NET script is tested. The following is a typical process for testing and debugging a VB .NET document validation script in the Administration module and publishes a batch class.ConnectionString = oConnectionStringBuilder.CreateCommand() '*** The database has a Customers table with a column for SSN oCommand.NET scripts) must have been previously published and a batch must be ready to be processed. strSsn) oCommand. When a VB .Format("SELECT SSN FROM _ Customers WHERE SSN=N'{0}'". and changes are made to the script as desired.NET Custom Scripts A VB .Text Dim oReader As IDataReader oReader = oCommand.NET document validation script: 1 2 3 4 A user with administrator rights creates a VB . the batch class and script must be republished before changes can take effect.Read() oReader. However. the VB .CommandText = String. The VB . the batch class (with one or more associated VB .NET script project is opened in Visual Studio. _ ByVal strSsn As String) As Boolean Dim oCommand As IDbCommand oCommand = oConnection.NET custom validation script can be tested and debugged without republishing the associated batch class.Chapter 3 oConnection = New SqlConnection oConnection.ExecuteReader() Dim bFound As Boolean bFound = oReader.NET script that is being debugged is the unpublished copy.Close() Return bFound End Function End Class End Namespace Testing VB . 34 Kofax Capture 10 Developer’s Guide .NET script without republishing the batch class is not supported in Visual Basic Express Edition.ConnectionString Return oConnection End Function Private Function FindSsnInDatabase( _ ByVal oConnection As IDbConnection. In this case. When this exception is thrown. or logged in the Recognition Server. However. and the debugger stops at the first break point. the DocumentValidationScript.FieldPreProcessing and FieldScript. recognition. The FieldScript. the validation process is terminated and the batch is left in an “In progress” state. It is treated as a fatal error if the Recognition Server receives this exception.DocumentPostProcessing event is called.FieldPostProcessing events for any unvalidated fields in the document are skipped. The script is compiled. The Kofax Capture .Creating Custom Scripts Using VB . Kofax Capture 10 Developer’s Guide 35 . Testing and debugging can continue until you are satisfied with the script. Note When debugging a Validation script in VB . The batch is set to an error state and sent to Quality Control.NET 5 6 7 The validation script is run from Visual Studio.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. It may take time for the batch to return to the “Ready” state.NET A VB . 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. Error Handling in VB . Example Throw New FatalErrorException("Missing validation resource") RejectAndSkipDocumentException This exception is used by the validation script to reject and skip a document. if you stop the debugger while a batch is open. and the batch is published. and field scripts. This exception is thrown in document validation scripts only. the error message is displayed in Validation or Verification.NET. and to advance to the next document.NET script uses an exception during event handling to signal an error state. modifying the process of a Kofax recognition engine. Example Throw New ValidationErrorException() ValidationErrorException (ErrMsg.NET project location of your script. IndexField specifies the field to get the focus. For example. the script deployment. In this section. then the last field that is being evaluated gets the focus. then an exception is thrown with the third field getting the focus. you will learn How to choose the VB . The objects. IndexField) ValidationErrorException (ErrMsg) If this version is used. if cross-field validation is being performed in the DocumentValidationScript. or performing an offline recognition process. 36 Kofax Capture 10 Developer’s Guide .Chapter 3 There are two versions for this exception: ValidationErrorException (ErrMsg) ValidationErrorException (ErrMsg. Choosing the Scripting Language Although it is possible to create a custom script outside of Kofax Capture using a supported Visual Studio environment. then the error message is displayed in the status bar of the Validation or Verification module and will not advance to the next field.oIndexField) Note If ErrrorMsg is empty.NET Scripting API.DocumentPostProcessing event and a computation routine determines that the third field does not match the sum of the first and second fields. and properties that are available for use from the Kofax Capture . If the field does not exist or is null. Refer to the Kofax Capture API Reference Guide for details about the syntax and parameters for these exception classes. Example Throw New ValidationErrorException("Sum does not match". Creating a Recognition Script in VB . the typical method for creating a custom script is from the Kofax Capture Administration module. then the default error message is displayed. and publishing requirements are the same as those for validation scripts.NET Recognition scripts are useful for processing zone snippets with a custom recognition engine. The focus remains on the last field that is being validated.NET as the scripting language for the recognition script. methods. 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. A recognition profile for which the custom recognition script processes must exist. The VB . NET 1 2 3 4 On the Tools tab.NET Scripting API Your recognition script project will have access to the events and properties of the Kofax Capture . Three types of exceptions are available: FatalErrorException RejectAndSkipDocumentException ValidationErrorException For details about each event. The following events. event arguments. refer to the Kofax Capture API Reference Guide. Called when a batch is closed.RecognitionPostProcessing event. in the Recognition group. Click Create.NET on page 35.Creating Custom Scripts Using VB . RecognitionScript Class The RecognitionScript class contains the events that are available for use in a recognition script.NET script can throw an exception during event handling. The Recognition Script window will display.NET application. the VB . For more information about exceptions. event arguments. A VB .NET project is created for the script and opens in the code editor of your .NET.NET Scripting library. refer to Error Handling in VB . Called before each zone snippet is processed. Kofax Capture 10 Developer’s Guide 37 . You add code for a selected event to perform a custom recognition routine. In the Scripting language list. This class represents the event arguments for the RecognitionScript. In the Recognition profiles list. select a scripting language to create the script. Recognition Script Events Events BatchLoading BatchUnloading RecognitionPreProcessing RecognitionPostProcessing PreRecognitionEventArgs PostRecognitionEventArgs When Called Called when a batch is opened. choose the recognition profile for which you want to create a script. Exceptions To signal an error state.NET To create a recognition script with VB . Kofax Capture . and their associated properties can be used Table 3-2. Each script can consist of several events and event handlers. In this case.RecognitionPreProcessing event. select VB . click Scripts. You add your code to create your custom script. Called after each zone snippet is processed. and properties. This class represents the event arguments for the RecognitionScript. Chapter 3 Debugging Your Settings with a VB .NET Recognition Script You can use a VB .NET recognition script to display the zone snippet when the batch is processed in the Recognition Server module. This is a good way to test your settings. To use a recognition script to debug your settings 1 2 3 4 5 6 7 Create a recognition profile for a zone. From the Administration module’s menu bar, select Scripts | Recognition. The Recognition Script window will display. Select a profile from the list of Recognition profiles. Select a scripting language from the list of Scripting languages. In this case, select VB .NET. Select Create. A new script will display in the VB .NET code editor. Add the example code snippet shown below to your VB .NET script. Compile the script and close the Recognition Script window. Example Code Private Sub CustomRecognitionProfile_BatchLoading(ByVal sender As Object, _ ByRef ImageFileRequired As Boolean) Handles Me.BatchLoading '*** Enable the image file property when loading the batch. ImageFileRequired = True End Sub Private Sub CustomRecognitionProfile_RecognitionPostProcessing(ByVal _ sender As Object, _ ByVal e As Kofax.AscentCapture.Scripting.PostRecognitionEventArgs) _ Handles Me.RecognitionPostProcessing '*** Display a message box with the image file, value, and confidence '*** for each field. MsgBox(e.ImageFile + " " + e.Value + " " + e.Confidence.ToString()) End Sub Publish the batch class and process a test batch through the Recognition Server module. For every zone to which the recognition profile is attached, a message will display with the file name of the zone snippet, the value, and the confidence. If you have access to a viewer, you can display the zone snippet file to see the zone snippet image. 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 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 38 Kofax Capture 10 Developer’s Guide Creating Custom Scripts Using VB .NET End Sub Removing a Recognition Script You can remove a recognition script to restore the default recognition procedures. You use the Kofax Capture Administration module to remove recognition scripts. To remove a recognition script 1 On the Tools tab, in the Recognition group, click Scripts. The Recognition Script window will display. 2 3 In the Recognition profiles list, select the recognition profile for which you want to restore the default processing. Click Remove. The script is no longer associated with the recognition profile. When you remove a recognition script, the source code file is not deleted from the \Scripts directory. Although you cannot select the file to “reattach” it to a recognition profile, you can add the customizations to a new script. The easiest way to do this is to create a new recognition scripts and open the old recognition script in a text editor such as Notepad. Then, you can cut-and-paste code from the old script to the new script. 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 FieldFormatting When Called Called for every field as every other field is exited. Allows the display of a field to differ from the stored value. Kofax Capture 10 Developer’s Guide 39 Chapter 3 Table 3-3. Field Script Events Events FieldPreProcessing FieldPostProcessing FormatFieldEventArgs PreFieldEventArgs PostFieldEventArgs When Called 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. This class represents the event arguments for the FieldScript.FieldPreProcessing event. This class represents the event arguments for the FieldScript.FieldPostProcessing event. 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 nonalphanumeric 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 40 Kofax Capture 10 Developer’s Guide Register the custom extension using one of the following: The Administration module. see Using the Kofax Capture Extension Registration Utility on page 57. Export connectors and runtime OCXs cannot be registered using the methods described in this chapter. which is run from a command line.aex) file is similar to that of a standard Windows . and workflow agents) must be registered with Kofax Capture before they can be used. For details. the custom extension registration file (the executable or DLL file). Kofax Capture Extension Registration Utility. For more information on export connectors.aex file must contain a header section labeled [Modules] that lists the display name of each custom module defined in the file. Alternatively you can have separate files for each custom extension. You can have a single file that contains information for all your custom modules. Custom module display names cannot exceed 32 characters.aex file) that defines the property settings for the custom extension. you must put the setup OCX information in the same registration file as the extension that uses it. Custom extension registration is a two-part process that requires you to do the following: Set up a registration file (. [Modules] Section To register one or more custom modules. setup OCX programs. The registration process is necessary so that Kofax Capture recognizes the custom extension as valid. Refer to Example Registration Files on page 50 for examples of registration files. Registration files offer you great flexibility.Creating an Export Connector. If you have a custom module or a workflow agent that requires a setup OCX. the . and the optional setup OCX must be saved to the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin). Refer to Format for the Registration File on page 41 for more information about the registration file. For details. workflow agents. see Using the Administration Module to Manage Extensions on page 54.Creating Custom Panels and Applications. or setup OCXs.Chapter 4 Creating a Registration File Introduction Custom extensions (custom modules. Format for the Registration File The format for the registration (. Prior to registration.ini file. see Chapter 9 . For more information on runtime OCXs see Chapter 7 . Kofax Capture 10 Developer’s Guide 41 . The registration file can contain sections as described below. an error will occur during registration. 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 Export module. The description displays in the Queues tab of the Create Batch Class and Batch Class Properties windows for the selected module. the . Note that some of the keys are required. errors will occur when you attempt to register a custom module.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. [Module Name] Section Keys Key Description Description Description of the purpose of the custom module.Chapter 4 Note Items listed in the [Modules] section can be registered with the Custom Module Manager available from the Administration module. If a required key is missing. If you do. Alternatively. Indicates the processing function that the custom module function must follow in the batch class workflow. you can set values for Follow and/or Precede or set a value for Function. Required Yes Follow No 42 Kofax Capture 10 Developer’s Guide . Each [Module Name] section can include the keys listed below. Maximum length is 250 characters. Table 4-1. they can be registered with the Kofax Capture Extension Registration Utility (RegAscEx. do not set a value for Function.exe) available from the Kofax Capture Bin folder. If you specify a value for Follow or Precede. Note that to specify proper queue ordering. [Module Name] Section For each custom module listed in the [Modules] section. The defined function is used to perform publish checks and to ensure proper queue ordering. This identifier must be unique across both custom modules and workflow agents. delimited by semicolons. you can set a value for Function or set values for the Follow and/or Precede keys. No No Required No ModuleID Yes Kofax Capture 10 Developer’s Guide 43 . errors will occur when you attempt to register a custom module. If you specify a value for Function. Maximum length for the icon file and path is 250 characters. [Module Name] Section Keys (continued) Key Function Description Specifies the function to be performed by the custom module. do not set Follow or Precede. Used to synchronize information about custom modules when data is exported and imported between databases. A semicolon and the numeric index of the desired icon in the file may optionally follow the path. If you do.Creating a Registration File Table 4-1. IconFile Path to a file containing the icon associated with the module name. Precede Indicates the processing function that the custom module function must precede in the batch class workflow. If you do. the module name will display without an icon. errors will occur when you attempt to register the custom module. you can set values for Follow and/or Precede OR set a value for Function. These Precede key values are valid: Document Separation Form Identification Automatic Index Validation Verification Full Text OCR Export (default value) Custom modules are not allowed to precede the Scan module. If you specify a value for Follow or Precede. Unique identifier for a custom module. Note that to specify proper queue ordering. 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. Maximum length is 250 characters. do not set a value for Function. If this property is not specified. the default icon for the RuntimeProgram file is used. One or more of the following functions may be specified. If no icon is found in either file. or omitting the key. This key applies only to custom standard modules.Chapter 4 Table 4-1. Specifies whether the custom module supports non-image files (eDocuments). Setting this key to True enables non-image file support for the custom module. [Module Name] Section Keys (continued) Key Runtime Command Line Runtime Program Description Specifies command line parameters that must be passed to the custom module’s runtime program when it is invoked from Batch Manager. Setting this key to False. Refer to [Setup] Section on page 47 for more information about defining [Setup] sections. Maximum length is 250 characters. This executable will be invoked when a batch in the ready state is selected in Batch Manager. causes the Batch Navigation toolbar to be available. No Required No Yes SupportsNon ImageFiles No SupportsTable Specifies whether the customization supports tables. Setting this key to True removes the toolbar. Setting this key to False or omitting the key disables nonimage file support for the custom module. The name of this section will also be the display name of the custom module. Setting this key to True removes the toolbar.aex file that defines the properties of the setup module for a custom module. The runtime executable for the custom module. Setting this key to False disables table support for the customization. or omitting the key. If not specified. Maximum length is 250 characters. Setting this key to False. the default setting is False. This key applies only to custom standard modules. Setting this key to False. Setting this key to True removes the panel. Setting this key to False. or omitting the key. This key applies only to custom standard modules. causes the Batch Filters toolbar to be available. SuppressBatch Specifies whether the custom standard module includes the Batch Filter Filters toolbar. SetupProgram Specifies a [Setup] Section within the . Setting this key to False. causes the Batch Thumbnails panel to be available. or omitting the key. Maximum length is 250 characters. This key applies only to custom standard modules. The executable must exist in the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin) for each workstation that will use it. No No 44 Kofax Capture 10 Developer’s Guide . This key applies only to custom standard modules. SuppressBatch Specifies whether the custom standard module includes the Batch Contents Contents panel. causes the Batch Contents panel to be available. causes the Batch Tools toolbar to be available. Setting this key to True removes the toolbar. Setting this key to True removes the panel. or omitting the key. SuppressBatch Specifies whether the custom standard module includes the Batch Thumbnails Thumbnails panel. Setting this key to True Fields enables table support for the customization. SuppressBatch Specifies whether the custom standard module includes the Batch Tools Tools toolbar. No No No SuppressBatch Specifies whether the custom standard module includes the Batch Navigation No Navigation toolbar. Suppress ImageViewer Specifies whether the custom standard module displays the Kofax Capture No Image Viewer. causes the Notes to be available. named “Kofax. the Recognition Server is able to generate the extended recognition data in the form of an XML string. causes the Image Tools toolbar to be available. if this value is not provided. or omitting the key. or omitting the key. Setting this key to False. By default. causes the Scan Controls Panel to be available. This key applies only to custom standard modules. Setting this key to False. Setting this key to True removes the panel. or omitting the key. 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”. 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. is “False. Setting this key to False. No No No Required No Kofax Capture 10 Developer’s Guide 45 . Kofax This key applies only to custom standard modules. or omitting the key.” A document-based custom storage string. Setting this key to True hides the image viewer. and a custom module has registered itself as using extended recognition information.AC. the Recognition Server does not output this XML data unless a custom module is registered that indicates a desire to use this it. If a batch class contains any custom module with this flag set to true. SuppressScan Controls Specifies whether the custom standard module includes the Scan Controls panel.0 UsesExtendedRecognitionInfo=True The default. Setting this key to False. This key applies only to custom standard modules. causes the image viewer to be visible.ExtendedRecognitionInfo” is used for the storage of extended recognition data. UsesExtended Recognition Info In order to enable communications between custom modules. “Kofax High Performance ICR Zonal”. Setting this key to True removes the panel.Creating a Registration File Table 4-1. This is because the extended recognition data could be very large and have a significant impact on performance and/or disk space.Sample Description=This Sample module supports nonimage files Version=1. then extended recognition information is generated in the Recognition Server. For Example: [Sample] RuntimeProgram=CMSample. [Module Name] Section Keys (continued) Key Suppress ImageTools Description Specifies whether the custom standard module includes the Image Tools toolbar. or the “Kofax Advanced OCR Zonal” engines.EXE ModuleID=Kofax. Maximum length is 250 characters. No Required No [Workflow Agents] Section To register one or more workflow agents. Maximum length is 250 characters. Specifies a [Setup] Section within the . or Kofax OCR) do not cause the generation of ExtIndexField elements within the string. Note Items listed in the [Workflow Agents] section can be registered with the Workflow Agent Manager available from the Administration module.Chapter 4 Table 4-1. If this property is not specified. If this property is not specified. no version number will display.ExtendedRecognitionInfo” custom storage string is never cleared.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.exe) available from the Kofax Capture Bin folder. Version Custom module version number assigned by the developer. they can be registered with the Kofax Capture Extension Registration Utility (RegAscEx. [Workflow Agent Name] Section For each workflow agent listed in the [Workflow Agents] section. no version number will display. [Workflow Agent Name] Section Keys Key Description SetupProgram Description Description of the purpose of the workflow agent.AC. the . Workflow agent version number assigned by the developer. even when the index value is changed.aex file must contain a header section labeled [Workflow Agents] that lists the display name of each workflow agent.dll that contains the Workflow Agent runtime COM server. The Recognition Server updates only those ExtIndexField elements where the corresponding index field value is updated. This is the .aex file that defines the properties of the setup program for a workflow agent. Each [Workflow Agent Name] section can include the keys listed below. Note The “Kofax. the . If a required key is missing. an error will occur during registration. Note that some of the keys are required. [Module Name] Section Keys (continued) Key UsesExtended Recognition Info (continued) Description Index Fields whose values are assigned by other means (such as OMR. Table 4-2. Alternatively. Workflow agent display names cannot exceed 32 characters. Required Yes No Version No WorkflowAgentFile Yes 46 Kofax Capture 10 Developer’s Guide . If a required key is missing. Required No Kofax Capture 10 Developer’s Guide 47 . Yes No Required Yes [Setup Programs] Section To register one or more setup OCXs. instead continuing with the default batch workflow. [Setup] Section For each item listed in the [Setup Programs]. an error will occur during registration. This identifier must be unique across both Workflow Agents and Custom Modules. Maximum length is 250 characters. Note that some of the keys are required. Multiple items must be delimited by semicolons.Creating a Registration File Table 4-2. [Module Name]. the system places the batch in error if it cannot load the runtime COM server on a particular station. If a setup program is listed in [Setup Programs]. the . By default. The name of the section is also the internal name of the menu (passed to the OCX on ActionEvents). WorkflowAgentProgID WorkflowAgentSkipIfCantLoad This is the runtime COM ProgID of the Workflow Agent. [Setup] Section Keys Key BatchClassMenus Description Names one or more [Menu] sections in the . Maximum length is 250 characters. Refer to [Setup] Section on page 47 for more information about defining [Setup] sections. or [Workflow Agent Name] sections.aex file must include a corresponding [Setup] section (labeled with the item name) that defines the setup program. include WorkflowAgentSkipIfCantLoad=true in the . with this flag set.aex file. Table 4-3.aex file that define the menu items to be added to the context menu for batch class nodes. 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. To set this flag. but not defined in its own [Setup] section.aex file must contain a [Setup Programs] section that lists the names of all [Setup] sections defined in the file. They cannot be registered from the Administration module. the system will not place the batch in error if the Workflow Agent does not exist. Each [Setup] section can include the keys listed below. However. [Workflow Agent Name] Section Keys (continued) Key WorkflowAgentID Description This value indicates a unique identifier for the Workflow Agent. the .exe) available from the Kofax Capture Bin folder. of the Setup OCX file. No No No InitSizeX InitSizeY MenuBarMenu The initial horizontal size of the panel in screen resolution No pixels. The minimum vertical size of the panel when undocked in screen resolution pixels. Multiple items are not allowed. <Kofax Capture installation folder>\Bin will be used. Same as BatchClassMenus. The initial vertical size of the panel in screen resolution pixels. except that it defines the menu items to add to the context menu for form identification zone nodes. The minimum horizontal size of the panel when undocked in screen resolution pixels. except that it defines the menu items to add to the context menu for index zone collection nodes. The default is 50. The default is 50. except that it defines the menu items to add to the context menu for index group zone nodes. Same as BatchClassMenus. Names one [Menu Bar] section that defines the tab to add to the Ribbon. 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 page level bar code nodes. If there is no path. except that it defines the menu items to add to the context menu for page level bar code collection nodes.Chapter 4 Table 4-3. No PageLevelBarcodesMenus No 48 Kofax Capture 10 Developer’s Guide . Same as BatchClassMenus. Required No FieldTypeMenus No FormIdZoneMenus No FormTypeMenus IndexGroupMemberZoneMenus No No IndexGroupMemberZonesMenus Same as BatchClassMenus. except that it defines the menu items to add to the context menu for index group zone collection nodes. Path. except that it defines menu items to add to the context menu for index zone nodes. Maximum length is 250 characters. [Setup] Section Keys (continued) Key DocumentClassMenus Description Same as BatchClassMenus. Same as BatchClassMenus. Same as BatchClassMenus. No No MinSizeX MinSizeY OCXFile No No Yes PageLevelBarcodeMenus Same as BatchClassMenus. The default is 50. Maximum length is 250 characters. except that it defines menu items to add to the context menu for form type nodes. including the file name. except that it defines the menu items to add to the context menu for field type nodes. The default is 50. IndexZoneMenus IndexZonesMenus Same as BatchClassMenus. [Setup] Section Keys (continued) Key ProgID RegistrationZoneMenus Description The COM program ID of the module specified with the OCXFile key. A [Menu] section has one required key. Table 4-4. This key is ignored when registering a custom module from the command line. [Menu Bar] Section Keys Key MenuBarText Description Display text for the tab. the panel will not be initially displayed and the DisplayName will not appear. If a key is missing. Required Yes [Menu Bar] Section For each Ribbon tab listed in a [Setup] section. A value of 1 indicates visible. If set to 0. the . 0 indicates invisible. except that it defines the menu items to add to the context menu for separation zone nodes. [Menu] Section Key Key MenuText Description Display text for the command. an error will occur during registration. Same as BatchClassMenus. except that it defines the menu items to add to the context menu for registration zone collection nodes. Maximum length is 250 characters. Each [Menu Bar] section must contain the keys listed below. Same as BatchClassMenus. The default is 1. Same as BatchClassMenus. Note that all keys are required. If the key is missing. an error will occur during registration. Required Yes Kofax Capture 10 Developer’s Guide 49 . except that it defines the menu items to add to the context menu for registration zone nodes. Same as BatchClassMenus.aex file must include a corresponding [Menu Bar] section (labeled with the tab name) that defines the tab. Required Yes No RegistrationZonesMenus No SamplePageMenus No SeparationZoneMenus No Visible No [Menu] Section A [Menu] section defines the text for a command listed in the [Menu Bar] and [Setup] sections. Table 4-5. except that it defines the menu items to add to the context menu for sample page nodes.Creating a Registration File Table 4-3. Setup Section OCXFile=XYZSetup. XYZ Index. Example 1: Registering Two Custom Modules The example registration file shown below specifies two custom modules: ABC Image Cleanup and XYZ Index.exe RuntimeCommandline=/k SetupProgram=XYZ Setup Description=The XYZ Index module automatically gathers index data Function=Automatic Index [XYZ Setup] .Module Name Section ModuleID=XYZ.IndexSetup InitSizeX=200 InitSizeY=100 Visible=1 BatchClassMenus=XYZ Batch Menu 1. The XYZ Index batch class context menu has two custom menu items: XYZ Properties and XYZ Reset to Default.ImageCleanup Version=1. but XYZ Index does. Multiple commands are delimited by semicolons. with two commands: XYZ Item 1 and XYZ Item 2.ico RuntimeProgram=XYZIndex. [Modules] . Required Yes Example Registration Files This section contains several examples that show the file structure for registration files.XYZ Batch Menu 2 50 Kofax Capture 10 Developer’s Guide .ocx ProgID=XYZCorp. Maximum length is 250 characters.” Comments are shown in bold text and are not part of the registration file. The Ribbon has a custom tab item. [Menu Bar] Section Keys (continued) Key Menus Description Names one or more [Menu] sections that define the commands to be added to this tab.Module Name Section ModuleID=ABC. ABC Image Cleanup does not have a custom setup module. By default the group will be called “Menu Items.exe Description=The ABC Image Cleanup module performs image enhancement [XYZ Index] . The name of the section is also the internal name of the tab (passed to the OCX on ActionEvents).Index IconFile=XYZ.Chapter 4 Table 4-5.Modules Section ABC Image Cleanup XYZ Index [ABC Image Cleanup] .0 RuntimeProgram=ABCImage. Kofax Capture 10 Developer’s Guide 51 .Menu Section MenuText=XYZ Item 1 [XYZ Bar Menu 2] .Menu Section MenuText=XYZ menu item 1 [XYZ Bar Menu 2] .Setup Programs Section Sample Setup [Sample Setup] .XYZ Bar Menu 2 [XYZ Bar Menu 1] . [Setup Programs] .XYZ Bar Menu 2 [XYZ Bar Menu 1] .Menu Section MenuText=XYZ Item 2 Example 2: Defining a Tab for the Ribbon The following custom module registration file (.Menu Section MenuText=XYZ Properties [XYZ Batch Menu 2] .Creating a Registration File MenuBarMenu=XYZ Menu Bar [XYZ Batch Menu 1] . 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.aex file) defines one tab for the Ribbon.Menu Bar Section MenuBarText=XYZ Index Menus=XYZ Bar Menu 1.Menu Section MenuText=XYZ menu item 2 Note The above example requires that SmpSetUp.Menu Section MenuText=XYZ Reset to Default [XYZ Menu Bar] .ocx be located in the C:\ folder.SmpSetUp Visible=1 MinSizeX=50 MinSizeY=50 InitSizeX=432 InitSizeY=351 MenuBarMenu=XYZ Menu Bar [XYZ Menu Bar] .Setup Section OCXFile=c:\SmpSetUp.ocx ProgID=SampleSetUp. Comments are shown in bold text and are not part of the registration file. including the name of the tab and two commands.Menu Bar Section MenuText=XYZ Index Menus=XYZ Bar Menu1. [Setup Programs] .Menu Bar Section MenuBarText=XYZ Index 52 Kofax Capture 10 Developer’s Guide .ocx ProgID=SampleSetUp.Setup Section OCXFile=c:\SmpSetUp.Setup Programs Section Sample Setup [Sample Setup] .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] .Chapter 4 Comments are shown in bold text and are not part of the registration file. Menu Section MenuText=I show up on the Form&Id tree node [FieldType 1] .XYZ Bar Menu 2 [XYZ Bar Menu 1] .Menu Section MenuText=XYZ menu item 1 [XYZ Bar Menu 2] .Menu Section MenuText=I show up on the &DocClass tree node [FormType 1] .Menu Section MenuText=XYZ menu item 2 [BatchClass 1] .dll Kofax Capture 10 Developer’s Guide 53 . [Workflow Agents] – Workflow Agents Section Validation Workflow Agent [Validation Workflow Agent] – Workflow Agent Name Section WorkflowAgentID=Kofax.Menu Section MenuText=I show up on the Separation &Zones tree node [RegZone 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 &FieldType tree node [PLB 1] .Menu Section MenuText=I show up on the &SamplePage tree node [Separation 1] .Menu Section MenuText=I show up on the Group&Parent tree node [GroupMember 1] .Menu Section MenuText=I show up on the &Index Zones tree node [PLBs 1] .Creating a Registration File Menus=XYZ Bar Menu 1.AgentWithOCX WorkflowAgentProgID=WFAgent.Menu Section MenuText=I show up on the &FormType tree node [SamplePage 1] .Menu Section MenuText=I show up on the Regzon&es tree node [GroupParent 1] .Menu Section MenuText=I show up on the &BatchClass tree node [DocClass 1] .Menu Section MenuText=I show up on the &Index Zone tree node [FormId 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.SampleWorkflowAgent WorkflowAgentFile=WFAgent.Menu Section MenuText=I show up on the &Reg Zone tree node [IndexZone 1] .Menu Section MenuText=I show up on the Page level bar code pare&nt tree node [Regzones 1] . Comments are shown in bold text and are not part of the registration file. click the Add button. Using the Administration Module to Manage Extensions You can use the Administration module to register custom modules and workflow agents.. which is explained in Using the Kofax Capture Extension Registration Utility on page 57. From the Custom Module Manager window. The custom module(s) listed in the [Modules] section of the .aex file will display in the Custom Modules window. From the Open window.aex file associated with the custom module you want to register.. 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 (.Menu Section MenuText=Validation &Workflow Properties. Click Open.5 SupportsNonImageFiles=True SetupProgram=Workflow Agent Setup [Workflow Agent Setup] – Setup Section OCXFile=SampleWorkflowOcx.aex) file for the custom extension To register a custom module with the Custom Module Manager 1 2 3 4 Start the Administration module. browse to Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin) and select the . From the Tools tab. you must use the Kofax Capture Extension Registration Utility. in the System group. Registering a Custom Module Before registration. Version=7. click Custom Modules. The Custom Module Manager window will display.Chapter 4 Description=This sample workflow agent is combined with a setup OCX. Managing Custom Modules The following procedures cover registering and removing custom modules. Note You cannot use the Administration module to register setup OCXs. You can also use the command line registration utility. 5 54 Kofax Capture 10 Developer’s Guide .ocx ProgID=SampleWorkflowOcx.SampleWorkflow Visible=0 MinSizeX=300 MinSizeY=150 BatchClassMenus=Workflow Agent Test Menu [Workflow Agent Test Menu] . Select the name of the custom module to be removed. you can view the location of the runtime file for the module. The properties are listed for reference purposes only. 5 Kofax Capture 10 Developer’s Guide 55 . Click OK to clear the message. From the Tools tab. Removing a Custom Module You can use the Administration module to remove or “unregister” a custom module from Kofax Capture. If the selected custom module is not used in any published batch class. you can view the functions defined for the custom module. The “Follow” entry lists the processing function that the custom module function must follow. Click Close. The settings are based on the information defined in the . Viewing Properties for a Custom Module The Custom Module Properties and Workflow Agent Properties windows list all of the registered settings for the selected application. you cannot edit them. From this tab. The Advanced tab also lists the valid processing order that is allowed for the custom module function. Click the Advanced tab. From the General tab. 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 windows. choose a custom module and click the Properties button. along with the location of the optional setup program. The “Precede” entry lists the function that the custom module must precede. The name of the newly registered module(s) will appear in the Custom Module Manager window. Also. Otherwise. 2 3 Click the Programs tab. you must ensure that it is not used in any published batch class. From this tab. in the System group. Kofax Capture will prevent you from removing it. you can view information that describes the custom module. The selections for Follow/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 windows. The Custom Module Manager window will display. Click Remove. A confirmation message will appear to inform you when the registration is successful. and then click Close to exit the Custom Modules window.Creating a Registration File 6 7 Select the name of the module(s) you want to register and click Install. Before removing the custom module. it will be cleared from the list. To view properties for a custom module 1 From the Custom Module Manager window.aex file for the custom extension. The Custom Module Manager will not allow you to remove a custom module that is used by any batch classes. To remove a custom module 1 2 3 4 Start the Administration module. The Custom Module Properties window will display. click Custom Modules. aex file will display in the Workflow Agents window. The workflow agent(s) listed in the [Workflow Agents] section of the . 6 7 Select the name of the workflow agent(s) you want to register and click Install. The name of the newly registered agent(s) will appear in the Workflow Agents Manager window. To view properties for a workflow agent 1 From the Workflow Agent Manager window. From this tab. Click OK to clear the message. in the System group. The properties are listed for reference purposes only. along with the location of the optional setup program. Registering a Workflow Agent Before registration. 5 56 Kofax Capture 10 Developer’s Guide . browse to the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin) and select the . and then click Close to exit the Workflow Agents window. click the Add button. Click Open. From the Workflow Agent Manager window. A confirmation message will appear to inform you when the registration is successful. From the General tab. From the Tools tab. Also. you can view information that describes the workflow agent. The Workflow Agent Manager window will display. you can view the location of the runtime file for the module. 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 (. choose a workflow agent and click the Properties button. Viewing Properties for a Workflow Agent The Workflow Agent Properties windows list all of the registered settings for the selected workflow agent.aex) file for the custom extension To register a workflow agent with the Workflow Agent Manager 1 2 3 4 Start the Administration module. From the Open window.Chapter 4 Managing Workflow Agents The following procedures cover registering and removing workflow agents. you cannot edit them. click Workflow Agents.aex file. The Workflow Agent Properties window will display.aex file associated with the workflow agent you want to register. 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 windows. 2 Click the Programs tab. The settings are based on the information defined in the . If any invalid or incomplete parameters are specified. RegAscEx. 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. workflow agents. and the optional setup OCX must be saved to the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin). the . Kofax Capture will prevent you from removing it. Before removing the workflow agent.exe) is a standalone console application that registers and unregisters custom modules. Otherwise. 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. this utility is an alternative to the windows that are available from the Administration module.aex file. For custom modules and workflow agents. you will be prompted with the correct usage. Prior to registration. it will be cleared from the list. Click Remove. executable file. To remove a workflow agent 1 2 3 4 5 Start the Administration module. Click Close. Using the Kofax Capture Extension Registration Utility The Kofax Capture Extension Registration Utility (RegAscEx. Select the name of the workflow agent to be removed. If you launch the Administration module prior to using the command line to register the custom module. and is controlled completely via command line parameters. If the selected workflow agent is not used in any published batch class. the custom module should display as expected.exe resides in the Kofax Capture Bin folder. as shown in Figure 4-1. The Workflow Agent Manager window will display. an output file. Command Line Parameters The utility supports several command line parameters to specify which custom extensions are to be registered or unregistered. From the Tools tab. you also can incorporate the registration process into the custom extension installation program. in the System group. With the registration utility. you must ensure that it is not used in any published batch class. and silent mode operation. Kofax Capture 10 Developer’s Guide 57 .Creating a Registration File Removing a Workflow Agent You can use the Administration module to remove or “unregister” a workflow agent from Kofax Capture. click Workflow Agents. You can find this utility in <Kofax Capture installation folder>\Bin. This happens because the Administration module hides the custom panel if it is launched after you register the custom panel. and setup OCXs. rather than the default behavior of processing all Kofax Capture extensions in the input file.log Module Name [/m {module name}] You may optionally specify a single custom module from the input file that should be registered or unregistered. Refer to Format for the Registration File on page 41 for more information about the .aex /r “Runtime OCX” 58 Kofax Capture 10 Developer’s Guide . The /r flag is followed by the runtime program name enclosed in quotation marks. rather than the default behavior of processing all Kofax Capture extensions in the input file.aex (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. The messages are output to the file and to the default display of the console.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. 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 ACWflowAgnt. as in the following example: RegAscEx /f custom. Only the specified setup program will be processed. rather than the default behavior of processing all custom modules in the input file. 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 workflow agent will be processed. Only the specified runtime program will be processed.aex file. The /m flag is followed by the custom module name enclosed in quotation marks. Output File [/o {filename}] You may optionally specify an output file where all messages and statuses will be recorded.aex (for a custom module and/or workflow agent) RegAscEx /f SetupOCX.aex /w “Validation Workflow Agent” Setup Programs [/x {setup program name}] You may optionally specify a single setup program from the input file that should be registered or unregistered.aex /o output. The /w flag is followed by the workflow agent name enclosed in quotation marks.Chapter 4 Input File [/f {filename}] You must specify an . as in the following example: RegAscEx /f custom.aex filename. The /f flag is followed by the . as in the following example: RegAscEx /f RuntimeOCX. The /o flag is followed by the output filename. Only the specified custom module will be processed. as in the following examples: RegAscEx /f custom.aex file that contains the registration settings for one or more custom extensions to be registered or unregistered in the Kofax Capture database. as in the following example: RegAscEx /f custom. If the /w parameter is also used. that file will still be generated with all output messages. Subsequent sections itemize the properties for each custom extension to be registered. only the specified setup program will be unregistered. The following examples assume that silent mode operation (using the /s command line parameter) has not been specified. If the /x parameter is also used.aex file will be unregistered. Kofax Capture 10 Developer’s Guide 59 .aex /u If the /m parameter is also used.aex file is documented in Format for the Registration File on page 41. This message will be followed by a list of up to 10 batch classes that use the custom extension. Output This section contains messages that may be displayed by the Kofax Capture Extension Registration Utility. Console messages will also appear in the output file if they are specified using the /o command line parameter.aex /s If an output file is specified using the /o parameter. as follows: <Application Name> is being used by the following batch classes and cannot be removed. It defines each of the supported command line parameters and provides an example for formatting the command line. the first nine will be listed.” 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. If any batch class is using a custom extension.aex file. the application cannot be unregistered. followed by the phrase “and more. only the specified custom module will be unregistered. you can use the following to display information about proper usage: RegAscEx /? Input The exact format of the . as in the following example: RegAscEx /f custom.Creating a Registration File Unregister [ /u ] You may optionally use the /u flag to unregister one or more custom modules in the Kofax Capture database. The Kofax Capture Extension Registration Utility verifies the values for the properties that are required in the . A warning message will be displayed. all custom extensions specified in the . only the specified workflow agent will be unregistered. If more than 10 batch classes are detected. For example. Otherwise. Usage [ /? ] The “/?” parameter displays the proper usage of the registration utility to the console. The file contains a header section that lists the name of each custom extension to be defined. If an invalid parameter is specified or a required parameter is missing. the valid parameter information will be displayed.Chapter 4 Proper Usage If you call the Kofax Capture Extension Registration Utility with the “/?” parameter or specify an invalid command line parameter. Figure 4-1. as shown in Figure 4-1. 60 Kofax Capture 10 Developer’s Guide . the proper usage prompt is also displayed. an error or warning message is displayed to explain the problem. Kofax Capture Extension Registration Utility Output Error and Warning Messages If the utility fails to register or unregister a custom extension. and register a workflow agent to customize your Kofax Capture process. When designing the workflow agent. install.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. This chapter describes how you can create. 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. restrict access to a batch in certain modules.NET is provided later in this chapter. a setup OCX will be needed.Chapter 5 Creating a Workflow Agent Introduction A workflow agent is a custom application that you can create to examine and modify batch data. An example workflow agent written in Visual Basic . Workflow agents are attached at the batch class level and invoked whenever a batch is closed from a module. 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 . change the routing of a batch.) 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. and obtain the status of a batch. Kofax Capture 10 Developer’s Guide 61 . 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.NET Framework 3. the . If it is not already installed.NET Framework 3. The example workflow agent provided later in this chapter is written in Visual Basic .dll) The workflow agent COM class must implement the IACWorkFlowAgent interface.ACWFLib. a setup OCX should be considered. you are ready to code your application. 62 Kofax Capture 10 Developer’s Guide .NET.5 is installed by either Kofax Capture or Visual Studio 2008. When creating the setup OCX. Kofax. Refer to Chapter 6 – Creating a Setup OCX for more information about coding a custom setup OCX. These properties will be available only for batch classes that are assigned the workflow agent. the following must be set: The workflow agent must be a registered COM server. panels.Interop. Code Project Settings When generating your Visual Basic project. or context menus. The code project must reference the Kofax Capture . but if your workflow agent requires configuration prior to running. Writing the Runtime Module Now that you’ve determined the purpose of your custom workflow agent and defined it’s functions and goals.5 installed in your development environment.NET Interop library (in this case. You can write a workflow agent using any of the following supported programming languages and development environments: 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 You will also need the .Chapter 5 Implementing the Setup OCX A setup OCX for the workflow agent is optional. This menu item will enable the administrator to specify whether or not the workflow agent will check for even-numbered page deletion. References a setup OCX. custom panel.0 | API Reference Guide. and a page note is added indicating that the page should not have been marked for deletion. which deletes the even-numbered pages that are marked for deletion. These incorrectly marked pages are reset. Referencing the Kofax Capture API Libraries The example custom workflow agent will use the objects. 5 6 Kofax Capture 10 Developer’s Guide 63 . Provides a custom panel that the operator uses to mark even-numbered pages for deletion. refer to the Kofax Capture API Reference Guide in the Kofax Capture Documentation CD or access the guide by selecting Start | Programs | Kofax Capture 10. This example application: Ensures that only even-numbered pages are deleted. which adds a new menu item to the Batch Class context menu. and sections of the code that performs certain functions are described. Has the workflow agent check the pages of the batch for odd-numbered pages that were incorrectly marked for deletion. and properties defined in the following API libraries: Kofax Capture Custom Workflow Interface (ACWFLib.dll) Set your Visual Basic project to reference these libraries. which shows that the pages were reset.dll) and the Kofax Capture Optimized Custom Module API (DBLiteOpt. custom setup OCX for the workflow agent. the batch is sent to Quality Control. Has a batch for the batch class created and scanned. methods.Creating a Workflow Agent The workflow agent application named DeletePageWFA is used as an example later in this chapter. The comprehensive example 1 2 3 4 Uses a workflow agent setup OCX that enables the administrator to decide whether evennumbered pages are to be removed for a specified batch class.dll) Kofax Capture Optimized Custom Module API (DBLiteOpt. and custom module. Runs the custom module.dll). Displays the Quality Control module. If odd-numbered pages are marked for deletion. The example code for the setup OCX is provided and described in Chapter 6 – Creating a Setup OCX. For more information about the Kofax Capture Workflow Library (ACWFLib. 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. the subroutine is exited. and Chapter 8 – Creating a Custom Module. 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 64 Kofax Capture 10 Developer’s Guide . This line of code (shown in bold below) should be placed near the beginning of the DeletePageWFA application.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. or suspended. however. the code for the setup OCX. the subroutine is exited. and flagged with a page note indicating that the page is not to be deleted.ACWFLib.DBLiteOpt Public Class Agent Implements Kofax. custom panel. respectively. rejected. Inherit the IACWorkflowAgent Interface Make sure that you have the line of code in your custom application that implements the IACWorkflowAgent interface. If so. This subroutine is called whenever a batch is closed. 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.ACWFLib Imports Kofax. Odd-numbered pages that are marked for deletion are reset. A check is also made whether the batch is being suspended or if the batch is in error. sent to Quality Control. Chapter 7 – Creating Custom Panels and Applications. 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. Workflow Agent Program The purpose of the example custom workflow agent is to ensure that only even-numbered pages are marked for deletion.Chapter 5 The code for the example workflow agent is provided in this section. If it isn’t. The workflow agent application (DeletePageWFA) includes the major functions outlined below. and the custom module are provided and described in Chapter 6 – Creating a Setup OCX. Imports Kofax. CurrentModule.Name = "Scan" Then '*** Extract the Runtime DataElement Dim oRTElem As ACDataElement oRTElem = oWorkflowData. 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.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 Dim oPageElem As ACDataElement For Each oPageElem In _ oPagesElem.ACWFLib.ACWFLib. lngPageCount) Next oPageElem Kofax Capture 10 Developer’s Guide 65 . (That is.AttributeValue("BatchClassName") '*** Get the Pages elem Dim oPagesElem As ACDataElement oPagesElem = oBatchElem.ExtractRuntimeACDataElement(0) '*** Extract the Setup DataElement m_oSetupDataElement = _ oWorkflowData. The ProcessWorkflow function code segment follows: Public Sub ProcessWorkflow(ByRef oWorkflowData As _ Kofax.ProcessWorkflow '*** Let's make sure we are leaving Scan If oWorkflowData.ACWorkflowData) Implements _ Kofax.Creating a Workflow Agent Iterate Through the Documents A segment of the code Determines whether the pages should be checked._IACWorkflowAgent.FindChildElementByName("Batch") '*** Set the Batch Class Name m_strBatchClassName = _ oBatchElem.ExtractSetupACDataElement(0) '*** Get the Batch element Dim oBatchElem As ACDataElement oBatchElem = oRTElem.FindChildElementsByName("Page") '*** Increment the Page count lngPageCount = lngPageCount + 1 '*** Check the page to make sure it should be deleted CheckPage(oPageElem. 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. m_strBatchClassName) '*** Get the BatchClassCustomStorageStrings Dim oBatchClassCSSs As ACDataElement oBatchClassCSSs = _ oBatchClassElem. Private Function IsCheckPagesEnabled() As Boolean Try '*** Get the BatchClasses element Dim oBatchClassesElem As ACDataElement oBatchClassesElem = _ m_oSetupDataElement.FindChildElementByName _ ("BatchClassCustomStorage Strings") '*** Get the CheckEvenPageDelete custom storage string Dim oCheckEvenPageCSS As ACDataElement oCheckEvenPageCSS = _ oBatchClassCSSs. _ "CheckEvenPageDelete") '*** Make sure we have a reference If Not oCheckEvenPageCSS Is Nothing Then '*** Check the value Return (oCheckEvenPageCSS.FindChildElementByAttribute _ ("BatchClassCustomStorageString". _ "Name".FindChildElementByAttribute("BatchClass".AttributeValue("Value") = "True") End If Catch ex As Exception '*** Just return false Return False 66 Kofax Capture 10 Developer’s Guide .Chapter 5 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.FindChildElementByName("BatchClasses") '*** Get the BatchClass element Dim oBatchClassElem As ACDataElement oBatchClassElem = _ oBatchClassesElem. "Name". _ ByVal lngPageNumber As Long) '*** Check if this is an odd page If (lngPageNumber Mod 2) = 1 Then '*** Check if we have the DeletePage CSS Dim oDeletePageCSS As ACDataElement oDeletePageCSS = oPageElem. oDeletePageCSS. Private Sub CheckPage(ByRef oPageElem As ACDataElement.Creating a Workflow Agent End Try End Function CheckPage Subroutine The CheckPage subroutine checks if a page is odd-numbered and marked for deletion. Once registered. the value is reset to “False. "Name". "DeletePage") '*** Make sure we have a reference If Not oDeletePageCSS Is Nothing Then '*** We don't want to delete odd pages.. the workflow agent is recognized as valid for a processing queue and can be attached to any Kofax Capture batch class. If it is. Compile the entire workflow agent code and register it as instructed in the next section.AttributeValue("Value") = "False" '*** Set the Page Note to say that we reset the flag oPageElem.you're not supposed to do that!" End If End If End Sub Creating the Registration File A workflow agent must be registered with Kofax Capture before it can be used.FindChildElementByName _ ("PageCustomStorageStrings").FindChildElementByAttribute _ ("PageCustomStorageString".AttributeValue("Note") = "The DeletePage flag _ was reset.” and a page note is added to indicate that the page should not be deleted because it is an odd-numbered page. Clear the value.. Kofax Capture 10 Developer’s Guide 67 . Format of the Registration File The format for the registration (. [Workflow Agents] Delete Page Workflow Agent [Delete Page Workflow Agent] WorkflowAgentID=KPSG.SetupControl Visible=0 The registration file (DeletePageWFA.Chapter 5 The workflow agent registration is a two-part process that requires you to do the following: Set up a workflow agent registration (. Version=8.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 68 Kofax Capture 10 Developer’s Guide . If you have a workflow agent that uses a setup OCX. 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.dll ProgID=DeleteEvenPageSetup.aex) for the example workflow agent program.Agent WorkflowAgentFile=DeletePageWFA. you must have Administrator privileges in order to install files to the Kofax Capture installation folder.aex) file is similar to that of a standard Windows .0 SupportsNonImageFiles=True SetupProgram=Delete Even Page Setup [Delete Even Page Setup] OCXFile=DeleteEvenPageSetup.DeletePageWFA WorkflowAgentProgID=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 (.ini file. The following is the registration file (DeletePageWFA. you must put the setup OCX information in the same registration file as the extension that uses it.dll Description=This workflow agent makes sure that odd pages are not deleted.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. From the Open window. click Workflow Agents.aex file associated with the workflow agent you want to register. To register a setup OCX that is associated with a custom extension 1 Copy the setup OCX. Select the name of the workflow agent you want to register and click Install. make sure that you have placed the following files in the <Kofax Capture installation folder>\Bin folder. The Workflow Agent Manager window will display. however. Click OK to clear the confirmation message.aex) file to the <Kofax Capture installation folder>\Bin folder on each workstation that runs the Administration module or the custom extension. Registering the Workflow Agent from the Administration Module To register the workflow agent from the Administration module 1 2 3 4 5 6 In the Administration module. (Alternatively. Registering the Setup OCX Having a setup OCX for your workflow agent is optional. A confirmation message will display when the registration is successful. Click Open. if a setup OCX is implemented. on theTools tab.) 2 To register a setup OCX that is not associated with a custom extension 1 2 3 Copy the registration (.aex> Installing and Registering the Workflow Agent This section provides instructions for installing and registering a workflow agent. Register the setup OCX with the Custom Module Manager or Workflow Agent Manager available from the Administration module. click Add. browse to the <Kofax Capture installation folder>\Bin folder and select the .aex file will display in the Workflow Agents window. custom extension files. The workflow agent listed in the Workflow Agents section of the . 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 windows. in the System group.aex file. Before registration. 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. you can use the Kofax Capture Extension Registration Utility.aex) file to the <Kofax Capture installation folder>\Bin folder Copy the setup OCX to the location specified by the . it must be registered before it can be used. Kofax Capture 10 Developer’s Guide 69 . From the Workflow Agent Manager window. and registration (. read Chapter 4 – Creating a Registration File. and then click Close to exit the Workflow Agent Manager window.Creating a Workflow Agent For more information about the registration file. If the selected workflow agent is not used in any published batch class. Removing the Workflow Agent You can use the Administration module to remove or “unregister” a workflow agent from Kofax Capture. The workflow agent is added to the Selected Workflow Agents list.Workflow Agent tab. on theTools tab. The workflow agent is displayed in the Workflow Agent Manager window. in the System group. Before removing the workflow agent.aex file for the custom workflow agent. select the workflow agent and click Install. Click Close. click Workflow Agents.Chapter 5 Note If you are customizing Kofax Capture under the Windows Vista operating system. it will be cleared from the list. Browse to the . Otherwise. 70 Kofax Capture 10 Developer’s Guide . To install and register the workflow agent 1 2 3 4 5 6 7 In the Administration module. click Workflow Agents. Click Close. Click OK to save your changes and exit the Batch Class Properties window. Kofax Capture will prevent you from removing it. and click Open. To remove a workflow agent 1 2 3 4 In the Administration module. select the desired workflow agent and click Add. Select the name of the workflow agent to be removed. you must have Administrator privileges in order to install files to the Kofax Capture installation folder. in the System group. The Workflow Agent Manager window will display. you must ensure that it is not used in any published batch class. select the file. From the Batch Class Properties . From the Workflow Agents window. Click OK. The Registration complete message is displayed if the registration was successful. Click Remove. on theTools tab. A setup OCX without an associated custom extension allows you to customize the batch class set up process for all batch classes. The example setup OCX is part of the comprehensive example for this guide. Kofax Capture 10 Developer’s Guide 71 . This chapter describes how to design. With a setup OCX. 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. The example setup OCX that is provided in this chapter is written in VB . Writing a Setup OCX The supported programming languages and development environment for creating a setup OCX are the same as with workflow agents. Designing the Setup OCX Determine whether a setup OCX is necessary for your custom extension. and the behavior of setup OCX panels and tabs. 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. See the topic Writing the Runtime Module on page 62 for the supported development environments. configuration settings. 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 commands defined in the setup OCX are available only for batch classes that contain the workflow agent. it is likely that you will want to use a custom setup OCX. A setup OCX can be associated with a custom extension (such as a custom module or custom workflow agent). create. Items defined in the setup OCX are available for all batch classes. you can define custom tabs. and register a setup OCX.Chapter 6 Creating a Setup OCX Introduction You can implement a setup OCX to customize batch class setup options. how a setup OCX is loaded and unloaded with the Administration module. The user interface and commands defined in the setup OCX are available only for batch classes that contain the custom module. and publish checks. While it is possible to use the standard configuration settings and publish checks available from the Administration module with a custom extension.NET and is associated with the example workflow agent provided in Chapter 5 – Creating a Workflow Agent. #End Region Private Const cm_strDEPSetup As String = "DEPSetup" Private Const cm_strDEPSetupText As String = "Delete Even Page _ Setup" 72 Kofax Capture 10 Developer’s Guide .dll) Kofax Capture . is not included here. which is generated by VB . It allows the administrator to enable the workflow agent to check for even-numbered page deletion. enables the administrator to determine whether a check for even-numbered page deletion is to be enforced and to configure that option through the Batch Class context menu. a Delete Even Page Setup window is displayed. SetupControl Public Class SetupControl Inherits System. Code Project Settings To generate the VB.NET.dll) Example Setup OCX for the Custom Workflow Agent The example setup OCX is part of the comprehensive custom extension example. 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 window. ensure that the following libraries are referenced in your Visual Basic project: Kofax Capture Admin Module Type Library (ACAdMod. This setup OCX for the custom workflow agent. Kofax. When the DeleteEvenPage option is chosen from the context menu of the Batch Class. NET project for the setup OCX. The setup OCX generates the context menu.NET Interop libraries (in this case.UserControl #Region " Windows Form Designer generated code " '***This segment of code. Right-click the Batch Class in the Batch tree view tab to view the context menu that is associated with the workflow agent setup OCX.Interop. The code segments are listed below.AscentCaptureAdminMod. 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. Setup OCX for the Workflow Agent The workflow agent setup OCX (DeleteEvenPageSetup) is written in VB .Chapter 6 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.Windows.Forms. which is described in Chapter 5 – Creating a Workflow Agent. Details about the example setup OCX is provided later in this chapter in Example Setup OCX for the Custom Workflow Agent on page 72.NET for the '***form. AscentCaptureAdminMod.AscentCaptureAdminMod.KfxOcxEvent.Creating a Setup OCX '*** Reference to the AdminApplication object Private m_oAdminApplication As _ Kofax.AdminApplication Set(ByVal Value As _ Kofax.AscentCaptureAdminMod.ActiveBatchClass) '*** Unload the Form oSetupForm = Nothing End If End If End Sub Private Sub InitializeMenu() m_oAdminApplication. _ cm_strDEPSetupText. "BatchClass") End Sub End Class Kofax Capture 10 Developer’s Guide 73 . ByRef _ oArgument As Object. ByRef nCancel As Integer) '*** Check the event number If nEventNumber = _ Kofax.ShowSetupDialog(m_oAdminApplication.AddMenu(cm_strDEPSetup.AdminApplication Public WriteOnly Property Application() As _ Kofax.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.AscentCaptureAdminMod.AdminApplication) '*** Cache the object m_oAdminApplication = Value '*** Initialize the menu InitializeMenu() End Set End Property Public Sub ActionEvent(ByVal nEventNumber As Integer. Forms.Chapter 6 SetupForm Imports Kofax.Windows.NET for the '***form. "False") End Sub Private Function GetBatchClassCSSSafe(ByVal strName _ As String) As String 74 Kofax Capture 10 Developer’s Guide . "True".CustomStorageString _ (cm_strCheckEvenPageDeleteCSS) = IIf(blnEnabled. is not included here.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.AscentCaptureAdminMod Public Class SetupForm Inherits System. #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.ShowDialog() '*** Save the settings Call SetEvenPageEnabled(chkCheckPages. which is generated by VB .Checked = IsCheckEvenPageEnabled() '*** Show the dialog (modal) Me.Form #Region " Windows Form Designer generated code " '***This segment of code. 2 To register a setup OCX that is not associated with a custom extension 1 2 3 Copy the registration (. you can use the Kofax Capture Extension Registration utility.aex) file and using the Kofax Capture Extension Registration utility.aex file. Alternatively.Hide() End Sub End Class Registering a Setup OCX Follow the procedures below to register your setup OCX.CustomStorageString(strName) Exit Function trap: GetBatchClassCSSSafe = "" End Function Private Sub cmdOK_Click() '*** Simply hide the form Me. Register the setup OCX with the Custom Module Manager or Workflow Agent Manager available from the Administration module. you must have Administrator privileges in order to install files to the Kofax Capture installation folder.Creating a Setup OCX On Error GoTo trap GetBatchClassCSSSafe = _ m_oBatchClass. custom extension files. Register the setup OCX with the Kofax Capture Extension Registration utility.aex) file to the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin). for details about creating the 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. To register a setup OCX that is associated with a custom extension 1 Copy the setup OCX. Refer to Chapter 4 – Creating a Registration File. Note the listing of the OCX file and ProgID in the workflow agent registration file in Format of the Registration File on page 68. Kofax Capture 10 Developer’s Guide 75 . Because the example setup OCX is associated with a workflow agent. Copy the setup OCX to the location specified by the . Note If you are customizing Kofax Capture under the Windows Vista operating system. the registration file for the workflow agent is also used to register the setup OCX. and registration (. Minimum vertical size of the panel when undocked in screen resolution pixels. The COM ProgID of the OCX. 0 (zero) indicates the setup OCX is used by a custom extension. the panel will not be initially displayed and the DisplayName will not appear. The setup OCX registry key values are listed in Table 6-1. The default is 50. The default is 50. and it also appears when the panel is undocked. {Value Name} is the name of the key value that was omitted. 1 indicates the setup OCX is not used by a custom extension. The Visible value determines whether or not the DisplayName appears. 76 Kofax Capture 10 Developer’s Guide . Where: {User Defined Key} is the registry key under “User Panels” causing the error. The default is 1. registry keys must be created on that computer to inform the Administration module how the OCX is loaded. Minimum horizontal size of the panel when undocked in screen resolution pixels. The default is 0.0” is intentional. The default is 50.0\Ascent Capture – Administration\User Panels\ Note The registry key path reference to “\Ascent Capture\3. The initial vertical size of the panel in screen resolution pixels. InitSizeX InitSizeY MinSizeX MinSizeY ProgID Type No No No No Yes Yes DWORD DWORD DWORD DWORD String DWORD Visible No DWORD If any of the required registry values are omitted when the Administration module attempts to load a setup OCX. If set to 0. The default is 50. Table 6-1. 0 (zero) indicates not visible.Chapter 6 Setup OCX Registry Entries After a setup OCX is installed on a client computer. the following error is reported: User defined OCX “{User Defined Key}” contains an invalid registry value for {Value Name}. This name is displayed on the View tab in the Panels group. Setup OCX Registry Key Values Value DisplayName Required? Yes Type String Description The display name of the panel. 1 indicates visible. The initial horizontal size of the panel in screen resolution pixels. Registry keys that define the Administrative module setup OCX are automatically created under the following path during the registration process: HKEY_LOCAL_MACHINE\Software\Kofax Image Products\Ascent Capture\3. and what tabs should be created. The application will shut down in this case. but the OCX cannot be loaded for some reason. Tab Registry Key Value Value Text Required? Yes Type String Description The display nameof the command. The value is ignored. Kofax Capture 10 Developer’s Guide 77 . To add a command to a tree node: BatchClass DocumentClass FieldType FormIdZone FormType IndexGroupMemberZone IndexGroupZoneCollection IndexZone PageLevelBarcode PageLevelBarcodeCollection RegistrationZone RegistrationZoneCollection SamplePage SeparationZone To add a tab to the Ribbon: MenuBar Commands are created by adding keys under the keys that are listed above. Table 6-2. The name of the key is the internal name for that command. The keys registered under “Menus” define the tabs for that OCX. Also. Where: {Value Name} is the name of the value. {Details} indicates the error number or error description. If a registry key is properly constructed. and program execution will continue. you can specify the value listed in Table 6-2. the Administration module will report the following error: Unable to create user defined OCX {DisplayName}({Details}). The following key names are valid. {DisplayName} is the value data for the DisplayName value. Keys defined directly under “Menus” dictate the location of a command.Creating a Setup OCX 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: {DisplayName} is the value data for the DisplayName value. Tab Registry Keys Each panel registry key should have a key entitled “Menus” under it. the command will not be added. Table 6-3. docking status. size. and if the setup OCX has been registered. Note that if your setup OCX is associated with a custom extension. a message specifying the name of the custom module that must be registered is displayed. If this value is omitted. make certain that your setup OCX is installed to <Kofax Capture installation folder>\Bin. A setup OCX that is not associated with a custom extension must be registered with the Kofax Capture Extension Registration utility. If this kind of message displays. The first time the setup OCX is loaded. Note Refer to Chapter 4 – Creating a Registration File. If you register the setup OCX while the Administration module is running. While the Administration module is running. if the setup OCX has been registered.aex file used for registration. the tabwill not be displayed. If the setup OCX is registered with the Kofax Capture Extension Registration utility. You are prompted to open the Custom Module Manager to register the setup OCX. and visibility used in the previous instance of the Administration module. the OCX is loaded: When the Administration module is launched. for more information about registering custom extensions and setup OCXs. the setup OCX will load the next time the Administration module is launched. When a setup OCX is loaded again. 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. it appears undocked with other display characteristics as defined in the registry settings for the OCX. Note Setup OCXs that are not associated with a custom extension must reside in the location specified in the . it assumes the same location. For details. and the setup OCX files are not available in the Kofax Capture Bin folder when the Administration module launches. see Setup OCX Registry Entries on page 76. MenuBar Registry Key Value Value Text Required? Yes Type String Description The display name of the tab. Then. if the setup OCX is registered from the Administration module. The MenuBar key is a special case. the setup OCX will load the next time the Administration module is launched. 78 Kofax Capture 10 Developer’s Guide . click OK to register the missing setup OCX. If the setup OCX is not associated with a custom extension. the OCX is loaded: When the Administration module is launched. such that it requires the value listed in Table 6-3.Chapter 6 If this value is omitted. Creating a Setup OCX 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. its panel and all associated tabs are removed from the Administration module. the Administration module can display a panel for each setup OCX. Enabling Panels Setup OCX panels are enabled as follows: If the setup OCX is associated with a custom extension. This panel may be resized and moved just like any other panel. the panel is enabled when both of the following are true: The Batch class tab of the Definitions panel is active. When a setup OCX is unloaded. If the setup OCX is not associated with a custom extension. if the custom extension is unregistered from within the Administration module If the setup OCX is not associated with a custom extension. Kofax Capture 10 Developer’s Guide 79 . When a panel is disabled. Setup OCX Panels At the discretion of the setup OCX developer. the OCX is unloaded: When the Administration module is shut down While the Administration module is running. The current selection is either a batch class with the custom extension in its workflow. the panel itself remains visible. or a component of such a batch class. but the user interface elements of the setup OCX are hidden. the panel is enabled when the Administration module is launched. (When a menu item is disabled. the menu items are enabled and disabled when both of the following are true. Ribbon Bar A setup OCX can add one or more tabs to the Administration module Ribbon. 80 Kofax Capture 10 Developer’s Guide . Custom Tab Names Custom tab names defined by a setup OCX must be different from the standard tab names provided on the Administration module Ribbon. Selecting one of these menu items sends an ActionEvent to the OCX. When setup OCX menu items are disabled.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. or they can be specified in the . If you attempt to create a custom tab with the same name as an existing tab. For this case. identifying the particular command selected. All of the custom menu items will be grouped together via separator bars. the tab will not be added. or a component of such a batch class.) The Batch class tab of the Definitions panel is active. If the setup OCX is not associated with a custom extension. 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. {ProgID} is the COM prog ID for the OCX. identifying the particular menu selected. it is grayed.aex file required for custom extension registration. The menus can be added programmatically. and define commands for the tab groups. Where: {DisplayName} is the display name of the tab to be added. for more information about registering custom extensions. the menu items are always enabled. The current selection is either a batch class with the custom extension. but program execution will continue. Selecting one of the custom commands sends an ActionEvent to the setup OCX. the following error will occur when the setup OCX is loaded: Cannot create {DisplayName} menu for the user-defined queue setup module {ProgID}. Refer to Chapter 4 – Creating a Registration File. they are grayed. Selecting a panel will show or hide the panel. When the batch class that contains the custom extension is not selected. the panel elements are not displayed. It is possible to show a panel that is disabled. the behavior of the commands for the custom tab are as follows: If the setup OCX is associated with a custom extension. Batch Class Publishing A setup OCX can define publish checks to be used by the Administration module when batch classes are published. If the setup OCX is not associated with a custom extension. As an example. according to the queue order listed in the workflow. 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 76). the commands are enabled when both of the following are true: The Batch class tab of the Definitions panel is active. Any warnings associated with the custom extension are displayed in the Results list when you publish the batch class. or a component of such a batch class. but the commands associated with it are grayed. and the batch class that contains the custom extension is selected from the Batch class tab of the Definitions panel. depending on its current state. the commands are always enabled. For example. however. However. For this case. changes to the publishing functionality can be defined. that panel will always be omitted from the Panels group. each queue performs its own publish checks. If the setup OCX is not associated with a custom extension. In that case. the setup OCX that defines the custom tab is associated with a custom extension. The custom tab is then enabled. Kofax Capture 10 Developer’s Guide 81 . the tab name “Sample Index” is available. the publish checks defined by the OCX are used when batch classes that contain the custom extension are published. The current selection is either a batch class with the custom extension. Note A panel being shown or hidden has nothing to do with it being enabled or disabled. if the workflow includes a custom extension that uses custom property settings. the publish checks are used when any batch class is published. a custom tab can be added to the Administration module Ribbon. they are published along with the other property settings for the batch class. Note the following: If the setup OCX is associated with a custom extension. No new user elements for publishing can be exposed with a setup OCX. When a disabled panel is shown. When a batch class is published. Panels Each panel created by a setup OCX will be listed on the tab that appears when you select the View tab and look in the Panels group.Creating a Setup OCX Enabling/Disabling Custom Commands Custom tabs added to the Ribbon by a setup OCX are always enabled. These properties and methods are associated with setup OCX applications. the custom properties for each custom extension are also published.Chapter 6 If all publish checks succeed. they are not reflected in the batch class until you publish it again. When the API Reference Guide opens in a new browser window. The Kofax Capture API Reference Guide documents the properties and methods in the Kofax Capture Admin Module Type Library. Setup OCX Development API The complete API for the Kofax Capture Admin Module Type Library is documented in the Kofax Capture API Reference Guide.0 | API Reference Guide from the Windows Start menu. If you change any custom properties. 82 Kofax Capture 10 Developer’s Guide . When a batch class is published. To access the Kofax Capture Admin Module Type Library 1 2 Select Start | Programs | Kofax Capture 10. All properties and methods are defined using Visual Basic syntax. click on the “Kofax Capture Admin Module Type Library” entry in the Table of Contents. the batch class is published. Programming in a High Availability Environment When customizing Kofax Capture in a high availability environment. These custom applications can be run from command lines and can also have their own interfaces that are entirely separate from Kofax Capture. This feature (Import Controller) supports virtually any type of custom import application you might care to create. Validation. In addition. refer to the Kofax Capture Installation Guide. Each panel contains a user-defined OCX.Chapter 7 Creating Custom Panels and Applications Introduction With the Kofax Capture Module Type Library. Quality Control. Custom commands. Validation. Quality Control. You can use different panels for each module to be customized. which may be added to the Scan. 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. User Interface Design and Behavior The following sections describe the user interface design and behavior of custom panels and commands. For more information on high availability. you can implement custom commands. you can add the following custom elements to the Scan. These will help ensure that your applications take full advantage of Kofax Capture’s high availability features. you can create standalone custom applications that act as input scripts. Each panel must be developed as an OCX. Kofax Capture 10 Developer’s Guide 83 . You can add up to 20 custom panels to a standard Kofax Capture module. and/or Verification modules. and/or Verification modules: Custom panels. These choices are entirely up to you. you should observe the error handling guidelines found in High Availability Environments on page 95. In conjunction with a custom panel. by taking advantage of the extended features of the Kofax Capture Module Type Library. which will allow it to display itself. If a panel is not visible. it will be visible when the application opens. The panel has a minimum size (which is 50.0 occurs when the OCX is first built. Clicking and dragging on the top edge of a panel causes the panel to move to a new location on the frame. state (floating/docked). Note The OCX cannot programmatically resize its parent window. the data entry panel. Custom Panels As an example. Any panel clicks outside this margin area are passed to the OCX.) Resizing a floating window. If the panel is dragged off the frame. The panel can be restored by selecting it from the View tab in the Panels group. Dragging a floating window back to the frame to redock the panel to the frame.Chapter 7 New or modified customizations can take advantage of the Fluent UI found in the Kofax Capture modules given above. it will not appear in the Panelgroup. floating window. Double-clicking on the top edge of a docked panel changes that panel into a floating window.50 for default panels). note information) are reflected by all standard Kofax Capture controls. A panel may receive several resize events just after creation. If the panel has the visible flag = 0 in the registry. The outside edge of the panel (about 4 pixels) is used for panel operations (listed below). depending on the screen resolution configuration. then keyboard events are also sent to it. This panel may be resized and moved just like any standard panel. the tree view. It can still be displayed via command selections. field data. Hiding a floating window by clicking its Close box. reject flag. If the panel is visible when the application closes. An initial resize of size 0. Standard panels and new OCX panels support the following operations: Saving the panel’s size. and the thumbnail view. The OCX has an API called ShowWindow(). then it becomes a distinct. including the image viewer(s). Note the following: Panels without windows: A “visible” flag in the registry will determine if a panel is displayed in the Panel group of the View tab. If the OCX obtains focus. Any changes to data made by the OCX (field content. for a custom panel in the Validation module. it will never appear in the Panel group. The OCX panel sends resizing events to the child OCX whenever the panel itself is resized. 84 Kofax Capture 10 Developer’s Guide . (Double-clicking the top edge of the panel toggles between a docked/undocked state. The OCX may display any desired graphical objects on the panel. and position between application invocations. the user OCX is contained completely within a new user interface panel. Windows may send other events. the tabs are inserted in the order that the panels are loaded. The registry alphabetizes its entries. An event and APIs have been provided to allow modified or new customizations to work properly with themes. AddMenuEx. The name of the new tab must be different from any existing tab text. Note The OCX developer is responsible for accelerator key uniqueness. has been provided explicitly for this purpose. the OCX can display a modal window. Selecting one of these menu items sends an action event to the OCX. A new method. Kofax Capture 10 Developer’s Guide 85 . but with several new parameters geared toward the Fluent UI. See the Kofax Capture API Reference Guide for details. Custom Tabs The Viewtabcontains a Panels group that allows hiding/showing the user panel. By default the panels will appear in their native Windows style. See the Kofax Capture API Reference Guide for details. The only way to provide a matching look and feel is to change the Kofax Capture theme to match the style of the custom panel. they are added in the order they are loaded. Commands as shown above (Show Me. accelerator. For an example. The Ribbon text and tab items can be read from the registry. Quality Control. Custom Panels in the Fluent UI Updated or new custom panels may take advantage of the Fluent UI. and Verification Tree Node (Context) Menus Each OCX may add one or more items to the tree nodes displayed in the Batch Contents panel. each OCX can add a tab to the Ribbon. The action event identifies the menu item selected. The menu text. The registry supports one Ribbon per panel. In addition. Or. Instead. Themes in the Fluent UI The look and feel for legacy custom panels may not conform to the look and feel of Kofax Capture with the Fluent UI. and Show Dialog) can be defined as part of your OCX. Panels hidden by the OCX: The application API allows the panel to hide/show itself. Validation. Multiple Ribbons may be defined programmatically. This method functions exactly like the older AddMenu method. you can hide the panel after opening the application.Creating Custom Panels and Applications As a workaround. If added programmatically. see the sample OCX provided in your installation folder. Refer to Using the Sample Custom Panel on page 90 for more information about installing and registering the samples. Duplicates will not be added. an error will be generated. don’t display the panel. and tree nodes are specified in the registry or can be added programmatically. Hide Me. Scan. The User Panel Name in the group is configurable. When more than one OCX (user-defined panel) exists in the registry. If you attempt to add duplicate text. Locations for tabs to appear. A tab entry “&OCXTest” was added by calling AddMenu() within the OCX. and Edited at Runtime The AddMenu() API allows the addition of commands by the OCX while loading or running. 86 Kofax Capture 10 Developer’s Guide . Multiple tabs can be added programmatically using AddMenu(). Removed. This text is passed back as part of the MenuClicked() action event. '*** Possible locations for user-defined '*** menus for Scan. Installing a Custom Panel To install a custom panel. Menubar: “&Sample OCX” is the Ribbon text added from a registry entry. Registry Entries for Tabs Each user-defined panel will have a Menus key under it. Quality Control. Batch Menu Sel Tab event text. This is the tab text for the Ribbon with the accelerator on it. Registry Keys Key Entries Menus Batch Document MenuBar Page Description This key indicates that tabs will follow. Text “&Pick me…” For example. Also. Table 7-1 describes the Menus registry keys. The example code below shows the tab location names. The MenuBar entry contains one string value. This is the text that will be returned to the OCX when the command is selected. the only property is the tab text. A ShowMenu() API allows a user-defined command to be shown or hidden. Currently. Table 7-1. The Menus key will have subkeys for each tab that allows the insertion of commands. '*** Validation. supplied by the developer. Refer to the Kofax Capture API Reference Guide for details about AddMenu() and ShowMenu(). The locations are under the tabs. This contains the accelerator key (“&” on the “P”). The OCX file need not reside in any specific folder location.Chapter 7 Tabs Can Be Added. Each tab will have a name and properties. Note The OCX developer is responsible for keytip uniqueness. any required customer DLLs must be installed (if necessary). “Text” is the non-localized value that contains the text to be displayed. and Verification m_RuntimeMenuLocationKeys(0) = “MenuBar” m_RuntimeMenuLocationKeys(1) = “Batch” m_RuntimeMenuLocationKeys(2) = “Document” m_RuntimeMenuLocationKeys(3) = “Page” The Ribbon contains one additional text key from the Ribbon to identify the text displayed on the frame. the OCX must be copied and registered on each client computer. The default is 50. If more than 20 keys exist in this folder.” Table 7-2. The OCX has no control over this functionality. The initial vertical OCX size in screen resolution pixels. The default is 50. then subsequent keys are ignored. some registry entries (on each client computer) must be created under the following path: HKEY_LOCAL_MACHINE\Software\Kofax Image Products\Ascent Capture\3. For more information. The COM program ID of the OCX. The initial horizontal OCX size in screen resolution pixels. the following values may be defined for the “{User-defined Key}. However. this tab contains the name of a userdefined OCX and the end user is allowed to turn the panel on and off. {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 Panelsgroup. Next. As shown in Table 7-2. The Visible value setting determines whether or not the panel name appears in the Panels group. The default is 50. the “{User-defined Key}” key is any valid registry key. see Using the Sample Custom Panel on page 90. InitSizeX InitSizeY MinSizeX MinSizeY ProgID 1 No No No No Yes DWORD DWORD DWORD DWORD String 1 Kofax Capture 10 Developer’s Guide 87 . The minimum undocked horizontal OCX size in screen resolution pixels. The minimum undocked vertical OCX size in screen resolution pixels.” Within the “User Panels” path. The Panelsgroup is available in the View tab. notice that the registry entry is created under a path that intentionally includes a reference to “3. sample custom panels are available in your Kofax Capture installation folder (a VB.Creating Custom Panels and Applications Note Custom panels are not included as part of the standard Kofax Capture installation. The “{module name}” must be replaced with one of the following names: Ascent Capture – Scan Ascent Capture – Quality Control Ascent Capture – Validation Ascent Capture – Verification Ascent Capture .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.Administration Note Although you may be working with a later Kofax Capture installation. Currently.NET sample is located at Source\Sample Projects\StdCust). The default is 50.0. Defaults to 1 (visible). the following message displays: 88 Kofax Capture 10 Developer’s Guide . There is no support for minimum docked size. {User-Defined Key} Values (continued) Value ReplacesIndex FieldsPanel Required? No Value Type DWORD Notes This applies to the Validation and Verification modules only. However. catch the new event and set focus as desired. its context menu will not show the Index Fields menu item. If any of the required values are missing. Registry Values for the {User-Defined Key} The initial docking location is always at the upper left of the client area. When enabled. 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}. 1 The minimum size parameters affect only the undocked minimum size.Chapter 7 Table 7-2. However. To do this. If the OCX has registered itself as ReplacesIndexFieldsPanel. Only one OCX can register itself as ReplacesIndexFieldsPanel. If the panel is not visible. and Index Fields commands are hidden. Because the OCX is an integral part of the application. Note that the panel works best when docked. Additionally. Visible No DWORD Determines if the panel is displayed in the Panels group. When an eDocument is displayed the internal Windows Explorer panel takes focus after displaying the eDocument. you may want to set focus to some subcontrol. the Index Fields panel and its View. If absolutely necessary. Toolbars. Kofax Capture gives focus to the “outer” OCX panel. Figure 7-1. the user may completely remove the OCX registry key and the software will run. it can still be displayed via commands. If any size parameter is out of range. then it will receive a new event (KfxOcxEventResetFocus) indicating that focus has been returned to the OCX. the user is not allowed to run the application unless the OCX is properly set up. this is not recommended as invalid data may occur (assuming the OCX is performing the necessary tasks). In such cases. 0 is not visible. In the case of an unexpected system error. bSendImmediate invokes the Windows API call “PostMessage. SelectMenuItem returns a nonzero value. and it can be set to True or False. If False. Resource ID of command. bSendImmediate invokes the Windows API call “SendMessage. and Verification modules through the SelectMenuItem function.Creating Custom Panels and Applications {parameter} for user-defined OCX {DisplayName} is out of range. Invoking Kofax Capture Commands from a Custom OCX Panel You can use a custom OCX panel to invoke Kofax Capture commands in the Administration.” which posts the command so it is executed when other events are completed. Quality Control. The command shown here displays the last page in a batch. The “{parameter}” string is one of the values shown in Table 7-2. but the OCX cannot be created for some reason. The following sample passes a command from a custom OCX to the Scan module. Table 7-3. Long] bSendImmediate [ByVal Optional Default to FALSE] Description Sends a selected command to a Kofax Capture module.” which executes the command instantly and fails if the module is processing another event. SelectMenuItem Function Function SelectMenuItem Arguments Returns: Boolean Parameters: lResourceID [ByVal. Kofax Capture 10 Developer’s Guide 89 . If True. If all parameters are read and valid. If successful. Validation. Scan. the following message is displayed: Unable to create user-defined OCX {DisplayName} ({details}) Where: {details} indicates the error number and/or description. SelectMenuItem will throw an error if any of the following are true: You specify an invalid resource ID for the command The item is currently grayed in the target module You execute an exit command immediately (bSendImmediate is True) The application is busy The bSendImmediate parameter is optional. it returns a value of zero. A separate set of commands is available for each Kofax Capture module. KfxAdminMenuHelpAboutAscentCapture is the item for the Administration module’s About Kofax Capture command. OCXReg (or OCXReg.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. OCX Tab Selection In the above example. the OCX Tab Selection invokes the About Kofax Capture tab selection in the Administration module.This folder contains Visual Basic source code for a sample OCX.Chapter 7 Figure 7-2. Using the Sample Custom Panel A sample custom panel is provided as part of your Kofax Capture installation. The sample is installed to the following folder: <Kofax Capture installation folder>\Source\Sample Projects\StdCust Two subfolders are included: OCXPanel (or OCXPanel. Passing a Command to the Scan Module In the following code.NET) . Figure 7-3. The source code in the preceding folders is provided in Visual Basic .This folder contains Visual Basic source code for a sample registration utility.NET) . 90 Kofax Capture 10 Developer’s Guide . SampleUserControl. For COM components. 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.exe).NET components. you do not need to change the other default settings. replace the default SampleOCX. use RegSvr32.SampleUserControl with Kofax. in the ProgID box. For . use RegAsm. Kofax Capture 10 Developer’s Guide 91 .dll to the Kofax\Bin folder. In the Required area. Click Save. Registering a Custom Panel 5 6 7 8 In the Modules area. For demonstration purposes. you need to register the custom panel in the Windows Registry. Figure 7-4. Browse to the following folder: C:\Program Files\Kofax\Source\Sample Projects\StdCust\OCXReg\ Start the User Panel Registration Tool (PanelReg.NET Framework.NET custom panel for COM Interop with the Windows Registry and the . Windows Registration In addition to the Kofax Capture registration.exe to register a custom panel in the Windows Registry. shown in Figure 7-4.Creating Custom Panels and Applications Registering the Sample Custom Panel Custom panel registration is a two-part process. Kofax Capture Registration This section explains how to use the sample registration utility to register the sample OCX panel for use with Kofax Capture. select the modules in which you want to enable the sample OCX panel.exe to register a . To register the sample custom panel 1 2 3 4 Start Windows Explorer and browse to the following folder: C:\Program Files\Kofax\Source\Sample Projects\StdCust\OCXPanel\ Copy the SampleOCX. To register the sample custom panel 1 2 From the Windows Start menu.NET Framework.dll is the name of the sample . Ocxname. The following is the code for the custom panel (DelPagePanel). type the following: <path1>RegSvr32. Smpleocx.NET\Framework\v2. From the Run window.ocx. usually for .exe <path2>Ocxname. From the Run window.exe <path2>Smpleocx.dll Where: <path1> is the full path to the latest . It enables you to mark the page for deletion. select Run. see User Interface Design and Behavior on page 83. OCXname.ocx is the name of your custom panel OCX. 92 Kofax Capture 10 Developer’s Guide . select Run.ocx Where: <path1> is the full path to the RegSvr32 application.NET custom panel 1 2 From the Windows Start menu.NET Framework 2.0: C:\WINDOWS\Microsoft. From the Run window. <path2> is the full path to Smpleocx.0.50727\ <path2> is the full path to OCXname. For details about typical custom panel behavior. browse to the OCXPanel folder included in your Kofax Capture installation and type the following: <path1>RegSvr32.Chapter 7 To register a custom panel OCX in the Windows Registry 1 2 From the Windows Start menu.exe <path2>OCXname. This custom panel uses a context menu accessible from a batch to mark pages for deletion. <path2> is the full path to Ocxname.NET The following example custom panel named DelPagePanel has no user interface but enables an operator to flag a page for deletion.NET custom panel OCX provided with Kofax Capture. select Run.ocx Where: <path1> is the full path to the RegSvr32 application. To register the sample . a context menu is displayed. When you right-click the page that you want deleted. Example Custom Panel in VB .dll. type the following: <path1>RegAsm. Viewing the Custom Panel After the registration process.ocx. the custom panel is available in each module for which it was registered with Kofax Capture.ocx is the name of the sample custom panel OCX provided with Kofax Capture. AscentCaptureModule.Application) m_oApplication = Value '*** Initialize Menus InitializeMenus() End Set End Property Public Sub ActionEvent(ByVal nEventNumber As Integer.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.ActivePage. ByRef _ oArgument As Object.KfxOcxEventMenuClicked Then '*** 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.AscentCaptureModule.AscentCaptureModule Public Class DelPagePanel Inherits System. ByRef nCancel As Integer) If nEventNumber = KfxOcxEvent.Forms.Application Get Return m_oApplication End Get Set(ByVal Value As Kofax.Creating Custom Panels and Applications DelPagePanel Imports Kofax.UserControl #Region " Windows Form Designer generated code " <This segment of code was removed--it is generated by VB .CustomStorageString _ (cm_strPageCSSName) = "True" End If Kofax Capture 10 Developer’s Guide 93 .ActiveBatch.Windows.AscentCaptureModule.Application #End Region #Region "*** Public Properties/Methods" Public Property Application() As _ Kofax. Chapter 7 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 94 Kofax Capture 10 Developer’s Guide . page registration. refer to the Kofax Capture Installation Guide. you might want to write a custom OCR module that uses an engine other than the engines provided with Kofax Capture. These errors can be grouped into the following categories: Kofax Capture 10 Developer’s Guide 95 . An example custom module. If a custom module does not properly handle close messages sent to terminate its process. custom modules should properly handle Microsoft Windows close messages. These will help ensure that your applications take full advantage of Kofax Capture’s high availability features. 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. you should observe the following error handling guidelines. or full text OCR. automatic or manual indexing. High Availability Environments When customizing Kofax Capture in a high availability environment. Therefore. To meet high availability requirements.Chapter 8 Creating a Custom Module Introduction Custom modules can be created to perform tasks such as document separation. Error Handling Guidelines Any component of a highly available system is subject to failure at any time. Kofax Capture upgrade installations may fail. Once you create the custom module. Note The Kofax Capture installation process may require that an interactive custom module be shut down before installation continues. you should design your Kofax Capture customizations to detect and recover from errors during operations that require access to a remote computer. such as bar code recognition on color images or form identification using a custom algorithm. and custom panel is also provided in this chapter. form identification. setup OCX. as well as the standard Export module as the final processing module). the custom module might perform a special type of image processing. This chapter gives you an overview of the development process for creating a custom module for Kofax Capture. Or. which is part of the comprehensive example of a custom workflow agent. verification. Custom Modules You can implement a custom module alongside the standard set of Kofax Capture processing modules. For more information on high availability. For example. or you can use it to replace a standard module. Custom modules can also perform unique functions suited to your business needs. contention. intermittent network failures. Since it takes a period of time for the file system to failover. the application must reconnect to the database and retry the operation if necessary. your application must check for errors after every function call. applications should continue to retry for at least 2 minutes. If an error occurs.Chapter 8 Database Operations Any customization that accesses a database on another computer may encounter errors. but not limited to. then during a failover. you must take care to determine if the same parameters can be used or if the failed operation changed the state of the system. 96 Kofax Capture 10 Developer’s Guide . if it is important that the failed operation be executed exactly once. then during a failover the database will be off-line for a short period of time. If an error occurs. it is possible that the database operation succeeded but that a network failure prevented the successful result from reaching your application. If the customization accesses a database that is on a cluster server. but did not complete. applications should continue to retry for at least 2 minutes. intermittent network failures and cluster failover. If an error occurs. To ensure high availability. The client/server application might be “cluster-aware” and be deployed on the cluster server. you must determine if it succeeded or failed in order to know if the operation should be retried. Note that when an operation returns an error. but not limited to. Therefore. Database errors can occur due to a variety of issues including. Therefore. it is possible that the file operation started. To ensure high availability. your application must check for errors on every file operation. and cluster failover. is used to demonstrate the design and implementation of a custom module. Sample Applications A custom module example named DeleteEvenPage. the application must determine if a retry is needed. If the customization accesses a file system that is on a cluster server.NET example. your application must check for errors on every database operation. it must retry the operation. Since it takes a period of time for the database to failover. which is part of the comprehensive VB . when retrying. The code for this custom module is provided later in this chapter. or it may provide some other mechanism to make the server highly available. Client / Server Operations Any customization that accesses a third-party server application on another computer may encounter errors. To ensure high availability. File access errors can occur due to a variety of issues including. it is up to the client/server application utilized by the Kofax Capture customization to provide high availability in some way. the file system will be off-line for a short period of time. File System Operations Any customization that accesses files on another computer may encounter errors. In any case. Note that even if there is an error. Third-Party Operations Any third-party function utilized by a Kofax Capture customization might access a remote computer. 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. because you could potentially use the standard Kofax Capture settings. 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. For details.NET program is located in the folder: <Kofax Capture installation folder>\Source\Sample Projects\CustMod\Generic. For example. You can present a list of batches to the user. However. This Visual Basic . Kofax Capture 10 Developer’s Guide 97 . if you developed a custom module to replace the standard Validation module. Then decide whether you want to make the custom module available in addition to. Then decide where (tabs or user interface panels) it would be appropriate to make the custom settings available to the user. see Appendix A – Custom Module Sample. You may decide to perform some tasks in a different order. For details about the sample custom module. and scope for the custom extension. You should produce specifications that define the design.NET The folder contains the files necessary to register a custom module named “Sample. Write the Runtime Application Use the Kofax Capture Document Access API library to integrate the application into your Kofax Capture installation. see Chapter 6 – Creating a Setup OCX. existing Kofax Capture functions. it is likely that most custom extensions will require unique configuration properties and publish checks. Before starting any development. The setup OCX is optional. you might be able to use the standard settings and publish checks. consider how your custom module will augment the standard Kofax Capture functionality. Develop the custom module to meet your specifications. Additionally. For example.” The sample gives a generic example of a custom module. be sure to take into account the characteristics of the forms you expect to process with the custom module. Typical Development Tasks The typical custom extension development process includes the tasks outlined in this section. the success of the custom module implementation process requires careful planning and analysis. which you can install and register for demonstration purposes.Creating a Custom Module Kofax Capture also ships with a sample custom module that is provided as part of your Kofax Capture installation. you need to determine if it would be appropriate to add custom configuration settings to support the new functionality. functionality. or you can opt to have the custom module automatically process batches as they become available. or in place of. you can proceed to create an installation program. custom extension runtime. Create an Installation Program If you plan to distribute the custom module. You will need to install the custom extension setup OCX.0 SupportsTableFields=True SupportsNonImageFiles=True The registration file (DeleteEvenPage. you register the custom module so that Kofax Capture will recognize it. you can add the custom extension to the batch class so you can test it.exe ModuleID=DeleteEvenPage. Once you are satisfied with the preliminary tests. Sample Document Type Definition (DTD) files required for custom module XML files are provided with Kofax Capture and are installed with the program. If desired.a very useful tool Version=8.exe Description=This module deletes even pages. Note Your XML transport files need to follow the format required for compatibility with Kofax Capture. you will need to write a program to add the application to your Kofax Capture installation. read Chapter 4 – Creating a Registration File. see Chapter 4 – Creating a Registration File. Register the Custom Module Once the registration file is in place.. it performs the custom function(s).Chapter 8 Kofax Capture Document Access also allows XML batch information to pass between Kofax Capture and the custom module. and registration file to the <Kofax Capture installation folder>\Bin folder 98 Kofax Capture 10 Developer’s Guide . Create the Custom Module Registration File You must create a registration file that defines the property settings for the custom module. you can also test the setup OCX to verify its validity..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 ProgID of the custom module For more information about the registration file. The file must be in place before you register the custom module. you can incorporate the registration process into the installation program. As the custom module receives a batch. After registration. and then sends the batch back to Kofax Capture. After registration.aex) for the example custom module: [Modules] Delete Even Page CM [Delete Even Page CM] RuntimeProgram=DeleteEvenPage. The following is the registration file (DeleteEvenPage. For details on registering custom extensions. If your module closes both parent and child batches.DBLiteOpt. a custom module passes valid closing parameters to a function. If a batch fails to close. causing the module to close. You can divide batches based on any programmable criteria such as form type. for example. _ ByVal oList As List(Of Kofax. Kofax Capture suspends both parent and child batches. Document Routing The Document Routing feature allows custom module developers to divide a batch into multiple batches. you can add a custom extension icon to the Kofax Capture program group. making it a parent. If you do not provide naming code. you can add code that names the batch. it can then reopen the child batch. You do this by opening the parent batch and then creating a child batch from the parent. Closing Batches A custom module cannot close a parent batch until it first closes the child batch. and then create a child batch based on it..DBLite.ACDataElement)) If oList IsNot Nothing AndAlso oList. Only a single child batch can be open at the same time as a parent batch. If desired. Using Document Routing Functions The batch create. and close operations are performed by the following functions: ChildBatchCreate (DBLite) MoveElementToBatch (DBLiteOpt) BatchCloseWithModuleID (DBLite) ChildBatchCreate ChildBatchCreate creates a child batch based on an existing open parent batch. move. the default child batch name is the parent batch name appended with the date and time.Count > 0 Then '*** Create the child batch Dim oChildBatch As Kofax. Private Sub SplitDocuments( _ ByVal oParentBatch As Kofax.ChildBatchCreate() . Each child batch uses the same published batch class as the parent batch. A custom module must close a child batch before it can create another one from the same parent. Naming a Child Batch When your custom module creates a child batch. and then fails to close.Batch = oParentBatch. Kofax Capture 10 Developer’s Guide 99 .DBLite. in this example. allowing you to add appropriate error handling.Creating a Custom Module for every workstation where you want the custom extension to be available.Batch. with the following exception: If you exit a custom module. You can then move pages and documents between the two open parent and child batches. is passed to the SplitDocuments subroutine. it throws an error. If. Batch classes are copied as well. The following portion of code taken from the CMSplit sample custom module creates a child batch based on a parent batch which.. A unique ID (i. The following code moves a document from oDocElement to oChildDocsElement (both of type ACDataElement). If the source page is the last page in a document or batch. user tracking statistics data reflects the page movement from both source and destination batch. there is no licensing charge. '*** Split this current document into the child batch oChildDocsElement. Note When your custom module moves pages or documents using the Document Routing feature. 100 Kofax Capture 10 Developer’s Guide . its DocumentGUID is not changed.exe) that specifies to which module to route the batch.e. you must delete the parent batch. ocr. if the source document is the last document. MoveElementToBatch MoveElementToBatch moves an ACDataElement (page or document) from one open batch to another. you must delete the parent document or batch. BatchCloseWithModuleID BatchCloseWithModuleID closes and unlocks a batch to be routed to a specified module. Also. note the following: A custom module cannot move an element (document or page) to a specific location in the destination batch. If necessary. About Document Routing Features Document Routing includes the following additional features. Tracking Statistics As a custom module moves pages or documents from a parent batch to a child batch. BatchCloseWithModuleID Parameters Input Parameter eNewState strModuleID Description Specifies the new state of the batch once it has been unlocked. Similarly. Document GUID When a custom module moves a document. For more information about error codes. Table 8-1. MoveElementToBatch automatically deletes the ACDataElement from the source batch. but its Page ID is changed. a custom module can modify an element after it has been moved. see the Kofax Capture API Reference Guide.MoveElementToBatch(oDocElement) MoveElementToBatch returns a new object from the destination batch containing the object that was moved.Chapter 8 your error handling code can attempt to close the batch again. the Reference Batch ID is available.Creating a Custom Module Reference Batch ID When a batch is created. It creates new batches for each form type except for the first form type identified. Using the Sample Custom Module This section explains how to use the provided sample custom module (CMSplit) which demonstrates the use of the Document Routing feature. Using your own custom module in conjunction with the Kofax Transformation Modules implementation may have unpredictable results. For example. Unsupported Features The Document Routing feature does not support: Batch totals Partial batch export Folders Using Kofax Transformation Modules You can use the Document Routing feature as follows: In your own custom module. no child batches are created. In this case. The Reference Batch ID is a GUID for each originally created batch. the sample custom module divides the existing batch into two additional batches. The original batch contains documents based only on the first identified form type. export. the sample custom module is typicially placed after the Recognition Server module. The sample custom module contains a single-form user interface that displays status only as it processes batches (similar to the Separate sample custom module). Using only the Kofax Transformation Modules implementation of Document Routing. This value is used to track the original batch and all child batches through the system. it has the same value for all batches created by calling CreateChildBatch from a parent batch. or PDF header value. Kofax Capture also adds the Reference Batch ID as a column in the StatsBatch table. However. If the original batch contains only one page or document. You can use this value as a batch field. You can also use batch-specific Kofax Capture values as endorser values. In the workflow. The sample custom module divides a batch based on form type. index field (for a document or folder). the Kofax Capture system assigns it a Reference Batch ID. if a batch contains scanned documents that are based on three form types. independent of Kofax Transformation Modules. Note Kofax Transformation Modules stores data in its own external files. The sample custom module is located in: <Kofax Capture Installation Folder>\Capture\Sample Projects\CustMod\CMSplit Kofax Capture 10 Developer’s Guide 101 . but it is not expanded. LoginClass '*** Log into Kofax Capture m_oLogin.NET 2.NET using . In the Initialize function.Threading Public Class Driver '*** Reference to the Login object rivate m_oLogin As Kofax.DBLite Imports Kofax.ApplicationName = "DeleteEventPage CM" m_oLogin.DBLite. The following is the code for the custom module named DeleteEvenPage. It checks that the pages marked for deletion are removed from the batch.0.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. The CMSplit sample shares code with the Kofax Capture Separation Custom Module Sample (separate.DBLiteOpt Imports System.exe).0 interfaces to maintain backwards compatibility.DBLite.Login() '*** Set the App name and version m_oLogin.Login *** Reference to the RuntimeSession object Private WithEvents m_oRuntimeSession As _ Kofax. we log into Kofax Capture and cache the appropriate data structures. DeleteEvenPage Module Imports Kofax.NET 3. Example Custom Module The example program named DeleteEvenPage is an unattended module that is designed to run after the Scan module.DBLite.DBLite.Version = "1.Batch '*** Create a mutex to protect calls to ProcessBatch Private m_oMutex As Threading.Chapter 8 CMSplit is written in VB. but it uses only .0" 102 Kofax Capture 10 Developer’s Guide .RuntimeSession '*** Reference to the Active Batch Private m_oActiveBatch As Kofax. This class definition makes up the blueprint for the custom module. RuntimeSession Catch ex As Exception RaiseEvent StatusMessage("An error occurred: " & ex. '*** Otherwise.ValidateUser("DeleteEvenPage.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. '*** This function returns True if we successfully process a Batch. the batch is processed by deleting those pages that were marked for deletion by the Scan operator.FindChildElementByName("Batch") '*** Get the Pages element Dim oPagesElem As ACDataElement = oBatchElem.KfxDbSortOnPriorityDescending.KfxDbFilterOnProcess _ Or KfxDbFilter. _ KfxDbState. No Batches Available) Private Function ProcessNewBatch() As Boolean Try '*** Get the new Batch m_oActiveBatch = m_oRuntimeSession.NextBatchGet( _ m_oLogin.Creating a Custom Module '*** Validate the User m_oLogin. If it is able to open a batch.exe".FindChildElementByName("Pages") Kofax Capture 10 Developer’s Guide 103 .Message) End Try End Sub ProcessNewBatch Function The ProcessNewBatch function attempts to open the next available batch for this module. _ KfxDbFilter. we will return False (ie.ProcessID. True) RaiseEvent StatusMessage("Logged into Kofax Capture") '*** Cache the Runtime Session m_oRuntimeSession = m_oLogin.KfxDbFilterOnStates _ Or KfxDbFilter. Message) '*** If we have a reference to the Batch object.BatchClose(KfxDbState.KfxDbQueueException. close _ in error If Not m_oActiveBatch Is Nothing Then m_oActiveBatch.Message) End If End Try End Function 104 Kofax Capture 10 Developer’s Guide . ex. _ KfxDbQueue.Chapter 8 '*** 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.KfxDbQueueNext. 1000. "") '*** Return success ProcessNewBatch = True Else RaiseEvent StatusMessage("No batches for me available. _ KfxDbQueue.KfxDbBatchReady.") '*** Return false so we fall back into polling/waiting for _ signal ProcessNewBatch = False End If Catch ex As Exception RaiseEvent StatusMessage("An error occurred: " & ex.Delete() RaiseEvent StatusMessage("Deleted Page " & lngCount) End If Next '*** Close the Batch m_oActiveBatch.BatchClose(KfxDbState.FindChildElementsByName("Page") '*** Increment our counter lngCount = lngCount + 1 '*** Check if we should delete this page If PageMarkedForDeletion(oPageElem) Then '*** Delete it! oPageElem.KfxDbBatchError. 0. Message) Finally '*** Release the mutex m_oMutex. A mutex is implemented to ensure that this logic is processed by only one thread at a time. Private Function PageMarkedForDeletion(ByRef oPageElem As _ ACDataElement) As Boolean '*** Get the Page Custom Storage Strings Dim oPageCSSs As ACDataElement oPageCSSs = _ oPageElem.ReleaseMutex() End Try End Sub Kofax Capture 10 Developer’s Guide 105 . Private Sub m_oRuntimeSession_BatchAvailable() Handles _ m_oRuntimeSession.BatchAvailable '*** Lock access to this call m_oMutex.Creating a Custom Module PageMarkedForDeletion Function The PageMarkedForDeletion function returns a flag that indicates that the Scan operator selected the page to be deleted. "Name".FindChildElementByAttribute _ ("PageCustomStorageString". This handler attempts to process as many batches as possible. "DeletePage") '*** Make sure we have a reference If Not oPageDeleteCSS Is Nothing Then '*** Check the value If oPageDeleteCSS.FindChildElementByName("PageCustomStorageStrings") '*** Get the Page Custom Storage String by element Dim oPageDeleteCSS As ACDataElement oPageDeleteCSS = _ oPageCSSs.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. This flag is stored in a page-level custom storage string file.AttributeValue("Value") = "True" Then PageMarkedForDeletion = True Exit Function End If End If End Function RuntimeSession_BatchAvailable Subroutine This function handles the BatchAvailable event from Kofax Capture. Chapter 8 End Class 106 Kofax Capture 10 Developer’s Guide . FileNet. These two components could be in one or two . you can modify one of the supplied connectors. Source code for this export connector is installed to the <Kofax Capture installation folder>\Source\Export Connectors\KCEC-Text folder. These export connectors are provided in Microsoft Visual Basic . but they can also be written with any tool that supports the development of COM servers. IBM. or an ODBC-compliant database. A fax export connector that exports documents via faxes. Note that a wide variety of export connectors are available from Kofax for popular applications developed by Documentum. Kofax Capture Export Type Library The complete export connector API library is documented in the Kofax Capture API Reference Guide. and others. Source code for this export connector is installed to your <Kofax Capture installation folder>\Source\Export Connectors\Database folder. Contact your Certified Solutions Provider for details on availability. To access the Kofax Capture Export Type Library 1 Select Start | Programs | Kofax Capture 10. full text OCR files.Chapter 9 Creating an Export Connector Introduction Export is the process of exporting images and data to long-term storage after all Kofax Capture processing is finished. Also. Both of these connectors export images. Hummingbird. and PDF files to the standard file system.NET.dll or . or you can purchase one from Kofax or other third party entities.0 | API Reference Guide from the Windows Start menu.exe files. Kofax Capture includes the following standard export connectors: A database export connector that exports document index data to a Microsoft Access 97 or later. Export connectors are typically written in Visual Basic . An export connector consists of two COM components that configure and execute this process. the following export connectors and their documentation are provided in the \Export Connectors folder in the product files: An email export connector that exports documents via email messages.NET. The source code for these export connectors is installed with Kofax Capture. A text export connector that exports document index data to an ASCII text file. If you need to export document index data or files to other sources. you can create an entirely new one. Kofax Capture 10 Developer’s Guide 107 . Chapter 9 2 When the API Reference Guide opens in a new browser window. When writing an export connector. These properties include the available document class index fields. and so forth. You should use this method to load a form or window that allows the user to configure the export process. Similarly. The Administration module uses this variable to expose and update export configuration for the document class. The export connector setup must implement the KfxReleaseSetupScript COM interface that the Administration module requires. image formats. batch class fields. Kofax Capture and the Export Process The Kofax Capture Administration module manages the Export Setup process. which the Administration program calls to perform the various stages of the export setup process. you store the user’s choices in the ReleaseSetupData variable and call the ReleaseSetupData. You should use this method to perform any initialization required for the connector. which is the user interface for configuring the export process within the Administration module. and image file formats. The export connector must implement the KfxReleaseScript COM interface that the Export module requires. The export portion of the export connector is called by the Export module when it is exporting batches. file folders. the database export connector displays a form that allows setup of database links. For example. The export connector setup portion of the export connector is called by the Administration module when the user selects an export connector to configure. The Database and the Text export connectors include the KfxReleaseSetupScript and KfxReleaseScript COM components in the ActiveX DLL. It loads the export connector setup when the system administrator selects an export connector for a document class/ batch class pair. When you use the Administration program to select and configure an export connector for the first time. there are two basic functions you must provide: Export connector setup. Four methods called OpenScript. It loads the appropriate export connector when the batch enters the Export Queue. and CloseScript. Export. The KfxReleaseSetupScript interface must include the following: One public object variable declared as ReleaseSetupData. which performs the actual export of images and data to long-term storage. 2 3 108 Kofax Capture 10 Developer’s Guide . it loads the export connector setup and does the following: 1 Fills in the document class properties in the ReleaseSetupData variable. Requirements for the Export Connector Setup The export connector setup component must define the KfxReleaseSetupScript COM interface.Apply method to save them permanently to the Kofax Capture database. the Kofax Capture Export module manages the Export process. RunUI. ActionEvent. When the user is finished with setup. Calls the RunUI method. Calls the OpenScript method. click on the “Kofax Capture Export Type Library” entry in the Table of Contents. You should use this method to perform any cleanup required for the connector. Calls the CloseScript method after the last ReleaseDoc method is completed and the connector is about to be unloaded. However. The KfxReleaseScript interface must include the following: One public object variable declared as ReleaseData. writing an export connector is not actually as complex as you may think. if a new index field is added. You should use this method to perform any initialization required for the connector. ReleaseDoc. The code involves use of the Kofax Capture 10 Developer’s Guide 109 . which the Export module calls to perform the various stages of the export process. Repeats the process described in Step 3 for each remaining document to be exported.Creating an Export Connector 4 Calls the CloseScript method after the RunUI method is completed and the connector is about to be unloaded. The Export module uses this variable to expose export data for the export process. The ReleaseSetupData and ReleaseData Objects Both database export connector and text export connector support a wide variety of features and both contain a long list of functions and subroutines. it loads the export connector 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 might want to call the RunUI method to provide an opportunity to save this new data in the external database. You should use this method to determine whether the change in the document class requires a change in the export setup process. The various methods listed above provide data to update the Export module user interface as documents and batches complete the export process. 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 export folders. it calls the ActionEvent method with a set of parameters that indicate why it is being called. These functions are documented in the Kofax Capture API Reference Guide. Most of the required work is confined to specific locations in the connector. Requirements for the Export Connector The Export module uses a COM interface called KfxReleaseScript to communicate with the export connector.cls code module. the Administration program performs the same series of steps as before. The standard Text and Database export connectors define this interface in the Release. The export process is designed to run unattended. 4 5 Note that you cannot provide your own user interface for the export process. and CloseScript. Three methods called OpenScript. If you make a change to the document class after the initial export setup process. You should use this method to perform any cleanup required for the connector. When a batch containing documents of a given class enters the Export module. For example. Fills in the properties specific to the first document to be exported in the ReleaseData variable and calls the ReleaseDoc method for the document. The Export module has its own user interface. with one exception: instead of calling the RunUI method. since the process varies widely from connector to connector. To export a document. For example. you need to add code to this method that calls the following methods: 1 2 ReleaseData. The properties set up by the Administration module are read-only. The connector must set the properties that identify the external data repository and the target export folders. The properties will be available to the export connector.ImageFiles.CopyKofaxPDFFile copies the PDF file that belongs to a document into the export PDF path that is defined during export connector setup. To do this. call the Apply method to save your changes. The ReleaseDoc method is called every time the Export module is ready to export a new document.Copy copies the full text OCR files (if any) to a location specified by the ReleaseData object. Understanding these two objects is the key to writing an export connector. ReleaseData. you must save the user’s settings in the Kofax Capture database. For example. You are responsible for writing the proper code to export your index data to the appropriate repository. The ReleaseData. This form can be as simple or as complex as you wish. Export Connector Setup There are only two places in the export connector setup where you have to write a substantial amount of code: The RunUI event should load a form that presents a user interface. When the user clicks OK to finish export connector setup. 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 export process. if you want to recalculate the 110 Kofax Capture 10 Developer’s Guide .Copy copies the images to a location specified by the ReleaseData object.TextFiles. Export Connector There is only one place in the export connector where you need to write a significant amount of code. image types.Values collection contains values for all the index fields that you specified in the links collection during export connector setup. ReleaseSetupData Object The ReleaseSetupData object is a top-level object used by both the Kofax Capture Administration module and the export connector setup to define the export process for a document class. Some properties of this object are set up by the Administration module when the ReleaseSetupData object is created. and storage types are set when the connector is loaded. you must set up a links collection that specifies which index fields should be exported and then copy other settings as necessary into the ReleaseSetupData object. The index data must be exported last. the available batch fields. and you are not limited to using the methods described above. but there is no method provided for exporting index data. When this is finished. The amount of code you write depends on how complex your export procedure is. index fields.Chapter 9 methods and properties for the ReleaseSetupData and ReleaseData objects. 3 ReleaseData. Refer to the Kofax Capture API Reference Guide for details on the specific properties and methods available in the ReleaseSetupData object. the connector must copy the image files. and your export connector is registered. any Kofax PDF files. COM Servers: In-proc or Out-of-proc? Export connectors can be developed using any language and tool that can create COM components. you are free to do it.dll SetupProgID=Custom. Properties specific to an individual document are set up before the Export module calls the ReleaseDoc method for that document. Click Open.Creating an Export Connector destination of every image file based on a custom requirement of your own. you can then place the new folder into the ReleaseData object and call the Copy method. and any full text OCR files to the target file system. Registering Your Export Connector After completing your export connector. has a format similar to that of an . To register an export connector 1 2 3 4 5 6 7 Create an .inf file is shown below: [Scripts] Custom Script [Custom Script] SetupModule=Custom. All of the properties of this object are set up by the Export module. In the Administration module. COM components for both export connector setup and export can be designed as in-process servers (ActiveX DLLs) or as out-of-process servers (ActiveX EXEs). select the connector you want to register. The connector must use the ReleaseDoc method to read the properties and save the index data and related document information in the external data repository. Then. From the Export Connector Manager window. A sample .inf file. in the System group. If you are working with a 32-bit development environment.inf file for your export connector. 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. on the Tools tab. If the destination is a folder. which should be located in the same folder as your compiled export connector. click Export Connectors. It’s completely up to you. ReleaseData Object The ReleaseData object is a top-level object used by both the Kofax Capture Export module and the export connector to access the batch and document class information and perform the actual document export. you must register it. The properties that are common to all documents in the batch are set up when the ReleaseData object is initialized.kfxreleasesetupscript Kofax Capture 10 Developer’s Guide 111 . Click OK. Registration is a two-part process. Click Add and then browse to your.ini file. Select the connector you want to use.inf file. Refer to the Kofax Capture API Reference Guide for details on the specific properties and methods available in the ReleaseData object. Close the open windows to complete the process. Click Install. The . the export connector will support the use of the original name of the file. the export connector supports multiple instances of the Export service. Scripting in a High Availability Environment When writing connectors for Kofax Capture in a high availability environment. the export connector will support the output of Kofax PDF files. If True. Table 9-1. Version number assigned to the export connector COM component.dll ReleaseProgID=Custom. the export connector will remain loaded until processing is complete. constructed through the combination of the control's project and object name (ProjectName. there must be a corresponding section with the entries listed in Table 9-1. For each entry in the [Scripts] section. Inf File Entries Inf File Entry ReleaseModule ReleaseProgID Description Name of the compiled . Version number assigned to the export connector setup COM component. 112 Kofax Capture 10 Developer’s Guide .dll containing the export COM component. constructed through the combination of the control's project and object name (ProjectName.inf file must contain a [Scripts] section that includes the name (up to 255 characters) of each connector you are registering. A ProgID is a unique identifier for every control. If True. These will help ensure that your applications take full advantage of Kofax Capture’s high availability features. If True.ObjectName). A ProgID is a unique identifier for every control. the export connector will support eDocuments (non-image files).0 SupportsNonImageFiles=True RemainLoaded=True SupportsKofaxPDF=True SupportsOriginalFileName=True SupportsMultipleInstances=False The .kfxreleasescript ReleaseVersion=1. you should observe the error handling guidelines found in High Availability Environments on page 95.Chapter 9 SetupVersion=1. You can explicitly set the ProgID of your object using the ProgID Attribute.exe or . Name of the compiled . Note that the Multiple Instance Support feature is only available for Kofax Capture Enterprise users.ObjectName).exe or . You can explicitly set the ProgID of your object using the ProgID Attribute. Name of the export connector setup COM component.dll containing the export connector setup COM component. SupportsMultipleInstances If True. For more information on high availability. ReleaseVersion RemainLoaded SetupModule SetupProgID SetupVersion SupportsKofaxPDF SupportsNonImageFiles SupportsOriginalFileName If True. Name of the export connector COM component. refer to the Kofax Capture Installation Guide.0 ReleaseModule=Custom. Also. Once you configure a customization update on a Kofax Capture server. Also. If an operator is using Kofax applications that require a customization update. Deploying customization updates does not force operators to stop work. The Kofax Capture Deployment Service does not: Automatically delete customizations from workstations.Chapter 10 Deploying Customizations Introduction The Kofax Capture Deployment Service allows Kofax Capture developers to easily and automatically deploy customizations throughout an entire Kofax Capture system. You can develop and test a customization on one node of the Kofax Capture system and then enable the deployment and registration to other client workstations and remote sites. Automatically deploy customizations before a batch needs it. the service provides a comprehensive log of all deployment activity. Deploy other types of Kofax software such as export connectors or KTM. Deploy other types of generic software. by deploying a customization update to a Kofax Capture Network (KCN) Server central site. a message displays indicating that updates are available. it can be automatically downloaded and installed to client workstations connected to that server. Operators can decide when to reboot and automatically trigger the update. deployments are set up by central site administrators. the RSA agent automatically updates remote servers from a single source on the central site. it deploys only Kofax Capture customized software. workstations that have been installed after an initial deployment can obtain posted customizations. Kofax Capture customizations include: Workflow agents Custom panels Custom modules Export connectors The Kofax Capture Deployment Service deploys Kofax Capture customizations to any client workstation that is connected to a server and has the service installed and enabled. Kofax Capture 10 Developer’s Guide 113 . Plus. Run this service as a user with read-write access to the Customization Deployment folder on the server as well as with administrator rights to allow files to be copied and replaced in the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin). if necessary.exe” The “Enable Kofax Capture Deployment Service” window appears.NET\Framework\v2.exe”.0. 114 Kofax Capture 10 Developer’s Guide . alerts users to restart their computer so that a customization deployment can finish. To install the Kofax Capture Deployment Service 1 At a command prompt. If you installed Kofax Capture in the default location.exe /username=”MyDomain\MyName” /password=xj987L2 KCDeploymentService. The background program displays an icon in the Windows notification area. /u or /uninstall Use this parameter to uninstall the Kofax Capture Deployment Service. enter the following and press Enter: C:\WINDOWS\Microsoft. Command Line Parameters The Kofax Capture Deployment Service supports the following command line parameters. 2 Click OK.exe) with the Kofax Deployment Service as a parameter.exe “C:\Program Files\Kofax\Capture\Bin\KCDeploymentService. /unattended Use this parameter to suppress the “Enable Kofax Capture Deployment Service” window. run the Microsoft installation utility (InstallUtil.exe) must be the last parameter in the command line. The service installation starts a background program that.exe /password=[password] Use this parameter to specify the password for the user account. Note When using command line parameters.Chapter 10 Installing the Customization Deployment Service For any workstation that requires customization deployment. you must manually install the provided Kofax Capture service named “KCDeploymentService.50727\InstallUtil. the name of the service (KCDeploymentService. /username=”[user name]” You can specify the Windows account that will be used to run the service with the username parameter along with the password as shown in the following example: InstallUtil. \\<server name>\CaptureSV\Customization Deployment\MyModule\Custom. Kofax Capture 10 Developer’s Guide 115 . create a folder for the customization files that you want to deploy. so if a registration script unintentionally creates an endless loop.exe) are required. you must manually stop it.ocx" if errorlevel 1 exit errorlevel call regsvr32. Therefore. The following shows how one folder might contain both Custom.Deploying Customizations Setting Up a Customization Deployment Setting up a customization deployment involves creating subfolders in a server’s CaptureSV folder.exe /s "C:\Program Files\Kofax\Capture\Bin\WFAgent. For example. as explained below.exe and Custom. The following shows the contents of a sample registration file. During the deployment process. placing your customization files in appropriate subfolders. For example.exe) or the Kofax Capture Extension Registration Utility (RegAscEx. create the following folder: \\<server name>\CaptureSV\Customization Deployment In the “Customization Deployment” folder.exe /f "C:\Program Files\Kofax\Capture\Bin\WorkflowAgentWithOCX. you must create a batch file named “Registration.dll You can create more than one folder for deployment.AEX" if errorlevel 1009 exit errorlevel if errorlevel 1008 exit 0 You should write the script so that a successful exit returns a zero. if Microsoft registration utilities (Regasm. a registration script has 25 seconds to finish.dll" if errorlevel 1 exit errorlevel call RegAscEx.exe or Regsvr32. Registration may include both Windows components and Kofax files.dll. you might create a folder named “MyCustomModule”. If it does not finish. The deployment service will not terminate any registration script process. \\<server name>\CaptureSV\Customization Deployment\MyCustomModule_1\ \\<server name>\CaptureSV\Customization Deployment\MyCustomModule_2\ \\<server name>\CaptureSV\Customization Deployment\MyWorkflowAgent_1\ 3 If any of your customization files require registration.cmd” in your customization folder that contains any scripting needed to register your files. the deployment process fails.exe \\<server name>\CaptureSV\Customization Deployment\MyModule\Custom. and creating a time file.exe /s "C:\Program Files\Kofax\Capture\Bin\SampleWorkflowOcx. This folder should contain the executables and dlls that you want to deploy to multiple workstations. To set up a customization deployment 1 2 On a server. you might create three folders containing different customization files. call regsvr32. they must be available on the target system or you may want to include them in the deployment so that availability and system paths are not factors. Any exit failure should return a non-zero value. txt) and placing it in the customization folder as explained below. 116 Kofax Capture 10 Developer’s Guide . For subsequent deployments. If the time. The deployment will occur the first time the deployment service checks the folders after the specified time.txt” in the “Customization Deployment” folder.txt file in each of your customization folders. 2 Perform one of the following: For a first time deployment.txt file does not exist. Any additional lines are ignored. If the time file is not in the correct format. When you create or modify this file. The Kofax Capture Deployment Service uses the first line of this file to uniquely identify the customization during status logging. “mm” must be a value from 00 to 59. This time applies to all customizations across all sites.txt” and enter a version indicator on the first line. Its length is not checked or truncated. This gives the file a new time stamp and signals to the service that an updated deployment is ready. This time is an approximate time for deployment. and “mm” is the number of complete minutes since the start of the hour. and save the file. The following figure shows the contents of a sample Customization Deployment folder. The first line must contain a string that specifies the local time to deploy the customizations. Initiating a Customization Deployment When your customization files are in place. open Version. update the version string. Each deployment service running at each workstation will deploy the customizations at the specified local time. To initiate customization deployment 1 When you are ready for workstations to deploy a customization.txt. “hh” must be a value from 00 to 23. create a file named “Version. you are ready to initiate the deployment. The version string allows you to specify a version of the customization files so that you can distinguish between updates. no deployments will occur. no deployments will occur. The version string can be empty or lengthy. place a separate Version. The format of the string is: hh:mm “hh” is the number of complete hours that have passed since midnight. it signals to the deployment service that all files are in place and ready to be deployed. The Kofax Capture Deployment Service uses the time stamp of this file to coordinate deployments and prevent customizations from being repeatedly deployed.Chapter 10 4 Create a file named “time. Initiating the deployment involves creating a version file (Version. <deployment version string>. the deployment service adds a status entry to a log file named “deployedMMYY. MMYY is the two-digit month and year.txt” located in the “Customization Deployment\Logs” folder on the server. Each entry in the file is a single line with the following comma separated values: <Station ID>.<status> The comma-separated values allow you to import the file into Excel for sorting or other analysis.Deploying Customizations Figure 10-1. Table 10-1: Status Values Value Station ID Deployment name Deployment version string Status Description The station ID of the workstation where the deployment was attempted. Completed <date/time> Pending reboot <date/time> Failed <date/time>: <error> Where <error> is the error string returned when the file deployment fails.<deployment name>. Kofax Capture 10 Developer’s Guide 117 . The customization deployment folder name. The service automatically creates a new file at the beginning of each month. The first line from the version. The following table describes each value.txt file in the customization deployment folder. Sample Customization Deployment Folder Viewing Customization Deployment Status When a customization is deployed to a workstation. the completion of the deployment and the final move of the locked files takes place on the next system reboot. the deployment service writes to a local log file at: “<Application Data>\Kofax\Capture\Local\Customization Deployment\Logs. In this case. If the user reboots the system. Close the background program. the updates will take place. the deployment service only deploys customizations that were pending a reboot or failed on the last deployment attempt. and restart the stopped services once the deployment is complete. Instead. the deployment service will temporarily stop the services. If the user ignores the notification. 118 Kofax Capture 10 Developer’s Guide . it does not stop any processes. If customization files are only locked by services. Adds an entry to the deployment log file on the server with status indicating that deployment will complete pending a reboot. Note When a user reboots a workstation. but it will run again at system startup.Chapter 10 Note If the “\\<server name>\CaptureSV\Customization Deployment\Logs” folder is inaccessible. Reboot the system. If the deployment service detects that customization files are locked by interactive applications.” Deploying Customizations When Applications Are Running When the deployment service detects that customization files on a workstation are in use. the following actions occur on the workstation where the reboot is required: The deployment service: Sets any service that is currently locking customization files to manual startup but leaves it running. deploy the customization. The notification message displays once every 24 hours. it attempts to determine if they are locked only by service processes or if they are locked by some combination of services and interactive applications like Kofax Administration or Validation. The user can: Ignore the update message. it will no longer display an update message. If the user closes the background program. the background program continues to run and will display the message 24 hours later. Schedules the customization files to be moved on the next reboot (when the deployment service starts up). The customization deployment background program in the Windows notification area: Displays a message to the user indicating that updates are ready and a system reboot is necessary. On the server. To prepare for a deployment. Deployment Service Actions The following actions are performed by Kofax Capture Deployment Service. Customization has failed to deploy. Locally. Kofax Capture 10 Developer’s Guide 119 . Note Do not modify the contents of DeploymentStatus. Administrator Actions The following actions are performed by a system administrator on the server. on each workstation. After the deployment.txt. an administrator creates or updates one or more Version.Deploying Customizations About the Customization Deployment Process This section explains the basics of the customization deployment process for system administrators. This file contains a value that corresponds to one of the following status values. Customization was or is in the process of deployment. The deployment service uses this file to determine at what stage the deployment is in the process. an administrator creates and populates the “\\<server name>\CaptureSV\Customization Deployment” folder with the required files.txt”. the deployment service writes to a file in the client machine’s “<Application Data>\Kofax\Capture\Local\Customization Deployment” folder called “DeploymentStatus. Customization requires a system reboot to complete.txt files. Customization has successfully been deployed.txt” located in the “\\<server name>\CaptureSV\Customization Deployment\Logs” folder. To initiate a deployment. the Kofax Capture Deployment Service copies customization files from the “<Application Data>\Kofax\Capture\Local\Customization Deployment” folder to the workstation's Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin) and executes the registration scripts. at various steps in the deployment process. the Kofax Capture Deployment Service reports status to a log file on the server named “deploymentsMMDD. the Kofax Capture Deployment Service copies each customization folder in the “\\<server name>\CaptureSV\Customization Deployment” folder that contains a version file to a corresponding folder in the “<Application Data>\Kofax\Capture\Local\Customization Deployment” folder on each workstation. Table 10-2: Local Deployment Status Values Value 0 1 2 3 4 Description Customization has not been deployed. On each workstation. Chapter 10 KCN Server When synchronization occurs between the central site and remote sites, deployment files are copied to the Kofax Capture server folder at remote sites. Customization files then become accessible to remote workstations. A synchronization does not result in immediate deployments. The time that a customization is deployed is still determined by the time file. Status Each remote site’s deployment log will update to the central site as needed. When status is returned from the remote sites to a central site, it uses the following folder convention: \\<server name>\CaptureSV\Customization Deployment\Logs\<Site name><Site GUID>\deployedMMYY.txt 120 Kofax Capture 10 Developer’s Guide 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. Kofax Capture includes a module similar to the Quality Control module that you can use as a starting point for a customized Kofax Capture module. By using this module as a starting point, the task of creating a custom module is greatly simplified. You can take advantage of the existing panel, menus, and other features of the standard module to create a module of your own. The standard module also includes support for scanning, normally a difficult feature to implement. 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. Files for this feature (CustomStandard.exe, CustomStandard.aex, and online Help IDs.doc) are located in the Source\Sample Projects\CustMod\CustomStandard directory in your Kofax Capture installation folder. 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. The differences between using a custom standard module and using the generic custom module interface are listed below. Table A-1. Difference Between Custom Standard Module and Custom Module Custom Standard Module Starting Point To create a custom standard module, first copy the Kofax Capture CustomStandard.exe to a unique name. There is no need to create a Visual Basic .NET project and start from scratch. Kofax Capture Module Type Library (AcModule.dll) Custom Module A custom module is created as a new project and written in Visual Basic .NET. Data Access Kofax Capture Document Access (DBLite.dll) Kofax Capture Optimized Custom Module API (DBLiteOpt.dll) Runtime XML - read/write Setup XML - read-only Kofax Capture 10 Developer’s Guide 121 Appendix A Table A-1. Difference Between Custom Standard Module and Custom Module Custom Standard Module User Interface Custom Module Any of the Kofax Capture interface elements in The user interface is entirely the custom standard module can be written by the developer. suppressed. The following UI elements are included. Image Viewer Image Tools Toolbar Batch Contents Panel Batch Thumbnails Panel Scan Controls Panel Notes Panel Batch Tools Toolbar Batch Navigation Toolbar Batch Filters Toolbar Customizations are done using OCXs. Advantages Starting with a Kofax Capture module provides: batch editing and scanning an image viewer batch selection scan/import The module is designed and implemented by the developer. Disadvantages Registering in Kofax Capture is the same for both. Licensing All added code must use the OCX interface. The developer must write the entire application. RegAscEx.exe registers the .exe as a custom module. A Concurrent Station license is required only if pages are added. RegAscEx.exe registers the .exe as a custom module. A Concurrent Station License is required only if pages are added. Licensing Custom standard modules use the Kofax Capture licensing mechanism; a Concurrent Station License is required. Kofax Capture Optimized Custom Module API This is an easy-to-use custom module interface that allows fast retrieval and selective update of data. This API provides a mechanism that allows use of the Kofax Capture Document Access dynamic-link library (DBLite) to select and open a batch. However, once open, it is not necessary to export the data to XML. Instead, the code can retrieve an API object that acts like an XML element, but without XML. The code can selectively extract and update Kofax Capture data through this API. Because the data is processed selectively, execution is faster than XML importing and exporting. The actual organization of Kofax Capture data (the element and attribute structure) is identical between the XML and this new API. 122 Kofax Capture 10 Developer’s Guide Custom Module Sample The Kofax Capture Optimized Custom Module API is intended to be used for both custom modules and workflow agents. Because of the performance overhead with XML, we suggest that you use the optimized API whenever possible. Kofax Capture continues to support XML, which may still be better for developers with applications that are well suited to an XML interface. The Kofax Capture Optimized Custom Module API is implemented in the DBLiteOpt library (DBLiteOpt.dll). The complete API for the Kofax Capture Optimized Custom Module library is documented in the Kofax Capture API Reference Guide, which can be accessed in Windows from the Start | Programs | Kofax Capture menu. Kofax Capture Document Access This section gives you information about Kofax Capture Document Access, the component that allows you to integrate a custom module into your Kofax Capture installation. Kofax Capture Document Access makes it possible for the custom module to access batch information from Kofax Capture. Likewise, it allows your custom module to relay batch information from the custom module to Kofax Capture. The Kofax Capture Document Access dynamic-link library, DBLite.dll, is available from your < Kofax Capture installation>\Bin folder. Kofax Capture Document Access allows you to do the following: Route a Kofax Capture batch to a custom module for processing Use XML transport files to export/import batch information between Kofax Capture and a custom module Close a batch from a custom module and route it to the next module in the Kofax Capture workflow Although it is possible to access and modify batch data using Kofax Capture Document Access and XML, we recommend that you use the Kofax Capture Optimized Custom Module API because it provides a more efficient mechanism to selectively retrieve and manipulate data. A degradation in performance could occur when using XML to import and export data. The complete API for the Kofax Capture Document Access library is documented in the Kofax Capture API Reference Guide, which can be accessed in Windows from the Start | Programs | Kofax Capture menu. Note Some API methods and properties are reserved for exclusive use by Kofax. These APIs are not documented and their use is not supported. These items are not displayed when browsing the API definitions. Development Environment To develop a custom module that is compatible with Kofax Capture, you need the following tools for the setup OCX (optional) and runtime executable. Kofax Capture 10 Developer’s Guide 123 NET Kofax Capture Administration module type library. Located in your < Kofax Capture installation folder >\Bin folder.NET that allows you to create an instance of a COM interface.Appendix A Setup OCX Tool such as Visual Basic . A degradation in performance could occur when using XML to import and export data. DBLiteOpt. To install the sample custom module files 1 2 3 Start Windows Explorer and browse to the <Kofax Capture installation folder>\Source\Sample Projects\CustMod\Generic folder.dll. Custom module testing with Kofax Capture has been certified with Visual Basic . Installing the Sample Custom Module This section explains how to install the files required to register and run the sample custom module. is available from your <Kofax Capture installation>\Bin folder.dll. so you can use it as an Kofax Capture processing queue. also allows your custom module to relay information about batches to Kofax Capture. Custom module testing with Kofax Capture has been certified with Visual Basic . the COM object that allows your custom module to access batch information from Kofax Capture. Copy the following files from the CustMod folder to your Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin): CMSample. the file is ACAdMod. Registering the Sample Custom Module This section explains how to use the Custom Module Manager to register the sample custom module. Kofax Capture Document Access. This API provides the mechanism to use the Kofax Capture Document Access library that is used to select and open a batch. Runtime Executable Tool such as Visual Basic .NET. we recommend that you use the Kofax Capture Optimized Custom Module API because it provides a more efficient mechanism to selectively retrieve and manipulate data. 124 Kofax Capture 10 Developer’s Guide .exe Note If you are customizing Kofax Capture under the Windows Vista operating system. DBLite. The Kofax Capture Document Access dynamic-link library. Kofax Capture Optimized Custom Module. is available from your <Kofax Capture installation>\Bin folder. Although is it possible to access and modify batch data using Kofax Capture Document Access and XML.aex CMSample.dll. The Kofax Capture Optimized Custom Module dynamic-link library. you must have Administrator privileges in order to install files to the Kofax Capture installation folder. Display the contents of the Generic folder. the API that allows your custom module to selectively and quickly retrieve data from Kofax Capture.NET that allows you to implement a COM interface. create or open a batch class for which you want to include the sample custom module in the workflow. The Custom Modules window will display. To add the sample custom module to the batch class workflow 1 2 3 4 From the Administration module. The name of the newly registered custom module “Sample” will appear in the Custom Module Manager window. in the System group. which you copied earlier to the Kofax Capture Bin folder. Just select the custom module from the list of Available Queues and click Add. You can now view the properties for the registered custom module sample. Click OK to close the window. see Chapter 4 – Creating a Registration File. For detailed information about the format for the registration file. Publish the batch class. it will be available for selection as a batch class processing queue from the Create Batch Class and Batch Class Properties windows. To register the sample custom module 1 2 3 4 5 6 From the Administration module’s Ribbon. You can select it as a processing queue for a batch class. you can move it to any position within the list of Selected Queues after Scan and before Export. The Custom Module Manager window will display. From the Custom Modules window. and click Open. The Open window will display. select Sample and click Install. When you move the custom module to the list of Selected Queues. The properties are defined in the registration file (CMSample. click Add. onthe Tools tab. Select the batch class name from the Definitions panel and right-click to open the Properties Queues tab. and then add Sample to the list. check the results log on the Publish window. Notice that “Sample” appears in the list of Available Queues. Click Close to exit the Custom Modules window. For example. From the Open window.aex. just like any other processing queue. From the Custom Module Manager window.aex). A message will appear to confirm that the registration process is complete. which is explained in Chapter 4 – Creating a Registration File. Ensure that Scan appears on the Selected Queues list. click Custom Modules. it will be inserted according to the valid processing order. When you publish the batch class with the custom module in its workflow. Click OK to clear the confirmation message. select CMSample. Therefore. browse to the Bin folder. Kofax Capture 10 Developer’s Guide 125 . the Sample custom module is defined to follow Scan and precede Export. according to its processing function.Custom Module Sample Note You can also register custom modules with the Kofax Capture Extension Registration Utility. Be sure that no errors or warnings are associated with the custom module. 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). Adding the Sample to the Batch Processing Workflow Once a custom module is successfully registered. create a batch as described in Creating a Batch to Open in the Sample Custom Module on page 126. select the batch that is ready to open in the sample custom module. the options for opening a batch are slightly different. in the Batch group. 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.exe from the Kofax Capture Bin folder (<Kofax Capture installation folder>\Bin). the setup data includes the standard administrative data. If you use Batch Manager to start the custom module. you can launch the custom module and process the batch from Batch Manager. If you did not launch the sample from Batch Manager. 5 6 Processing by Document The previous section explained how to open a batch in the Sample custom module using the “By Batch” process mode. image cleanup. If desired. click Process Batch. click Open Batch # (where # is the incremental batch identification number) to open the batch. Scan the batch and close it. recognition profiles. The Sample custom module starts and appears on the desktop. rather than the entire batch. To enable the “By Document” process mode 1 In the Scan module. including export connectors. Be sure that the batch includes documents. from which you can select the desired batch. The setup data includes information about the batch class properties. and more. including a batch that includes a custom module in its workflow. Select “By Batch” as the process mode. and click OK. If you launched the sample from Batch Manager. If desired. you can view the status of any batch. see Processing by Document on page 126. the custom module is available from the list queues for batches that have the custom module defined as part of their workflow. do one of the following: Click Open Next Batch to open the next available batch. 126 Kofax Capture 10 Developer’s Guide . For this demonstration. This mode allows you to open a specific range of documents in a batch. Click Select Batch to display the Open Batch window. Your implementation will probably include a setup OCX to provide batch class configuration settings and publish checks associated with a custom module. and on the home tab. select the Include Setup Data check box to import the batch class setup data along with the batch data. you can redirect a batch to a custom module from Batch Manager. You can also process a batch with the “By Document” process mode. Start the sample module in one of the following ways: Double-click CMSample. For information about the “By Document” process mode. In addition. 4 If desired. Start Batch Manager. To create and open a batch 1 2 3 Start the Scan module and create a batch based on the batch class you published.Appendix A Using Batch Manager With a Custom Module From Batch Manager. you can only read the value. process a batch that uses the CMSample custom module. the sample custom module uses a runtime XML file called RTExport. Kofax Capture 10 Developer’s Guide 127 . 6 7 8 9 Click the Open Documents button.xml is used. If the batch is closed. Under Process Batch. the options for selecting and opening a range of documents are grayed on the window. To get the Batch Custom Storage string 1 2 3 4 From Batch Manager. click Copy XML or Corrupt XML. using the “Open Batch n” button. Select the option to open the batch. another XML file called RTImport. When the sample module window displays. To set the Batch Custom Storage string 1 2 3 4 From Batch Manager. When batch information is imported back to the database after processing in the custom module. Note If the batch has no documents. select a range of documents to process in the sample custom module. 10 Click Close Batch. Open the batch using the Sample window. The name and value will be set in the batch. process a batch that uses the CMSample custom module. Click Close Documents. Open the batch using the Sample window. To test this capability. select “By Document” as the process mode and select the “Include Setup data” check box. Click Get. click Copy XML or Corrupt XML. see XML Transport Files on page 127. Type the name of the batch custom storage string in the name field. For more information.xml to list Kofax Capture database information that the custom module uses. use the following procedure. For example.Custom Module Sample 2 3 4 5 Start the sample custom module as described in Creating a Batch to Open in the Sample Custom Module on page 126. 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. using the “Open Batch n” button. Click Set. Under Process Documents. Type a Name and a Value in the appropriate fields. At Open documents. 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. Any modifications that you make to the XML format are validated by Kofax Capture to ensure compatibility. xml. The Sample custom module includes a mechanism to demonstrate the effect of XML content that is incompatible with Kofax Capture. When the “By Document” process mode is enabled. and the first batch element. unless it is suspended or closed in error.xml.xml. When you select Corrupt XML. Suspended. Click the Close Batch button. To copy the XML files back to Kofax Capture 1 Click the Copy XML button. A set of Document Type Definition (DTD) files are also generated. AcDocs. Error) in which the batch should be closed.dtd. 2 3 Corrupt XML Even if the XML format is technically “valid” and “well-formed. RtImport. a separate file (DcExport. If desired. You can click the Corrupt XML button to intentionally insert an incompatible text string in one of the XML import files. The batch is routed to the next module in the Kofax Capture workflow. you can open them in any text editor.xml.xml) is generated with the document information. you can select a state (Ready.xml: Contains configuration settings and publish checks associated with the custom module.dtd files appear in the Kofax Capture installation folder. These files are used to import batch information to Kofax Capture from the sample module.xml: Contains Kofax Capture database information related to the current batch. SuExport. The configuration information is relayed between Kofax Capture and the custom module via files called SUExport. This file is generated if you selected the “Include Setup data” check box before opening the batch.Sample folder: RtExport.xml file.xml file. 128 Kofax Capture 10 Developer’s Guide . Notice that additional import files are generated in the Kofax. DcExport. the batch will be suspended when you close it. and AcSetup. Once the batch is open. A message will display with text explaining that the error is related to the import process.Sample folder: DcImport.) The . you can click the Corrupt XML button to insert a similar string in the RtImport. and SuImport. If you are processing in the “By Batch” mode.xml: Contains Kofax Capture database information related to selected documents in the batch. the following files are generated in the Documents and Settings\All Users\Application Data\Kofax\Capture\Local\Kofax. the batch will not be routed to the next queue in the Kofax Capture processing workflow. If you want to examine these DTD files in detail.Appendix A The sample module uses the standard Kofax Capture configuration settings.xml and SUImport. RtExport. (The AcDocs. you can click the Corrupt XML button to insert an incompatible text string in the DcImport.” the content may not be compatible with Kofax Capture. If you are processing in the “By Document” mode. The DTD files list the required XML format that Kofax Capture requires: AcBatch. This file is generated only if you select the “By Document” process mode.dtd.xml includes data related to all the documents in the batch.dtd file is generated only if you opened the batch in the “By Document” mode. When the “By Batch” process mode is enabled. When the XML format is not compatible with Kofax Capture.dtd. the KofaxCaptureRuntime root element. You will probably implement a setup OCX to define additional custom configuration and property settings associated with custom module functionality. To create a page or a document. You can open the RtImport. the Process mode must be set to “by Batch. a document and page will be added to the XML file. Kofax Capture 10 Developer’s Guide 129 .Sample folder to see the added lines.” Clicking the Create Page button adds a new page to the XML file.Custom Module Sample Create Page The Create Page button allows you to create a page or a new document. If “Create page in new document” is selected.xml file in the Kofax. Appendix A 130 Kofax Capture 10 Developer’s Guide . The name of this sample is “Validation Workflow Agent. This folder contains a Visual Basic .aex). and then register the agent. you must have Administrator privileges in order to install files to the Kofax Capture installation folder. Note Workflow agents are very similar to custom modules. Kofax Capture 10 Developer’s Guide 131 . Note If you are customizing Kofax Capture under the Windows Vista operating system. as well as change the routing (next module) and status for the batch. If all the documents in a batch meet the confidence level. 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. The sample supports a setup OCX that adds a new menu item (Validation Workflow Properties) to the Batch Class context menu. Workflow agents consist of a runtime module and optional setup program. the Validation module (and Verification module.Appendix B Workflow Agent Sample Introduction This appendix walks you through the process of installing. Workflow agents are invoked whenever a batch is closed from any module. This folder also contains a compiled version of this Project. At runtime. you must write the necessary code. and using the sample workflow agent provided in your Kofax Capture product package. registering. and the windows for registering workflow agents are nearly identical to those for custom modules.” A workflow agent is a custom application that has the ability to examine and modify batch data.NET Project for both a Workflow Agent and Setup OCX. Installing the Sample Workflow Agent This section explains how to install the files required to register and run the sample workflow agent. You can specify the confidence level with extensions added by the Workflow Agent setup OCX. if applicable) is skipped. Prior to using a workflow agent. and the associated sample Kofax Capture Registration File (. You can find the sample workflow agent application in the \Kofax\Capture\Source\Sample Projects\Workflow\WFSample folder. see Chapter 7 – Custom Extension Registration. Copy the following files from the WFSample folder to your Kofax Capture Bin folder (Kofax Capture installation folder>\Bin): WorkflowAgentWithOCX. From the Workflow Agent Manager window. The name of the newly registered workflow agent “Validation Workflow Agent” will display in the Workflow Agent Manager window. 132 Kofax Capture 10 Developer’s Guide .aex. Click OK to clear the confirmation message. Click Close again from the Workflow Agent Manager window. A message will appear to confirm that the registration process is complete. From the Open window. Using the Sample Workflow Agent This section explains how to use the sample workflow agent in a batch class. select Validation Workflow Agent and click Install. select WorkflowAgentWithOCX.aex). Click Close to exit the Workflow Agents window. From the Workflow Agents window. 7 8 9 Click the Properties button to open the Workflow Agents Properties window . Click the General and Programs tabs to familiarize yourself with the other properties for the sample workflow agent. in the System group. on the Toolstab.dll Registering the Sample Workflow Agent This section explains how to use the Workflow Agent Manager to register the sample workflow agent. click Add. You can now view the properties for the registered workflow agent. Note You can also register workflow agents with the Kofax Capture Extension Registration Utility.ocx WFAgent. and click Open. Display the contents of the WFSample folder.Appendix B To install the sample workflow agent files 1 2 3 Start Windows Explorer and browse to the Kofax\Capture\Source\Sample Projects\Workflow\WFSample folder. so you can use it in Kofax Capture. The Open window will display. The Workflow Agent Manager window will display. browse to the Bin folder. select Workflow Agents. The properties are defined in the registration file (WorkflowAgentWithOCX. and then click Close.aex SampleWorkflowOcx. To register the sample workflow agent 1 2 3 4 5 6 From the Kofax Capture Administration module’s Ribbon. For detailed information about the format for the registration file. The Workflow Agents window will display. which you copied earlier to the Kofax Capture Bin folder (Kofax Capture installation folder>\Bin).General tab. right-click to display the context menu. Click OK to close the Batch Class Properties window From the Definitions panel. Select Validation Workflow Properties. 9 10 Publish the batch class. If the confidence level for all the documents in your batch meets or exceeds this setting.” Move the slider to the desired confidence level. Select the batch class name from the Definitions panel and right-click to open the Batch Class Properties window . Ensure that Scan. Kofax Capture 10 Developer’s Guide 133 .Workflow Agents tab . the Validation module (and Verification module if it is part of the batch class) will be skipped. Click OK. create or open a batch class for which you want to include the sample workflow agent. Select “Skip validation if the confidence for all fields is at least.Workflow Agent Sample To use the sample workflow agent 1 2 3 4 5 6 7 8 From the Administration module. From the Batch Class Properties window .Queues tab. Validation and other modules as appropriate appear on the Selected Queues list. select “Validation Workflow Agent” and click Add to move it to the Selected Workflow Agents list. The Validation Workflow Properties window will display. Appendix B 134 Kofax Capture 10 Developer’s Guide . 12 Kofax Capture . 29 customizations deploying.NET field. 82 registering with Administration module. 101 C COM servers. 108 export connectors API library. 12 Kofax Capture Export Type Library. 99 KTM. 55 custom panels. 12 DBLiteOpt. 83 installing. 97 toolbars. 13 deploying customizations. 41 Setup Programs section.NET Scripting Library. 82 Kofax Capture Export Type Library. 54 removing. 49 ModuleName section. 12 ScriptInterface.dll. 98 runtime executable. 108 setup. 97 installation. 77 registry keys.dll. 98 menu items. 46 Workflow Agents section.dll.dll. 113 development API Kofax Capture Admin Module Type Library. 55 E error DWORD values. 86.htm. 107 docking location custom panels.dll. 85 registration. 90 user interface design. 88 document routing. 12 DBLite. 34 validation. 13 AcSetup. 113 customizing software needed for. 84 custom scripts. 12 ACModule. 24 validation. 83 visible flag. 13 AcDocs. 29 software requirements. 12 ACWFlib. 91 sample. 15 custom scripts.dll. 46 API library ACAdMod. 29 recognition.htm. 57 custom extensions development tasks.htm. 97 setup OCX. 12 setup OCX development. 111 command line parameters custom extension registration.Index A Aex file example. 47 Setup section. 29 testing. 12 Kofax Capture Optimized Custom Module API. 107 process. 81 registration. 47 Workflow Agent Name section. 11 D data layout files AcBatch. 12 Kofax Capture Custom Workflow Interface. 41 Menu Bar section. 80 menus. 80 publish checks. 108 Kofax Capture 10 Developer’s Guide 135 .dll. 81 custom menus. 12 Kofax Capture Document Access. 49 Menu section. 110 requirements. VB . 76 export connector setup. 86 menus. 42 Modules section. 12 AscRel. 12 Kofax Capture Module Type Library. SBL recognition. 50 format. 57 custom extension registration command line parameters. 83 custom modules properties. 132 workflow agents. 15 Softbridge Basic Language. 109 removing custom module. 77 RegSvr32. 83 custom extensions. 92 related documentation. 83 standard. 107 Module Type Library. 79 Softbridge Basic Language (SBL) vs Visual Basic. 77 terminology. 12 Admin Module Type Library. 113 Document Access. 84 P panels. 97 custom panel.NET Scripting API. 57 F Fluent UI add ribbon tab. 26 return codes.Index source for standard connectors. 82 loading. 72 writing. SBL. 50 custom tabs. 91 registration custom extensions. 91 SBL Editor/Debugger. 107 standard. 91. 56 registration file See Aex file registry entries keys. 81 136 Kofax Capture 10 Developer’s Guide . 82 Custom Workflow Interface. 109 ReleaseSetupData object. 76 unloading. custom see custom panels publish checks custom extensions. 24 process. 13 H help for Kofax products. 30. 85 panels. 54 menus custom. 79 designing. 81 ribbon. 12. 12 Deployment Service. 91 file format for custom extensions.exe. 15 recognition. 24 RegAsm. 26 system variables. 124 custom panels. 15 separator menu bars. 48 commands. 86 tab registry keys. 80 for custom panels. 90 registration. 76 menu. 24 functions. 12 ribbon bar. 15 validation. 107 R recognition scripts. 12. 27 writing. 71 setup panel. 86 registry keys custom extension setup OCX. 10 M managing extensions Administration module. 98 custom module sample. 71 development APIs. 25. 10 K Kofax training. 101 DeleteEvenPage. 51 tab registry entries. 55 workflow agent. 9 ReleaseData object. 41 workflow agent sample.NET Scripting Library. 12 S sample custom module CMSplit. 12 Export Type Library.exe. 80 setup OCX. 20 support site. 37 . 18 scripts. 85 O OCX custom extension setup. 83 Optimized Custom Module API. 10 Kofax Capture . 102 sample custom panel. 12. 97 OCX panels custom. 80 tab. 78 registry keys. 15 about. custom SBL about. 79 workflow agent example. 128 Kofax Capture 10 Developer’s Guide 137 . 20 W workflow agent designing. 18 functions. 32. 22 testing.xml. 132 X XML files. 128 XML transport files DcExport. 81 training. 18 return codes. 98. 16 process. 36 sample. VB . 56 registering with Administration module. 22 system variables. 128 RtExport. 127. 10 V validation scripts. 61 properties. 132 using.xml.Index T toolbars custom extensions. 128 SuExport. 15 validation scripts. 62 setup OCX. 30. 38 Visual Basic vs. 15 field macros. 56 removing. 15 about. SBL. 62 workflow agent sample installing. 62 VB .NET code project settings. 57 runtime module. 131 registering. 17.NET creating.xml. 19 writing. Softbridge Basic Language (SBL). Index 138 Kofax Capture 10 Developer’s Guide .