ValidationsAndTextAdjustments

Details

When recognizing a field it is recommended to configure the field properties for the target engine to correctly specify the type of text being recognized and limit the field to the expected character set. For example, if a field is expected to be numeric only, then the field should be preset to recognize only numerics. Perhaps a field may have some other restricted character set such as numerics plus "A, B, C, D, E, F", then the field can be setup to allow just those characters. This improves the recognition quality.

It isn't always possible to tell the recognition engine exactly what is expected. This action library can help filter out invalid characters or flag fields that do not match expected patterns or expected data types. For example, if a date does not match the expected date pattern for the locale, then the validation actions can flag the field so it can be examined by a verification operator. Likewise, a validation check can be done for numeric formats or totals of several numeric fields.

Upon failure of a tested condition, most of the actions in this action library will also store the reason for the message in a standard variable called Message. This DCO variable is used by client verification panels to display messages to verify operators so they can understand why a page has failed a verification ruleset. If there are multiple reasons for a failure, these messages are only displayed to the user one at a time, so the operator must fix the displayed error, rerun the validation test and see if additional verification errors still remain. If errors still remain, the operator will need to repeat the process until they have rectified all of the issues that are causing a page to fail validation. Typically a the rule for a validation action is attached to the DCO object that needs to pass the validation so the message is associated with the failed object and typically the status of the object will be set to "1" to indicate the failure in a verification panel.

For example, one common validation is that a particular field is required to have a particular length. Perhaps, it has a minimum length, or a maximum length, or both. The validation action that checks a field's length can be added to a validation ruleset to confirm that the length is correct. If the length is incorrect after a recognition step, it can flag the failed field to the operator in the verify panel. Likewise, it can revalidate a field after it has been reviewed by an operator to help confirm the field is now at the required length before moving on to the next page. The more validations that can be placed on the field data for an application will provide a greater assurance that the data on the page was accurately recognized or correctly entered by an operator.

Locale Sensitive Operations

The validation actions are sensitive to the locale where it is applicable. For example, date validation and currency validation are performed based on the current locale. If not set within the application, the locale used is the machine's default Windows locale. The locale for the entire application can be set within the Application Manager, which will override the windows locale, and instead use the locale configured for the entire application.

Datacap clients and actions support multiple locales within a single application and multiple locales within a single batch. The hierarchical DCO variable hr_locale, can be specified to control the locale of the DCO object being processed.

rrSet("en-GB", "@X.hr_locale)

This example sets the locale for the current DCO node and it's children objects to English (United Kingdom).

If set at the batch level, it affects the entire application. If set on a document, then it sets the locale for all pages and fields within that document. This can be controlled at any level. If set at the page level then the locale will be set for the entire page, allowing each page within a document to have a unique locale. It is possible, although not usually required, to have unique locales configured for each field within a single page.

Smart Parameters and Common Operations

If an action supports smart parameters, it is specified in the action help. Smart parameters are very powerful specifications for parameters that allow access of data to and from other DCO objects and allow performing special pre-defined operations in one step.

Smart parameters can be used to dynamically obtain or create action input parameters at runtime. For example, an action could be fed the value of a field after recognition, a parameter could pull the value from a DCO variable that was set by a previous action, or a smart parameter could evaluate to the current date, the current time, the current job ID, the current operator ID, the path to the current batch that is running, and more.

Smart parameter syntax can also be used to build expressions at runtime that concatenate dynamic data and static data at runtime. Smart parameters are a flexible way to provide a wide range of input to any action that supports smart parameters. The following are some examples of manipulation that are common for manipulating data where it may be expected that a special action exists in the this action library but is not required. This summary is intended to show some manipulation that is typical for validation tasks. This set of examples are by no means the limit of how smart parameters can be used. While many of these examples show the value being passed to the handy action rrSet, the same smart parameter can be passed to any action that supports smart parameters as input.

Refer to the smart parameter guide for full details on all available smart parameters and how to use them.

Append Text To A Field:

rrSet("Append This +@F","@F")

Assuming this is running on a field object, it appends the text "Append This " to the current text value of the field. If the field originally contained "ABCD", the final value is "Append This ABCD")

rrSet("Append This +@F+ The End","@F")

Similarly, if the original field value is "ABCD", the final value of the field text is "Append This ABCD The End".

Concatinate Text From A Different Field:

rrSet("@P\AnotherField+@F","@F")

This example will grab the text value from the sibling field "AnotherField" and append the text to the front of the text in the current DCO field.

Concatinate Text From A Different Field Variable:

rrSet("@P\AnotherField.MyVariable+@F","@F")

This example will grab the value from the sibling field "AnotherField" variable called "MyVariable" and append the text to the front of the text in the current DCO field. Concatinate Text From A Different Field Variable Placed Into New Variable:

rrSet("@P\AnotherField.MyVariable+@CHR(32)+@F","@F.NewVariable")

This example will grab the value from the sibling field "AnotherField" variable called "MyVariable" and append the text to the front of the text in the current DCO field. The current value of the field object is not updated, instead the new result is placed into a variable for the current field called "NewVariable". Assuming that "MyVariable" contains the text "Hello" and the current field value is "Tom", the first parameter will fully resolve to "Hello Tom" and pass that value to the rrSet action, which will then place that new string into the variable called "NewVariable".

Assigning A Default Field Value:

rrSet("My Default Text","@P\MyField")

Assuming this action is run on a page object that contains a field called "MyField", it initialized the default value of the field the "My Default Text". If the field was already recognized, then this new text overwrites the existing text. If the field is later recognized, then this default text will be replaced by the recognized text.

Assigning Today's Date To A Field:

rrSet("@DATE(dd.mm.yyyy)","@X")

This example shows how to assign the current date in day, month, year format when rules are run on a field object. If a date format is not specified, the @DATE smart parameter will default to MM/DD/YYYY.

Likewise, the smart parameter @TIME() can be used to put a time stamp into a field or as a parameter to an action that supports smart parameters.

Assigning The Current Job ID A Field:

rrSet("@JOBID","@X")

Assuming this is called on a field level object, this example shows how to assign the current job ID to the text value of a field object.

Is the current Job ID the expected Job ID:

rrCompare("@JOBID","MyJobID")

This compares the current Job ID with the string "MyJobID" and returns true if it matches. If needed the hard coded "MyJobID" could reference a smart parameter that contains the value. Alternatively, rrCompareNot can be used to return true if the current Job ID is does not match the provided string.

Other comparison actions perform case insensitive comparisons. Clear a field's value:

rrSet("@EMPTY","@F\MyField")

This example shows how to empty the recognized value of the field "MyField" using a rule called on a page that contains the "MyField" child.

To continue if a field is empty:

rrCompare("@EMPTY","@X)

This action would be called on the field object. The smart parameters can reference hard coded values or obtain values from other objects or other DCO variables. To continue if a field is empty from page level:

rrCompare("@EMPTY","@X\MyField")

This tests to see if the page's field called "MyField" is empty. If so, the rule continues.

To continue if a field is not empty:

rrCompareNot("@EMPTY","@X")

This action would be called on the field object to check the text value of the field. If the current field is empty, the function will continue to the next action in the rule. If the field contains text, then control will branch to the next function in the ruleset.

To test if a field value is greater than a specific number:

rrCompareNumeric("1234", "˂", "@X")

This action tests to see if the numeric value of the current field text is greater than 1234. Parameters can be changed as needed. For example, if "@X" was replaced with "@D.MyVar", the value 1234 will be compared against the value of the parent document level variable called "MyVar".

Test if a field is hidden:

rrCompare("-1","@X.STATUS")

If a field has a STATUS of "-1", it is considered to be a hidden field or ignored and is not displayed in a client verification panel. If rules logic needs to determine if a field is hidden, it can be tested by checking the STATUS variable of the field to see if it is "-1". This example assumes the action is running on the current field object whose status will be checked. Of course, smart parameters can be used to navigate and check the status of other DCO objects.