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