EMC® Captiva® Taking the Mystery out of Scripting in

Captiva Capture 7 Version 1.0

EMC Corporation

Corporate Headquarters

Hopkinton, MA 01748-9103

1-508-435-1000

www.EMC.com

Legal Notice

Copyright © 1994-2014 EMC Corporation. All Rights Reserved.

EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. Adobe and Adobe PDF Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarks used herein are the property of their respective owners.

Table of Contents

Contents 1 SCOPE ............................................................................................................................................................ 4

2 OVERVIEW ..................................................................................................................................................... 4

3 FORMS OF CLIENT SCRIPTING ......................................................................................................................... 4

3.1 CLIENT SCRIPTING ............................................................................................................................................... 4 3.2 PROFILE SCRIPTING ............................................................................................................................................. 7

3.2.1 Modules which use Profile Scripting ...................................................................................................... 7 3.2.2 Profile Scripting capabilities by module type ......................................................................................... 9

3.3 RECOGNITION SCRIPTING ................................................................................................................................... 13

4 FORMS OF TASK SCRIPTING ......................................................................................................................... 15

4.1 .NET CODE MODULE ........................................................................................................................................ 15 4.1.1 .NET Code Module Namespace ............................................................................................................ 16

4.2 CAPTUREFLOW SCRIPTING .................................................................................................................................. 17 4.2.1 CaptureFlow Scripting Namespace ...................................................................................................... 17

4.3 WHEN TO USE ONE OR THE OTHER ....................................................................................................................... 19

5 FINAL Q AND A TOPICS ................................................................................................................................. 21

4

1 SCOPE The goal of this document is to help clarify the various forms of scripting available in the Captiva 7.x release. The scripting support in C7 is a result of an evolution in scripting models, including some new forms of scripting as well as some legacy models. This mixture of old and new has led to some confusion which this white paper will help clarify. This white paper is not a replacement for the documentation, nor will this white paper give concrete scripting examples, but it will help the reader to sort out the differences and capabilities of each form of scripting and set the reader on the right path.

2 OVERVIEW Fundamentally there are two forms of scripting. One form is related to client modules and runs in conjunction with the task that is processed by that module. This form of scripting is very specific to a particular client module, as the scripting API allows interaction with that module’s data objects and behaviors which are unique to that module. Examples of this form of scripting are Profile Scripting, Client Scripting, and Recognition Scripting.

The other form of scripting is related to CaptureFlow processing. It is not related to any particular module, but instead is a means to enhance the ability of the CaptureFlow to apply complex logic to the processing of the batch through actual code written by the CaptureFlow developer. Depending on the requirements, this form of scripting can be added directly into the CaptureFlow and will run on the InputAccel Server (IA Server), or for more demanding applications the scripting can run on any client machine as a generic step in the CaptureFlow. Examples of this form of scripting are CaptureFlow Scripting and .NET Code Module Scripting.

All of these various forms of scripting will be further explained in this white paper.

3 FORMS OF CLIENT SCRIPTING There are three general categories of client-based scripting. The reason for having these different categories has to do with the origins of the client modules they pertain to. Different categories of modules have different origins and timeframes in which they were developed, and this is reflected in the capabilities offered by each scripting model. The three categories described below are Client Scripting, Profile Scripting, and Recognition Scripting.

3.1 Client Scripting

Client Scripting (also known as Client-Side Scripting) is a legacy scripting introduced for select modules based on the latest “QuickModule Runtime” architecture that was introduced in Captiva Capture version 6.0. The modules which support Client Scripting include:

• ScanPlus/RescanPlus • IndexPlus (deprecated) • NuanceOCR • Documentum Advanced Export • Web Services Input/Output

5

Each of these client modules supports the general QuickModule Client Scripting API (with a few exceptions for ScanPlus/RescanPlus) as well as module-specific APIs to further customize the module behavior. Below are the namespaces for each module:

Module Scripting Namespace

ScanPlus/RescanPlus Emc.InputAccel.ScanPlus.Scripting

IndexPlus (deprecated) Emc.InputAccel.IndexPlus.Scripting

NuanceOCR Emc.InputAccel.NuanceOCR.Scripting

Documentum Adv. Export Emc.InputAccel.DocumentumExport.Scripting

Web Services Input/Output Emc.InputAccel.WebServices.Scripting

<All of the above> Emc.InputAccel.QuickModule.ClientScriptingInterface

The module-specific namespaces above provide interfaces to module-specific data and behaviors.

The common namespace Emc.InputAccel.QuickModule.ClientScriptingInterface provides access to a powerful set of interfaces to manipulate batch data, structure, and stage files.

Please refer to documentation section Scripting Guide > Client Scripting Guide for more details.

Client Scripting Quick Summary

Languages Supported Visual C# and Visual Basic (.NET)

Script Editor Microsoft Visual Studio

Alternatively, simple “text scripts” can be written within the built-in script editor on the Scripting tab of module setup UI.

Script Location Compiled Client Scripts (using Visual Studio) are initially uploaded to IA Server (ultimately stored in the IA Database) during setup of the corresponding module step in the CaptureFlow. When a client module processes a task requiring a script, the necessary script files are downloaded from the IA Server to the client machine.

Text scripts coded directly in the module’s built-in script editor are saved only within the CaptureFlow step configuration and therefore are only available to that CaptureFlow step.

Script Name There is no predefined naming convention for these script assemblies. Any number of uniquely-named assemblies and optional files (accessed by the script) can be uploaded/downloaded, but a CaptureFlow step can only be

6

configured to use one particular script assembly name.

Script Scope Compiled client scripts are uploaded to the IA Server and are globally available to all client modules which support them.

The granularity of configuration is a single step in a CaptureFlow. That is, each step in each CaptureFlow can be configured to use a specific script file for Task Events. See special note below regarding Module Events.

If multiple steps in the same or different CaptureFlow are configured to use the same script file, uploading a new version of that script file to the IA Server will affect all steps which reference it.

Text scripts are embedded within each step of a CaptureFlow. Updating the code in a text script only affects the particular step in the particular CaptureFlow that is being edited.

Special note on Module Events: A client-script can contain code for Task Events and/or Module Events. When Task Events are configured on a step, those settings apply only to that step in that CaptureFlow.

However, when Module Events from a script file are configured on a step, those settings apply globally to every instance of that module, and will overwrite any previous definition of Module Events.

For example, if you configured CaptureFlow “A”, step “s” to use a script file named “MyScript.dll” and you mapped both the Task Events and Module Events to this DLL, the result would be that the code for the Task Events would be executed only when using the particular CaptureFlow and step that you configured, but the code for the Module Events would be executed every time you ran that module, independent of any particular CaptureFlow.

The reason for this difference is that Module Events must run outside the context of task processing, so the configuration of Module Events must be stored globally on the IA Server for the module itself, and not within any particular CaptureFlow setting.

Documentation Scripting Guide > Client Scripting Guide

API Reference Scripting Guide > Client Scripting Guide > Programming Reference

Direct access to batch data and structure

Yes, through namespace:

Emc.InputAccel.QuickModule.ClientScriptingInterface

7

3.2 Profile Scripting

Profile Scripting is the most recent form of client module scripting, first introduced in Captiva Capture 7.0. In some respects, Profile Scripting is comparable to the older Client Scripting in that both run on the client machine in conjunction with a task processed by a client module, and both provide access to module-specific events, methods, and properties to further customize the module behavior for a given task.

The primary difference between them is that the legacy Client Scripting additionally provides access to batch data and structure, as well as methods to manipulate the batch structure, whereas Profile Scripting does not offer direct access to general batch data or batch structure, as that is outside the scope and intent of Profile Scripting. Essentially the capabilities of the older Client Scripting have been split into the newer Profile Scripting for customization of module runtime behaviors, and Task Scripting for access batch data and batch structure.

3.2.1 Modules which use Profile Scripting

In the Capture Capture 7.0 and 7.1 releases, the following modules utilize Profile Scripting, with each module supporting a unique set of classes, properties and methods appropriate to that module:

• Image Processor • Extraction • Captiva Desktop

As new modules are created for Captiva Capture in the future, each will be evaluated to determine if it could benefit from some form of Profile Scripting, possibly resulting in new scripting APIs being defined for that module. Note that some new modules will not require scripting extensions. For example, the Standard Export module introduced in Captiva Capture 7.0 does not utilize Profile Scripting, as the module behavior is already sufficiently configurable through conditional behaviors controlled by expressions defined in the Export Profile.

Profile Scripting Quick Summary

Languages Supported Visual C# and Visual Basic (.NET)

Script Editor Microsoft Visual Studio

Script Location Compiled Profile Scripts are uploaded to IA Server (ultimately stored in the IA Database) through the Captiva Designer feature known as “Deployment Files”.

When a client module processes a task requiring a script, the necessary script files are downloaded from the IA Server to the client machine.

Profile scripts can contain code for multiple different document types and/or super filters. Beginning with Captiva Capture 7.1 this code can also be distributed among multiple script DLLs following a specific naming convention (see Script Name section).

8

EXCEPTION: If custom image processing filters are created in an assembly named Custom.ImageFilter.<yourname>.dll (this is not common) the assemblies must be manually copied into the “binnt” folder of each machine where it will be used.

Script Name Profile script assemblies must use one of the following naming conventions:

in Captiva Capture 7.0 or later:

Custom.InputAccel.UimScript.dll <or>

ISV.InputAccel.UimScript.dll

Additionally in Captiva Capture 7.1 or later: Custom.InputAccel.UimScript.<yourname>.dll

NOTE 1: you are still required to have Custom.InputAccel.UimScript.dll with at least a “ScriptMain” class before you can use additional assemblies with the <yourname> suffix.

NOTE 2: use of ISV.InputAccel.UimScript.dll is intended for solutions offered by independent software vendors.

EXCEPTION: Custom image processing filters are not really profile scripts, but a special case and therefore must be created in an assembly named Custom.ImageFilter.<yourname>.dll (this is not common) and manually copied to workstations.

Script Scope Since all module steps of all CaptureFlows will load the same profile script assembly files, the content of these script files is globally shared.

However, the code within these script files is written to be unique for each Document Type (or Super Filter), such that unique behaviors per step or per CaptureFlow can be achieved through the use of different Document Type names.

Documentation+Events Scripting Guide > Profile Scripting

API Reference Scripting Guide > Profile and Task Scripting API Reference

Direct access to batch data and structure

No*

* While there is no direct access to batch data within Profile Scripting context, it is possible to provide some batch data to the Profile script through the use of an IA value named StepCustomValue. This value exists at task level for any module supporting Profile Scripting, and is a general purpose string which can be uniquely populated per task by the CaptureFlow. For example, a simple value assignment in the CaptureFlow diagram could populate it with any desired batch data, or a more “just in time” approach could be achieved by populating this value through CaptureFlow Scripting code in the <step>_Prepare event of the step which will need the data. The Profile Script will then have access to this value for use in the logic.

9

Additionally, Profile Scripting offers the ability for the script code to generate and write back custom data values to the batch. Both the Extraction and Captiva Desktop modules use the TaskValues dictionary object property which can create dynamic values in the batch. The Image Processor module can use the outValues dictionary object property on the ExecuteSuperFilter method to populate existing MDF values in the batch. Please refer to the documentation for more details on these properties.

3.2.2 Profile Scripting capabilities by module type

3.2.2.1 Image Processor

Note that Profile Scripting for this module is also referred to as “Image Processing Scripting”.

• Custom.InputAccel.UimFilterScript namespace provides capabilities to implement a context-sensitive override of the sequence and application of image processing filters as defined in the Image Processing Profile. For example, certain filters can be conditionally skipped or the sequence of filter processing can be dynamically altered. This namespace can be included within the Custom.InputAccel.UimScript.dll assembly along with any other Document Type scripting code and will be automatically deployed to client machines once it is properly deployed to the IA Server through Captiva Designer.

• Emc.InputAccel.ImageFilter namespace provides a means to create custom Image Processing filters, for example to integrate a 3rd party image processing library. Custom filters also support custom configuration options, and appear directly in Captiva Designer when configuring an Image Processing Profile. IMPORTANT: All code related to custom Image Filter implementations must be compiled into an assembly named Custom.ImageFilter.<yourname>.dll and manually copied into the InputAccel\Client\binnt folder of the machine used for Captiva Designer as well as any client machine where Image Processor will run and attempt to use the custom filter. Unlike other scripts, this particular assembly must always be manually copied and cannot be deployed automatically.

3.2.2.2 Extraction

Note that Profile Scripting for this module is also referred to as “Document Type Scripting”, or sometimes informally as “UIM Scripting”.

Extraction uses the same scripting namespace as Captiva Desktop, with the exception that interfaces relating to the user interface (form and controls) are only accessible from Captiva Desktop.

Below is a summary of the non-UI interfaces available to both Extraction and Captiva Desktop.

• Emc.InputAccel.UimScript namespace provides a set of classes, properties and methods which facilitate scripted interactions with the data coming from the Extraction and Captiva Desktop modules. Please refer to the documentation on this namespace for complete details on all the interfaces provided, but below you will find a subset of the most important ones relating to Extraction:

10

o IUimDataContext interface provides access to details about the current document being processed, as well as certain methods to affect the processing, such as:

Document Type Name Field Names Temp Directory Path StepCustomValue (a means for the CaptureFlow to supply additional

data to the task) Task Values Methods to gain access to individual field objects Methods to run validation rules Methods to suppress validation rules Methods to affect validation rule error messages

o IUimFieldDataContext interface provides access to field-specific properties

and methods such as Whether field is array field or not Array index of an array field Actual “raw” text of a field (underlying value before processing by doc

type rules and expressions) Actual type-specific value of the field (after processing by doc type

rules and expressions) Field flags Validation or Confirmation state of the field Validation exception currently thrown by the field Name of table section to which the field belongs Name of the field Node ID of the page from which the field was extracted Method to indicate field value has changed, or that field needs

character repair Method to parse a field, or apply predefined formatting to it Method to set or clear the validation error on a field Method to set or clear the confirmation status of a field Method to set the value of the field

o IUimNodeData interface provides access to details about the task node’s

context within the batch, such as Batch ID of the batch containing this node Level of the node within the batch (page level, document level, etc) Node ID of the node Task values of the task Method to get complete set of documents belonging to this node (for

example, if triggered at folder level, returns all child document nodes)

o IUimTableSectionControl interface provides access to details about the particular table section, such as

DataContext (document instance) that own the current section Number of Rows in the table Name of the Table Method to clear the table Method to insert or delete a row in the table Method to get all field names in the table section

11

3.2.2.3 Captiva Desktop

Note that Profile Scripting for this module is also referred to as “Document Type Scripting”, or sometimes informally as “UIM Scripting”.

Captiva Desktop uses the same scripting namespace as Extraction, with the exception that interfaces relating to the user interface (form and controls) are only applicable to Captiva Desktop.

Below is a summary of the additional UI-related interfaces available only to Captiva Desktop.

See previous section on Extraction for the non-UI interfaces.

• Emc.InputAccel.UimScript namespace provides a set of classes, properties and methods which facilitate scripted interactions with the data coming from the Extraction and Captiva Desktop modules. Please refer to the documentation on this namespace for complete details on all the interfaces provided. Captiva Desktop supports the same interfaces as Extraction (described above), with some additional interfaces described below which are unique to Captiva Desktop and the UI of the form it displays:

o IUimDataEntryFormContext interface provides access to elements of the data entry form, such as Access to the name of the form Access to the entire document data object bound to the form Method to find UI controls using the name of field to which it is bound Method to find UI controls using the name of the control Method to find a named section in the form by section name Method to get an array of all controls on the form Method to get/set the tooltip for a control by name Method to get/set the caption text of a control by its bound field name Method to update the content of all form controls to show latest values Method to show/hide a control by specifying its bound field name

o IUimFormControlContext interface provides properties and methods

related to UI controls on the data entry form, such as Access to the text of a selected choice (for choice-based control) Access to the name of a control Access to the arbitrary “custom value” property of a field as defined in

the Document Type definition Access to the form section which contains the given control Access to the current enabled/disabled status of a control Access to the current hidden/displayed status of a control Access to the current read-only/editable status of a control Access to the form (parent form) which contains the given control Access to a table row’s index Access to a control’s currently displayed text value (may not be same

as the bound field’s current value) Method to enable/disable a specific control Method to access the data field object using the bound UI control

name Method to access the data field object using the field name Method to get the choice names from a list box for drop-down list box

12

Method to determine whether the value of control is bound to a given data field

Method to force the current selection of a list item by its index Method to set/clear the read-only state of a text box control Method to set focus to a given control Method to fill the choices (both display name and returned value) for a

list box or drop-down list box Method to set the text for a control Method to show/hide a control

o IUimFormSectionContext interface provides properties and methods

related to table sections on the data entry form, such as Ability to get/set a property specifying if user can delete rows Ability to get/set a property specifying if user can edit fields in the

section Ability to get/set a property specifying if user can insert new rows Access to the data table that is bound to the form section Access to the form (parent form) that owns the form section Access to the name of the form section Access to property indicating if table section is currently displayed in

form or grid view Access to property indicating if the section has been explicitly hidden Access to property indicating if section contains array fields displayed

as a sub form array Method to access a table data field object using the field name and row

number Method to access a table data field object using the bound UI control

name and row number Method to get the names of all control objects in the section Method to show/hide the section

13

3.3 Recognition Scripting

Recognition scripting is a legacy scripting specifically used to customize Advanced Recognition (former known as Dispatcher) modules. It is typically used within the context of the following modules:

• Classification • Classification Edit • Recognition (deprecated) • Validation (deprecated)

For new projects, it is strongly recommended not to use Recognition or Validation modules, as these are already deprecated and will no longer be shipped with the next Captiva Capture release. The recommended alternatives are the Extraction and Captiva Desktop modules, which utilize their own Profile Scripting.

Note: While it may be technically possible to use Recognition Scripting in conjunction with the newer Extraction module, this is not a recommended practice because the Extraction module uses a higher-level, document-centric data model which is not well suited to some of the lower-level scripting events in Recognition Scripting. Please refer to the following documentation for more details on migrating from Recognition Scripting to Profile Scripting:

Scripting Guide > Profile Scripting > Choosing Between Document Type Scripting and Recognition Scripting > Mapping of Recognition (Dispatcher) Scripting Events to Document Type Scripting Events

Use of Recognition Scripting should be limited to the Classification and Classification Edit modules only. For these modules, Recognition Scripting is primarily used to perform the following:

• Manipulating template codes assigned to each page • Manipulating pre-indexing field data values

Recognition Scripting Quick Summary

Languages Supported VBA-like and VB .NET-like scripting syntax (with some limitations)

Script Editor IDE embedded in Recognition Designer

(formerly known as Dispatcher Manager)

Script Location Script code is embedded within the Recognition Project file (DPP), which is maintained through the Recognition Designer plug-in of Captiva Designer.

Eventually these DPP files are deployed to the production folder (typically a shared network path) and accessed by the client modules as needed. Client modules may load the DPP directly over the network, or may first copy the DPP locally. Either way, the client modules will execute whatever code is found inside the DPP that is loaded.

Script Name Core scripts are implicitly named by Recognition Designer (e.g. DispatcherProject.bas, <IndexingFamily>.bas) however user can

14

create arbitrarily-named additional code modules to supplement the primary scripts.

Script Scope All scripts belong to a particular DPP, and a CaptureFlow step is configured to access one specific DPP.

CaptureFlow steps can therefore reference different DPPs (and scripts), or the same DPP, depending on the desired application behavior.

Documentation Scripting Guide > Recognition Scripting > Programming Reference

Scripting Guide > Recognition Scripting > VBA Script Editor

API Reference Scripting Guide > Recognition Scripting >

Dispatcher Event Model

Dispatcher Object Model

Dispatcher Function Library

Direct access to batch data and structure

Limited access to batch data*

* While there is no direct access to batch data within Recognition Scripting context, it is possible to provide access to read and write access to specific Level 0, Level 1, and Level 7 values by configuring them in setup mode as “external IA values”. The Recognition Script will then have access to these values through the ExternalValues property in the Dispatcher Object Model. Please refer to documentation for more information on “External Values”.

Additionally, all field values can optionally be written back to the batch as discrete IA values through a setup option of the Advanced Recognition modules.

15

4 FORMS OF TASK SCRIPTING The term “Task Scripting” refers to two forms of scripting which are used to run arbitrary code within a CaptureFlow with the goal of implementing complex logic that can access and manipulate any data anywhere in the batch structure.

One form is the powerful .NET Code Module Scripting, and the other is the new CaptureFlow Scripting recently introduced in Captiva Capture 7.0.

4.1 .NET Code Module

The first and most powerful form of Task Scripting is through the use of the .NET Code Module Scripting, which is a scripting API which runs within the context of a generic client module called .NET Code Module.

The .NET Code Module is an unattended, standalone client module designed solely to execute arbitrary custom code as a unique step in the CaptureFlow. Unlike CaptureFlow Scripting, which runs directly on the InputAccel Server, the .NET Code Module scripting runs on the workstation where the client module is installed.

This module has access to a very powerful scripting API which provides access to all batch data at all levels for all steps, as well as methods to insert, delete, and move batch nodes, and methods to read and write “stage files” from the batch. It also supports the creation of a custom setup UI which can be invoked during the module’s setup mode to present a set of custom configuration parameters which affect the script’s behavior.

In many situations, this module could be used as a lightweight alternative to the client module SDK to create the equivalent of an unlicensed custom module without having to learn an entire SDK. For example, this module could be used to connect to and interact with some external subsystem, or to integrate some 3rd party library to manipulate or export images and/or files from the batch. Alternatively, it could be used with a custom setup mode to create a sort of “control panel” for configuring specific behaviors of the CaptureFlow. As with a custom module, using this module requires an explicit step to be added to the CaptureFlow.

16

4.1.1 .NET Code Module Namespace

.NET Code Module Scripting uses following namespace with following interfaces:

• Emc.InputAccel.CaptureClient namespace

The interfaces provided are too numerous to list here, but encompass things such as batch, node, task, stage file, step definition, tables, and value accessors.

Please refer to documentation for complete list and details in section

Scripting Guide > Profile and Task Scripting API Reference > Namespaces > Emc.InputAccel.CaptureClient Namespace

.NET Code Module Scripting Quick Summary

Languages Supported Visual C# and Visual Basic (.NET)

Script Editor Microsoft Visual Studio

Script Location Scripts compiled in Visual Studio are uploaded to IA Server (ultimately stored in the IA Database) through Captiva Designer (requires .NET Code Module 7.0 or later).

For backward compatibility with the 6.x version of .NET Code Module, the 7.x version of the module will also look in the local InputAccel\Client\binnt folder for the assembly if it is not able to retrieve it from the IA Server first.

It is not recommended, however, to continue using this legacy behavior. If you have used the 6.x version of this module in the past, it is recommended to remove any local copies of script assemblies from the binnt folder of the client machines and always deploy your script assemblies through Captiva Designer.

Script Name There is no predefined naming convention for these script assemblies. Any number of uniquely-named assemblies can be uploaded to the IA Server through the Captiva Designer “Deployment Files” feature.

Within each script assembly, however, it is possible to create different classes to encapsulate different sets of script behavior for a given step. As each CaptureFlow step is configured, you select both the assembly file name and the name of the class to use within that file.

A “best practice” recommendation would be to create one script assembly for all logic related to a particular business application, and within that assembly create different classes for different functional steps within the CaptureFlow.

If this results in an unmanageable number of script files, you can also combine larger numbers of classes into a single file, but it

17

will likely result in more frequent updates to the file.

Script Scope The granularity of configuration is a single step in a CaptureFlow. That is, each step in each CaptureFlow can be configured to use any of the deployed script files as well as the specific class name within a given script file.

Documentation Scripting Guide > Task Scripting > .NET Code Module Guide

API Reference Scripting Guide > Profile and Task Scripting API Reference > Emc.InputAccel.CaptureClient Namespace

Direct access to batch data and structure

Yes

4.2 CaptureFlow Scripting

Sometimes referred to as “server-side scripting” or “code-behind”, this form of scripting was recently introduced in the Captiva Capture 7.0 release to provide an ability to add custom code directly into the CaptureFlow. This was something not possible prior to Captiva Capture 7.0 unless the CaptureFlow was hand-coded in VBA using Process Developer.

In Captiva Capture 7.0 and later, the Captiva Designer environment allows optional code (in C# or VB .NET) to be written and associated with any of the module steps. This code runs directly on the IA Server either immediately before a task is sent to a client module (via “Prepare” event), or immediately after a task is completed by a client module (via “Finish” event).

This form of scripting provides full access to all batch data, at all levels and for all steps. However, this scripting does not provide any means to alter batch structure, to access stage files (such as actual images) from the batch, or to make calls to libraries which could potentially stall the IA Server (since the code runs on the IA Server). The intent of this form of scripting is to implement custom logic or data manipulations using the rich set of tools in the .NET programming languages and the interface to all of the batch values.

No special IDE is required to develop CaptureFlow Scripting. The necessary IDE is built-in to Captiva Designer.

4.2.1 CaptureFlow Scripting Namespace

CaptureFlow Scripting API uses following namespace with following interfaces:

• Emc.InputAccel.CaptureFlow namespace

o IBatchNodeData interface provides access to Batch and Node properties, access to ancestor and descendent nodes, and methods to log errors to IA Server

o IUimDataAccessor interface provides access to document object

information as created by Extraction and Captiva Desktop modules

18

o IUimFieldDataAccessor interface provides access to field object data and properties (field values, flags, validation state, etc).

CaptureFlow Scripting Quick Summary

Languages Supported Visual C# and Visual Basic (.NET)

Script Editor Built-in to Captiva Designer, in CaptureFlow designer

Script Location Scripts are embedded within the CaptureFlow file (XPP) and automatically compiled and installed to IA Server when the CaptureFlow is deployed.

Technically, these script files reside in special subfolders below the \IAS\process folder on each IA Server machine, but it is not advised to manipulate these files directly. The reason for mentioning this location is for the purpose of understanding that these can be backed up during a file system backup of the IAS root folder.

Should the files be inadvertently deleted from the IAS root folder, they can be restored by simply redeploying the CaptureFlow through Captiva Designer.

To fully remove these files from the IA Server, use Captiva Designer to delete the CaptureFlow from the IA Server. The use of Captiva Administrator to delete XPP-based processes on the IA Server is not recommended.

Note that CaptureFlows with scripting should only be deleted once it is confirmed that there are no remaining batches on the IA Server which were created from this CaptureFlow. If such batches do remain, they may fail to process if the CaptureFlow Scripting files have been deleted.

Script Name Script assemblies are internally named. There is no user specification for these names.

Script Scope The scope of any CaptureFlow script is the CaptureFlow (XPP) itself. If a given CaptureFlow (XPP) is deployed to the IA Server with multiple installed process names, as would be the case for having multiple copies of same CaptureFlow, each with different settings, then all of these deployed processes will share the same CaptureFlow scripting.

If an XPP is explicitly saved under a different name, a copy of the embedded scripting is saved with it, and becomes independent of the original XPP at the point when it belongs to a new XPP file.

For example, if CaptureFlow “A.xpp” is deployed to the IA Server under names A1.iap, A2.iap, A3.iap then all 3 of these processes will be accessing the same CaptureFlow script code from the original XPP “A”. If the scripting code is updated in “A.xpp”, all

19

the installed processes will use the updated code.

However, if “A.xpp” is saved under a new name of “B.xpp”, and deployed to the IA Server as B1.iap, B2.iap, B3.iap, then the scripting code inside “B.xpp” is now completely independent from that of “A.xpp”.

Documentation Scripting Guide > Task Scripting > CaptureFlow Scripting

API Reference Scripting Guide > Profile and Task Scripting API Reference > Emc.InputAccel.CaptureFlow Namespace

Direct access to batch data and structure

Yes (but structure cannot be modified)

4.3 When to use one or the other

.NET Code Module Scripting should be used if any of these conditions apply:

• Need to insert, delete, or move nodes in the batch structure • Need to access stage files from the batch • Need to access databases other external libraries which could endanger the IA

Server if they were to stall • Need to execute slow code that could otherwise slow down the IA Server (by running

this code on a client machine, it will not impair IA Server throughput)

CaptureFlow Scripting could be used if you only need these features:

• Access nodes above the current task node • Access collection of child nodes below the current task node • Read/write nodal values on any node from any level and from any step • Read/write certain batch properties • Access node properties such as node ID, ordinal position from perspective of an

ancestor node, or number of child nodes at any lower level • Write custom messages into the IA Server’s event log or debug.out file

20

Comparison of Task Scripting (both forms) with legacy IPP Scripting

VBA Finish Routine (IPP)

CaptureFlow Scripting (XPP)

.NET Code Module

Where does it run? Server Server Client

What language? VBA Visual C# or

Visual Basic (.NET)

Visual C# or

Visual Basic (.NET)

Access 3rdParty APIs?

No No Yes

Runs within Step’s Prepare/Finish?

Yes Yes No (runs in dedicated step)

Requires Visual Studio to write/debug code?

No No Yes

21

5 FINAL Q AND A TOPICS

Question: How can multiple developers work on scripting solutions for the same project?

Answer:

• Client Scripting: each developer generally works on a different client-side script in Visual Studio, and uploads that script to the IA Server through module setup of a test CaptureFlow. Since each script can be uniquely named, and each step in each CaptureFlow can reference a different client-side script, there is no collision among developers working on the same IA Server.

• Profile Scripting: since all three modules which use Profile Scripting use the same script file named Custom.InputAccel.UimScript.dll, it is important that multiple developers coordinate their coding efforts. The only code which is mandatory to be placed in Custom.InputAccel.UimScript.dll is the ScriptMain class.

Additional document type classes (which extend Emc.InputAccel.UimScript.UimScriptDocument) and/or super filter classes (which extend Emc.InputAccel.UimScript.UimScriptFilter) can either be put into the same Custom.InputAccel.UimScript.dll or, beginning with Captiva Capture 7.1, additional document type classes or image processor super filter classes can be created by different developers and added to separate, uniquely named DLLs that follow the naming convention of: Custom.InputAccel.UimScript.<yourname>.dll

provided the primary DLL exists. For example developer A could create Custom.InputAccel.UimScript.TaxForms.dll

and developer B could create Custom.InputAccel.UimScript.InsuranceForms.dll

with each containing different document type/super filter classes. At runtime, the Extraction, Captiva Desktop, or Image Processor modules will load all of these DLLs.

NOTE: All Profile Scripts are deployed through Captiva Designer. If multiple developers are using independent copies of Captiva Designer, but all are connected to the same IA Server, the developers should be careful to coordinate and deploy only 1 set of common “Global Options”, such as the list of Deployment Files and the Recognition Project Shared Directory. If each developer uploads a different set of “Global Options”, each will be overwriting the other. For this reason it is necessary that only one developer deploys “Global Options”, or that all developers maintain the same set of “Global Options” on their workstations.

• Recognition Scripting: since this scripting is part of the DPP file, and only one person at a time can edit a DPP file, it is best that only one developer at a time work on any given DPP file.

22

• .NET Code Module Scripting: each developer can work on a differently named .NET Code Module Script file in Visual Studio and upload it to the IA Server through Captiva Designer. As new scripts are created to be uploaded, the names of those scripts must be defined in “Global Options” and therefore care must be taken to ensure that the “Global Options” deployed to the IA Server always reflect all of the Deployment File names.

• CaptureFlow Scripting: since this scripting is embedded in an XPP, and each developer can work on a differently named XPP, there is no chance for collision.

Question: How can I transition values into and out of the scripting context?

Answer:

• For Client Scripting, .NET Code Module Scripting, and CaptureFlow Scripting, the scripting API offers direct access to IA values anywhere in the batch.

• For Profile Scripting, data can be made available to the script either by placing it into the StepCustomValue, or by pre-populating a field value through the use of InUimData_<Field> dynamic value. To get data out of Profile Scripting and available to the CaptureFlow or other module steps, the output form data can be “flattened” into dynamic output values per field, or if the data to be output does not exist in any field, it can be written to any IA value name (at task level) by adding the value to the TaskValues list object property in the script code.

• For Recognition Scripting, the use of “external values” can be used to get data in or out

Question: How do I debug the scripts?

Answer:

• For Profile Scripting, use Visual Studio and refer to documentation section Captiva Capture Guide > Scripting Guide > Profile Scripting > Developing Profile Scripts > Debugging Profile Scripts

• For Client Scripting, use Visual Studio as follows: o NOTE: Visual Studio Express cannot be used for debugging, but can be used

for writing and compiling the code. o Compile a Debug version of your script DLL (not a Release version). o Upload this Debug version to your IA Server through the module’s setup

mode. o Launch the module whose script you want to debug on the same machine

where you currently have the script source open in Visual Studio. o In Visual Studio, attach to the ‘QuickModuleHost.exe’ process that represents

the module you just launched. o In Visual Studio, verify the PDB (symbol file) for your script is loaded, by

checking menu option Debug > Windows > Modules and looking for the name of your script file. It should show that it has loaded the corresponding PDB from the same solution folder as your script source.

23

o Set a breakpoint in your source code, and process a task with the module, and the breakpoint should be reached if the module fires an event which leads to your breakpoint.

• For Recognition Scripting, use the IDE integrated into Recognition Designer. Refer to documentation section Captiva Capture Guide > Scripting Guide> Recognition Scripting > Recognition Programming Reference > VBA Script Editor > Using Breakpoints

• For .NET Code Module Scripting, you can use the same approach as Client Scripting, but you would instead attach to the ‘CodeClient.exe’ process. Alternatively, you can add code to the script to write debug messages to the trace log and UI window using the Trace method, which is invoked only when module is launched with a tracing command line parameter. Refer to documentation section Captiva Capture Guide > Scripting Guide > Task Scripting > .NET Code Module Guide > Setup > Debugging and Error Handling > Custom Code Errors

• For CaptureFlow Scripting, use Captiva Designer to debug as per instructions in documentation section Captiva Capture Guide > Captiva Designer > Capture Process Design > Managing Scripting > Debugging Scripting

Question: What are the major limitations in each type of scripting?

Answer:

• Client Scripting: no major limitations

• Profile Scripting: no direct access to batch data outside of the current task

• Recognition Scripting: no direct access to batch data outside of the current task

• .NET Code Module Scripting: no major limitations

• CaptureFlow Scripting: no ability to alter batch structure or access stage files; not supported to access databases or use 3rd party DLLs