Scripting overview

The scripting capabilities of the component allows you to provide your own authentication method or to modify the standard behavior of a form.

Some of the scenarios where you can use scripting include:

Implement a custom authentication method.
Add and remove fields to a form dynamically.
Change field contents (for example: load the contents of a list field from a database).
Validate field contents before the document is scanned and sent to the workflow server.

About the scripting environment

When using scripting for dynamic forms you must provide a script file that contains the code to respond to events. A script editor is provided as part of the component; to access the editor, do the following:

To edit Custom Authentication scripts click the Edit Script button in the Authentication tab in the main component window
To edit Dynamic Form scripts click the Edit Script button in the General tab of the Form Settings window.

The included script editor facilitates the creation and edition of scripts, provides intellisense and allows for the compilation of scripts. To compile the script click the Compile button in the script editor window, if errors are found you can double click the error message to go to the associated line of code.

Both Visual Basic .NET and C# are supported for writing scripts with Visual Basic as the default language. Switching to your language of choice can be achieved using the Languages submenu located under the Compilation menu in the script editor.

With Visual Basic .NET, your code must be contained inside a Module named Script, for example:

Imports System
Imports NSi.AutoStore.Capture.DataModel
Module Script
   'Add your event handlers here...
End Module

With C#, your code must be contained inside a public static class named Script, for example:


using System;
using NSi.AutoStore.Capture.DataModel;
public static class Script {
   // Add your event handlers here...
}

By default only the component library and the following assemblies are loaded in the scripting environment at runtime:

System.dll
Mscorlib.dll
System.Web.dll
System.DirectoryServices.dll

If you need to use other .NET libraries you will need to add the following comment at the top of your script in order to load the respective assembly:

'LoadAssembly:AssemblyName.dll
//LoadAssembly:AssemblyName.dll

Where assembly name is the name of the assembly, for example to use the System.Data assembly you would specify:

'LoadAssembly:System.Data.dll
//LoadAssembly:System.Data.dll

You can load native .NET framework assemblies, Global Assemblies or .NET assemblies that are located in the workflow server installation directory. If you plan to use a third party assembly you must make sure that it meets one of the above criteria.

Besides any namespaces you want to reference in your script, you will also need to import the NSi.AutoStore.Capture.DataModel namespace. This contains the classes that will allow you to interact with the form, fields and authentication data.

Responding to Events

To respond to events generated by a form or custom authentication you need to provide an event handler for the desired event.

Authentication Event

This event is generated when Custom Script authentication has been configured for the component and the user presses OK in the device login screen. The syntax for the procedure that responds to this event is:

Sub CustomAuthenticate(authData As MetadataCollection, result As AuthResult)
 'TODO add code here to authenticate based on the information entered at MFP
End Sub
public static void CustomAuthenticate(MetadataCollection authData, AuthResult result) {
 //TODO add code here to authenticate based on the information entered at MFP
}

See the AuthResult class for an example of how to respond to this event.

The code for responding to the authentication event must be included in the script file selected in the Authentication tab of the component.

Form Events

The form can generate two events, one when the form is loaded and one when the form is submitted (when the user presses the OK button on the form screen). Form events are only fired if you explicitly configured the component to do so. For details on doing this please refer to the Dynamic Form section of the component help.

The syntax for the procedure that responds to the form load event is:

Sub Form_OnLoad(ByVal eventData As MFPEventData)
public static void Form_OnLoad(MFPEventData eventData)

The syntax for the procedure that responds to the form submit event is:


Sub Form_OnSubmit(ByVal eventData As MFPEventData)
public static void Form_OnSubmit(MFPEventData eventData)

See the MFPEventResult.IsFormValid property for an example of how to respond to this event.

Field Events

Fields can generate an event when the value of the field is changed. This event is only fired if you explicitly configured the field to do so. For details on doing this please refer to the Adding Fields section of the component help.

The syntax for the procedure that respond to the field changed event is:

Sub FieldName_OnChange(ByVal eventData As MFPEventData)
public static void FieldName_OnChange(MFPEventData eventData)

In addition to the changed event, the ListField can also generate an even when the user press the Find button on the device. The syntax for a procedure that respond to the list field find event is:

Sub FieldName_OnFind(ByVal eventData As MFPEventData)
public static void FieldName_OnFind(MFPEventData eventData)

When using FieldName_OnFind, the function should check that valid values are returned. If invalid values are returned, the field becomes empty.

The code for responding to form events must be included in the script file selected in the Dynamic Form section of the form settings.

In case of Numeric fields, if multiple commas are entered as Default value, the commas are ignored during the conversion. To avoid it, use the following script:

Option Strict Off

Imports System
Imports NSi.AutoStore.Capture.DataModel

Module Script
    Sub Form_OnLoad(ByVal eventData As MFPEventData)
		On Error Resume Next
		'Option 1, set limits 
		Dim fields = eventData.Form.Fields 	
		For Each field As BaseField In fields 
			If TypeOf field Is NumericField Then
				Dim myField As NumericField = DirectCast(field, NumericField)
				'Overrides for NumbericField
				myField.MaxValue = 6
				myField.MinValue = 4
				myField.Precision = 2
				myField.Display = "Scripted NumericField"  'This changes the field label
				myField.Value = "5,4"  'sets the initial value (default).  The client locale's decimal character must match, in this example a comma is used.
			End If
		Next
		
		'Option 2, set limit on specific field.		
		Dim myField2 As NumericField = DirectCast(eventData.Form.Fields.GetField("Numericfield"), NumericField)
		'Overrides for NumbericField
		myField2.MaxValue = 10
		myField2.MinValue = -10
		myField2.Precision = 2
		myField2.Display = "Specific NumericField"  'This changes the field label
		myField2.Value = "7,3"  'sets the initial value (default).  The client locale's decimal character must match, in this example a comma is used.
		
	End Sub
End Module

Debugging scripts

To trace into the scripting code using a VisualBasic.Net debugger (such as Visual Studio) you can attach the debugger to the batch.exe process (this is the workflow server service process).

Also if you don't have a debugger but want to display detailed information about the script execution, you can run the workflow server in server mode, and use the methods from the System.Console class to display information in the command window. To run in server mode you need to type the following command in a command window:

<Workflow Server Install Path>\batch.exe -e -c<Path to configuration script>

So if your script is invoked by a configuration file located at C:\My.cfg then you will have to use the following command line:

<Workflow Server Install Path>\batch.exe -e -cc:\My.cfg