EN INVOICES CustomizationTraining ExerciseBook MI50-C STUDENT

Customization
Training
EXERCISE BOOK
• Exercise 4A: Sum total validation using
field expressions (page 3)
• Exercise 4B: Having INVOICES correct

invalid values automatically (page 5)
• Exercise 4C: Adding static output data to

the transaction description (page 7)
• Exercise 5A: Sum total validation using

your own code (page 9)
• Exercise 5B: Applying a predefined

transfer format (page 13)
Customization • Exercise 6A: Using ADO to validate
Training information in an external (page 15)
• Exercise 6B: Using ADO to output data to

EXERCISE BOOK an external system (page 17)
• Exercise 6C-1: Automatic routing of

invoices to queues (page 21)
• Exercise 6C-2: Routing invoices to queues

with a user-defined menu (page 23)
• Exercise 6D: Adding scan information with

a user-defined dialog (page 25)
INVOICES Customization Training Exercise Book
Eyes & Hands® software and documentation are protected by law from unauthorized
reproduction. It is a punishable offense to make copies or revisions of the Eyes & Hands software
and documentation.
This publication may not wholly or partially, in any form, optically, manually, or in any other way
be reproduced, sent, rewritten, or translated into any other language without prior written
permission from ReadSoft. The contents of this document are subject to change without notice.
ReadSoft and Eyes & Hands are registered trademarks of ReadSoft AB.
Other product and company names herein may be the trademarks or registered trademarks of their
respective owners.
Comments regarding this publication can be sent to:
ReadSoft AB – Professional Services
Box 807
S-191 28 Sollentuna
Sweden
training@readsoft.com
www.readsoft.com
© 2004 ReadSoft AB
Date of issue: April 2004
Article number: MI50-C
All rights reserved
EXERCISE BOOK OVERVIEW
Foreword
What is this course about?
The ReadSoft INVOICES Customization Training course provides the background that you need
in order to get started in customizing INVOICES based on customer specifications. “Getting
started” means that this course should be seen as providing basic customization skills.
How this Exercise Book is organized

The INVOICES Customization Training Exercise Book is made up of hands-on exercises that you
will carrry out during the following sections of the course:
• Using the built-in power of INVOICES
• Getting started with customization in INVOICES
• Greater business benefits from complex customizations
Each exercise has a main function of demonstrating either data validation, transformation, or
supplementation. Right-hand pages include text for you to focus on, while left-hand pages have
large blank areas for you to write your own notes.
When you are finished with the INVOICES Customization Training course, use this Exercise
Book in combination with other course materials to remind yourself of details to keep in mind
when customizing INVOICES.
1
"
2
EXERCISE 4A: VALIDATION USING BUILT-IN FUNCTIONALITY
Exercise 4A:
Validation using built-in functionality
Sum total validation using field expressions
Technical objectives
• Using the field expression function in the Single item field profile (or “Field profile”) dialog
to validate that the calculated sum of the matches the amount interpreted for the
Total_Amount field
Learning objectives
• Orienting yourself to the advanced parts of the Field profile dialog
• Experiencing when the validation fails in Verify and interacting with the resulting dialog box
Resources
• Help file information on the field expression function
• ProfileAPI invoice profile
• Job description General
Procedure
Keep in mind
• The syntax check performed after you click OK in the Field profile dialog makes sure you
have created a valid expression. If not, a message is shown and you have to review your
settings. Note that the syntax check is case sensitive (for example,
"=NET_aMounT+vat_amount" would give an error).
• Expressions are only used for validation, not supplementation. The values are not
calculated from the expressions, only validated against them.
3
"
4
EXERCISE 4B: VALIDATION USING BUILT-IN FUNCTIONALITY
Exercise 4B:
Validation using built-in functionality
Having INVOICES correct invalid values automatically
• Correcting a partially interpreted value using active validation and an internal table
Learning objectives
• Understanding more about internal tables and how to connect them to different fields
• Experiencing how INVOICES corrects field values based on the table data
Resources
• Help file information on active validation
• ProfileAPI invoice profile and job description General
Procedure
• Open the Manager module and create a new table called BankAccts with the following
values: 1234567899, 8328012834, 5150661064
• Open the Bank_Account field in ProfileAPI:
• Table validation settings part of the configuration, select the BankAccts table in the
Table name field.
• Select Use active validation.
• Run the General job in Interpret (importing images) and Verify. Pay close attention in Verify
to what happens when the Bank_Account field is not properly interpreted.
• Edit the Bank_Account field to a value not found in the table, in order to make sure the
validation is activated.
Keep in mind
• Internal tables have to be updated manually. A better solution may be to use an external
table (either an ODBC source or a text file) that is updated automatically by an external
system.
• Active validation is only performed in Interpret. If a value is entered in Verify, the value is
only validated against the table, not translated automatically.
5
"
6
EXERCISE 4C: TRANSFORMATION USING BUILT-IN FUNCTIONALITY
Exercise 4C:
Transformation using built-in functionality
Adding static output data to the transaction description
• Adding specific characters to the output file that are not dependent on the information
captured from processed invoices
Learning objectives
• Understanding more about how transaction descriptions work and seeing the potential value
of using multiple transaction descriptions instead of customization programming.
Resources
• Help file information on transaction descriptions
• ProfileAPI invoice profile and transaction description Tran_Ex4
• Job description General
Procedure
• Open the transaction description Tran_Ex4.
• Add a field that outputs the data “CompanyCode:2285”.
• Run the General job in Interpret (importing images), Verify, and Transfer. Make sure the
output file contains the static data defined earlier.
Keep in mind
• Having multiple job descriptions (each processing invoices from specific queues, for
example) that each use a different transaction description with some static data can
eliminate the need for customization in transfer.
7
"
8
EXERCISE 5A: VALIDATION USING LESS COMPLEX CUSTOMIZATION
Exercise 5A:
Validation using less complex customization
Sum total validation using your own code
• Creating an INVOICES plug-in
• Using code to create the same sum total validation as in exercise 4A
Learning objectives
• Understanding what is needed to create an INVOICES plug-in
• Starting to understand how events and objects are handled in INVOICES’ COM API
• Familiarizing yourself with the way INVOICES uses statuses
Resources
• Detailed information about INVOICES’ COM API and specifics on how to create a plug-in
• Visual Basic development environment
Procedure
• Delete the sum total validation rule that you created earlier for the Total_Amount field.
• Open a new VB project as an ActiveX DLL.
• Set a reference to the Eyes & Hands INVOICES 5-2 Type Library.
• Name the class module Connect and the project Exercise5A.
• Write a Connect and Disconnect function in the class module. Subscribe to the event(s) you
need for the sum validation.
• Write a ConfigurePlugin function that displays a message box.
• Write code for the sum validation. When the sum is not correct, display a message box.
• Before you can run the VB project, you have to add the plug-in in the eilocal.ini file.
The following lines have to be added in directly under the section [Plugins::eiitrp]
(for Interpret) and [Plugins::eiveri](for Verify):
Plugin*=Exercise5A
[ei****::Exercise5A]
Name=API Training Exercise 5A
Type=COM
SupportIDispatch=True
ClassName=Exercise5A.Connect
9
"
10
EXERCISE 5A: VALIDATION USING LESS COMPLEX CUSTOMIZATION
• Set a breakpoint (press F9 in the VB editor) inside the event handler function in your code.
• Run the VB project, and select Wait for components to be created.
• Open the Interpret module. Open the Extension programs dialog (HelpÖAbout Eyes &
HandsÖExtensions). Select your plug-in and click Configure. Your message box is
displayed.
• Run the General job in Interpret (importing images).
• Run the General job in Verify, correcting any invalid fields.
• When you are satisfied with your code, compile the project to a DLL.
Keep in mind
Events
• Events are fired at predefined occasions.
• When an event is fired, INVOICES checks if there is a handler defined for the event.
• You must always use a return value (evtOK, evtOKAbort, evtError, or
evtCancel) in your event handler.
• In your code, try not to use the same events that standard components or Option Packs use.
If you cannot avoid doing this, then return make sure to return evtOK.
Objects
• There are three different types of objects in INVOICES: application, definition, and run-
time objects.
• The objects have associated properties and methods, and some also belong to collections.
• Not all objects are available with all events; an event’s level is what dictates which objects
are available.
• To get the correctly formatted field value (as specified in eiglobal.ini), use the
InvoiceField object property called DisplayString.
Plug-ins
• Plug-ins subscribe to events.
• Multiple plug-ins can be used for the same event. Be aware that if, for example, two plug-
ins subscribe to the same event, the “worst” event handler return value will take
precedence and be used by INVOICES.
• INVOICES 5-2 does not guarantee the executing order for plug-ins subscribing to the
same events. In INVOICES 5-3 SP1 and later, the order in ehlocal.ini defines the
execution order.
Validations
• Customizations involving validation are most often used with the InvoiceComplete and
FieldComplete events.
• If the event FieldValidate is used for validations, remember that this event is fired before
INVOICES’ internal validations are done, so INVOICES could reset any changes when
the internal validations are performed. Therefore, you’ll have to use evtOKAbort in
order to skip internal validations.
11
"
12
EXERCISE 5B: TRANSFORMATION USING LESS COMPLEX CUSTOMIZATION
Exercise 5B:
Transformation using less complex
customization
Applying a predefined transfer format
• Making sure that an order number is always formatted to 10 characters with leading zeros
• Adding the country prefix to the VAT registration number field in cases where the country
prefix does not exist
Learning objectives
• Formatting values to fit external systems or other parts of the solution (such as the Integration
Option Pack)
Resources
• Help file information on transaction descriptions
Procedure
• Name the class module Connect and the project Exercise5B.
• Write a Connect and Disconnect function in the class module. Subscribe to the event(s) you
need for the field formatting.
• Write code for the field formatting.
• Activate your new plug-in in the eilocal.ini file.
• Run the General job in Interpret (importing images) and Verify. Make sure the fields are
formatted according to the rules that you set up.
• When you are satisfied with your code, compile the project to a DLL.
Keep in mind
• When only one field is involved in a field event, use SubscribeToObject.
13
"
14
EXERCISE 6A: VALIDATION USING MORE COMPLEX CUSTOMIZATION
Exercise 6A:
Validation using more complex customization
Using ADO to validate information in an external database
• Validating the existence of an order in an external system (represented by a separate database
on the database server)
Learning objectives
• Learning how to use ADO and incorporating it into the INVOICES flow
Resources
• Information on ADO from the presentation
Procedure
• Name the class module Connect and the project Exercise6A
• Save your project
• Make sure that the Visual Basic class module ADODatabase.cls has been copied to the
folder where you saved your project.
• Add the ADODatabase class to your project
• Add a project reference to “Microsoft ActiveX Data Objects 2.5” (or later).
• Write a Connect and Disconnect function in the Connect class module. Subscribe to the
event(s) you need for the validation.
• In your event handler, write code for the following:
• Create an instance of the ADODatabase class and connect using the connection string:
"Provider=SQLOLEDB;User ID=sa;Initial Catalog=MyExternalSystem;Data
Source=(local);Password="
• Confirm the existence of the order number by using the GetRecordCount method on the
ADODatabase class, passing Orders as the table, OrderNumber as the field name, and
strOrder as the name of the variable you will populate with the order number from the
PO_Number field on the invoice.
• If the order could not be found in the database, change the status of the PO_Number field
to ValidationError.
15
"
16
EXERCISE 6B: TRANSFORMATION USING MORE COMPLEX CUSTOMIZATION
• Activate your new plug-in in the eilocal.ini file

• Run the General job in Interpret (importing images) and Verify. Make sure the order field is
validated according to the database table (you can open SQL Enterprise Manager and look for
valid data).
• When you are satisfied with your code, compile the project.
Keep in mind
• It can be better in some cases to use an invoice event instead of a field event. In this case,
the database operation might take a few seconds, and the user will probably prefer to
perform this operation on an invoice event—since this might not be the only field that
should be validated, it's better to gather these kinds of operations in one place, which
would correspond to only one break for the user.
Exercise 6B:
Transformation using more complex
customization
Using ADO to output data to an external system
• Sending data to an external system (represented by a separate database on the database server)
Learning objectives
• Continuing to learn to use ADO and incorporating it into the INVOICES flow
• Learning how to retrieve an identity number created by SQL Server
• Learning how to “loop through” an invoice's line items
• Learning how to skip an invoice during transfer
Resources
• Information on ADO from the presentation
Procedure
• Name the class module Connect and the project Exercise6B
• Save your project.
• Make sure that the Visual Basic class module ADODatabase.cls has been copied to the
folder where you saved your project.
17
"
18
EXERCISE 6B: TRANSFORMATION USING MORE COMPLEX CUSTOMIZATION
• Add the ADODatabase class to your project.

• Add a project reference to “Microsoft ActiveX Data Objects 2.5” (or later).
• Write a Connect and Disconnect function in the Connect class module. Subscribe to
InvoiceTransfer, since this is the only event where you have complete control of the transfer
flow.
• In your event handler, write code for the following:
• Create an instance of the ADODatabase class and connect using the connection string:
"Provider=SQLOLEDB;User ID=sa;Initial Catalog=MyExternalSystem;Data
Source=(local);Password="
• Insert the header values (invoicenumber, invoicedate, netamount and vatamount) into
the InvoiceHeaders table (open the SQL Enterprise Manager to get the column names
needed).
• Insert the line item values (description, quantity, and unitprice) in the InvoiceItems table
(open the SQL Enterprise Manager to get the column names needed).
• If any of the database operations fail, return evtCancel (=2) in the InvoiceTransfer
event. This will tell INVOICES to skip the current invoice, and try later when the job is
run the next time.
• Also, in case of failure, be sure not to put up any message boxes since Transfer might be
running as a service or on a server computer. Instead, log any errors to a text file.
• Activate your new plug-in in the eilocal.ini file.
• Run the General job in Interpret (importing images), Verify, and Transfer. Make sure your
data is being transferred correctly (check inside SQL Enterprise Manager).
• Now, force a database error by adding an error in any of the SQL queries in your code. Run
some invoices to make sure they are skipped and that a log file is created.
Keep in mind
• evtCancel is not defined in the INVOICES 5-2 COM API type library. If you wish to use
it (for the few events that support it), you need to define this constant yourself:
Private Const evtCancel As Long = 2
• An alterative to using the invoice data for external transfer is the Transaction object (only
available in the TransferApp application object). This object will give you the data
corresponding to the current transaction description.
The benefit of this is that the transaction description can be altered without changing your
code, giving the possibility to change the data being transferred.
The drawback is that the Transaction object is more complex and harder to work with
than the Invoice object.
19
"
20
EXERCISE 6C-1: VALIDATION USING MORE COMPLEX CUSTOMIZATION
Exercise 6C-1:
Automatic routing of invoices to queues
• Sending invoices to specific queues based on whether or not an invoice contains a purchase
order number
• Creating a job that only verifies invoices from this queue
Learning objectives
• Understanding how queues can be used to control the flow of invoices
Resources
• Information on using queues to control the flow of invoices
Procedure
• In the Manager module, create a new job description called PO that only verifies invoices
from queue number 1 (which we will use as our purchase order queue).
• Then, create another new job description called GE that only verifies invoices from queue
number 2 (which we will use as our general expense queue).
• Name the class module Connect and the project Exercise6C.
• Write a Connect and Disconnect function in the class module. Subscribe to an event that is
only fired one time for each invoice when the interpretation is finished.
• Write code for the following:
• If the PO_Number field contains a value, move the invoice to queue number 1; if this
field does not contain a value, move the invoice to queue number 2.
• Deactivate the Exercise6A plug-in (since we now allow the PO_Number field to be empty)
• Run the General job in Interpret (importing images), and then run the PO and GE jobs in
Verify to make sure the invoices ended up in the correct queues.
21
"
22
EXERCISE 6C-2: VALIDATION USING MORE COMPLEX CUSTOMIZATION
Keep in mind
• Only invoices and batches can be put in queues.
• Invoices and batches can be placed into more than one queue, but this often leads to
confusion, and is therefore not recommended.
• There is no automatic way of placing invoices and batches in queues—this has to be
accomplish by means of customization.
Exercise 6C-2:
Routing invoices to queues with a user-defined menu
• Adding a user-defined menu that makes it possible for the operator to send an invoice to one
of the following queues: PO, GE, and a new one, Admin, for problematic invoices
Learning objectives
• Experiencing further how queues can be used to control the flow of invoices
• Understanding how to create user-defined menus
Resources
• Information on using queues to control the flow of invoices
• Information on user-defined menus
• ProfileAPI invoice profile and job descriptions General & Interpret6D
• VB project Exercise6C
Procedure
• Create a new job description that only verifies invoices from queue number 3 (which we will
use as our administrator queue). Name the job Admin.
• Open the Exercise6C VB project again.
• In the Connect class, add code that will create a user-defined menu in the Verify module.
• Add an event handler function for your menu item and write code that results in a dialog that
displays which queue the invoice is currently in and which also provides the possibility of
moving the invoice to a selected queue.
23
"
24
EXERCISE 6D: SUPPLEMENTATION USING MORE COMPLEX CUSTOMIZATION
• Run the General job in Interpret (importing images). Run the PO and GE jobs to see which
invoices ended up in which queues. Try rerouting invoices to other queues by using the user-
defined menu. Send some invoices to the Admin queue, and then run the Admin job to see
that the invoices were moved correctly.
Keep in mind
• User-defined menus are useful when you want to give the operator the possibility to do
something that not is possible with INVOICES’ standard functionality.
• User-defined menus are not available in Scan.
• If you have trouble with your user-defined menus (for example, not showing up or
showing up more than one time), try deleting the eiveri.ini file located in the
Windows root folder.
Exercise 6D:
Supplementation using more complex
customization
Adding scan information with a user-defined dialog
• Adding a user-defined dialog in Scan to set certain initial values (company code and credit)
for all invoices being scanned in that job
• Setting a credit flag on invoices that were selected for credit during scanning
Learning objectives
• Learning how to control the job flow
• Understanding how user-defined variables work
• Learning how to communicate between Scan and Interpret
• Using late bound properties
Resources
• Help file information on job events
• Presentation and Help file information on user-defined variables
Procedure
25
"
26
EXERCISE 6D: SUPPLEMENTATION USING MORE COMPLEX CUSTOMIZATION
• Name the class module Connect and the project Exercise6D.

• Write a Connect and Disconnect function in the class module. Subscribe to the JobStarted
and InvoiceScanned events in Scan and the InvoiceInterpreted event in Interpret.
• Add a dialog with the possibility of selecting a company code and a check box that indicates
that the scanned documents are credit documents.
• Display the dialog in the event handler for the JobStarted event. If the user clicks Cancel in
the dialog, the job should stop (by returning a specific value).
• When invoices are scanned (in the event handler for the InvoiceScanned event), add two
user-defined variables: one indicating the company code chosen, and the other indicating if
the Credit documents setting on the user-defined dialog was chosen or not.
• When invoices are interpreted, check for the existence of the credit flag (from the saved user-
defined variable). If this flag is set, mark the current invoice as being a credit document by
setting the property Type to “1”:
mobjEHApplication.CurrentInvoice.Type = 1 '// this will set
the invoice to credit
• Activate your new plug-in in the eilocal.ini file. If you haven’t already done so, set up
scan emulate at this time, as well (including even specifying the image file path on the
ScanSource= line, if you want to prevent the Browse from Folder dialog from appearing
each time you run Scan).
• Run the General job in Scan. Make sure your dialog is shown. Click Cancel to see if the job
stops. Next, start the job again, making sure again that the dialog is shown. Select a company
code, as well as Credit documents. Go ahead and emulate scanning by continuing with the
Scan job.
• In the Manager module (and with the invoice profile ProfileAPI selected), click the processed
invoices icon on the Invoice profile toolbar and make sure your invoices received the
intended user-defined variables.
• Run the Interpret6D job in Interpret (interpreting the “scanned” images). Then, run the
General job in Verify to make sure your invoices are marked as credit documents.
Keep in mind
• The Type property for the Invoice object is a late addition to the type library. Because of
the way COM works (with backwards compatibility), all new additions have been added in
the IDispatch (late bound) interface. This means you won't see the property when coding
(the IntelliSense feature only works for type libraries), but it's still there! Another well-
used property in the IDispatch interface is the DisplayString on the Field object, which
will give you the formatted value of a field. This is useful when working with dates and
amounts.
• Fields (and anything else related to fields, such as the credit flag) are not available in Scan,
since they are created during interpretation. Therefore, communication between events
(and even modules) is often needed when you add information during scanning. Using
user-defined variables is the best way of doing this.
27
"
28

EN INVOICES CustomizationTraining ExerciseBook MI50-C STUDENT

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

EN INVOICES CustomizationTraining ExerciseBook MI50-C STUDENT

Uploaded by

Copyright:

Available Formats

Customization

• Exercise 4B: Having INVOICES correct

• Exercise 4C: Adding static output data to

• Exercise 5A: Sum total validation using

• Exercise 5B: Applying a predefined

Training information in an external (page 15)

• Exercise 6B: Using ADO to output data to

• Exercise 6C-1: Automatic routing of

• Exercise 6C-2: Routing invoices to queues

• Exercise 6D: Adding scan information with

How this Exercise Book is organized

• Activate your new plug-in in the eilocal.ini file

• Add the ADODatabase class to your project.

• Name the class module Connect and the project Exercise6D.

You might also like