Scripting

Overview - What is Scripting?

PSIcapture Capture Profiles provide a rich set of configuration options to cover a wide variety of situations for document capture, indexing, validation  and migration. However, business requirements are as varied as businesses themselves, and there is simply no way to account for every business need. To that end, PSIcapture provides a powerful scripting interface to add custom logic directly into a batch process. 

Where Can It Be Used?

The scripting interface is available at key points during a batch’s life cycle:

  • Auto-import
  • Document separation
  • Barcode processing
  • Indexing
  • Advanced indexing
  • Classification
  • QA Auto Processing (versions 6.1+)

Use scripts to apply custom business rules for index data validation and manipulation. Scripts can also connect to external databases, or call external programs and web services

What can you do with scripting?

  • Filter and sort files before they are queued for Auto Import
  • Control separation and trigger separation profiles
  • Extend barcode processing
  • Manipulate and validate captured values
  • Alter lookup query parameters, and filter values returned from lookups
  • Call a function in an external API or DLL
  • Query external databases
  • Trigger Zone Definition profiles
  • Restructure batches

What can you NOT do with scripting?

  • Scripting can’t control aspects of the graphical user interface. It can’t alter what the operator sees on the screen, control tabbing behavior between index fields, etc.
  • Scripting can’t be used to skip or alter PSIcapture’s internal processes. For example, scripting can’t be used to bypass workflow steps.
  • Documents cannot be added or removed, and folder and document records cannot be deleted. 

Script Programming

Scripts are written in C#, a standard Microsoft .Net managed language. The C# language can be a bit daunting at first glance. While it does take a while to master, it takes very little time to learn the basics. There are many hundreds of tutorials available on the internet, and equally as many books on the subject.

Experienced C# programmers will have no trouble navigating the PSIcapture Script Editor. The editor is very similar to the one in Visual Studio, complete with intellesense prompting to help navigate the various properties available.

For more complex scripting requirements, contact PSIGEN Professional Service. We can construct a suite of scripts to fit any business need.

The Script Editor

Use the various Open Script Editor buttons during Capture Profile configuration to open the Script Editor.

Pressing the Open Script Editor button displays the Script Editor.

The editor contains a toolbar and four main areas:

A. Capture Profile Preview – Use this area to look up the names of batch, folder and document index fields.  If the capture profile uses multiple record types, they are also listed.

B. Scripts and Methods – Use this window to select which script to edit.

C. Method Editor – This window displays the code associated with the selected script method.

D. Error Message Window – Displays any coding errors detected after pressing the Build & Save button.

The toolbar contains the following functions:

Build & Save

Build & Save compiles all script methods. If no errors are detected, the scripts are saved to the document type and the Script Editor closes.

Close

This closes the Script Editor without saving.

Export

Export writes the selected scripts to an external text file.

Import

Import reads in the script files that were saved through the Export function.

Reset All Scripts

This discards all custom code and resets all scripts to their default values.

Edit References

This button adds external DLL references to the Script Editor. Use this command to add references to your own custom, external DLLs.

Edit Namespaces

Adds additional .Net namespaces to the Script Editor to provide access to additional C# functionality.

Current Source

Displays the source (including unsaved changes) in the editor window.

Original Source

Displays the currently saved source (without unsaved changes) in the editor window.

Both Versions

Displays a “split” editor window showing both the original source and the current source.

When the Script Editor is opened, the scripts for the area currently configured area are displayed by default. For example, pressing the Open Script Editor button on the Auto Import Settings screen displays the scripts for Auto Import by default. However, once the Script Editor is opened, all scripts are available for editing.

The Anatomy Of A Script – Classes and Methods

PSIcapture scripts are written in C#, and therefor follow the organization of the C# language. In C#, related tasks are grouped together into what is known as a class. Each class contains methods, each of which represents a unique task.

In the Script Editor, each area of the document type that supports scripting will contain one or more script classes. For example, in Figure 1, auto import contains one scripting class called AutoImportFileSetScript. Inside this class are four methods – IsScriptMehtodEnabled, EnableUnrestrictedCode, SortFileSet and FilterFileSet. During the remainder of this document, “editing a script” is synonymous to “editing a particular method within a scripting class”.

A method can receive data from a batch through a set of parameters. Use the data from the parameters to make decisions in the code. In many cases users can also alter the values stored inside these parameters, which are then communicated back to the batch. For example, if an index is passed as a parameter, any change made to that index’s value is communicated back to the batch when the method completes.

The methods themselves will often return values. For example, the method DocumentDataFieldValidated in the DataRecordIndexingScript class is designed to return a value of  true or false. The code in this method will determine which value is returned – true if the value of index is valid, or false if it is in error. PSIcapture will then use this information to flag invalid indexes in the Index Module.

Inside each method is a C# construction known as a try-catch. Code is entered between the curly brackets underneath the “try” portion. If an error occurs while running the method, the “catch” block will trap the error and report it back to the batch.

Figure 2 below shows an example of a typical script method. The first line displays the scripting class that the method belongs to, in this case the AutoImportFileSetScript class. The method name appears in line three (IsScriptMehtodEnabled). The method returns a bool (C# for boolean) - true or false. It receives data from the current batch through several parameters – the current batch, the workflow step number and the script method name. 

The editable part of the method is between the brackets underneath the “try”. By default, this method has one line of code (line 7) that returns true. However, users can remove this code and substitute their own.

Parameters Overview

The parameters passed into each script method are either value types or reference types.

A value type contains a single value - a whole number, a decimal, a character, a boolean, etc. In Figure 2 above, workflowStepNumber is a value type parameter. It contains a single integer number (int).

A reference type points to an object that itself is a collection of properties and methods. users access this collection by typing the parameter’s name followed by a period. In Figure 2, the “batch” parameter is of type IBatch which is a reference type – it references all of the information available about the current batch. Type “batch.”, and the script editor displays all of the values and methods that are valid for a batch (Figure 3 - below).

In many instances, a reference type parameter will contain properties that are themselves a Reference type. For instance, the “batch” parameter in Figure 2 contains a property called Folders, which is the collection of all folders in the batch. Each folder in the Folders collection in turn has a Documents property, which is a collection of all the dcouments in the folder. So, if users wanted to examine the first document in the first folder in the batch, the user could access it this way:  

batch.Folders.First().Documents.First()

The Class Description section contains descriptions for the scripting interface classes. It contains a list of all enumerations, properties and methods available for each Reference type parameter that users will encounter in scripting.

By typing batch you get all the current available scripts for batch.

The reference type parameters are not usually editable; for example, users can’t remove all of the folders that are stored in a batch’s Folders parameter. However, users can change the value of many of the properties stored within a reference parameter. For example, users can select one of the documents within a batch folder and modify the value of the document’s DocumentNote or Flag property.

In the documentation that follows for each method, parameters will be designated as follows:

INIncoming value or reference is not editable
OUTThe parameter contains no value when the method is called, but users can supply one before the method ends
IN/OUTThe value contained in the parameter can be edited

Common Methods

Most script classes contain two default methods: IsScriptMehtodEnabled and EnableUnrestrictedCode

IsScriptMethodEnabled Method

IsScriptMethodEnabled returns either true or false. It is called before each method in any script class is called. If the method returns true, the script method named in scriptMethodName is executed. If false, the specified method is bypassed.

 For example, just before method AutoImportFileSetScript.FilterFileSet is called, IsScriptMethodEnabled is called. Parameter scriptMethodName will have the value “FilterFileSet”. If IsScriptMehtodEnabled returns true, AutoImportFileSetScript.FilterFileSet runs.

Parameters:

DirectionParameterTypeDescription
INbatchIBatchThe current batch; batch properties can be changed
workflowStepNumberintegerA read-only reference to the current workflow step number
scriptMethodNamestringThe name of the script method that is about to be called

EnableUnrestrictedCode Method

EnableUnrestrictedCode returns either true or false. It is called when the script environment is initialized for a batch. By default, the script editor provides only a subset of the .Net feature set. Return true from this method to access more advanced functionality (such as writing text files, accessing databases, etc.).


Script Debugging

The Scripting Console

PSIcapture provides a Script Console window to display debugging messages from a user's script code. To display the console, select User Settings under the Settings tab, and check the Show script console check box (last option in the window).

Whenever the user opens a screen in the Navigator that supports scripting, such as Capture/Import, Indexing or Quality Assurance, a new Script Console tab will be displayed at the bottom of the screen:

Hover the mouse pointer over this tab or click the tab to display the console window:

Click anywhere outside of the console window to collapse the console from view.

Writing Message to The Scripting Console

Within the code, use a call to Console.Write or Console.WriteLine. As the names imply, Write will write only the text to the console, while WriteLine will automatically append a Cr/Lf to the end of the message.

The following commands will produce the Script Console output displayed below:

Other Methods of Debugging

In some instances, the Script Console isn’t the best method for displaying messages from the script code. Users may be working with a Capture Profile that auto-processes batches through the workflow. This will close workflow steps before users have the chance to open the console. Users could also have a very large batch which is producing large numbers on messages which are hard to wade through in the console itself. 

Because scripting uses the powerful C# language, there are many ways to record debugging messages. For example, users could write all of the messages to an external file or to a special database table. If users use any of these alternate methods, be sure to enable unrestricted code by returning true from the EnableUnrestrictedCode() method as described in the Common Methods section above.