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:
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
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.
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.
This closes the Script Editor without saving.
Export writes the selected scripts to an external text file.
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.
This button adds external DLL references to the Script Editor. Use this command to add references to your own custom, external DLLs.
Adds additional .Net namespaces to the Script Editor to provide access to additional C# functionality.
Displays the source (including unsaved changes) in the editor window.
Displays the currently saved source (without unsaved changes) in the editor window.
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.
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:
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:
Incoming value or reference is not editable
The parameter contains no value when the method is called, but users can supply one before the method ends
The value contained in the parameter can be edited
Most script classes contain two default methods: IsScriptMehtodEnabled and EnableUnrestrictedCode.
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.
The current batch; batch properties can be changed
A read-only reference to the current workflow step number
The name of the script method that is about to be called
Example: Execute only the FilterFileSet script method, and only if the workflow step number is equal to 1:
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.).
Example: Enable unrestircted code by returning true from the method:
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:
Console.WriteLine(" This is how Write and WriteLine work!");
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.