Kofax DOKuStar Validation User Manual

DOKuStar Validation for Ascent Capture

Programming Manual

Océ Document Technologies GmbH

The reproduction, transmission or use of this document
or its contents is not permitted without express written
authority.
Océ Document Technologies GmbH Offenders will be liable for damages. All rights, including
Max-Stromeyer-Straße 116 rights created by patent grant or registration of a utility
D-78467 Konstanz - Germany model or design, are reserved.
Phone: ++49(0)75 31/87-0
Fax; ++40(0)7531/87-4567 Availability and changes of technical information
E-Mail: [e-mail] reserved.
www.odt-oce.com

Copyright  2004 Océ Document Technologies GmbH
Portions  1996-2000, Microsoft Corporation. All rights reserved
Edition: 6.2004 (V3.6 SR01) Printed in Germany

Contents

Introduction 1

The VBA Studio 2

Development Environment........................................................................................................... 2

Files.............................................................................................................................................. 5

The Document Model 7

Overview...................................................................................................................................... 7

Relation to the Ascent Capture Definition ................................................................................. 10

Support of Ascent Capture Index Field Properties.......................................................... 12

Table issues..................................................................................................................... 13

InvoiceItems Postprocessing........................................................................................... 16

Events 17

Concept ......................................................................................................................................17

Events for the FieldType Object ................................................................................................ 19

OnFieldActivated............................................................................................................ 19

OnFieldChanged ............................................................................................................. 19

OnFieldDeactivated ........................................................................................................ 20

Subfield Events ............................................................................................................... 20

OnFieldDataSourceChanged........................................................................................... 21

Table Fields..................................................................................................................... 22

Event Order.....................................................................................................................24

Events for the DocumentType Object........................................................................................ 26

OnField Events................................................................................................................ 26

OnDocumentActivated.................................................................................................... 27

OnDocumentDeactivated................................................................................................ 27

OnDocumentDeleted....................................................................................................... 27

OnDocumentCreated....................................................................................................... 28

OnDocumentDataSourceChanged .................................................................................. 28

OnDocumentDescriptorLost, OnDocumentDescriptorGot............................................. 28

Batch Events............................................................................................................................... 30

OnPreImported................................................................................................................ 30

OnPostImported .............................................................................................................. 30

OnPreExported................................................................................................................ 31

OnPostExported .............................................................................................................. 31

OnImport, OnExport ....................................................................................................... 31

Controller Events........................................................................................................................ 32

OnDocumentActivated.................................................................................................... 32

OnDocumentDeactivated................................................................................................ 32

OnDocumentDeleted....................................................................................................... 33

OnDocumentCreated....................................................................................................... 33

OnFieldDeactivated ........................................................................................................ 33

OnFieldActivated............................................................................................................ 33

OnFieldChanged ............................................................................................................. 34

DOKuStar Validation for Ascent Capture Page • i

OnCursorChanged........................................................................................................... 34

FieldClass Events ....................................................................................................................... 35

Data Objects 36

Dataset........................................................................................................................................ 36

Schema ....................................................................................................................................... 37

DocumentTypes .............................................................................................................. 37

DocumentType................................................................................................................ 38

FieldTypes....................................................................................................................... 39

FieldType ........................................................................................................................ 39

Data ............................................................................................................................................ 40

Documents ...................................................................................................................... 41

Document........................................................................................................................42

Fields............................................................................................................................... 43

Field ................................................................................................................................ 44

TableField ....................................................................................................................... 45

Alternatives..................................................................................................................... 45

Alternative....................................................................................................................... 45

SourceInfo, ImageSourceInfo ......................................................................................... 46

DataSource, ImageDataSource ....................................................................................... 46

Zone ................................................................................................................................ 46

UserData ......................................................................................................................... 47

VerifyEventArgs............................................................................................................. 48

Controller ...................................................................................................................................49

Cursors and Filters .......................................................................................................... 50

Add-Ins 55

Introduction................................................................................................................................ 55

Registry Key for Validation Add-Ins ......................................................................................... 56

Creating an Add-In..................................................................................................................... 58

Creating a Custom User Control ................................................................................................ 60

Creating a Custom Toolbar ........................................................................................................ 63

Creating Menu Entries for Validation ........................................................................................ 66

Workspaces ................................................................................................................................ 71

Handling Keyboard Strokes .......................................................................................................75

Replacing Existing Controls....................................................................................................... 77

Managing the Image Control......................................................................................................79

Predefined Add-Ins ....................................................................................................................80

Special Issues 81

Information Bar.......................................................................................................................... 81

Exchanging the Fields View....................................................................................................... 83

Table Data Output ...................................................................................................................... 86

Character correction mode ......................................................................................................... 88

How Do I… 93

Reject Documents and Pages .....................................................................................................93

Test the Scripting Code.............................................................................................................. 95

Not Restore Old Contents ..........................................................................................................98

Display Multi-Line Status Texts ................................................................................................99

Check All Fields Before Closing the Batch ............................................................................. 100

Check if the Last Field is Reached........................................................................................... 101

Merge Table Rows ................................................................................................................... 102

Changing the Color of Documents........................................................................................... 104

DOKuStar Validation for Ascent Capture Page • ii

Introduction

This manual covers the topics an integrator needs to adapt DOKuStar Validation for Ascent Capture to specific
requirements. This is mainly the scripting interface, DOKuStar Validation offers, and this will cover most of this
manual.

An additional chapter describes the format of the table data output. This is interesting only for those applications that
also use the DOKuStar Recognition Server and read table data.

This manual assumes that you are familiar with Visual Basic for Applications (VBA) programming. For the table
data output section, knowledge in XML is a prerequisite.

DOKuStar Validation for Ascent Capture Page • 1

The VBA Studio

Development Environment

When planning to write scripts, you must know

- where to write the code

- how to test the code.

These are both done in the same environment:

After defining your batch class (which uses DOKuStar Validation as one queue) in the Ascent Capture
Administration, select the batch class and give a right click with the mouse. In the context menu, you will find an

DOKuStar Validation Scripting...:

item

If you have more than one stage of validation installed, each of these stages has a separate menu item, allowing you
to write different scripting code for each stage:

DOKuStar Validation for Ascent Capture Page • 2

Selecting this menu item will open the DOKuStar Validation Module. This is almost exactly the DOKuStar
Validation program window that the validation operator will see, with one important difference: in the toolbars there
is a button which, when pressed, opens the VBA studio:

In the VBA studio, a tree view in the left window with a root node named
up to the

TheApplication node, and then double click. This will open the editing window, where you can add

your code, as described in the following chapters.

Project can be seen. Expand this node

When you have finished programming, save the code and return to the DOKuStar Validation program. If scanned
batches already exist, you can now open them and test out your script, setting breakpoints, etc..

DOKuStar Validation for Ascent Capture Page • 3

Some important remarks:

- You can (but you don’t have to) publish the batch class before you start writing scripts. This is useful in order to
get test data.

- It is not necessary to „republish“ the batch after code changes.

- You can switch to the VBA studio regardless of whether you have a batch open in the DOKuStar Validation or
not.

- In order to get the code you just entered working, it is often necessary to re-open the batch: Suspend the batch in
DOKuStar Validation and then re-open it. This is especially true when defining new event sinks (see below), or

adding code in the

OnProjectLoaded event routine.

Besides the main
project, give a right click with the mouse, and choose

You might want to insert new modules or class modules to:

- structure your code,

TheApplication object, you can add additional modules, class modules and forms. Select the

Insert:

- re-use modules in different projects.

Note: When you add a
are not supported in DOKuStar Validation Scripting.

DOKuStar Validation for Ascent Capture Page • 4

UserForm, be sure that you will open it modal in your scripting code. Modeless forms

Files

Yet, I didn’t mention one important thing: Where does all the code go?

In most development environments, you have some file handling functionality, like File...Open/Close menus or
something similar to that. The VBA studio is different here: When you look around in the studio, you will not find
anything like it. So: Where is the code stored?

The answer is simple: It all goes into one file on the Ascent Capture Server. For each stage of DOKuStar Validation,
a subdirectory of the server directory …

DokuStarValidation_2, etc.. In these directories, the scripting files are stored, named like the batch classes,

with an extension

.vps:

\Ascent\AdminDB is created, named DokuStarValidation,

In this example, there are two batch classes named

All code always goes to this single file, no matter how many Modules, Class Modules or User Forms you added.

As you can see in the picture above, there is also a file named like the batch class with an extension
“Validation Project File”. It is generated automatically from the Ascent Capture batch class definition and contains
the knowledge about document classes, field names etc. needed by DOKuStar Validation. It is generated
automatically whenever:

- a batch class is published,

- Validation Scripting is called from the Administration module.

Usually, you don’t have to care about this Validation Project File.

When you developed your scripting code on one PC and you want to transfer it to another one (e.g. to the Ascent
Capture installation at a customer’s site), just copy the scripting file (
additionally is that the Ascent Capture batch class definition is the same, so it is best to export it into a
import it again on the target PC (see the Ascent Capture documentation for details).

DOKuStar Validation for Ascent Capture Page • 5

TaxForms and TwoTypes.

.vps) . The only thing you have to make sure

.vpj. This is the

.cab and

So, when you plan to copy the scripting code from one system to another, proceed as follows:

- export the Ascent Capture batch class definition,

- import it on the target system,

- copy the DOKuStar Validation Scripting file,

- publish the batch class on the target system.

Although all the scripting code goes into one file, you can still store the modules, class modules and forms into
separate files by exporting them into text files. Select the module you want to export, give a right click with the

mouse and choose

Export File…:

You are then asked for a filename.

These text files can be imported again by using

Import File…. When you import a file and the module name

already exists in the project, a new module name will be generated. So, if you want to replace an existing module,
first delete the existing module and then import the new code.

DOKuStar Validation for Ascent Capture Page • 6

The Document Model

Overview

In order to access fields, values, documents, etc., it is important to understand how data is organized in DOKuStar
Validation. This data structure is called the document model.

This document model is quite a large structure, and contains parts that you will probably never use. This manual
concentrates on those items that are common to most applications.

At the top of the hierarchy stands the Application object, which has some assigned members and methods. To get
down to the data, use the following chain of members:

Application.Project.DataSet

Application and Project have some members and methods, but they will be disregarded right now to

Note:

concentrate on the dataset.

The Dataset has three members:

- the

- the

- the

You will use the
and/or for which field is an event needed? The

When an event is received, the data for the specific document will be handed over.

Before getting too theoretic, let us look at a simple example. But before that, one important remark:

In the Ascent Capture batch class definition, both document classes and form types exist. Index fields are defined
for the document class. In our document model, document classes do not appear at all. Everything is based on the
form types, which are here called document types. Index fields are assigned to these document types. So if, for
example, a document class “Invoice” is defined in Ascent Capture, along with two form types named “MyInvoice1”
and “MyInvoice2”, these two form types will appear as document types in the document model; something like
“Invoice” is unknown.

Now for the example:

Suppose a form type

Schema: This is the part that describes the structure of the batch, i.e. the form types that are defined and

the index fields, and mainly corresponds to the Ascent Capture definition of form types and index fields, but
may also include the table definition from DOKuStar

Data: This is the part where the data is stored

Controller: This object controls the dataset’s behavior at the user interface.

Schema or the Controller when defining field and document events: For which document

Data will then be used in the code you write for the specific event:

Invoice has been defined in the Ascent Capture batch definition, which has a field

TotalAmount. Whenever the user changes this TotalAmount field, the field shall be checked if the value is

greater than 1000.00; if so, the user shall confirm the change in a message box.

DOKuStar Validation for Ascent Capture Page • 7

Here is the source code for this example:

Dim WithEvents Amount As FieldType

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set Amount = App.Project.DataSet.Schema.DocumentTypes("Invoice").FieldTypes("Amount")
End Sub

Private Function Amount_OnFieldChanging(ByVal Field As Field, ByVal SubField as Field, ByVal
VerifyEventArgs As VerifyEventArgs) As Boolean
Amount_OnFieldChanging = True 'Preset return value
If Val(Field.Value) > 1000 Then
If MsgBox("You entered a value > 1000. Please Confirm.", vbOKCancel) = vbCancel Then
Amount_OnFieldChanging = False 'User clicked cancel, so stay in the field
End If
End If
End Function

Let us go through this line by line:

Dim WithEvents Amount As FieldType

You define a variable Amount that shall be used in the VBA code. This variable has the type FieldType, which is
a notion from the

Schema part of the Dataset. This variable shall get events (WithEvents), one of these

events is used below.

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set Amount = App.Project.DataSet.Schema.DocumentTypes("Invoice").FieldTypes("Amount")
End Sub

This subroutine will be called when the project is loaded, i.e. right after opening the batch. The only thing that is
done here is that you assign the variable

Amount, which you defined above, to the right field type: set to the

FieldType Amount on the DocumentType Invoice. The names you use here are the names from the

Ascent Capture definition: the form type

Invoice has an index field Amount (to be more precise: form type

Invoice is assigned to a document class which has an index field Amount).

Private Function Amount_OnFieldChanging(ByVal Field As Field, ByVal SubField As Field, ByVal
VerifyEventArgs As VerifyEventArgs) As Boolean

Defining this function enables to catch the FieldChanging event for the amount field: Whenever the user changes
the amount on an invoice, this function will be called and gets an Object
field itself. This object has the type

The function is expected to return a boolean; when returning

Field, which is a notion from the Data part of the Dataset.

False, the changing is aborted, i.e. the old value

(before the user typed his changes) is restored and the focus stays on this field. When returning
are accepted, and the focus usually moves to the next field (the “usually” will be explained shortly).

Amount_OnFieldChanging = True 'Preset return value

The boolean return value is preset to True.

If Val(Field.Value) > 1000 Then

Now take the Field received as a parameter and determine the field’s value. Since a value of a field is always a
string, the

Val function is be used to convert to a double integer.

If MsgBox("You entered a value > 1000. Please Confirm.", vbOKCancel) = vbCancel Then
Amount_OnFieldChanging = False 'User clicked cancel, so stay in the field
End If

Field as the first parameter, which is the

True, the changes

Open the message box. If the user hits Cancel, set the return value to False, thus aborting the change and
restoring the old contents.

DOKuStar Validation for Ascent Capture Page • 8

Before getting more into the details, here is a second way of solving the same problem:

Dim WithEvents ctrl As Controller

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set ctrl = App.Project.DataSet.Controller
End Sub

Private Function ctrl_OnFieldChanging(ByVal Controller As Controller, ByVal Field As Field, ByVal
SubField As Field, ByVal VerifyEventArgs As VerifyEventArgs) As Boolean
ctrl_OnFieldChanging = True 'Preset return value
If Field.Document.Name = "Invoice" And Field.Name = "Amount" Then
If Val(Field.Value) > 1000 Then
If MsgBox("You entered a value > 1000. Please Confirm.", vbOKCancel) = vbCancel Then
ctrl_OnFieldChanging = False 'User clicked cancel, so stay in the field
End If
End If
End If
End Function

This code does the same as the one above, but with a different approach to the problem. Looking at the differences:

In the first line, a variable of the

Controller type is defined, and then set to ...Dataset.Controller when the

project is loaded. The Controller is a central object that gets events for every field and document. The outcome here
is an event for every field, no matter which document type and field type.

In the event handling routine, we must therefore determine if we got the correct field by asking for the field’s name

Field.Name) and for the name of the corresponding document (Field.Document.Name). If these are

(

Amount and Invoice, we open the dialog box.

Which way of defining the event you prefer, depends very much on the project: Suppose there are many different
form types, all of them having an

Amount field, and the same code should be executed if any of these fields

change. Then here to define an event handling function for every single form type would be tedious, so you would
prefer the second method. On the other hand, if only a specialized behavior for an index field on a special form type
is desired, the first method is more convenient.

As you will see later on, there is also something in between these two methods: You can also use the

DocumentType’s FieldChanging event, which would get an event for all fields of a certain document type.

These two short examples might have given you an idea how to do scripting. The next chapters will go more into the
details.

DOKuStar Validation for Ascent Capture Page • 9

Relation to the Ascent Capture Definition

There are some relations between the document model and the Ascent Capture batch class definition.

Whenever a batch class is published, and also whenever DOKuStar Validation scripting is called from the
administration module, the document model is created from the Ascent Capture batch class definition. As stated in
the previous chapter, the Ascent Capture form types will become the document types in Validation’s document
model. Ascent “Document Classes” do not appear in Validation.

Furthermore, there is something called
on the Ascent side – while the document models’

Before this gets too confusing, let us sum it up into a table:

Ascent Capture object… …corresponds to DOKuStar Validation object

Document Class ---

Form Type Document Type

Field Type Field Class

Index Field Field Type

When you define a field type in Ascent Capture, you give it a name, for example

FieldClass named alike, so you have a FieldClass Varchar_100 in the document model. An Ascent

a
index field of this type, named for example

FieldClass in the document model. This corresponds to the Field Types

FieldTypes are the Index Fields in Ascent Capture.

Varchar_100. This will lead to

MyDescription, will result in a Validation FieldType

MyDescription, whose FieldClass is Varchar_100.

In addition, there is always a

Note: The Field Class

Ascent Capture Field Types are based on certain Data Types, like DATE, VARCHAR, etc.. These imply certain
restrictions to the data they can hold, e.g. a

maximum number of characters, etc.. These data types are checked in the Validation automatically: When the user
tries to type something in that does not correspond to the data type, a message box is displayed:

FieldClass named TableField, which is used for all tables.

TextField, which existed in previous versions of DOKuStar Validation, is no longer used.

DATE field type can only hold valid dates, a VARCHAR has a

DOKuStar Validation for Ascent Capture Page • 10

Ascent Capture Field Types can have value lists; if so, the user input is also checked against this list:

DOKuStar Validation for Ascent Capture Page • 11

Support of Ascent Capture Index Field Properties

In the Document Class Properties dialog box, properties can be assigned to index fields. Some of these
properties are supported by DOKuStar Validation, others are not.

In the following picture the supported properties are marked:

Name:

This is obvious. The name must match the field name in the Extraction project file.

DisplayName:

This is the name of the field as displayed in Validation. If not present, the display name will be the field name.

Choosing a
assumed that you use an

DisplayName is useful for fields where you have naming restrictions, as in the example above: It is

InvoiceTotals index field in the extraction project, and you want the
TotalAmount part from this field to appear in a single index field. To achieve this, you must use
<fieldName>/TotalAmount as the field name (see the User’s Manual of DOKuStar Extraction for details).

This won’t be a nice name in Validation, so one might like to use a DisplayName instead.

The display name is only used for display purposes; in scripting, you still have to use the field name.

FieldType:

As mentioned above, the field type will become the FieldClass in Validation scripting.

DOKuStar Validation for Ascent Capture Page • 12

Hidden:

A hidden field will not appear in Validation, but can still be accessed by scripting routines.

Sticky:

If a field is set to be sticky, it will get its value from the preceding field, in case its value is empty.

Table issues

There are two field types of DOKuStar Extraction, that will be displayed in a table grid in Validation: Table and

InvoiceItems.

When defining a table in DOKuStar Extraction, you will also specify its columns. These columns will be
automatically displayed in Validation, in the order you defined them.

When you define an
names, which are:

InvoiceItems field in DOKuStar Extraction, you will get a fixed set of columns with fixed

ItemQuantity, ItemUnit, ItemUnitPrice, ItemAmount, ItemNumber, ItemDiscount, ItemText,
ItemType and ItemState.

The ItemState column is always hidden, the other columns will be displayed by default in Validation, in this order.

The only thing you must to do is define a placeholder field in the Ascent Capture index field definition:

In this example, it is assumed that you defined an
you must define an index field in the Ascent Capture definition with the same name.

The

FieldType of this field is of no interest, you can use any.

DOKuStar Validation for Ascent Capture Page • 13

InvoiceItems field named Items in DOKuStar Extraction, so

This is all that must be done. Beyond that, there are some options that can influence the layout of the tables in
Validation: Columns can be hidden, renamed, added, and reordered. This will be explained in the following (using an

InvoiceItems field in the example, but in can be done for other tables as well).

Generally, when changing something on table columns, this is done by a placeholder field for the column in the
Ascent Capture index field definition. This placeholder field must be named

<TableName>/<ColumnName>. Then, you can use the hidden attribute to hide the column, and the
DisplayName attribute to give the column a different display name, which will then be displayed in the

Validation table grid as the column header.

In the following picture, the

ItemText column was set to hidden, while the ItemType column was renamed to

Type (it would be consequent to rename the other columns as well, but for shortness, we only rename one):

Also, the
column; the cell’s value will be checked against this

FieldType now comes into play: This will become the Validation FieldClass for every cell in the

FieldType. This replaces the default TextField

FieldClass type for table cells.

To add a column, simply add a placeholder for the new column, named
can choose any name you like for the new column name. You could also set the

column. The new column will always be empty; it is up to you to fill it using scripting. For example, you might want
that the contents is the sum of some other columns; you would then write a script that cycles through the table’s rows
and fills the additional cell.

DOKuStar Validation for Ascent Capture Page • 14

<TableName>/<ColumnName>. You

hidden attribute for the new

To reorder columns, you can add a position number to the column name. This number is separated by a ‘
column name. In the example above, if you want your new column to be the second column in the table, you name it

#’ from the

Items/ANewColumn#2. This will make your column the second one in the table grid, moving all other

columns one place backward.

Numbers on hidden columns are ignored; also, hidden columns are not counted when determining the position.

The following is a complete example, where all the
hidden, one is added, and all are reordered:

InvoiceItems columns have a DisplayName, some are

DOKuStar Validation for Ascent Capture Page • 15

InvoiceItems Postprocessing

There is obviously a correlation between the Invoice Items fields and the Invoice Totals field: Invoice

Items

lists the details, and Invoice Totals holds the sums.

When opening a batch that contains these two fields, some automatic checking is done. Especially, the total amount
is checked against the details; if they do not match, some self-correction is tried.

This is all done “behind the scenes”. You must do nothing, as long as you use an

Invoice Total

Only if you gain the totals of an invoice by other means (e.g., self-made
automatic invoice postprocessing, you must somehow tell AC Validation that these are the invoice’s total fields.

This is done by a naming convention:

The name of the field that holds the invoice’s total amount must end with

If you also define fields for other things that will be delivered by the
rate and the tax amount, the following naming conventions apply:

The name of the field that holds the invoice’s value added tax rate must end with

The name of the field that holds the invoice’s net amount must end with

field in the DOKuStar Extraction project file.

KeyValue fields) and still want to use this

TotalAmount

InvoiceTotals field, like the value added tax

NetAmount.

Invoice Totals or US

VatRate.

The name of the field that holds the invoice’s tax amount must end with

The name of the field that holds the invoice’s currency must end with

The name of the field that holds the invoice’s expenses amount must end with

There is no need to specify all of these fields, they are all optional.

DOKuStar Validation for Ascent Capture Page • 16

VatAmount.

Currency.

Expenses.

Events

Concept

Certain objects can get events. You will probably use the events defined for the FieldType and the

DocumentType object, but there are many more objects which have the ability to get events. For example, an

event may be assigned to a single
So you could add code that would be executed if the user changed the amount on the first document, but not, if he
changed the amount on one of the following documents.

This manual will not describe every event for every object, but concentrates on the most important items. To see the
complete list, use VBA‘s object browser: Open the VBA development studio, press

DOKuStarValidation library.

Field (instead of the FieldType), e.g. to the amount field on the first document.

F2 and select the

DOKuStar Validation event handling routines use a special naming scheme: They all begin with

ing, ...ed or …ingCanceled. For example, consider the OnFieldChanging, OnFieldChanged and

...

OnFieldChangingCanceled event. For most events, you will always have such a group of three events. Rules:

The ...

ing event always comes first. The ...ing events can be aborted by the scripting routine. If the scripting routine

wants to abort the event, it must return
means: “The value of the field is about to be changed. Any Objection?” When

…ed event, in our case the OnFieldChanged. This event indicates, that the changing of the field now took

the
place. Contrarily, when

the changing of the value was canceled.

Note that when you return

Canceled event); especially, you will not get the corresponding ...ed event.

In the example above the
situations. If the

Consequently, event handling routines for ...
routines are always subroutines.

OnFieldChanged event had been used, the old contents could not have been restored.

False was returned in the …ing you will next get an …ingCanceled , indicating that

False in the ...ing event, all events that might follow will not be fired (except the

OnFieldChanging event was used, since we wanted to abort the changing in some

False, else True. So, for the OnFieldChanging example, this event

True is returned, you will next get

ing events are always functions that return a boolean; while ...ed

On... and end with

DOKuStar Validation for Ascent Capture Page • 17

When writing an event handling routine, proceed as follows:

- Define a variable of the appropriate object type:

Dim WithEvents fld As FieldType

- This variable will now appear in the drop down list above the editing window. Select it:

- In the drop down list to the right, select the event handling routine wanted. The function body will then be added

to the code automatically:

In the following chapters, events are described in detail, always in the ...

ed format.

DOKuStar Validation for Ascent Capture Page • 18

Events for the FieldType Object

OnFieldActivated

This event will be fired when a field gets activated, either by keyboard entry, mouse click or by the scripting code
itself.

Definition:

Private Sub fld_OnFieldActivated(ByVal Field As Field, ByVal PreviousField As Field)

The parameter Field is the field that gets activated, PreviousField is the field that gets deactivated.

When you return

False in the OnFieldActivating, always the next field will be activated automatically.

OnFieldChanged

This event will be fired when the contents of a field changed. This happens when the user enters data, but also when
a field’s value is changed by another scripting routine. Be aware of this to avoid cycles in the code!

Definition:

Private Sub fld_OnFieldChanged(ByVal Field As Field, ByVal SubField As Field)

The parameter Field is the field itself. SubField may point to a sub-field of the Field; e.g. a cell of a table is a
sub-field of the table field. For more information, see chapter

The event will only be fired if the data really changes; if the user just steps through the fields without changes, the
event will not be triggered.

If the user again types in the same contents as before, the event will also not be triggered.

If you return
will be restored. See the

False in the OnFieldChanging event, the old contents of the field (before the user did any typing)

How Do I… section on how to change this behavior.

Field.Value always contains what the user typed in. The original contents of the field can be seen in the
OnFieldChanging event in the additional VerifyEventArgs parameter.

Tables below.

DOKuStar Validation for Ascent Capture Page • 19

OnFieldDeactivated

These events will be fired when the field was deactivated. If the OnFieldDeactivating event is aborted, the
current field will remain active.

Definition:

Private Sub fld_OnFieldDeactivated(ByVal Field As Field, ByVal NextField As Field)

The parameter Field is the field that becomes deactivated, where NextField is the field that will become activated.

Note that the old field contents will not be restored when the

OnFieldDeactivating event is aborted! The

OnFieldDeactivating event occurs after the OnFieldChanged event, so the changing of the value has

already taken place and cannot be taken back (see

Event Order below).

Subfield Events

Sub-fields (e.g. table cells) have their own activation and deactivation events: OnSubFieldActivating,

OnSubFieldActivated, OnSubFieldDeactivating and OnSubFieldDeactivated.

These events get the
parameters.

Definitions:

Private Sub fld_OnSubFieldActivated(ByVal Field As Field, ByVal SubField As Field, ByVal
PreviousSubField As Field)

Private Sub fld_OnSubFieldDeactivated(ByVal Field As Field, ByVal SubField As Field, ByVal
NextSubField As Field)

Here, fld is expected to be set to the table field.

There is no ...

OnFieldChanged event for the field itself, delivering both the field and the sub-field as parameters.

an

Field (e.g. table), the Subfield (the cell), and the next (or previous respectively) sub-field as

Changed event for sub-fields. This is unnecessary because every change in a sub-field will result in

DOKuStar Validation for Ascent Capture Page • 20

OnFieldDataSourceChanged

These events result when the DataSource (i.e. the image) of the field changes. This may happen in several
situations:

- The user chooses a DOKuStar alternative for the field, which is on a different page of the document.

- The user splits a document: field contents may be emptied, thus losing their image.

- The user moves pages from one document to another: again fields may be emptied, thus losing their image.

Definition:

Private Sub fld_OnFieldDataSourceChanged(ByVal Field As Field, ByVal DataSource As DataSource,
ByVal PreviousDataSource As DataSource)

Parameters are the Field, and the old and the new data source.

DOKuStar Validation for Ascent Capture Page • 21

Table Fields

Tables require additional features, because they are fields that are made up of rows, columns, and cells.

As an example, imagine a table in your document that has (among others) three columns

Quantity,

SinglePrice and TotalPrice. Whenever the user corrects a cell in the Quantity or SinglePrice

column, the corresponding total price is recalculated (by:
against the value in the

TotalPrice column. If the values are different, the user shall decide whether to override

the total amount value or not.

Solution:

Option Explicit

Dim WithEvents Table As FieldType

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set Table = App.Project.DataSet.Schema.DocumentTypes("Invoice").FieldTypes("Table")
End Sub

Private Function Table_OnFieldChanging(ByVal Field As Field, ByVal SubField As Field, _
ByVal VerifyEventArgs As VerifyEventArgs) As Boolean
Dim t As TableField
Dim row As TableRow
Dim calculatedTotalPrice As Double
Dim totalPrice As Double

Table_OnFieldChanging = True
If SubField.Name = "Quantity" Or SubField.Name = "SinglePrice" Then
Set t = Field
Set row = t.row(SubField)
totalPrice = Val(row("TotalPrice").Value)
calculatedTotalPrice = Val(row("Quantity").Value) * Val(row("SinglePrice").Value)

If calculatedTotalPrice <> totalPrice Then
If MsgBox("Calculated total price: " & calculatedTotalPrice & vbCrLf & _
"Total price from column: " & totalPrice & vbCrLf & _
"Override?", vbYesNo) = vbYes Then
row("TotalPrice").Value = calculatedTotalPrice
Else
Table_OnFieldChanging = False

End If
End If
End If
End Function

Quantity times SinglePrice) and compared

Let us look at the interesting parts of the code:

First of all, a variable (

Table above) is defined as for any other field and set accordingly:

Dim WithEvents Table As FieldType

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set Table = App.Project.DataSet.Schema.DocumentTypes("Invoice").FieldTypes("Table")
End Sub

This code expects that there is an Ascent Capture index field named Table in the document class definition (as
for any other field).

Along with the event, the field and the sub-field come as parameters. The

Name property of the sub-field delivers

the column name (as defined in the DOKuStar project), so you can ask if the cell is in one of the columns in
question:

DOKuStar Validation for Ascent Capture Page • 22

If SubField.Name = "Quantity" Or SubField.Name = "SinglePrice" Then

Next, the generic Field must be converted to a specialized TableField variable:

Set t = Field

This allows you to use methods and properties that only exist for TableFields. One of these methods is the Row
method, that delivers the row in which the cell is in. The cell is passed as a parameter to this method. What we get is
an object of type

TableRow:

Set row = t.row(SubField)

Within this row, we can access the cells by indexing the row with the column name. Since the cell delivered is
actually of type

Field, methods like Value can be used as with any other field:

totalPrice = Val(row("TotalPrice").Value)

The rest of the code should be clear: If the user enters Yes in the message box, the TotalAmount column will
be overwritten, else the event will be aborted and the user must type in something again.

There is another approach to dealing with table events: Instead of one event for the table as a whole, you could also
use events for single columns. This is done by setting the event sink variable equal to the column:

Dim WithEvents SinglePriceColumn As FieldType

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set SinglePriceColumn=
App.Project.DataSet.Schema.DocumentTypes("Invoice").FieldTypes("Table").FieldTypes("SinglePrice")
End Sub

As you can see, below the FieldType there is again a collection of FieldTypes, that denote the columns.

You now get events for every cell in the

SinglePrice column:

Private Sub SinglePriceColumn_OnFieldChanged(ByVal Field As Field, ByVal SubField As Field)

The parameter Field in this case is the cell, the parameter Subfield is unused.

From this cell parameter, the whole table may be accessed by using the

Parent property, which delivers the

TableField:

Dim t As TableField
Set t = Field.Parent

Having this table, you can access the rows like in the example above:

Dim row As TableRow
Set row = t.row(Field)

So, using events for the table as a whole or for the individual columns is a matter of preference. The first method
allows handling events for multiple columns alike, while the second method would be used for different event
handling on different columns.

DOKuStar Validation for Ascent Capture Page • 23

Event Order

Field events occur in the following order:

OnFieldActivating

OnFieldActivated

<user types in something and leaves field>

If any of the ...

ingCanceled event for this specific event.

...

Note: The
old field!

ing events is aborted, the events following this one will not be fired. Instead, you will get an

OnFieldActivating event for the next field is fired before the OnFieldDeactivated event for the

OnFieldChanging

OnFieldChanged

OnFieldDeactivating (old field)

OnFieldActivating (next field)

OnFieldDeactivated (old field)

OnFieldActivated (next field)

DOKuStar Validation for Ascent Capture Page • 24

For table fields, the event queue is as follows:

OnFieldActivating (when the user steps into the table)

OnFieldActivated

OnSubFieldActivating (for the first cell)

OnSubFieldActivated

<user types in something and goes to next cell>

OnFieldChanging

OnFieldChanged

OnSubFieldDeactivating (for the first cell)

OnSubFieldActivating (for the second cell)

OnSubFieldDeactivated (for the first cell)

OnSubFieldActivated (for the second cell)

<user types in something and goes to next cell>

....

OnFieldChanging

OnFieldChanged

<user leaves table>

DOKuStar Validation for Ascent Capture Page • 25

OnFieldDeactivating

OnFieldDeactivated

Events for the DocumentType Object

OnField Events

For the DocumentType object, the same OnField... events are available as for the FieldType object. These
events will be fired for any field on the document.

Definition (example

OnFieldChanged):

Private Sub doc_OnFieldChanged(ByVal Field As Field, ByVal SubField As Field)

This is a convenient way of handling all fields of a certain form type together.

Example: Suppose a form type

TaxForm exists with several amount fields. The only other field is a field named

IdentityNumber. Whenever the user corrects one of the amount fields, it shall be checked if a correct format

has been entered.

This could be solved as follows:

Option Explicit

Dim WithEvents taxForm As DocumentType

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set taxForm = App.Project.DataSet.Schema.DocumentTypes("TaxForm")
End Sub

Private Function taxForm_OnFieldChanging(ByVal Field As Field, ByVal SubField As Field, _
ByVal VerifyEventArgs As VerifyEventArgs) As Boolean

taxForm_OnFieldChanging = True
If Field.Name <> "IdentityNumber" Then

If Not ValidFormat(Field.Value) Then
MsgBox ("You entered an invalid amount")
taxForm_OnFieldChanging = False
End If
End If
End Function

Private Function ValidFormat(fieldValue As String) As Boolean
'* code to check the format
End Function

This produces an OnFieldChanging event for every field on the TaxForm. We exclude the

IdentityNumber field and do the checking for all other fields.

DOKuStar Validation for Ascent Capture Page • 26

OnDocumentActivated

This event occurs whenever a new document is selected.

This may happen explicitly (e.g. when the user selects a different document in the tree view) or implicitly (e.g. the
user moves from field to field and the document changes).

Definition:

Private Sub doc_OnDocumentActivated(ByVal Document As Document, ByVal PreviousDocument As
Document)

The current document and the previous document come as parameters.

OnDocumentDeactivated

This event will be fired when the current document is deactivated.

This may happen explicitly (e.g. when the user selects a different document in the tree view) or implicitly (e.g. the
user moves from field to field and the document changes).

Definition:

Private Sub doc_OnDocumentDeactivated(ByVal Document As Document, ByVal NextDocument As Document)

OnDocumentDeleted

This event will be fired when a document is deleted.

This may happen explicitly (e.g. when the user deletes a document in the tree view, or when two documents are
joined) or by scripting code.

Definition:

Private Sub doc_OnDocumentDeleted(ByVal Document As Document)

DOKuStar Validation for Ascent Capture Page • 27

OnDocumentCreated

This event will be fired when a new document is created.

This may happen explicitly (e.g. when the user splits a document in the tree view) or by scripting code.

Definition:

Private Sub doc_OnDocumentCreated(ByVal Document As Document)

OnDocumentDataSourceChanged

This event will be called when one of the data sources of the document (i.e. one of the images) is changing. This may
happen when

- the user splits documents

- the user joins documents

- the user moves pages from one document to another

Definition:

Private Sub doc_OnDocumentDataSourceChanged(ByVal Document As Document)

Document is the document whose data source has changed.

OnDocumentDescriptorLost, OnDocumentDescriptorGot

These events all occur when a document’s descriptor changes. Document Descriptor is just a synonym for

Document Type.

The event might be caused by user action (the user changed the form type) or by a script itself.

Changing the descriptor is a two-step process: A document looses its descriptor and then gets a new one. For each
step, there is a pair of events. Event order is as follows:

OnDocumentDescriptorLoosing

OnDocumentDescriptorGetting

OnDocumentDescriptorLost

DOKuStar Validation for Ascent Capture Page • 28

OnDocumentDescriptorGot

Definition:

Private Sub doc_ OnDocumentDescriptorLost(Document As Document, DocumentDescriptor As
DocumentDescriptor, NextDocumentDescriptor As DocumentDescriptor)

Document is the document whose descriptor changes

DocumentDescriptor is the current descriptor

NextDocumentDescriptor is the descriptor the user selected from the context menu

Private Sub doc_ OnDocumentDescriptorGot(Document As Document, DocumentDescriptor As
DocumentDescriptor, PreviousDocumentDescriptor As DocumentDescriptor)

Document is the document whose descriptor changes

DocumentDescriptor is the new current descriptor

PreviousDocumentDescriptor is the old descriptor

DOKuStar Validation for Ascent Capture Page • 29

Batch Events

Batch events concern opening and closing of a batch. When a batch is opened and closed, you get an event where
scripts can be added.

These events are events of the

Dim WithEvents data As Data

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set data = App.Project.DataSet.Data
End Sub

Data object, thus requiring the use of a Data object as the event sink:

OnPreImported

This event will be called after the user selected a batch, but before the batch is really opened, and can be canceled in

OnPreImporting routine. Since no data has been loaded yet, the Data object returned as a parameter is

the
empty. The

routine.

Definition:

Private Sub data_OnPreImported(ByVal Data As Data)

Schema part of the Dataset has been loaded at this point and can be examined by the scripting

OnPostImported

This event will be fired after the batch has been loaded. The Data object, which has been returned as parameter, is
filled.

Definition:

Private Sub Data_OnPostImported(ByVal Data As Data)

Note: There is no OnPostImporting event. The event cannot be canceled.

DOKuStar Validation for Ascent Capture Page • 30

OnPreExported

This event will be fired after the user selected to close or suspend the batch, but before the batch is really closed. The
data are still present. If
open.

OnPreExporting returns False, the closing process is aborted and the batch remains

The closing mode (

Definition:

Private Sub Data_OnPreExported(ByVal Data As Data, ByVal Mode As ExportMode)

Suspend or Close) is handed over as a parameter.

ExportMode can take the values:

ExportModeSuspend (= „Suspend“)
ExportModeNone (= „Close“)

The OnPreExporting event is a good place to do checks across the whole batch before being closed. See the

How Do I… chapter for an example.

Note: Following this event, no

example via Controller.ActiveField, will cause an error.

ActiveField or ActiveDocument. is defined. Trying to access this, for

OnPostExported

This event is fired after the batch has been closed and all data has been transferred to Ascent Capture. The parameter

Data still contains the data just transferred.

Note: There is no

OnPostExporting event. This event cannot be canceled.

Definition:

Private Sub data_OnPostExported(ByVal Data As Data, ByVal Mode As ExportMode)

OnImport, OnExport

These events are not supported in the Ascent Capture version of DOKuStar Validation. You will never get these
events.

DOKuStar Validation for Ascent Capture Page • 31

Controller Events

The controller object itself is described below in a separate chapter, please refer for a description.

This object gets events when the active object changes, i.e. a field or document gets activated or deactivated. So here
is another potential place to enter the (de)activation code. This is especially useful for routines that are common to all
documents or all fields.

OnDocumentActivated

Will be fired for any document that gets activated.

Definition:

Private Sub ctrl_OnDocumentActivated(ByVal Controller As Controller, ByVal Document As Document,
ByVal PreviousDocument As Document)

Parameter Document is the document that gets activated, PreviousDocument the one that becomes
deactivated.

OnDocumentDeactivated

Will be fired for any document that becomes deactivated.

Definition:

Private Sub ctrl_OnDocumentDeactivated(ByVal Controller As Controller, ByVal Document As
Document, ByVal NextDocument As Document)

Parameter Document is the document that becomes activated, NextDocument is the one that will become
activated next.

Example:

Dim WithEvents ctrl As Controller

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set ctrl = App.Project.DataSet.Controller
End Sub

Private Function ctrl_OnDocumentDeactivating(ByVal Controller As Controller, ByVal Document As
Document, ByVal NextDocument As Document) As Boolean
ctrl_OnDocumentDeactivating = True
If Val(Document.Fields("SinglePrice")) * Val(Document.Fields("Quantity")) <>
Val(Document.Fields("TotalPrice")) Then
MsgBox "SinglePrice*Quantity does not equal TotalPrice, please correct"
ctrl_OnDocumentDeactivating = False
End If
End Function

This example assumes that on every document, no matter which document type, there are fields SinglePrice,

Quantity and TotalPrice. A check will be made if SinglePrice*Quantity = TotalPrice.

DOKuStar Validation for Ascent Capture Page • 32

OnDocumentDeleted

Will be fired for any document that gets deleted.

Definition:

Private Sub ctrl_OnDocumentDeleted(ByVal Controller As Controller, ByVal Document As Document)

Parameter Document is the document that gets deleted.

OnDocumentCreated

Will be fired for any document that is created.

Definition:

Private Sub ctrl_OnDocumentCreated(ByVal Controller As Controller, ByVal Document As Document)

Parameter Document is the document that is created.

OnFieldDeactivated

Will be fired for any field that becomes deactivated.

Definition:

Private Sub ctrl_OnFieldDeactivated(ByVal Controller As Controller, ByVal Field As Field, ByVal
NextField As Field)

Parameter Field is the field that looses becomes deactivated, NextField is the one that will become activated next.

OnFieldActivated

Will be fired for any field that gets activated.

Definition:

Private Sub ctrl_OnFieldActivated(ByVal Controller As Controller, ByVal Field As Field, ByVal
PreviousField As Field)

Parameter Field is the field that gets the activated, PreviousField is the one that will become deactivated.

DOKuStar Validation for Ascent Capture Page • 33

OnFieldChanged

Will be fired for any field that gets changed.

Definition:

Private Sub ctrl_OnFieldChanged(ByVal Controller As Controller, ByVal Field As Field, ByVal
SubField As Field)

The parameter Field is the field itself. SubField may point to a sub-field of the Field.

OnCursorChanged

Will be fired when a cursor changes. See below for a description of cursors.

Definition:

Private Sub ctrl_OnCursorChanged(ByVal Controller As Controller)

DOKuStar Validation for Ascent Capture Page • 34

FieldClass Events

There are the same events for FieldClass objects as for FieldType objects, see there for a description of the
events. The only additional event for the

used in the Ascent Capture version of DOKuStar Validation.

FieldClass object is a OnFieldClassDeleted event, which is not

You will use

FieldClass events when you want to handle all fields of a certain FieldClass (= Ascent Capture

FieldType) alike. For example, if you have several date fields, you might define them in the Ascent Capture

Administration module in a way that they all belong to the same Ascent Capture
will then define a

FieldClass in the script accordingly and use its OnFieldChanging event to do checks:

Dim WithEvents myDateType As FieldClass

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set myDateType = App.Project.DataSet.Schema.FieldClasses("MyDateType")
End Sub

Private Function myDateType_OnFieldChanging(ByVal Field As Field, ByVal SubField As Field, ByVal
VerifyEventArgs As VerifyEventArgs) As Boolean
myDateType_OnFieldChanging = True
If DateCheck(Field.Value) = False Then
MsgBox "Date is invalid"
myDateType_OnFieldChanging = False
End If
End Function

Private Function DateCheck(strDate As String) As Boolean
' Do Date Checking, return True or False
End Function

FieldType MyDateType. You

DOKuStar Validation for Ascent Capture Page • 35

Data Objects

Dataset

The Dataset is the topmost object in DOKuStar Validation concerning the data, and can be accessed from the

Application object via:

Application.Project.Dataset

Every sub-object of the Dataset object has a property called Dataset, which delivers a pointer to its parent

Dataset object. Example:

Field.Dataset

Furthermore, there are often properties that point to the parent(s) of an object. The Field object, for example, has a
property called

Properties of the

Property Returns Description

Schema Schema

Data Data Delivers a data object which describes the batch data

Controller Controller

Document which delivers its parent Document object.

Dataset object:

Delivers a schema object which describes the batch
structure

Delivers the controller object which describes the
behavior of the data set

DOKuStar Validation for Ascent Capture Page • 36

Schema

The Schema object describes the batch structure, i.e. the Document Types and Field Types. The schema
has completely been filled with the Ascent Capture form types and index fields for this batch upon opening, so you
don’t have to care about filling this structure.

Note: Although technically adding
data would not be transferred back to Ascent Capture.

The Schema and belonging descendents will be used when defining events, e.g. wanting a ...Changed event for

DocumentTypes and FieldTypes on the fly is possible, the corresponding

FieldType TotalAmount on DocumentType Invoice, wanting an event for every text field, etc. You

will hardly use them within the event handling code.

Properties of the

Property Returns Description

DocumentTypes DocumentTypes

FieldClasses FieldClasses

Schema object (excerpt):

Returns a collection of DocumentType objects

Returns a collection of FieldClass objects

DocumentTypes

DocumentTypes is a collection object that holds a list of DocumentType objects. There are methods and

properties to traverse through the list and access individual elements in the collection. Also, as with every collection,

For...Each can be used to traverse through the list.

An individual element can be accessed by using the
as a parameter or a string that denotes the
omitted. If, for example,
statements will all deliver the same result:

DocumentTypes.At(MyDocType)
DocumentTypes(MyDocType)
DocumentTypes.At(„MyInvoice“)
DocumentTypes(„MyInvoice“)

MyDocType is a Document object that has the name MyInvoice, the following four

DocumentType. The At property is the default property and so can be

At property. This property can take a DocumentType object

Properties and methods of the

DOKuStar Validation for Ascent Capture Page • 37

DocumentTypes object (excerpt):

Property/Method Returns Description

At DocumentType

Begin DocumentType Delivers the first document type object in the collection

Empty Boolean Returns true if the collection is empty

Last DocumentType Delivers the last document type object in the collection

Next DocumentType Delivers the next document type in the list

Delivers a document type object at the specified
position

Parameter:

PreviousDocumentType as DocumentType

Previous DocumentType Delivers the previous document type in the list

Parameter:

NextDocumentType as DocumentType

DocumentType

The DocumentType object describes one single document type, i.e. one form type from the Ascent Capture
definition, and belongs to the
instance of the

Properties and methods of the

Property/Method Returns Description

FieldTypes FieldTypes

DocumentType object.

Schema part of the Dataset. On the Data side, the Document object is an

DocumentType object (excerpt):

Returns the collection of FieldTypes defined for this

DocumentType

Name String

Name of the DocumentType. This is the form type
name from the Ascent Capture definition

DOKuStar Validation for Ascent Capture Page • 38

FieldTypes

See the description for DocumentTypes. The properties and methods are identical after replacing

DocumentTypes by FieldTypes and DocumentType by FieldType respectively.

FieldType

FieldTypes are used at two places:

- linked to a

- linked to a

Currently, the only place where

FieldTypes describe the column definition of a table.

these

Properties and methods of the

Property/Method Returns Description

FieldTypes FieldTypes

Name String

DocumentType object, they describe the index fields for this document type,

FieldType itself, they describe sub-fields of an index field.

FieldTypes are used as sub-fields of a FieldType is the TableField. Here,

FieldType object (excerpt):

Returns the collection of FieldTypes , i.e. sub­fields, for this FieldType

Name of the FieldType. For normal fields, this is
the index field name from the Ascent Capture

definition. If the FieldType is used as a sub-field
of a table, this is the column name from the
DOKuStar table definition.

DOKuStar Validation for Ascent Capture Page • 39

Data

The Data object is situated below the Dataset object, parallel to the Schema object. While the Schema holds
the document definition, the

The

Data object has been filled completely when the batch was opened. Although you technically could add

documents yourself, which also would show up in the Validation, there is not much use doing this since these
documents could not be transferred back to Ascent Capture when the batch is closed.

The

Data object provides access to various objects like Document, Field etc.. These objects have some

common properties and methods; these are:

Property/Method Returns Description

Activate Boolean

Activated Boolean Checks if the object is activated or not.

Deactivate Boolean

Deactivated Boolean Checks if the object is deactivated or not.

Data object holds the data itself.

Activates the object; the object gets the focus.
returns False if the object cannot be activated. See

note below.

Deactivates the object; the object gets the focus.
returns False if the object cannot be deactivated.

See note below.

Properties and methods of the

Property/Method Returns Description

Documents Documents

DataSources DataSources

Data object (excerpt):

Returns the collection of Document objects for
this batch

Returns the list of DataSource objects (i.e.
Images) for the whole batch. DataSource objects

are also linked to the individual documents, here it
serves as an overview of all images of the batch.

DOKuStar Validation for Ascent Capture Page • 40

Documents

Holds the collection of documents in this batch. An individual document can be accessed using the At method,
which takes a

Document as parameter.

Properties and methods of the

Property/Method Returns Description

At Document Delivers a document object at the specified position

Begin Document Delivers the first document object in the collection

Clear -- Deletes all documents from the collection

Empty Boolean Returns true if the collection is empty

Last Document Delivers the last document object in the collection

Next Document Delivers the next document in the list

Documents object (excerpt):

Parameter:

PreviousDocument as Document

Previous Document Delivers the previous document in the list

Parameter:

NextDocument as Document

To traverse through the Documents collection, For...Each can also be used.

DOKuStar Validation for Ascent Capture Page • 41

Document

Holds information about one document, especially the fields and the images. Furthermore, there is an Activate
method which lets the document get activated.

Properties and methods of the

Property/Method Returns Description

Activate Boolean

Activated Boolean

DataSources DocumentDataSources

Deactivate Boolean

Fields Fields

Document object (excerpt):

Activates the document. Returns True if
successful.

Returns True if the document is currently
activated.

Returns the list of DataSource objects
for this document.

Deactivates the document, moving
activation to the next one.

Returns the list of fields for this document.
This will always deliver the complete list of
fields as defined for the corresponding

DocumentType, no matter if the fields

were found by DOKuStar or not.

Name String

Name of the document. This is the

DocumentType name, which in turn is

the form type name from Ascent Capture.

Note that the

Activate and Deactivate methods return a Boolean; these methods will fire the event

OnDocumentActivating/ed, or OnDocumentDeactivating/ed respectively, which might be canceled

by a scripting routine; in this case, they would return

False.

DOKuStar Validation for Ascent Capture Page • 42

Fields

Holds a collection of Field objects. Individual Fields can be accessed either by name or object:

Fields(MyField) ‘ MyField is supposed to be a Field object
Fields.At(MyField)
Fields(„OrderDate“)
Fields.At(„OrderDate“)

Properties and methods of the

Fields object (excerpt):

Property/Method Returns Description

At Field Delivers a field object at the specified position

Begin Field Delivers the first field object in the collection

Empty Boolean

Returns True if the collection is empty

Last Field Delivers the last field object in the collection

Next Field Delivers the next field in the list

Parameter:

PreviousField as Field

Previous Field Delivers the previous field in the list

Parameter:

Next Field as Field

To traverse through the Fields collection, For...Each can also be used.

DOKuStar Validation for Ascent Capture Page • 43

Field

Properties and methods of the Field object (excerpt):

Property/Method Returns Description

Activate Boolean

Activated Boolean

ActivateSubField Boolean

ActiveSubField Field

Alternatives Alternatives

Composed Boolean

Deactivate Boolean Deactivates the field, moving activation to the next one.

DeactivateSubField Boolean

HasSourceInfo Boolean

Name String

SourceInfo ImageSourceInfo

State State Returns the state of the field.

Value String Value of the field. Always a string.

Activates the field. Returns True if successful.

Returns True if the field is currently activated.

Activates a sub-field. Returns True if successful. Can
be used to jump to a specific cell of a table field.

Parameter: SubField as Field

Returns the currently active subfield (i.e. table cell) of a
field.

Returns the list of alternatives for this field. This
assumes that DOKuStar is used as the recognition
engine and parameterized to deliver alternatives.

Returns True if the field is a composed field, i.e. has
sub-fields.

Deactivates the current sub-field, moving activation to
the next one.

Returns True if the field has a SourceInfo object
assigned.

Name of the field. This is the FieldType name, which
in turn is the index field name from Ascent Capture

Returns the ImageSourceInfo object assigned to
this field. Contains the box of the field.

States are:

StateEmpty

StateError

StateNone

StateReject

StateOk

DOKuStar Validation for Ascent Capture Page • 44

TableField

A TableField is a special Field object. Being derived from Field, all Field’s properties and methods can be
used. A

TableField also has some additional properties and methods:

Properties and methods of the

Property/Method Returns Description

Row TableRow Returns the row object for a given table cell.

TableField object (excerpt):

Parameter:

Cell as Field

Rows TableRows

To convert a Field to a TableField object, simply assign:

Private Sub Table_OnFieldActivated(ByVal Field As Field, ByVal PreviousField As Field)
Dim t as TableField
Set t = Field ' convert to TableField

....

Returns a TableRows object, which is the
collection of the tables‘ rows.

Alternatives

Alternatives is a collection that may be assigned to a field, and exists if DOKuStar recognized alternatives for this

field.

The

Alternatives collection has the same methods and properties as the other collections, e.g Fields.

Alternative

Holds a single alternative for a field as recognized by DOKuStar.

Properties and methods of the

Property/Method Returns Description

SourceInfo ImageSourceInfo

State State

Value String Value of the alternative.

DOKuStar Validation for Ascent Capture Page • 45

Alternative object (excerpt):

Holds the ImageSourceInfo for this
alternative, which consists of the image and the
box.

State of the alternative. See the Field object for
a description of values.

SourceInfo, ImageSourceInfo

SourceInfo is the base class of ImageSourceInfo. Within DOKuStar Validation for Ascent Capture, only
ImageSourceInfo is used.

Properties and methods of the

Property/Method Returns Description

DataSource ImageDataSource

Zone Zone Describes the box around the field.

ImageSourceInfo object (excerpt):

Holds the ImageDataSource object, which
includes the images filename.

DataSource, ImageDataSource

DataSource is the base class of ImageDataSource. Within DOKuStar Validation for Ascent Capture, only
ImageDataSources are used.

Properties and methods of the

Property/Method Returns Description

FileName String Name of the image file (full path)

ImageDataSource object (excerpt):

Zone

Describes a rectangle around a field.

Properties and methods of the

Property/Method Returns Description

Height Long Height of the rectangle in 1/10 mm

SetValue -- Sets all four values of the rectangle

Zone object (excerpt):

Parameters:

x as Long

y as Long

w as Long

h as Long

Width Long Width of the rectangle in 1/10 mm

X Long Left corner of the rectangle in 1/10 mm

Y Long Upper corner of the rectangle in 1/10 mm

DOKuStar Validation for Ascent Capture Page • 46

UserData

UserData is an object that is linked to each field and document object. It serves as a container for additional data

that you want to attach to the field or document. This data are organized as key/value pairs. You can attach as many
of these key/value pairs to the document as you like.

Example:

Whenever the user changes the contents of a field, the original value shall be saved. When the field is activated again
later on, the old contents shall be displayed in the status window.

Option Explicit

Dim WithEvents ctrl As Controller
Dim status As New StatusTextTransporter

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set ctrl = App.Project.DataSet.Controller
End Sub

Private Sub ctrl_OnFieldActivated(ByVal Controller As Controller, ByVal Field As Field, _
ByVal PreviousField As Field)
If Field.UserData.HasValue("OldValue") Then
status.Text = "Original Value: " & Field.UserData.Value("OldValue")
Else
status.Reset
End If
End Sub

Private Function ctrl_OnFieldChanging(ByVal Controller As Controller, ByVal Field As Field, _
ByVal SubField As Field, _
ByVal VerifyEventArgs As VerifyEventArgs) As Boolean
'* Don't override an existing OldValue
If Not Field.UserData.HasValue("OldValue") Then
'* Store the old value which is contained in the VerifyEventArgs
Field.UserData.Value("OldValue") = VerifyEventArgs.PreviousValue
End If

ctrl_OnFieldChanging = True
End Function

Properties and methods of the

UserData object (excerpt):

Property/Method Returns Description

HasValue Boolean Checks if there is a value for a specific key

Parameters:

key as String

Value String Sets/Gets a value associated with a key

Parameters:

key as String

RemoveValue -- Removes a key/value pair

Parameters:

key as String

DOKuStar Validation for Ascent Capture Page • 47

VerifyEventArgs

VerifyEventArgs is an object that is used with some events like OnFieldChanging. When such an event

occurs, a

VerifyEventArgs has two properties: Error, which is currently unused, and PreviousValue, which contains

the old value before the user typed something in.

VerifyEventArgs object is one of the parameters of the event handling function.

Properties and methods of the

Property/Method Returns Description

PreviousValue String

Error String Currently unused

VerifyEventArgs object (excerpt):

Returns the previous contents before the user
did any typing

DOKuStar Validation for Ascent Capture Page • 48

Controller

The Controller object is the third sub-object of the Dataset, with the purpose of controlling the behavior of the
application.

Using the controller object enables to:

- activate and deactivate documents and fields,

- administer the cursor.

Cursor object is described below in a separate chapter.

The

With the controller object, a second way of activating fields or documents (the first one is the
the field and document object) is provided. You can determine which field/document is active or activate/deactivate
a field/document.

Properties and methods of the

Property/Method Returns Description

ActivateDocument Boolean

Controller object (excerpt):

Activates a specific document. Returns False if the
document could not be activated (e.g., a scripting
routine canceled the activation)

Parameter:

Activate method on

Doc as Document

ActivateField Boolean

Activates a specific field. Returns False if the field
could not be activated (e.g., a scripting routine
canceled the activation)

Parameter:

fld as Field

ActiveDocument Document Returns the currently active document

ActiveField Field Returns the currently active field

Cursor Cursor Gets/Sets the currently active cursor

Cursors Cursors Gets the collection of currently defined cursors

DeactivateDocument Boolean

DeactivateField Boolean

HasCursor Boolean

Deactivates the current document. Returns False if
the document could not be deactivated (e.g., a
scripting routine canceled the deactivation)

Deactivates the current field. Returns False if the
field could not be deactivated (e.g., a scripting
routine canceled the deactivation)

Returns True if there the controller has a cursor
assigned

DOKuStar Validation for Ascent Capture Page • 49

Cursors and Filters

These topics are covered together, because there are some dependencies between them.

Cursors define a behavior which fields and/or documents will get activated in the DOKuStar Validation’s user
interface. They do not denote the shape of the cursor.

Cursors are mainly defined by a set of filters. There are three types of filters defined in DOKuStar Validation: Field
state filters, field confidence filters and document type filters. These filters can either be set by the user, using the
combo boxes in the toolbars, or by script programming.

The cursor reflects the setting of these filters. If, for example, the Field state filter is set to “all”, the method

Cursor.NextField will activate the field following the current one. If the Field state filter is set to “empty”,
Cursor.NextField will activate the next empty field.

Currently, there is one cursor named

fieldconfidence

and documenttype. To change the behavior of the cursor at the user interface (i.e. which

default, which has three filters assigned, named fieldstate,

fields get activated), there are two ways:

- take the default cursor, and change the behavior of the filters,

- add a new cursor along with filters.

Each way will be shown in an example. The goal is to jump only to documents of type
and there only to fields that have the state

error or reject:

Invoice or Order,

Example 1:

Option Explicit

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Dim crs As Cursor
Dim fieldFilter As FieldStateFilter
Dim docFilter As DocumentTypeFilter
Dim docType As DocumentType

Set crs = App.Project.DataSet.Controller.Cursor ' take the current cursor which is the
default cursor
Set fieldFilter = crs.Filters("fieldstate") ' get the fieldState Filter
Set docFilter = crs.Filters("documenttype") ' get the Documenttype Filter
fieldFilter.Reset ' sets all states to FALSE
docFilter.Reset ' sets all Doc. Types to FALSE
fieldFilter.State(StateReject) = True ' set StateReject to TRUE
fieldFilter.State(StateError) = True ' set StateError to TRUE
Set docType = App.Project.DataSet.Schema.DocumentTypes("Invoice") ' get the "Invoice"
doc.type object
docFilter.Type(docType) = True ' set it to true
Set docType = App.Project.DataSet.Schema.DocumentTypes("Order") ' get the "Order" doc.type
object
docFilter.Type(docType) = True ' set it to true
End Sub

The code first gets the current
predefined filter objects
implementations of the common

Cursor object, which is the cursor named default. From this cursor, those two

fieldstate and documenttype are fetched. These two objects are special

Filter object, FieldStateFilter and DocumentTypeFilter. Next, the two

filters are reset (if the code ended here, no field would ever get activated). Then you switch on which field states and
document types will get activated.

The alternative is to create a new cursor and add filters, which may be the predefined two filters or newly created
ones, as in the second example:

DOKuStar Validation for Ascent Capture Page • 50

Option Explicit

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Dim crs As Cursor
Dim fieldFilter As FieldStateFilter
Dim docFilter As DocumentTypeFilter
Dim docType As DocumentType

Set crs = App.Project.DataSet.Controller.Cursors.Add("dataset::DefaultCursor", "MyCursor")
' Add a new cursor
App.Project.DataSet.Controller.Cursor = crs ' Activate it
Set fieldFilter = crs.Filters.Add("dataset::FieldStateFilter", "ErrorAndReject") ' Add a
fieldState Filter
Set docFilter = crs.Filters.Add("dataset::DocumentTypeFilter", "InvoiceAndOrder") '
get the Documenttype Filter
fieldFilter.Reset ' sets all states to FALSE
fieldFilter.State(StateReject) = True ' set StateReject to TRUE
fieldFilter.State(StateError) = True ' set StateError to TRUE
docFilter.Reset ' sets all Doc. Types to FALSE
Set docType = App.Project.DataSet.Schema.DocumentTypes("Invoice") ' get the "Invoice"
doc.type object
docFilter.Type(docType) = True ' set it to true
Set docType = App.Project.DataSet.Schema.DocumentTypes("Order") ' get the "Order" doc.type
object
docFilter.Type(docType) = True ' set it to true
End Sub

Here, a new cursor object with name MyCursor (the className is always dataset::DefaultCursor) is
created, and activated afterwards by being assigned to the controller’s
filters, one for each existing type

dataset::FieldStateFilter and dataset::DocumentTypeFilter. The rest

Cursor property. We then create two new

of the code is the same as in the first example.

The

Cursor object has got properties Documents and Fields. These return the list of documents/fields with

respect to the currently selected filters.

Properties and methods of the

Cursors object (excerpt):

Property/Method Returns Description

Add Cursor

Adds a new cursor to the list. The newly created
cursor is returned.

Parameters:

ClassName as String: Always
dataset::DefaultCursor

Name as String

At Cursor

Returns the cursor from the list at the given index
position or with the specified name.

Parameter:

Index as Long or Name as String

Name is the name under which the cursor was added
to the list; the standard cursor is named default

In addition, all the methods defined for collections are available.

Properties and methods of the

DOKuStar Validation for Ascent Capture Page • 51

Cursor object (excerpt):

Property/Method Returns Description

Documents Documents

Fields Fields

Filters CursorFilters

FirstDocument Document

FirstField Field

LastDocument Document

LastField Field

Name String Name of the cursor object.

NextDocument Document

Returns the list of documents with respect to the currently
selected filters.

Returns the list of fields with respect to the currently
selected filters.

Returns the list of CursorFilters appended to this cursor.

Returns the first document from the Documents list.

Returns the first field from the Fields list.

Returns the last document from the Documents list.

Returns the last field from the Fields list.

Returns the next document from the Documents list.

Parameter:

CurrentDocument as Document

NextField Field

Returns the next field from the Fields list.

Parameter:

CurrentField as Field

PreviousDocument Document

Returns the previous document from the Documents
list.

Parameter:

CurrentDocument as Document

PreviousField Field

Returns the previous field from the Fields list.

Parameter:

CurrentField as Field

Properties and methods of the

Property/Method Returns Description

Add CursorFilter

CursorFilters object (excerpt):

Adds a new filter to the list. The newly created filter is
returned.

Parameters:

ClassName as String: One of the two predefined

class names dataset::FieldStateFilter and dataset::

DocumentTypeFilter

Name as String: New name of the filter

At CursorFilter

Returns the filter from the list at the given index position or
with the specified name.

Parameter:

Index as Long or Name as String

Name is the name under which the filter was added to the

list; the standard filter names are fieldstate and

documenttype

DOKuStar Validation for Ascent Capture Page • 52

In addition, all the methods defined for collections are available.

For the filter objects, there is a base class called
you hardly will use. Derived from this base class there are the three classes

CursorFilter. This class has few methods and properties, which

DocumentTypeFilter,

FieldStateFilter and FieldConfidenceFilter, where you define which document types and field states

respectively are switched on and off.

Properties and methods of the

Property/Method Returns Description

All --

Reset --

State Boolean

FieldStateFilter object (excerpt):

Switches all field states on. Every field will get
activated.

Switches all field states off. No field will get
activated.

Returns/sets a single state to on or off.

Parameter:

State as State

Values for State are:

StateEmpty

StateError

StateNone

StateOk

StateReject

Properties and methods of the

Property/Method Returns Description

All --

Reset --

Type Boolean

DocumentTypeFilter object (excerpt):

Switches all document types on. Every document
will get activated.

Switches all document types off. No document will
get activated.

Returns/sets a document type to on or off.

Parameter:

doc as DocumentType

Properties and methods of the

Property/Method Returns Description

Reset -- Sets the threshold to 100.

Threshold --

FieldConfidenceFilter object (excerpt):

Sets the threshold to a value between 0 and 100.
Only fields with a confidence value less or equal to
the threshold will be activated.

DOKuStar Validation for Ascent Capture Page • 53

DOKuStar Validation for Ascent Capture Page • 54

Add-Ins

Introduction

Validation allows to modify its behavior using VBA. Because of some limitations of this method, Validation
provides, starting with version 3.2, another way for interaction: add-ins .

An add-in for Validation is an
custom user control and one custom toolbar. In addition it is possible to easily handle the existing image control or to
replace the existing edit and fields controls with your own controls.

Add-ins also allow to react to mouse movements on the image control and to keyboard actions.

The following sections explain the new functions using a simple example. You will find this example in the
examples directory under

For detailed information study the complete example
description of the complete interface can be found in the reference file

ActiveX Control. An add-in allows to add new menu entries or create and use one

Tutorial.

ValiTour contained in the examples directory. A detailed

ValRef.chm.

DOKuStar Validation for Ascent Capture Page • 55

Registry Key for Validation Add-Ins

To be able to use a newly created add-in you must first add some information into the registry. It is useful to do this
as a first step, because afterwards you are already able to test the add-in while you write the program code.

Therefore Validation will use the following registry path (for version 3.2; for later versions replace this string by the
respective version):

HKEY_LOCAL_MACHINE\SOFTWARE\ODT-OCE\DOKuStarValidation\3.2\Addins:

Under this registry key you must first specify for which application you want to add the add-in. Normally the
application you will use is the program file of DOKuStar Validation,

dsval.exe. In this case you must create a key

DSVAL. Alternatively you can specify the full path of the program file at this point. If the program resides in the

directory
key name is not case-sensitive.

For example, if you rename
Validation is looking into the registry and tries to match from right to left, not regarding the file name extension and
maybe a character
After creating the right sub-key under

c:\validation\bin, then you could use c:/validation/bin/DSVAL as key name. The

dsval.exe to mydsval.exe then you must use MYDSVAL for the key name.

d before the extension. So you are able to use the same entry for the release and debug version.

Addins - in our example now DSVAL - you must always create a sub-key

CLSID. The key name is not case-sensitive.

DOKuStar Validation for Ascent Capture Page • 56

Under this key a sub-key has to be created for each add-in that should be used for the respective application, here

dsval.exe. The key name must be the program id of the add-in, which has the format <project>.<class>.

<project> is the name of the VB6 project and <class> is the name of the class module.

Here

In the following section we will create a library

ValiTour.dll with an add-in that is represented by the class
MyValidation. Therefore the program id, and thus the sub-key name for this example add-in is
ValiTour.MyValidation:

You will also find the default add-in

Important Note: If you work with your own add-ins, save the add-ins and export the corresponding registry
entries, before installing a new release of DOKuStar Validation. When DOKuStar Validation is removed, the registry
keys may be deleted, so that you have to reinstall your own add-ins after a new release has been installed.

ODT_F4.Module here.

DOKuStar Validation for Ascent Capture Page • 57

Creating an Add-In

An add-in for DOKuStar Validation is always an ActiveX Control. You can write such an ActiveX Control in
any programming language. In our example we use Visual Basic.

In Visual Basic use the
appearing

Now choose

New Project dialog box:

References from the Project menu. In the References dialog box select the entry ODT

DOKuStar DataSet

able to use the add-in functionality:

New Project command of the File menu and choose ActiveX Control from the

x.y Type Library (x.y is the version number of the currently installed version) to be

Name the project

ValiTour and add a new class module MyValidation to the project. Change the property

Instancing of the class MyValidation from PublicNotCreatable to MultiUse. This is important;

otherwise the add-in will not work.

There is now one new function:

DOKuStar Validation for Ascent Capture Page • 58

Private Sub IAddIn_Initialize(ByVal App As DOKuStarDataset.IApplication)

for this class. It is called when the add-in has been initialized by Validation.

Now type in the following code for the class

MyValidation and generate ValiTour.dll.

If you now start Validation, a message box will appear:

DOKuStar Validation for Ascent Capture Page • 59

Creating a Custom User Control

In the previous section is described, how to create an add-in for Validation.

In this section a new custom user control is added to Validation. The appropriate service is called

UserCtrlBarData service. It is only possible to add one and only one custom user control.

We will implement the custom user control for Validation using an add-in:

First we have to add another reference. Use the command

References of the Project menu. In the

References dialog box select the entry ODT DOKuStar Validation (Services) … Type Library of the

currently installed version:

Now we add an ActiveX control to our project and change its name from
now contains a class and a user control:

UserControl1 to User. Our project

In the object view of the new control
respectively:

DOKuStar Validation for Ascent Capture Page • 60

User we add two buttons and set the caption to Clear and Restore

Modify the code of our example in the following way and generate

ValiTour.dll:

There is also a special custom user control interface
or otherwise the custom user control will not work properly.

When you now start
interface. The

dsval.exe you will see that our custom user control appears on the Validation user

View menu now allows activating or deactivating the custom user control.

IUserCtrl. You must implement the function of the interface,

DOKuStar Validation for Ascent Capture Page • 61

DOKuStar Validation for Ascent Capture Page • 62

Creating a Custom Toolbar

It is also possible to create one and only one custom toolbar for DOKuStar Validation. The appropriate service is

UserToolbarData service.

called

First add a new user control to the project and name it

Afterwards define the elements of the toolbar. For our example we add a toolbar and an image list to the form. To be
able to add a
dialog of the

ToolBar control, you have to add it to the ToolBox first. To do this, go to the Components
Project menu and select Microsoft Windows Common Controls 6.0.

Toolbar:

To activate the toolbar change our example in the following way:

DOKuStar Validation for Ascent Capture Page • 63

As you can see, the toolbar is activated in the same way as the user control. The only difference is the type of service
which has to be defined.

There is also a special custom toolbar interface
interface, otherwise the toolbar will not work properly. The first one sets the caption of the toolbar. It can be seen
when the toolbar is dragged outside the toolbar area and changes into a window. The other functions allow to specify
the width and the height of the toolbar. If they are not set properly the toolbar will appear without any content.

Therefore type in the following code for the toolbar and again generate

IUserToolbar. You must implement all three functions of the

ValiTour.dll:

If you now start Validation, the new custom toolbar will appear at the right end of the toolbar area and it can be
enabled or disabled using the

DOKuStar Validation for Ascent Capture Page • 64

View menu:

DOKuStar Validation for Ascent Capture Page • 65

Creating Menu Entries for Validation

The programming interface allows to change the menu entries of DOKuStar Validation. The appropriate service is

Workspace service. New menu entries can be added, existing menu entries can be replaced or deleted.

called

Now we will modify the menu using our add-in:

First of all we have to define the workspace by the line

Dim WithEvents workspaceSink As DOKuStarValidationServices.WorkspaceService.

Then we have to get the specific service for processing workspaces. That is done by the line

Set workspaceSink = dsValApp.Services("Workspace").

In our example we place the code that changes the menu in a separate function called
will replace the existing menu entries

In addition, we will add the modules

• API_Declarations,

• Translation

• ValidationIDS

to our example. You will find the corresponding files in the directory

DOKuStar Validation for Ascent Capture Page • 66

New and Import.

Common.

changeMenu(). There we

After this code has been entered, generate
look like this:

ValiTour.dll and start dsval.exe. The File menu will now

DOKuStar Validation for Ascent Capture Page • 67

The

New command has been replaced and shows a submenu with two entries. Following the Export Data

command the new command
implementing what should happen if the new menus are used.

For this purpose the

Workspace service has two functions: workspaceSink_OnCommand and

Import Extraction Result… appears. The only thing you have to do now is

workspaceSink_OnCommandUpdate.

Let us first look at
command with our own one. There is also a
from existing toolbars, so we have to disable the menu command
button is also disabled. With

= False

This is done by the statement
and the status bar by setting the variables

it is disabled. We must also tell Validation that we have handled the menu command New by ourselves.

workspaceSink_OnCommandUpdate. In our example we replace the existing New

New button in the toolbar. It is not possible to replace such a button

New and with this the corresponding toolbar

EventArgs.Enable = True a menu entry is enabled, with EventArgs.Enable

EventArgs.Handled = True. In addition we have to specify texts for tool tips

ToolTiptext and the StatusText for our new menu entries.

DOKuStar Validation for Ascent Capture Page • 68

The second function of the

Workspace service, workspaceSink_OnCommand, is needed to specify the

actions that should take place when the menu command is used.

Here you must again use

EventArgs.Handled = True to tell Validation that we have programmed and

executed the actions for the respective menu entry:

DOKuStar Validation for Ascent Capture Page • 69

If you enter the code shown above, generate

ValiTour.dll, start dsval.exe, and open the File menu, the

new menu items will be shown. If you use one of them, the corresponding message box will appear:

DOKuStar Validation for Ascent Capture Page • 70

Workspaces

In the previous section we used the Workspace service of Validation. In this section it is explained what a
workspace is and how it is used.

The workspace of Validation comprises the size and location of the various elements of the user interface of
Validation within the main window. For example, if you drag custom user control of our example from the bottom of
the main window to the top, you are changing the workspace of Validation. The same is true, if you change the order
of the toolbars.

Validation normally does not save the current workspace. So if you start Validation the main window will show the
default layout and will not reflect changes made during the previous session. In our example, the custom user control
will appear again at the bottom and not at the top.

To be able to solve this problem it is possible to save the workspace to the registry or to a file.

At first we will save a workspace to a file. The methods

workspaceSink.LoadWorkspace and

workspaceSink.SaveWorkspace allow to load a workspace from file or to save it to a file respectively. As a

preparation the
previous section. There it was saved to the variable

Workspace service of Validation must be provided. In our example we did this already in the

workspaceSink. We load the workspace in a function

loadDefault() that shall be called when Validation is already initialized (i.e. in the function
dsValApp_OnFinalInitialized) and we save it in a function storeDefault() that shall be called before

Validation is closed (function

After entering the code, generate
like this:

dsValApp_OnClosed):

ValiTour.dll and start dsval.exe. The Validation window will now look

DOKuStar Validation for Ascent Capture Page • 71

What happens? We have loaded the workspace

default.vws at startup of Validation. In this workspace our

custom user control is no longer at the bottom of the Validation window. Now enlarge our control until the

Restore button appears and close Validation. If you now restart dsval.exe you will see that its behavior has

changed:

DOKuStar Validation for Ascent Capture Page • 72

Validation now comes up with the last changes you made in the workspace. Play a little around to get a feeling. You
could remove the call to

To write it to a file is probably not the best method to save a workspace. Therefore it is also possible to store the
workspace information in the registry. The corresponding commands are

storeDefault and check that changes of workspace will no longer take effect.

workspaceSink.LoadWorkspaceFromRegistry and
workspaceSink.SaveWorkspaceToRegistry.

The registry path that is used is

HKEY_CURRENT_USER\Software\<base path>\Workspaces\<sub-key> .

The base path is controlled by
Validation uses the standard base path
key, Validation appends the standard base path to the specified key. If it contains a hierarchy, Validation uses the
value as it is.

The sub-key has to be specified in the load and save functions.

In our example we use the single key
standard base path. We will have to take that into account when we check the registry key for our workspace later.
To be able to set

RegistryKey must be specified in the function IAddIn_Initalize, otherwise it will take no effect.

RegistryKey we will have to provide the workspace service also in the function

RegistryKey. If RegistryKey is an empty string, which is its default value,

DOKuStar Validation\<version> for base path. If it is a single

ValiTour for RegistryKey. Therefore Validation will append its

IAddIn_Initalize and to delete the corresponding statement in dsValApp_OnFinalInitialized. In the load

and save functions we will use the sub-key
version 3.2; for later versions replace this string):

Default. Therefore Validation will use the following registry path (for

HKEY_CURRENT_USER\Software\ValiTour\DOKuStar Validation\3.2\Workspaces\Default

DOKuStar Validation for Ascent Capture Page • 73

Then we have to modify the functions

loadDefault() and storeDefault(). In loadDefault() we

first check whether the registry key already exists. If not we load the workspace from file, otherwise we fetch it from
the registry. In

storeDefault() we store the workspace to the registry and into a file. So, when dsval.exe

is started for the first time, the workspace will be loaded from file. When Validation is closed the workspace will be
written to the registry as well. From then on the workspace will always be loaded from and stored to the registry. If
you delete the specified key from the registry the same will happen again. So you are now able to handle different
workspaces.

DOKuStar Validation for Ascent Capture Page • 74

Handling Keyboard Strokes

Keyboard strokes can also be handled by an add-in for DOKuStar Validation. The appropriate service is called

Keyboard service. First you must provide the keyboard service of Validation.

The keyboard service has two functions
from the keyboard. That means if you press

OnChar() and OnKeyDown(). In OnChar() you get the final code

Shift-A, you get the final key code in OnChar(), in this case 65. In

OnKeyDown() you get the code for Shift and a. Normally you would implement hotkeys in OnKeyDown().

For our example we assume that numbers should be suppressed in the edit control and that the user should get a
message box if he presses

F4.

DOKuStar Validation for Ascent Capture Page • 75

Now start now Validation with

dsval ValiTour.vpj. The Validation window will look as follows:

Press the

F4 key and the message box will appear:

Now try to enter numbers for the fields. Numbers will be suppressed but all other characters will appear normally.

DOKuStar Validation for Ascent Capture Page • 76

Replacing Existing Controls

In a previous section we created a custom user control. As was stated there, you can create only a single new user
control, but you can replace existing controls, namely edit control and the fields control. In our example we will

replace the edit control. The appropriate service is called

Let us replace the current edit control and use a new one for the text fields. First of all we create a new user control
and name it

Place an edit text box on this control. Change the color so that you can easily recognize any effects on Validation:

Edit.

UserEditData service.

To be able to work with the control, it must be attached to the respective objects., e.g. to a special field type. In our
example we will attach it only to text fields. To do this, a project must be loaded in Validation. Therefore we place

the code as a function call into

In the function
Validation project is already available. If this is the case we connect to the Validation field type

It is possible to connect to edit control elements of the

applyEditControl we have now to implement the necessary code. We first check if a

dsValApp_OnProjectLoaded:

TextField.

DocumentDesciptor and elements of the

FieldDescriptor. TextField is an element of the FieldDescriptor. For more details you should read the

chapter “Integration”.

DOKuStar Validation for Ascent Capture Page • 77

Now start Validation with the command

dsval ValiTour.vpj. The Validation will look like this:

The replaced edit control can be easily recognized by its changed color. If you move the cursor to the field
the color will disappear because this field is of the field type
only to text fields. If the new control should also be active for fields of type

TableField and our new edit control was attached

TableField, it must be attached to type

Table,

TableField additionally, in the same way as we attached it to the type TextField.

DOKuStar Validation for Ascent Capture Page • 78

Managing the Image Control

The behaviour of the image control, like scrolling and zooming, can also be managed by an add-in. The appropriate
service is called

Dim sourceCtrlSink As DOKuStarValidationServices.SourceCtrlService and Set
sourceCtrlSink = dsValApp.Services("SourceCtrl"):

SourceCtrl service. Like the other services it must first be provided which is done by the lines

Let us now implement a special behaviour of the image control. We want to use three key combinations to set the
zoom factor to 300, 200 and 100 respectively and an additional one to scroll to the right.

The zoom factor of the image control can be changed using

sourceCtrlSink.Zoom. Using
sourceCtrlSink.ScrollTo allows to scroll to a specified position. In our example we use Control+3,
Control+2 and Control+1 to switch to a specified zoom factor and Control+R for scrolling to the right.

DOKuStar Validation for Ascent Capture Page • 79

Now start

dsval ValiTour.vpj and try the key combinations to see the effects.

Predefined Add-Ins

There are two add-in modules that will be provided by DOKuStar Validation.

ODT_F4.Module

This default add-in is ready for use. It changes the layout of the DOKuStar Validation user interface from "normal"
view to "table" view by using the

DOKuStarValidation.Spy

This add-in starts an event spy window. In the window all events fired by DOKuStar Validation will be listed. This
will be helpful during development and test of Validation scripts.

The add-in is contained in the file

To be able to use this ActiveX control in your environment, first you have to register it using regsvr32.exe.

Furthermore you have to add the key
use the following registry path (for version 3.2; for later versions replace this string):

C:\Programme\Gemeinsame Dateien\ODT-OCE\DOKuStar.

HKEY_LOCAL_MACHINE\Software\ODT-OCE\DOKuStarValidation\3.2\Addins\DSVAL\CLSID

Table Mode command of the View menu.

validationspy.dll. You will find it in the directory

DOKuStarValidation.Spy to the registry entry Therefore Validation will

When you start DOKuStar Validation in administrator mode from a DOS-Box, use the addin option to create this
add-in object as shown in the following example:

The DOKuStar Validation user interface will be shown. When you type CTRL+F8 the system tree windows will
appear. When you type

To disable the function use the option

DOKuStar Validation for Ascent Capture Page • 80

C:\Programme\DOKuStarValidation\Bin\dsval –a –addin=DOKuStarValidation.Spy

CTRL+F9 the Event Spy windows will be shown.

–drop-addins from a DOS box.

Special Issues

Information Bar

The information bar is one of the windows of the Validation’s user interface; when the program starts, it is located
above the field source bar (which displays the field’s snippet), but it can be moved around like any another window.

This information bar can be filled programmatically, in order to display messages to the validation operator. To do
so, there is a class

Text property to display a text:

use its

Option Explicit

Public infoBar As New StatusTextTransporter

Private Sub Application_OnProjectLoaded(ByVal App As Application)
infoBar.Text = "Hello InfoBar"
End Sub

StatusTextTransporter. Define an object of this class (preferably as a global variable) and

While the Text property displays the text in a standard format and size, the HtmlText property allows you to
format the text individually by using standard HTML tags. The following example will display the text bold,
enlarged, and in italics:

Option Explicit

Public infoBar As New StatusTextTransporter

Public WithEvents DateField As FieldType

Private Function DateField_OnFieldChanging(ByVal Field As Field, ByVal SubField As Field, _
ByVal VerifyEventArgs As VerifyEventArgs) As Boolean
DateField_OnFieldChanging = True
If Not ValidDate(Field.Value) Then
infoBar.HtmlText = "<b> <h1> <i> Invalid Date </i> </h1> </b>"
End If
End Function

Private Function ValidDate(fieldValue As String) As Boolean
'* code to check the format
End Function

DOKuStar Validation for Ascent Capture Page • 81

The result will look like this:

DOKuStar Validation for Ascent Capture Page • 82

Exchanging the Fields View

In the Validation’s Fields View all fields of the current document are displayed together with their values. The
fields are displayed one below the other, the active field is always highlighted.

The appearance of this window can be exchanged individually for each Ascent Capture form type.

This is done by defining an HTML template for each form type. To do so, place a file named

type>.html

(<form type> must be replaced with the name of the form type) in the directory

<form

…\Ascent\AdminDB\DokuStarValidation\templates

(or in the DokuStarValidation_x directory for subsequent validation stages).

If DokuStarValidation does not find such a HTML file for a certain document type, it uses the standard way of
displaying the fields:

There are two modes, in which a field in a customized HTML view can be displayed:

-

Edit Mode: The field’s contents can be edited directly in the HTML view. The normal editing window will then

just display the current contents of the field, the editing itself is done in the HTML window:

DOKuStar Validation for Ascent Capture Page • 83

In this mode, you could also close the editing window.

-

Display Mode: In this mode, editing is still done in the editing window. The HTML view just offers a

different way of displaying the fields:

DOKuStar Validation for Ascent Capture Page • 84

Note 1: You can also mix the modes: Use the editing mode for some fields, and the display mode for others

Note 2: Tables can only be edited in the editing window, not in the HTML view.

The HTML file itself can be created with any HTML editor (FrontPage etc.). To link it to the document model, you
must use an attribute named

id in your tags, which has the field name as value.

In editing mode, you will use an

<input type="text" id='CustomerId'>

In the display mode, you will use a tag like <span>:

<span id='CustomerId'>

Which mode (display/editing) you use, is only determined by the HTML tags you use (<input> versus <span>,

input tag, which has this id attribute set:

<pre>,..). Using the id is all that needs to be done to link to the Validation data!

There are two examples of customized HTML files installed with DOKuStar Validation for Ascent Capture. These
are named

These examples define the two views you see in the pictures above;
mode,

can try out these HTML views in the following way:

Along with the DOKuStar Extraction for Ascent Capture installation comes an example named
consists of a

DOKuStar Validation module to the batch classes’ queues. This
form type named
definition.

To do so, choose which one of the two HTML files you want to use. Copy it to the

form_Static.html and form_Edit.html and reside in the …\Ascent\bin\DokuStar directory.

form_Static is the example for the display

form_Edit for the editing mode. If you have DOKuStar Extraction for Ascent Capture installed as well, you

AllTypes, which

.cab file and the DOKuStar file. Import this .cab file in the Administration module, and add the

AllTypes batch class defines, among others, a

form. This form type is the one we want to be displayed in the Validation according to our HTML

…\Ascent\AdminDb\DokuStarValidation\templates directory and rename it to form.html.

When you now run the sample images, those which have the form type
way shown above.

form will be displayed in Validation in the

DOKuStar Validation for Ascent Capture Page • 85

Table Data Output

When DOKuStar recognizes tables, the corresponding data is transported in separate files outside the Ascent Capture
data structure.

When you finally release your batch, it is important to know how to access this data.

Table data are stored in XML files. There is one file for each document, which has the same name as the image file
of the first page of the document with an extension

....\Ascent\images\0000009C\200\1.tab. The path where an image resides can be determined in

release scripts, providing access to the table data file as well.

The table data file has the following format (DTD-Notation):

<!ELEMENT DOKuStarValidation (Tables*)>
<!ELEMENT Tables (Table*)>
<!ELEMENT Table (Rows*)>
<!ATTLIST Table Name CDATA “”>
<!ELEMENT Rows (Row*)>
<!ELEMENT Row (Cells*)>
<!ELEMENT Cells (Cell*)>
<!ELEMENT Cell EMPTY>
<!ATTLIST Cell Name CDATA “”>
<!ATTLIST Cell Value CDATA “”>

.tab instead of .tif. For example, you could have a file name like

Example:

<?xml version="1.0" ?>
<DOKuStarValidation>
<Tables>
<Table Name="Table">
<Rows>
<Row>
<Cells>
<Cell Name="Position" Value="1.1.02" />
<Cell Name="Description" Value="Auswechseln von Lampen u. Startern" />
<Cell Name="SinglePrice" Value="4.10" />
<Cell Name="TotalPrice" Value="3017.60" />
<Cell Name="Quantity" Value="736,00" />
</Cells>
</Row>
<Row>
<Cells>
<Cell Name="Position" Value="1.1.03" />
<Cell Name="Description" Value="Auswechseln von Lampen u. Startern" />
<Cell Name="SinglePrice" Value="7.00" />
<Cell Name="TotalPrice" Value="3017.00" />
<Cell Name="Quantity" Value="431,00" />
</Cells>
</Row>
</Rows>
</Table>
</Tables>
</DOKuStarValidation

DOKuStar Validation for Ascent Capture Page • 86

If no table was found on the document, there will be a table data file whose <Rows> element is empty:

<?xml version="1.0" ?>
<DOKuStarValidation>
<Tables>
<Table Name="Table">
<Rows />
</Table>
</Tables>
</DOKuStarValidation>

DOKuStar Validation for Ascent Capture Page • 87

Character correction mode

For editing single characters (for example rejects as first step of a multi-grade Validation), you can use the character
correction mode feature. This feature is realized by an additional ActiveX Control named

UserEditData service and will replace the default EditControl.

the

The following example demonstrates the integration of the character correction mode feature and replaces the default

Edit Window of a (user controlled) Validation user interface by the ValRejectEdit Control.

Step 1

From Ascent Capture - Administration Module select a batch class (which uses at least one DOKuStar Validation
queue) and select the desired validation stage to open the DOKuStar Validation Module. Open the VBA studio,

expand the nodes and double-click the

TheApplication node.

ValRejectEdit, using

Step 2

Now choose References from the Tools menu and add the ODT DOKuStar Validation (Services) type
library to the project. From the same menu select the

and add

Now the project will contain the following references:

<system drive>:\program files\common files\ ODT-OCE\DOKuStar\

ValRejectEdit.dll as reference to your project.

Browse… button, change to the common files folder:

DOKuStar Validation for Ascent Capture Page • 88

Step 3

Now we are ready for integrating the following code lines

When the project is loaded, first we call

InitRejectEditCtrl to connect all field classes of the schema to the

RejectEditControl, with the exception of TableFields. TableFields are displayed in the DOKuStar Validation

GUI by the TableEdit Control. Therefore we prevent the TableField class from registering by the RejectEditControl.
So we are able for editing characters in TableFields by the TableEdit Control.

Furthermore we call

; this means we adjust the layout of the control and the allowed interactions for the validation operator.

trol

In addition we connect the

StateReject to activate all fields including a reject character (“?”) when a batch is opened. In this case only

to
indexfields including rejects has to be processed by the validation operator.
Of course the setting of other field state filter is practicable.

ApplyRejectEdit (code lines see below) for setting the properties of the RejectEditCon-

Controller, or the Cursor object respectively, to the field state filter and set the filter

DOKuStar Validation for Ascent Capture Page • 89

Remarks:
You will find the above code lines, explaining the character correction mode, as a complete

BatchClass, in your

Ascent Capture installation path in the folder

.

\Bin\DOKuStar\ValAC_Demos\Demo3

So you can copy and implement the sample code for your own batch classes.

DOKuStar Validation for Ascent Capture Page • 90

Properties and methods of the ValRejectEdit control:

Property/Method Value Default Description

AllowLeaveRejectMode True or False

AllowRemoveDetail True or False

AllToUppercase True or False

BackColor

VB color

True

True

False

vbWhite

Enable the editing of all characters, not only rejected ones.

Enable the deleting of a rejected character

All entered characters will appear in upper case.

Background colors of the reject edit control.

definitions

FixedMode True or False

False

The rejected character will always displayed in the middle of
the reject edit control if FixedMode is set to True.

Font VB StdFont

Default

Set the font for characters in the reject edit control

system font

RejectChar

String with

?

Set the reject character

one character

ShowDetailZone *) True or False

True

Zoom zone of rejected character in the snippet window. Only
takes affect if FixedMode is set to True

ShowFirstChoice *) True or False

True

Show first choice and not the reject character. The function
keys Return or Enter confirm the choice and the focus is

set to the next rejected character.

UseShortCuts True or False

True

Enable shortcuts:

• Ctrl-Shift-y: → toggle FixedMode

• Ctrl-Shift-c: → toggle ShowFirstChoice

• Ctrl-Shift-z: → toggle ShowDetailsZone

In case: AllowLeaveRejectMode = True

• Left/Right: → change to "normal" EditMode

• Ctrl-Shift-F12: → change to RejectMode

*)

These features only takes affect, if the preceding recognition server supply the validation module with the
appropriate information, this means, the recognition server should delivers value details and alternative values for a
result.

The following figures show the screen layout of the snippet - and the edit window in DOKuStar Validation
depending of the adjusted properties of

FixedMode or ShowDetailZone respectively.

• FixedMode = False

• ShowDetailZone = True

DOKuStar Validation for Ascent Capture Page • 91

In the snippet view window the image of the index field is displayed, where the rejected character is highlighted; in
the edit view you see the Reject Character ready for processing.

• FixedMode = True

• ShowDetailZone = True

In the snippet view window only the image of the rejected character is displayed. This mode will be usefull to
enlarge the image of the Reject Character to see further details.

• FixedMode = True

• ShowDetailZone = False

In this case the snippet view window displays the image of the index field without highlighting the rejected
character. This will also be done, if there are no value details for the reject character available.

DOKuStar Validation for Ascent Capture Page • 92

How Do I…

Reject Documents and Pages

Documents and pages can be rejected and un-rejected by the user: He clicks on the document/page in the tree view
and chooses

This can also be achieved by scripting.

reject… or unreject from the context menu. Also, he can add a reject text to the object.

To reject a document or page, add a
and set its value to

1. If you additionally want to add a reject text, add a UserData named RejectText and set it

UserData named Rejected to the Document or DataSource object

to the desired text.

DOKuStar Validation itself uses the same
can determine in the script if the user rejected a document or page by checking a
exists and if its value is set to

1.

In the following example, all documents which are of document type

UserData when the user rejects an object from the tree view. Thus, you

UserData named Rejected

Unknown will be rejected, and a text will be

added. Before adding the text, it is checked if the user himself rejected the document and added a text; if so, the
additional text is inserted in front of the existing one. This is all done when the user closes the batch.

Option Explicit

Dim WithEvents batch As Data

Private Sub Application_OnProjectLoaded(ByVal App As Application)
Set batch = App.Project.DataSet.Data
End Sub

Private Sub batch_OnPreExported(ByVal Data As Data, ByVal Mode As ExportMode)
Dim doc As Document
Dim userText As String ' text entered by the user
If Mode = ExportModeSuspend Then Exit Sub ' No action, if suspended
For Each doc In Data.Documents ' cycle through the documents
If doc.Name = "Unknown" Then
userText = ""
If doc.UserData.HasValue("Rejected") And doc.UserData.Value("Rejected") = "1" Then
' user already rejected it
If doc.UserData.HasValue("RejectText") Then
userText = ", " & doc.UserData.Value("RejectText") ' get the text and add a
comma in front of it
End If
End If
doc.UserData.Value("Rejected") = "1" ' Reject this document
doc.UserData.Value("RejectText") = "Validation operator did not change this unknown
form type" & userText
End If
Next doc
End Sub

DOKuStar Validation for Ascent Capture Page • 93

Note: In this example, it is important to check for the existence of the Rejected UserData before trying to read

its value. As long as the user does not reject a document, this UserData does not exist, and trying to read its value
would cause an error!

DOKuStar Validation for Ascent Capture Page • 94

Test the Scripting Code

Something about this topic has already been said in the first chapter, this chapter discusses some more details.

It is important to understand that each Ascent Capture Batch Class that uses DOKuStar Validation has a Validation
Project assigned to it. Each project in turn has its scripting code.

Whenever a batch is opened in DOKuStar Validation, the following things happen:

- The scripting code of the batches’ batch class is loaded.

- The project is loaded (which leads to the

- The data for the batch is loaded (which leads to the

When the operator closes or suspends the batch:

- The data are exported (which leads to the

- The project is closed (which leads to the

- The scripting code is unloaded.

This is the normal course on the validation clients. However, things are slightly different when you start DOKuStar
Validation from the Ascent Capture Administration Module:

Application_OnProjectLoaded event in the scripting code).

Data_OnDataImported event in the scripting code).

Data_OnExported event in the scripting code) and unloaded.

Application_OnProjectClosed event in the scripting code).

DOKuStar Validation for Ascent Capture Page • 95

DOKuStar Validation is opened, and you can modify your scripting code for the batch class you selected in the
Administration module, without having to open a batch. Only the first two steps from above have so far been
executed:

- The scripting code of the batch class you selected in the AC administration module is loaded.

- The project is loaded (which leads to the

Obviously, the third step, loading the data, was not executed, because we did not select a batch so far.

You might now edit your code and then select a batch to try out if your changes work:

Application_OnProjectLoaded event in the scripting code).

This leads to the following:

- The project that is currently open is closed and the scripting code is unloaded. If you did not save your latest

scripting code changes, you are asked if you want them to be saved.

- The scripting code is loaded once again.

- The project is loaded (which leads to the

- The data for the batch are loaded (which leads to the

The unloading/loading of the scripting code ensures that your latest code changes always come into effect. The
unloading/loading of the project ensures that the same things happen as in “real life” (at the Validation client

workplaces) later on (especially: the

DOKuStar Validation for Ascent Capture Page • 96

Application_OnProjectLoaded is executed).

Application_OnProjectLoaded event in the scripting code).

Data_OnDataImported event in the scripting code).