saperion eventscript - kofax · onsecurity event ... eventscript allows internal programming of...

SAPERION EventScript

Copyright © 2016 Lexmark. All rights reserved.

Lexmark is a trademark of Lexmark International, Inc., registered in the U.S. and/or other countries. All other trademarksare the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in anyform without the prior written permission of Lexmark.

Table of Contents

1 Introduction ......................................................................................................... 1

2 Installation of the "EventScript" Option ............................................................ 2

2.1 Licensing .............................................................................................................. 2

2.2 Activating with the Feature Key .......................................................................... 2

2.3 Choosing the "Macro" Folder ............................................................................. 2

3 Programming Guideline ...................................................................................... 2

3.1 Declarations ......................................................................................................... 2

3.1.1 Area of Validity ................................................................................................ 2

3.1.2 Naming ............................................................................................................ 3

3.1.3 Variables ........................................................................................................... 3

3.1.4 Special Types ................................................................................................... 3

3.1.5 Constants ......................................................................................................... 4

3.1.6 Functions ......................................................................................................... 4

3.1.7 Parameters ....................................................................................................... 4

3.2 Indentation .......................................................................................................... 4

3.2.1 Declarations ..................................................................................................... 5

3.2.2 Blocks ............................................................................................................... 5

3.2.3 Continuation of Lines ..................................................................................... 5

3.3 Commentaries ..................................................................................................... 5

3.4 Tips ....................................................................................................................... 6

4 Creating Macros .................................................................................................. 6

4.1 SAPERION Macro Editor .................................................................................... 6

4.2 Creating Macros .................................................................................................. 7

4.3 Creating Dialogs .................................................................................................. 9

4.4 Testing Macros and Finding Errors .................................................................. 9

4.4.1 Aktivating Debug Mode .................................................................................. 10

4.4.2 Using the Debug Window .............................................................................. 11

4.5 Specifying A User ................................................................................................ 11

4.6 Tips for Programming and Debugging .............................................................. 11

4.6.1 Checklist Debugging ....................................................................................... 11

4.6.2 Accessing Functions in Further BAS Files ..................................................... 11

4.6.3 Handling Errors with the "On Error" Instruction .......................................... 12

Proposal for Solution .................................................................................... 14

5 Assigning Macros to Events ............................................................................... 14

5.1 Assigning the Macro to an Event ....................................................................... 14

5.2 General System Events ....................................................................................... 15

5.2.1 Syntax of Macros ............................................................................................. 15

5.2.2 Archiving Event ................................................................................................ 16

5.2.3 Revision Event ................................................................................................. 16

5.2.4 Delete Event ..................................................................................................... 17

5.2.5 Edit Event ......................................................................................................... 17

5.2.6 Print Event ....................................................................................................... 17

5.2.7 Error Event ....................................................................................................... 17

5.2.8 User Administration Event ............................................................................. 18

5.2.9 Record Transfer Event ..................................................................................... 19

5.2.10 System Event ................................................................................................... 19

5.2.11 Document in Tray Event ................................................................................. 20

5.2.12 Program Start Event ........................................................................................ 20

5.2.13 Program End Event ......................................................................................... 20

5.2.14 Periodic Event .................................................................................................. 21

5.2.15 Main Menu Loaded ......................................................................................... 21

5.3 Events in Query and Index forms ...................................................................... 22

5.3.1 Form Events (Dialog Events) .......................................................................... 22

OnInitDialog Event ........................................................................................ 23

OnSaveDialog Event ...................................................................................... 23

OnSetFocus Event ......................................................................................... 23

OnKillFocus Event ......................................................................................... 23

OnItemAccept ................................................................................................ 23

OnItemDrop .................................................................................................. 23

5.3.2 Events in Form Fields (Control Events) ......................................................... 23

OnEditChanged Event ................................................................................... 25

OnSetFocus Event ......................................................................................... 25

OnKillFocus Event ......................................................................................... 25

OnEditSetText Event ...................................................................................... 25

OnSelChange Event ....................................................................................... 25

5.3.3 Events in Result Lists ...................................................................................... 25

OnSelChange Event ....................................................................................... 27

OnItemDrag Event ........................................................................................ 27

OnItemAccept Event ..................................................................................... 27

OnItemDrop Event ........................................................................................ 27

OnTooltip Event ............................................................................................. 27

OnDragCancel Event ..................................................................................... 27

OnEdit Event ................................................................................................. 27

OnView Event ................................................................................................ 27

OnPrint event ................................................................................................ 27

OnDelete Event ............................................................................................. 27

OnIndex Event ............................................................................................... 27

OnSave Event ................................................................................................ 27

OnNew Event ................................................................................................ 27

OnSecurity Event ........................................................................................... 27

5.3.4 Events in Outliner ........................................................................................... 27

OnSelChange ................................................................................................. 29

OnExpand ...................................................................................................... 29

OnItemDrag ................................................................................................... 29

OnItemAccept ................................................................................................ 29

OnItemDrop .................................................................................................. 29

OnItemNew ................................................................................................... 29

OnItemEdit .................................................................................................... 29

OnItemDelete ................................................................................................ 29

OnDragCancel ............................................................................................... 29

5.3.5 Events Triggered by Buttons in Forms ........................................................... 29

Defining a Button that Executes a Macro .................................................... 30

Assigning the Macro via the "OnButtonClick" Event .................................. 31

"OnButtonClick" Event .................................................................................. 32

5.3.6 Events Executed via ActiveX Objects in Forms .............................................. 32

6 Samples ................................................................................................................ 34

6.1 Simple SAPERION Functions ............................................................................. 34

6.1.1 Programming Ribbons .................................................................................... 34

6.2 More Complex SAPERION Functions ................................................................ 34

6.2.1 Deletion from the Lookup Table during Archiving ........................................ 34

Scenario ......................................................................................................... 34

Sample Code ................................................................................................. 34

6.2.2 Macros in Forms: Selecting an Application ................................................... 35

Scenario ......................................................................................................... 35

Sample Code ................................................................................................. 35

6.2.3 Using COM Objects of other Applications .................................................... 36

1

SAPERION EventScript

1 Introduction

SAPERION can be adapted quickly and flexible to project-specific defaults using its extensive

programming options. With EventScript, COM interface and UBI different possibilities are available to

you to do this.

EventScript allows internal programming of SAPERION in the form of BASIC macros. A macro editor is

available that offers color highlighting of syntax to facilitate programming, and there are comprehensive

testing options to look for errors. If needed, an external editor can also be used to create macros.

The BASIC commands of the macro editor are as far as possible compatible with the standard range

of VBA (Visual BASIC for Applications, a registered trademark of Microsoft Corporation). Furthermore,

COM interface objects (SAPERION API) can be used in macros. The essential functions of SAPERION are

made available through these objects. Other objects can be accessed using the Windows COM interface.

During the use of SAPERION, moreover, the "EventScript" option allows certain reactions to occur

(through the execution of a macro) in response to certain events. The possibilities that this feature offers

are almost limitless. Among other possibilities, it allows the creation of specific workflow mechanisms,

complex document transfers, and convenient interfaces to other applications.

Using SAPERION, events occur in various ways. Clicking a button in a query form is an event just as the

archiving of a document through the Core Server is an event. Furthermore, periodic events can be defined

that occur repeatedly at definable intervals. To each event, a macro can be assigned that is executed

when the event occurs. Many of these events even activate the macro twice (once before and once after

the actual execution). If desired, in the "before" activation, the further execution of processes linked to

the event can be interrupted in the macros.

It can also be used for presetting mask fields with the aid of macros and BASIC functions.

! A fundamental knowledge of BASIC is required in order to use the option "EventScript".

2 Installation of the "EventScript" Option

2

2 Installation of the "EventScript" Option

2.1 Licensing

The "EventScript" option is not user limited and is licensed system-wide only once. All users of the

SAPERION version can work with it.

2.2 Activating with the Feature Key

The "EventScript" option is installed during system installation by default.

2.3 Choosing the "Macro" Folder

Macros are saved in the SAPERION directory "MACROS" by default. However, any desired macro folder

can be chosen by making an additional entry in the PROGRAM.INI file.

[Setup]

...

PathVBAModules=<save location> Path to the macro directory. If this

is a subfolder of the SAPERION directory, the name of the subfolder is sufficient.

If this entry in not present, the SAPERION directory is used.

...

! It is essential that SAPERION be closed on all work stations before the PROGRAM.INI file is

edited.

3 Programming Guideline

The following guidelines contain set data, which are meant to improve cooperation, maintainability and

reusability when programming projects. It consists of recommendations that will have a positive effect

when working with macros.

3.1 Declarations

3.1.1 Area of Validity

Global variables should only be used in exceptional cases. It is better to limit the area of validity of

declarations as much as possible, due to the fact that unwanted side effects can then be avoided.

3.1 Declarations

3

When using function parameters, keep in mind that they are defined by "Val", when they are accessed

for reading. In this way, you can avoid unintentional assigning to a parameter, which would lead to

repercussions outside of the function.

3.1.2 Naming

To ensure the possibility of international use, the use of English names is preferred. The names should

be selected so that the purpose is expressed as clearly as possible. New parts within compound terms

should begin with a capital letter. Underscores should only be used with constants. It is not permitted

to use special characters (e.g. umlauts).

Abbreviations are only allowed if an outside third party can intuitively understand them. If necessary, the

abbreviations being used should be explained in the header.

Names that are also used by SAPERION for example mask, document, cursor, must be provided with

a prefix.

3.1.3 Variables

Variables always begin with a small letter. Frequently used terminology can be abbreviated if it is generally

understandable. In case of doubt, the written out version is to be provided with the declaration as a

commentary.

If loop variables are to be used, where no sensible name can be found, the variable should be marked

correspondingly with an "i" or "j".

If the naming was done properly, there is usually no need for the win data type prefix. If there is a need

to use prefixes, the following applies:

+ The prefix consists of one letter.

+ The prefix is written in small letters.

+ The next letter is a capital letter.

The following letter are used:

+ b: Boolean

+ s: String

+ l: Long

+ o: Object

3.1.4 Special Types

Floating point variables should only be used if they cannot be avoided. Otherwise, the danger exists of

creating a rounding error.

3 Programming Guideline

4

To prevent an overflow situation, the data types should be sufficiently dimensioned.

3.1.5 Constants

Constants should only be named carefully and expressively. Otherwise, the use of constants can lead

to poor readability.

Constants should always be named independently of the value, so that a change to the value can be

done without problems.

Constants are always marked with capital letters. For better readability, underscores "_" can be used.

The same applies for jump labels.

Example

Const DOCTYPE_SCANPAGE=1

3.1.6 Functions

If it is possible, the purpose of the function should be seen in the name. They should start with a capital

letter so that the functions can be easily differentiated from the variables.

Example

newDir=MakeDir(newDirName)

Public Function MakeDir(byVal DirName) as long

3.1.7 Parameters

If it is possible, parameters should be adequately named to the variables when called. Otherwise, the

same rules for naming apply as for variables.

Example

CheckAdmin (SaperionApp)

Public Function CheckAdmin (byVal SaperionApp as Object) as Boolean

...

End Function

3.2 Indentation

Using suitable indentation can make the program text easier to understand and thereby provide a better

overview of the flow of the program. Every indentation should be done with two spaces, since tabs can

lead to unreadable results in external editors and when printing.

3.3 Commentaries

5

In the MS-IDE of VB, the indentation should be set to two spaces. In this way, the source text is easier

to read when lines become longer.

3.2.1 Declarations

As a rule, declarations begin left justified. Program text is always indented.

Example

Public Function GetFileExtension (ByVal FileName as String) as String

Dim FilePart as String

On Error Goto ERRORHANDLER

3.2.2 Blocks

The statement part of the If-queries is always written in a new line and indented.

Example

If condition then

...statements

else

...statements

End If

The same applies with statement parts of loops and with select statements.

3.2.3 Continuation of Lines

If the statement continues over several lines, it is marked by indentation to show that they are not

separate lines.

Example

MsgBox "This is the first part." &_

"Now we have the third part," &_

"that is indented."

3.3 Commentaries

Commentaries are an important aid for understanding the program at a later phase. To guarantee that

the program can be used internationally, all commentaries should be in English.

4 Creating Macros

6

Every program should have a commentary header, containing creation, modification and function

commentaries. Code positions that are understandable, should be commented in a complete, sensible

and expressive manner.

Every time a program is changed, be sure that the corresponding commentaries are updated.

3.4 Tips

To make it possible that a document can be completely revisioned when Document.SaveChanges is

used, the command Document.load must be executed first.

4 Creating Macros

4.1 SAPERION Macro Editor

In general, you will create macros with the macro editor that is integrated into SAPERION (Cypress

Enable by Cypress Software). This is a BASIC editor that is as far as possible compatible with VBA and

has numerous useful functions (syntax highlighting, tracing/debugging, etc.).

In principle, however, you can create the macros with any other suitable editor (such as VBA Editor by

Microsoft Office). In order to use the macros in SAPERION, you must adapt these macros to the ENABLE

syntax and save the macros in the SAPERION macro folder.

The exact language description of the BASIC dialect is located in the WBA.HLP help file in the SAPERION

directory.

The BASIC commands of the Macro Editor are compatible with the standard range of VBA (Visual BASIC

for Applications, a registered trademark of the Microsoft Corporation). Furthermore, COM interface

objects can be used in the macros. The essential SAPERION functions are available through these

objects.

You can access English language help for the standard BASIC commands by moving the mouse cursor

to the appropriate position in the code and pressing <F1>. The WBA.HLP help file is located in the

SAPERION directory and also contains general descriptions of the BASIC dialect in the Macro Editor.

For objects from the COM interface, the context-sensitive help feature is unfortunately not available via

the <F1> key. Information concerning the individual objects must therefore be sought out in the help

files of the application.

4.2 Creating Macros

7

Fig. 4–1: SAPERION Macro Editor

The code shown in the Macro Editor is automatically highlighted with a color to get a better overview.

The coloration follows these rules:

+ Light red: introduction or end of a procedure

+ Dark red: objects

+ Light blue: BASIC instructions

+ Dark blue: BASIC instructions (syntax can also be displayed in a quick info)

+ Green: objects in dialogs

The line as well as the column number are displayed in the lower left margin of the Editor. This feature

makes searching for a program line considerably easier, for example in the case of an error message.

4.2 Creating Macros

1. Open the Macro Editor via DESIGN ribbon > MODEL group > SCRIPTS command.

The "EventScript" dialog box opens, in which all of the BAS files contained in the

SAPERION macro folder are listed as modules. In addition, in the second column the

number of code lines within the module is displayed.

4 Creating Macros

8

2. Clicking the [+] symbol causes the procedures (subs and functions) contained in the BAS

file to be displayed.

! A module can contain a maximum of 99 Subs. Otherwise the module

cannot be saved. It is advisable for great modules to switch off syntax

highlighting about the entry PrettyLayout = FALSE in section [Macro]

for performance reasons.

3. Select the required entry and click the [Run] button to run the macro.

4. You can create a new BAS file with the [New] command, or open the BAS file selected under

Modules with the [Edit] command. In both cases, the SAPERION Macro Editor opens. If a

procedure is selected in advance, the mouse pointer jumps directly to the corresponding

position in the BAS file.

5. You can create, edit, or test one or more BASIC macros in the Macro Editor.

6. Via VBA ribbon > SAVE command you can save the macros currently displayed in the

Macro Editor in a BAS file. If no file name has yet been assigned, a window opens

automatically for entering a file name. The data type is always macro. The file is always

saved in the SAPERION macro folder.

! Within a macro you can define a maximum of 100 procedures for a

module. Otherwise the macro cannot be saved.

7. Via VBA ribbon > SAVE AS you cannot only save the displayed macros as BAS files, but

also as SES files (macro code) in coded form.

i A macro saved in coded form can not be subsequently decoded or

edited. For this reason, we recommend that you save a copy of the

original file.

4.3 Creating Dialogs

9

A macro is not completely coded until the client on which it was created has been closed.

Before the client is closed, the file can be opened by any user on this client. Macros saved

as macro code appear grayed out in the dialog box and can no longer be edited. If the

macro exists as a BAS file as well as a SES file, only the BAS file is shown here.

4.3 Creating Dialogs

In addition to the Macro Editor, there are also the Dialog Editor for user-defined dialogs. Most of the

dialog box controls contained in Windows standard are supported by Enable BASIC. The syntax is very

similar to Microsoft Word BASIC syntax. The syntax for dialogs is not contained in Microsoft Visual

BASIC or Microsoft Visual BASIC for Applications.

When running SAPERION on Windows Vista or higher, you may get an error when launching the dialog

editor. To prevent this, start SAPERION using the Windows "Run as administrator" command.

i You will find help for the Dialog Editor and for creating dialogs in the ENADLG.HLP and WBA.HLP

English-language help files. Both files are located in the SAPERION directory.

4.4 Testing Macros and Finding Errors

To test macros and find errors, (tracing, debugging) the following functions are available:

+ Starting a macro <F5>

START ribbon > EXECUTE group > START command

+ Stopping a macro

START ribbon > EXECUTE group > STOP command

+ Executing Single step OF A MACRO <F8>

START ribbon > EXECUTE group > SINGLE STEP command

+ Handling single procedures <F10>

START ribbon > EXECUTE group > STEP OVER command

+ Defining and removing toggle breakpoint <F9>

START ribbon > EXECUTE group > TOGGLE BREAKPOINT command

+ Display values in variables

START ribbon > EXECUTE group > QUICK WATCH command

4 Creating Macros

10

Toggle Breakpoint

With the START ribbon > EXECUTE group > TOGGLE BREAKPOINT command, you can set a stop point

in any desired program line or remove an existing stop point.

i Starting in halt mode is possible only for procedures (subs or functions) without parameters. If

the procedure contains parameters, a "Runtime Error on line: -1 - Wrong number of arguments"

error message appears.

Quick Watch

With the START ribbon > EXECUTE group > QUICK WATCH command you can display the value of a

variable in a message window. You must first position the mouse pointer on the relevant location in the

program code.

4.4.1 Aktivating Debug Mode

Errors often occur in macros that are hard to locate. The program code may contain syntactically correct

code, but the macro still does not react as desired.

In order to find such errors, you must test the macro in as realistic an environment as possible. Your

chances of finding an error are best if you are able to follow exactly each individual program step. The

debug mode serves just this purpose. You can activate the debug mode for individual procedures by

activating the "Debug" check box in the "EventScript" window. This causes the procedure to be marked

with a stop symbol. When the window is closed with a click of the [OK] button, the changes made in the

window are saved; if the [Cancel] button is clicked, the previous settings remain unchanged.

Fig. 4–2: Debug mode

If this procedure is called while SAPERION is running, the Macro Editor loads automatically and the

procedure is started in the Editor as a single step. The procedure is now in halt mode. You are now able

to set any desired stop points or allow the procedure to run step by step in order to better recognize any

errors that may be present. In contrast to the manually started halt mode, however, no menu commands

or keyboard shortcuts are available. Commands must be carried out with the icons in the toolbar of the

Macro Editor.

4.5 Specifying A User

11

! Debug mode should not be used for the "OnSetFocus" or "OnKillFocus" events. When these

events occur, the focus shifts to the Macro Editor, and the normal function of these events is

corrupted.

4.4.2 Using the Debug Window

When a macro is started in single or procedure step, a debug window also appears. In the debug window,

you can issue corresponding texts line by line with the "Print" command. This allows you to issue a wide

range of intermediate results.

4.5 Specifying A User

A user can be specified for a single module or the entire COM-API. Afterwards, when the module or

the entire COM-API is opened, it is opened under the name of the specified user with that user's rights

and client type.

1. Open the Macro Editor via DESIGN ribbon > MODEL group > SCRIPTS command. The

"EventScript" dialog opens first.

2. Via the [COM-API...] button or alternatively when a module is marked via the [Modul...]

button, a login dialog opens where the user can specify password and role.

Besides the conventional client types, API clients can also be selected explicitly here.

4.6 Tips for Programming and Debugging

4.6.1 Checklist Debugging

+ Do you use a module user? See also the sections PROGRAM.INI [Macro. ]. If you do so, deactivate

resp. set this user again.

+ Does the macro contain the right type for the event (sub/function/parameter)?

+ Do you want to execute the macro with the client or with the Core Server (e.g. for tasks)? Bei If you

use macros with the server, please note the following:

- It is recommended to define a module user for the BAS module used by the task.

- Do not use the command "CreateObject" in the macros initiated by the task. Do create documents

in the macros with "Application.CreateDoc".

- The task skips user messages ("Msgbox" or "Application.MsgBox"). However, content of a

"Msgbox" is written to the event log. Do create resp. test program code for a task taking into account

these circumstances.

- COM user and module user cannot be used simultaneously.

4.6.2 Accessing Functions in Further BAS Files

The RunScript () function can be used in order to make use of functions from other modules (BAS files).

4 Creating Macros

12

RetValue = Application.RunScript ("MyModule!MyFunction", Param1, Param2)

In this case, the "MyFunction" function in the "MyModule.bas" module is activated with the parameters

"Param1" and "Param2", and the value "RetValue" is returned. You will find further information on this

subject in the description of the COM interface.

4.6.3 Handling Errors with the "On Error" Instruction

Under certain circumstances, errors can occur that are not connected with the actual program code.

These so-called runtime errors – which can occur for example, when a document cannot be archived

because the Core Server is not available – can lead to an interruption or in the worst case termination

of your macro.

To avoid these incidents, you should integrate a so-called error handler into all procedures in the macro

that could possibly cause such errors. Error handlers are accessible through the "OnError" instruction

and are typically programmed according to the following principle:

Sub MyProcedure()

On Error GoTo MyErrorHandler' In case of error, go to MyErrorHandler jump mark

...' Commands of the actual procedure…

Exit Sub' End subroutine without running MyErrorHandler

MyErrorHandler:' Jump mark: error handler begins at this point

...' Commands of the ErrorHandler

Resume' The actual procedure is resumed'

End Sub

If an error occurs, the procedure is resumed at the indicated jump mark and the instructions that

follow are executed. This involves an evaluation of the error that has occurred and the triggering of an

appropriate reaction.

An exit sub instruction must be entered immediately before the jump mark that identifies the error

handler routine. This causes the error handler routine to run only when there is a jump to the jump mark

– i.e. when an error occurs – rather than every time the procedure is executed.

i The jump mark must be in the same procedure as the "OnError" instruction.

When using "OnError", there may be a malfunction when the method is used together with the Val (

) function.

' Diese Function tut gar nichts (besitzt aber ein Error-Handling)

Sub DoNothing ()

On Error GoTo DoNothingERR

Exit Sub

DoNothingERR:

MsgBox "Fehler in Prozedur Do_Nothing"

End Sub

Example 1

4.6 Tips for Programming and Debugging

13

There is an error in the following macro if no document has been selected in the results list. The user

is notified by an appropriate message.

Sub GetSelectedDoc ()

Dim crs As Object

Dim doc As Object

On Error GoTo GetSelectedDocERR

Set crs = Mask.Cursor

Set doc = crs.Document

doc.load

doc.EditImage

Exit Sub

GetSelectedDocERR:

MsgBox "Please select a document in the results list first!"

End Sub

Example 2

In the following example, a message draws attention to any errors in the use of the error handler. After

the error has occurred, the program does not jump into its own error handler, but rather to that of the

"DoNothing" procedure, because the last error handler was defined during execution of the "DoNothing"

procedure.

Sub MyProcedure()

On Error GoTo ErrorHandlerMain

DoNothing

err.raise = 91 ' An error is occuring!!!

Exit Sub

ErrorHandlerMain:

MsgBox "Error in Error_Handle"

End Sub

Sub DoNothing () ' This function does nothing at all (but it contains an error handler)

On Error GoTo DoNothingERR

Exit Sub

DoNothingERR:

MsgBox "Error in the Do_Nothing procedure"

End Sub

Possible solutions:

Sub MyProcedure()


DoNothing

On Error GoTo ErrorHandlerMainSolution: repetition of the "On Error…" instruction

Solution: Repeat statement "On Error..."

err.raise = 91

Exit Sub

ErrorHandlerMain:

5 Assigning Macros to Events

14

MsgBox "Error in Error_Handle"

End Sub

4.6.3.1 Proposal for Solution

Sub MyProcedure()


DoNothing

On Error GoTo ErrorHandlerMainLösung: Wiederholen der Anweisung "On

Error..."

err.raise = 91

Exit Sub

ErrorHandlerMain:

MsgBox "Fehler in Error_Handle"

End Sub


Macros must be assigned to an event in order for them to be executed during SAPERION runtime. Events

occur in very diverse ways during the use of SAPERION. Clicking a button in a query form for example,

is an event, just as the archiving of a document through the Core Server is an event.

Events can often be created in various ways. The event "display a document in the results list" for

example, is initiated by clicking the [Display] or [Edit] button, by using the appropriate context menu, or

by dragging and dropping a document to the display icon. However, you only need to assign the macro

once to the event.

! Events are always triggered at the client, not at the server.

SAPERION supports the assignment of macros for the following events:

+ General system events (e.g. archiving or displaying documents, periodic events, etc.)

+ Events that arise through the use of the query and index forms (open, close, retain focus, lose focus,

field entry, clicking on buttons, etc.)

+ Events that are triggered by clicking on symbols in the toolbar.

5.1 Assigning the Macro to an Event

1. Click the DESIGN ribbon > MODEL group > EVENTS command. The "Events" opens.

5.2 General System Events

15

2. With the [New] button or the [Edit] button the "Event Parameters" dialog openswhere you

can define or edit the according parameters.

3. Make the following settings:

+ Select from the dropdown box the required type.

+ Enter a description of the event.

+ In the dialog area "Periodic Event" you can choose for the "Periodic" type furhter

details, e.g. how often and at which time an event should be triggered.

4. With the [Macros] button you can select the according macro in the "EventScript" dialog

box.

5. With the [Delete] button you can remove an entry from the list of existing events.


SAPERION offers the option of automatically execute a certain macro when important system events

occur. This allows you to intervene selectively in SAPERION processes with appropriate macro functions

and for example, run additional security and plausibility tests during events such as archiving, revision,

and deletion.

In the following sections system events are described in detail.

5.2.1 Syntax of Macros

With the exception of periodic events, all macros must be defined as functions with two parameters

("pre" and "note" by default). In most system events, the macro is called twice. The "pre" parameter is


16

before event 1 and after event 0. The "note" parameter contains additional information that depends on

the context. The macro typically has the following structure:

Function MyArchivingEvent ( pre As Long, note As String ) As Boolean

If pre = 1 Then ' befor the event…

... ' ... instructions

If ... Then MyArchivingEvent = True ' set return value=True to continue event

Else ' after the event …


End If

End Function

You must explicitly give the function a return value of TRUE so that the actions normally associated with

the event are executed. By default the return value is FALSE and the event is interrupted. The return value

is only evaluated if pre = 1 (before the event).

The periodic event is handled differently in SAPERION. The macro for the periodic event has no

parameters and is defined as a sub rather than a function:

Sub MyPeriodicEvent()


End Sub

! If you do not have exact knowledge of the procedures in the system, you should never replicate the

actions in the macros that are normally associated with the event. In particular, you should never

use the "Store" or "SaveChanges" methods. However, a change of index values via "SetProperty"

or "ACL" is not critical.

5.2.2 Archiving Event

This event occurs when a document is archived.

Archiving event

pre = 1, note = "" After clicking [OK] in the index form

pre = 0, note = "" When archiving has been done without errors

pre = 0, note = "Document could not be created." When further execution of the event has been canceled (return value of the functi-

on is FALSE)

5.2.3 Revision Event

This event occurs when a revision is created.

Revision event

pre = 1, note = "" After confirming with [OK] in the "Create New Revision" dialog box

pre = 0, note = " "Set ACL: A" When ACL has been created or changed


17

pre = 0, note = " "Removed ACL" When ACL has been removed

pre = 0, note = "" For other revisions (indexing, annotations, etc.)

If the revision event is ended in the macro with a return value = FALSE, an "Error" event is created with

pre = 0 and note = "Revision could not be created"

5.2.4 Delete Event

This event appears before the user has confirmed the deletion of documents or entries from the user

administration (user, group, profile, ACL)

Delete event

pre = 1, note = "" With the inquiry, before the user confirms the delete

pre = 0, note = "" After the deletion

5.2.5 Edit Event

This event occurs when a document from a results list is opened (with the [Edit] or [Display] command).

It also occurs when the command is executed with <CTRL> key pressed and only the document structure

is displayed. It does not occur when documents are opened from the content window of the trays (In,

Document, or To Do).

Edit event

pre = 1, note = "" After executing the [Edit] or [Display] command

pre = 0, note = "" After the document is displayed

5.2.6 Print Event

This event occurs when documents are printed. If the print command is executed from the SAPERION

Viewer viathe "Print" command, no event is created.

Print event

pre = 1, note = "" After clicking the [OK] button in the "Print" dialog box

pre = 0, note = "" After conclusion of the print procedure

5.2.7 Error Event

This event occurs in error situations. Afterwards, the corresponding SAPERION error message is

displayed in a message window.


18

+ pre = 0, note = <error message>

5.2.8 User Administration Event

This event occurs during various actions connected to the user administration. These include logging

on and logging off; and creating, changing, or deleting users, groups, profiles and access lists and their

connections to one another. For deletions, a "Delete" event is also created.

User administration event

pre = 1, note = "LOGOFF" This event occurs after the command to end SAPERION but before the SAPERI-

ON confirmation message "Do you really want to end SAPERION"

pre = 0, note = "LOGON" This event occurs after the user has logged on in the logon dialog.

+ pre =0, note = "User <UserFullName> : New name: <UserName>"

+ pre =0, note = "User <UserFullName> : New description: <UserDescription>"

+ pre =0, note = "User <UserFullName> : New sync OS: <Boolean>"

+ pre =0, note = "User <UserFullName> : New Password"

+ pre =0, note = "User <UserFullName> : Added: Group <GroupFullName>

+ pre =0, note = "User <UserFullName> : Removed: Group <GroupFullName>

+ pre =0, note = "User <UserFullName> : Copied profile from: <UserFullName>"

+ pre =0, note = "User <UserFullName> : Deleted"

+ pre =0, note = "User <UserFullName> : Changed description: <old> -> <new>"

+ pre =0, note = "User <UserFullName> : Changed Password"

+ etc.

+ pre =0, note = "Group <GroupFullName> : New name: <GroupName>"

+ pre =0, note = "Group <GroupFullName> : New description: <GroupDescription>"

+ pre =0, note = "Group <GroupFullName> : New sync OS: <Boolean>"

+ pre =0, note = "Group <GroupFullName> : New role: Role <RoleFullName>"

+ pre =0, note = "Group <GroupFullName> : Added: Group <GroupFullName>

+ pre =0, note = "Group <GroupFullName> : Removed: Group <GroupFullName>

+ pre =0, note = "Group <GroupFullName> : Deleted"

+ pre =0, note = "Group <GroupFullName> : Changed description: <old> -> <new>"

+ pre =0, note = "Group <GroupFullName> : Changed role: <old> -> <new>"

+ etc.

+ pre =0 note = "Role <RoleName> : New name"

+ pre =0 note = "Role <RoleName> : New description: "RoleDescription>"

+ pre =0 note = "Role <RoleName> : New sync OS: <Boolean>"

+ pre =0 note = "Role <RoleName> : New access formula: <AccessFormula>"


19

+ pre =0 note = "Role <RoleName> : New work dir: <WorkDir>

+ pre =0 note = "Role <RoleName> : New excl Baskets: <Boolean>"

+ pre =0 note = "Role <RoleName> : New local config: <Boolean>"

+ pre =0 note = "Role <RoleName> : New command group mask: 111011001"

+ pre =0 note = "Role <RoleName> : New commands: <Commands>"

+ pre =0 note = "Role <RoleName> : Changed description: <old> -> <new>"

+ pre =0 note = "Role <RoleName> : Changed excl baskets: <old> -> <new>"

+ pre =0 note = "Role <RoleName> : Changed commands: <old> > <new>

+ pre =0 note = "Role <RoleName> : Deleted"

+ etc.

+ pre =0 note = "ACL <ACLName> : New name"

+ pre =0 note = "ACL <ACLName> : New description: <ACLDescription>"

+ pre =0 note = "ACL <ACLName> : New sync OS: <Boolean>"

+ pre =0 note = "ACL <ACLName> : New member: Group <GroupFullName>(RWDPV)"

+ pre =0 note = "ACL <ACLName> : Added member: User <UserFullName>(RDPV)"

+ pre =0 note = "ACL <ACLName> : Removed member: User <UserFullName>(RDPV)"

+ pre =0 note = "ACL <ACLName> : Deleted"

+ pre =0 note = "ACL <ACLName> : Changed description: <old> -> <new>"

+ etc.

5.2.9 Record Transfer Event

This event occurs during COLD transfer.

+ pre = 1, note = <file name>

+ pre = 0, note = <time>

5.2.10 System Event

This event occurs during certain Server actions (Core Server, Document Server).

System event

pre = 0, note = "Server started successfully." After the server starts successfully

pre = 0, note = "Server stopped." After the server was stopped in the MMC


20

pre = 0, note = "IMPORT: WInfo.CSF, LINES: 3, OK: 2, ER-

ROR: 1, TIME: 00:00:00"

After a CSF impor

5.2.11 Document in Tray Event

This event is called after a document has been put in one of the trays. The parameter "pre" is always

0. The parameter "note" contains a character chain composed of a number for the tray type (0=In Tray,

1=Documents Tray, 2=To Do Tray, 4=structure window) and the name of the SAPERION user.

Document in tray event

pre = 0, note = "0 <Username>" After a document has been put in a user's "In" tray.

pre = 0, note = "1 <Username>" After a document has been put in a user's "Documents" tray.

pre = 0, note = "2 <Username>" After a document has been put in a user's "To Do" tray

pre = 0, note = "4 <Username>" After a document has been put in the structure window; also when a document is

moved within the structure window.

5.2.12 Program Start Event

This event occurs when SAPERION is started.

Program start event

pre = 1, note = "" Before the logon dialog appears. If the return value of the macro is FALSE, the

start of SAPERION is cancelled.

pre = 0, note = "" After the interface appears, and immediately before SAPERION can be used.

5.2.13 Program End Event

This event occurs when SAPERION is ended.

Program end event

pre = 1, note = "" After execution of the command to end SAPERION (e.g. with [Documents][End])

but before the SAPERION confirmation message "Do you really want to end SA-

PERION?"


21

pre = 0, note = "" After the SAPERION confirmation message "Do you really want to end SAPERI-

ON?"

5.2.14 Periodic Event

A periodic event executes an appropriate macro at definable intervals (such as every minute) and at

definable times (e.g. between 8:00 a.m. and 6:00 p.m.)

5.2.15 Main Menu Loaded

This event occurs if the main menu was loaded. Using this event you can add your own menus to the

main menu. The own menu will be linked in a suitable function and get the respective commands.

The kind of menu is defined by the note parameter:

+ note="Main": main menu

+ note="Viewer": viewer menu

+ note="ResultListContext": context menu result list

+ note="ViewerContext": context menu viewer

+ note="StructureWindowContext": context menu structure window

+ note="TrayWindowContext": context menu tray

In addition the menu is committed to the IMenu object and can be edited.

Example

Function CommandHandler( cmdId As Long, cmdString As String ) As Boolean

MsgBox "Command called: " + cmdString

CommandHandler = False

End Function

Function menuLoad( pre As Long, note As String ) As Boolean

Dim customMenu As Object

If note = "ResultListContext" Then

MsgBox "installed own handler for menu " & note

Menu.handler = "menutest!CommandHandler"

Menu.InsertItem "", 0, 2048

Set customMenu = Application.CreateMenu( "MenuTest", "CommandHandler" )

customMenu.InsertItem "Test", 101

Menu.InsertMenu "New!", customMenu

End If

menuLoad = True


22

End Function

5.3 Events in Query and Index forms

SAPERION offers the option of automatically executing a certain macro when certain events occur during

the use of index and query forms. This allows you to selectively perform checks on how forms are used,

and protect users from user errors. Furthermore, plausibility checks can be carried out for new entries.

Macros are assigned at different locations within the SAPERION Form Editor.

5.3.1 Form Events (Dialog Events)

The events that are directly associated with the form are displayed in the "Define Events" dialog box via

START ribbon > MODEL group > EVENTS command.

1. Select the required line and then click the [Macro...] button. The "EventScript" dialog

opens.

2. Now choose the macro.

Typically, assigned macros are structured as follows (name of the function and of the

parameters are freely selectable):

Function OnSaveDialogEvent (controlld As Long) As Boolean

' ... instructions

...

If ... Then OnSaveDialogEvent = True' Set eventually ReturnValues=True in order to continue

End Function

3. With the [Delete] button you can remove an assignment of a macro.


23

5.3.1.1 OnInitDialog Event

This event occurs when a form is opened (with ControlID=0). The return value of the macro is ignored,

i.e. the macro cannot prevent the opening of the form. It serves only to initialize.

5.3.1.2 OnSaveDialog Event

This event occurs when the [OK] button is clicked in the form (with ControlID=1). In query forms, it also

occurs after a click on the [Result] button (with ControlID=18). The return value of the form must be

TRUE in order for SAPERION to resume the procedure that the macro has interrupted.

5.3.1.3 OnSetFocus Event

This event occurs when the form receives the focus. Please note that the focus must not be changed

in the corresponding macro; otherwise, an endless loop can develop. The return value of the macro is

ignored.

5.3.1.4 OnKillFocus Event

This event occurs when the form loses the focus. Please note that the focus must not be changed in the

corresponding macro; otherwise, an endless loop can develop. The return value of the macro is ignored.

5.3.1.5 OnItemAccept

The event occurs when a document was dragged to a form. If FALSE is given as return value the cursor

will be changed. With the help of "OnItemDrop" archiving of documents by dropping the document to

a form can be realized.

5.3.1.6 OnItemDrop

This event occurs if a document was dropped on a form.

5.3.2 Events in Form Fields (Control Events)

When forms are used, events occur in the individual form fields to which macros can be assigned.

1. Open the SAPERION Forms designer via DESIGN ribbon > APPLICATION group >

CREATE INDEX FORM...

2. Adding the form element "Field" the "Form Field" opens where you can set the respective

parameters.

3. In the "Procedure" tab, click the [Events...] button.


24

4. The "Define Events" dialog opens. here, all available events are listed.

5. Mark the required entry and then click the [Macro...] button. The "EventScript" dialog

opens.

6. Select in the "EventScript" dialog the according macro and click[Select].

Typically, assigned macros are structured as follows (name of the function and parameters

are freely selectable):

Function OnSetFocusEvent (controlld As Long) As Boolean

' Instructions

...

' Set eventually ReturnValue=True in order to continue

If ... Then OnSaveDialogEvent = True

End Function

As parameter a unique ID of the field of the form is transferred. You can read out this ID

by means of the function "FieldID" of the object IMask (COM interface).



25

8. Finally, click [OK] in the "Form Field" dialog in order to save your changes.

Existing form events will be listed in the following.

5.3.2.1 OnEditChanged Event

This event occurs whenever a change is made in a field (entry of a character, insertion of text from the

clipboard, replacement of selected text, deletion of individual characters or of selected text). The return

value of the macro is ignored.

5.3.2.2 OnSetFocus Event

This event occurs when the field receives the focus. The return value of the macro is ignored.

5.3.2.3 OnKillFocus Event

This event occurs when the field loses the focus. The return value of the macro is ignored.

5.3.2.4 OnEditSetText Event

This event occurs when a form is opened and the presetting of a field is evaluated and transferred to the

field. The return value of the macro is ignored.

5.3.2.5 OnSelChange Event

This event occurs when reference tables or the Outliner is to be accessed.

5.3.3 Events in Result Lists

In a results list events occur to which macros can be specifically assigned. This is done in the

"Masks-ResultList" dialog box



2. Adding the form element "Search" the "Form Results List" dialog opens where you can

define the parameters.

3. In the "Properties" tab, click the [Events...] button.


26



opens.




In the following all existing results list events are listed.


27

5.3.3.1 OnSelChange Event

This event occurs when access takes place.

5.3.3.2 OnItemDrag Event

This event occurs when a document is executed by dragging.

5.3.3.3 OnItemAccept Event

This event occurs when a drop would be possible at this location.

5.3.3.4 OnItemDrop Event

This event occurs when a drop is carried out.

5.3.3.5 OnTooltip Event

This event occurs when the Tooltip is displayed.

5.3.3.6 OnDragCancel Event

This event occurs when a Drag&Drop procedure is cancelled, i.e. when a drag without drop is carried out.

5.3.3.7 OnEdit Event

The event occurs when a document from the results list is edited.

5.3.3.8 OnView Event

The event occurs when a document from the results list is displayed.

5.3.3.9 OnPrint event

The event occurs when a document from the results list is printed. If multiple documents are selected,

the event is activated with the last one selected.

5.3.3.10 OnDelete Event

The event occurs when a document from the results list is deleted.

5.3.3.11 OnIndex Event

The event occurs when the index of a document from the results list is opened.

5.3.3.12 OnSave Event

The event occurs when a document from the results list is saved.

5.3.3.13 OnNew Event

The event occurs when a new data record is entered in the results list of a query mask for management

of a lookup table.

5.3.3.14 OnSecurity Event

The event occurs when an ACL is assigned to a document from the results list.

5.3.4 Events in Outliner

In results occurring in Outliner, macros can be specifically assigned. This is done in the "Masks Outliner"

dialog box by clicking the [Events...] button. The available events are listed in the "Define events" dialog

box.


28



2. Adding the form element "Ouliner" the "Form Outliner" dialog opens where you can set

appropriate parameters.

3. Open the "Parameter" tab and click the [Events] button.



opens.




In the following all existing outliner events are lsisted.


29

5.3.4.1 OnSelChange

This event occurs when the Outliner is to be accessed.

5.3.4.2 OnExpand

This event occurs when another Outliner level is opened.

5.3.4.3 OnItemDrag

This event occurs when a document is executed by dragging.

5.3.4.4 OnItemAccept

This event occurs when a drop would be possible at this location.

5.3.4.5 OnItemDrop

This event occurs when a drop is carried out.

5.3.4.6 OnItemNew

This event occurs when a new Outliner level is created.

5.3.4.7 OnItemEdit

This event occurs when an Outliner level is edited.

5.3.4.8 OnItemDelete

This event occurs when an Outliner level is deleted.

5.3.4.9 OnDragCancel

This event occurs when a Drag&Drop procedure is canceled, i.e. when a drag without drop is carried out.

5.3.5 Events Triggered by Buttons in Forms

Macros can be executed in two ways with buttons. On one hand, additional buttons can be defined

whose sole function is the execution of macros. On the other hand, any button can be assigned to a

macro via the "OnButtonClicked" event.


30

In the first variation, any desired sub-procedure can be used; in the second variation, the macros must

exist in a certain syntax. In both variations, the macros are assigned from the "Form Button" dialog box.

5.3.5.1 Defining a Button that Executes a Macro



2. Adding the form element "Button" the "Form Button" dialog opens where you can define

the parameters.

3. In the "Function" tab, click the [Events...] button.



opens.


The assigned macro is a procedure (sub or function) without parameters. The name may

be chosen as desired:


31

Sub MyMacroButton()

' instructions

...

End Sub



5.3.5.2 Assigning the Macro via the "OnButtonClick" Event



2. Adding the form element "Button" the "Form Button" dialog opens where you can define

the parameters.




32


opens.




Sub MyMacroButton()

' instructions

...

End Sub



5.3.5.3 "OnButtonClick" Event

This event occurs when a button is clicked in a form. The return value of the macro must be TRUE in

order for SAPERION to continue the procedure that the macro has interrupted.

5.3.6 Events Executed via ActiveX Objects in Forms

There are generally several events available to you when using ActiveX objects in a form. Which events

are available depends on the respective ActiveX object.



2. Adding the form element "ActiveX object" the "Create ActiveX objects" dialog opens.



33



opens.




Sub MyActiveXEvent()


End Sub


6 Samples

34


6 Samples

The following examples are intended to illustrate how the various function groups in "EventScript" are

used. The examples used below are drawn from actual applications in SAPERION.

6.1 Simple SAPERION Functions

6.1.1 Programming Ribbons

Ribbons that are introduced with SAPERION 7.1 base on third-party software of Codejock Software. They

are provided as ActiveX objects (Codejock.*.ocx; in the SAPERION directory). Via API interface you are

allowed to create own ribbon elements.

For this purpose refer to the "Best Practice Programming Ribbons".

6.2 More Complex SAPERION Functions

6.2.1 Deletion from the Lookup Table during Archiving

6.2.1.1 Scenario

Documents with barcodes are to be given index information automatically from a lookup table during

the archiving process. In order to check whether all barcodes are processed correctly, the data record

that belongs to the barcode is to be deleted from the lookup table.

6.2.1.2 Sample Code

A link from the "Archiving" event to the corresponding macro is created in the workflow component.

Sub Delete ( event As Long, s As String ) ' Sub Delete ( ) in halt mode

Dim vLabel As String

Dim DeleteCursor As Object

If Len( s ) = 0 Then

vLabel = document.Label

Set DeleteCursor = Application.SelectQuery ( "NKBel", "NLabel='" & vLabel & "'" )

If DeleteCursor.First Then

DeleteCursor.DeleteCurrent

End If

Else

MsgBox "Fehler: " & s

End If

End Sub

6.2 More Complex SAPERION Functions

35

i In halt mode, however, the functions must be defined without parameters because no call

parameters are supported in this mode.

6.2.2 Macros in Forms: Selecting an Application

6.2.2.1 Scenario

In indexing or results forms, it is in some cases necessary to make available special functions that are

not part of the standard SAPERION package. In Windows, of course, file extensions are not unique. A file

extension can be used to represent several different applications. For example, TXT files can be opened

with NOTEPAD as well as with WRITE. Thus, the extension does not always indicate which program

should be called up to edit the file.

6.2.2.2 Sample Code

In the SAPERION Forms designer, a macro button can be defined to which a macro can be linked.

Depending on the form type, the focus is on certain objects. In the indexing form, for example, the focus

is set on the current document so that the document can be worked with directly. Now it is possible to

select an application from a predefined selection list, save the document, and call up the application

with the saved document.

Sub StoreFile()

Dim FileName As String

Dim ID As Long

FileName = Document.FileName

FileName = "C:\TEMP\" & FileName

Document.SaveAs(0,FileName,0)

MsgBox "Save File as " & FileName

End Sub

Sub Apps()

Dim AppNames$(2)

Begin Dialog SelectAppDlg 20, 20, 150, 50, "SelectApp"

OKButton 80, 10, 50, 13

CancelButton 80, 30, 50, 13

DropListBox 10, 10, 60, 50, AppNames$(), .DrpList

TextBox 10, 30, 60, 13, .Parameter

End Dialog

Dim Button As Long

Dim FileName As String

Dim ID As Long

Dim SelectApp As SelectAppDlg

Dim ExecString As String

AppNames(1)="PBrush"

AppNames(2)="Notepad"

FileName = Document.FileName

FileName = "C:\TEMP\" & FileName

6 Samples

36

'MsgBox FileName

Document.SaveAs(0,FileName,0)

Button = Dialog (SelectApp)

If Button = -1 Then

'MsgBox AppNames(SelectApp.DrpList+1)

ExecString = AppNames(SelectApp.DrpList+1) & " " &

FileName & " " & SelectApp.Parameter

'MsgBox ExecString

ID = Shell (ExecString)

End If

End Sub

6.2.3 Using COM Objects of other Applications

The following example loads a Word.Doc file, inserts a text at the beginning, and then saves the

document.

Sub COMWord()

Dim WordObj As Object

Dim myData As String

' Demonstrates Automatic type conversion

myData = 4 * Atn(1)

Set WordObj = CreateObject("Word.Application")

WordObj.Documents.Open Filename:="C:\Saperion\Word.doc"

WordObj.Visible = True

WordObj.Selection.TypeText "The following was computed in Cypress Enable: "

WordObj.Selection.TypeText MyData

WordObj.ActiveDocument.Close

Set WordObj = Nothing

End Sub