PSIcapture Administrator Guide: Scripting

 Audience

This article is meant for PSIcapture Administrators.

Overview

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:

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:

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:

public virtual bool IsScriptMethodEnabled(IBatchbatch, int workflowStepNumber, string scriptMethodName)
{
  try
  {
	if(workflowStepNumber == 1 && scriptMethodName == "FilterFileSet")
		return true;  //run FilterFileSet bypassed
	else
		return false; //all other methods are bypassed
	}
	catch (Exception exception)
	{
		base.ProcessException(exception);
		return false;
	}
}

public virtual bool EnableUnrestrictedCode()
{
	try
	{
		return true;
	}
	catch (Exception exception)  { . . . 

Console.Write("Howdy");
Console.Write(" Partner!");
Console.WriteLine("  This is how Write and WriteLine work!");
Console.WriteLine("Pretty snazzy…");
Console.WriteLine("The End");