Introduction

This article documents data types and field options, as well as validation and usability features that will help improve the quality of your captured data without sacrificing indexing efficiency.  Fields represent the largest single configuration area when setting up a new document type, and as such understanding the information in this article is a critically important aspect to mastering document type creation.

Field definitions in PSIfusion consist of three distinct parts:  Field attributes, validation options and automation options.

Field Attributes

Field Name

Fields in each document type must be identified by a unique name.  Names are only required to be unique within the current document type, and can be reused within other document types in the application.  It is recommended that you use field names that are concise and accurately describe the data you wish to collect in that field.  If you wish to provide explanatory or descriptive text to the index operator, refer to the Field Description section of this article.

Data Type

Data types define the type and format of data the field should accept.  Each field is required to define exactly one data type.  The data types supported by PSIfusion are as follows:

This list includes documentation of some characters that have different meanings across different cultures and locales. When specifying supported characters by field data type, these character lists have no bearing on how data will be parsed with respect to the current system's culture and locale settings. The currently active culture and locale on the client system will always be used to parse text based numeric and date/time data, and PSIfusion will fully support data operations on systems where the current locale is not set to US English.

Text

Text fields can accept any printable characters and are suitable for containing any type and format of incoming data.  This is the default data type applied to newly added fields.

Text fields are rendered in the indexing interface as a single line text box.  While the underlying data field can accept line feeds, it is recommended that you use a Memo field type for these scenarios, as the user experience will be tailored to accept and display line feeds, whereas a text field will not.  Hitting the enter key while a text field is active will advance the interface to the next available field in the document type.  This differs from the memo field type where hitting the enter key will insert a line feed into the field data.

Text data is stored in double-byte compatible Unicode Transformation Format (UTF), where the UTF variant is automatically selected based from UTF-8, UTF-16 and UTF-32 based on the text content.

Number

Number fields are suitable for capturing and displaying any type of numeric data, including whole numbers, fractional numbers, and negative numbers.

Number fields are rendered in the indexing interface as a single line text box.  Number fields are filtered to accept only the following characters:

  • Digits (0 to 9)
  • Sign indicators (+ and -)
  • Decimal separator (.)
  • Thousands separator (,)

Number data is stored as a double width (64 bit) floating point value.

Currency

Currency fields are suitable for expressing monetary values, and are parsed, filtered and stored using the same rules documented for the Number field type.

Future releases of PSIfusion will expand currency support to allow the inclusion of culture specific currency symbols. The data format of currency fields will not change, currency fields will continue to be stored as double width floating point values.

Whole Number

Whole number fields are limited to displaying digits only and will not accept any form of punctuation or separator characters.  Use whole number fields when you wish to capture numeric field data, but restrict the entry of separator or signage characters from the field.

Whole number fields are rendered in the user interface as a single line text box, with filtering options set to accept only digit characters.

Whole number data is stored as a 32 bit integer value.

Decimal

Decimal fields are used for collecting numeric data that should always contain a decimal separator value.  Parsing, filtering and storage of decimal fields follows the same rules documented for the Number field type.

Future releases of PSIfusion will expand decimal support to require the entry of the decimal separator. The field type, as implemented today; is functionally equivalent to the Number field and is included to provide an indication of intent for the field, as well as for inter-operation with other products such as PSIcapture.

The data format of decimal fields will not change, decimal fields will continue to be stored as double width floating point values.

Date/Time

Date/Time fields are used for collecting date values, with an optional time component.  Date/Time values are always parsed and manipulated using culture-aware processes that respect the current culture and locale settings from the client application.

Date/Time fields are rendered in the user interface using a date picker control that also supports masked and validated text entry.

Storage of date/time values is done using Coordinated Universal Time (UTC) values coupled with a culture-agnostic text format that is capable of being persisted and retrieved multiple times with no loss of fidelity.  This ensures that captured date/time data can be moved between systems with different culture and locale settings, operating in different time zones without any negative effect on date/time data.

Boolean

Fields assigned the boolean data type can be used to capture true/false, on/off, set/unset data, and are represented in the user interface as a check box.

Boolean values are stored using a boolean data type and will always have a value of either true or false.

Memo

Memo fields function identically to Text fields, with the exception of the indexing interface, where they are rendered using a multiple line enabled text box control that is configured to accept line feeds.  This changes the user experience from that of the text field type since the enter key will no longer advance to the next field, but instead insert a line feed into the field data.

Data storage and filtering are handled exactly as documented for the text field type.

Description

The field description is used to provide explanatory information or instructions regarding the intended use of the field.  The field description is displayed to the indexing operators via the user interface, so this is an ideal place to specify instructions relating to the validation requirements for the field.  This will assist index operators in entering valid data quicker by ensuring that the data requirements for each field are clearly documented and accessible.

The description is limited to 200 characters.

Validation Options

Validation options are divided into general options and advanced options.

General Validation Options

General options include required fields, and minimum and maximum field lengths.  The remaining options displayed are automation options, and will be covered in the Automation Options section below.

Required

Marking a field as required forces index operators to provide a value for the field.

Minimum Length

Defining a minimum length for a field forces index operators to ensure that the length of the data in the field is not less than the specified minimum value.

Minimum length can only be set on Text or Memo field types.

Maximum Length

Defining a maximum length for a field forces index operators to ensure that the length of the data in the field does not exceed the specified maximum value.

Maximum length can only be set on Text or Memo field types.

Advanced Validation Options

Image 2015-06-16 at 1.48.14 PM.png

Advanced validation options include limiting field values to list entries, and data validation by regular expressions.  Mapping a field to a list, as well as the option to limit the field value selection to the list entries will be discussed in the Automation Options section.

Enable Regular Expression Validation

Regular Expression Validation enables complex text based matching rules to be defined against each field.  When a regular expression validation pattern is applied to a field, the data in the field result in a positive match against the regular expression pattern in order for validation to succeed.  Authoring regular expressions is a complex topic that we can not fully cover here, however there are excellent resources available should you wish to learn more.

A good tutorial and general reference site, maintained by the author of the excellent Regex Buddy tool:  http://www.regular-expressions.info/

Input Mask

When an input mask is defined, placeholders are defined by the PromptChar property. When inputting data, the user can only replace a placeholder with a character that is of the same type as the one specified in the input mask. If the user enters an invalid character, the control rejects the character. The control can distinguish between numeric and alphabetic characters for validation, but cannot validate for valid content, such as the correct month or time of day.

The input mask can consist of the following characters:

CharacterDescription
#Digit placeholder
Character must be numeric (0-9) and entry is required.
.Decimal placeholder
The actual character used is the one specified as the decimal placeholder by the system's international settings. This character is treated as a literal for masking purposes.
,Thousands separator
The actual character used is the one specified as the thousands separator by the system's  international settings. This character is treated as a literal for masking purposes.
:Time separator
The actual character used is the one specified as the time separator by the system's international settings. This character is treated as a literal for masking purposes .
/Date separator
The actual character used is the one specified as the date separator by the system's international settings. This character is treated as a literal for masking purposes.
\Treat the next character in the mask string as a literal. This allows you to include the '#', '&', 'A', and '?' as well as other characters with special meanings in the mask. This character is treated as a literal for masking purposes.
&

Character placeholder
Valid values for this placeholder are ANSI characters in the following ranges: 32-126 and 128-255 (keyboard and foreign symbol characters).

>Convert all the characters that follow to uppercase.
<Convert all the characters that follow to lowercase.
AAlphanumeric character placeholder. For example: a-z, A-Z, or 0-9. Character entry is required.
aAlphanumeric character placeholder. For example: a-z, A-Z, or 0-9. Character entry is not required.
9Digit placeholder
Character must be numeric (0-9) but entry is not required.
-Minus sign when followed by a number section defined by series of 'n's (like in "-nn,nnn.nn") indicates that negative numbers are allowed. When not followed by a series of 'n's, it's taken as a literal. Minus sign will only be shown when the number is actually negative.
+Plus sign when followed by a number section defined by series of 'n's (like in "-nn,nnn.nn") indicates that negative numbers are allowed. However, it differs from '-' in the respect that it will always show a '+' or a '-' sign depending on whether the number is positive or negative.
CCharacter or space placeholder
Character entry is not required. This operates exactly like the '&' placeholder, and ensures compatibility with Microsoft Access.
?Letter placeholder
For example: a-z or A-Z. Character entry is not required.
n

Digit placeholder
A group of n's can be used to create a numeric section where numbers are entered from right to left. Character must be numeric (0-9) but entry is not required.

mm,dd,yyCombination of these three special tokens can be used to define a date mask. mm for month, dd for day, yy for two digit year and yyyy for four digit year. Examples: mm/dd/yyyy, yyyy/mm/dd, mm/yy.
hh,mm,ss,ttCombination of these three special tokens can be used to define a time mask. hh for hour, mm for minute, ss for second, and tt for AP/PM. Examples: hh:mm, hh:mm tt, hh:mm:ss.
{date}{date} token is a place holder for short date input. The date mask is derived using the underlying culture settings.
{time}{time} token is a place holder for short time input. Short time typically does not include the seconds portion. The time mask is derived using the underlying culture settings.
{longtime}{longtime} token is a place holder for long time input. Long time typically includes the seconds portion. The long time mask is derived using the underlying culture settings.
{double:i.f:c}{double:i.f:c} is a place holder for a mask that allows floating point input where i and f in i.f specify the number of digits in the integer and fraction portions respectively. The :c portion of the mask is optional and it specifies that the inputting of the value should be done continous across fraction and integer portions. For example, with :c in the mask, in order to enter 12.34 the user types in "1234". Notice that the decimal separator character is missing. This allevietes the user from having to type in the decimal separator.
{double:-i.f:c}Same as {double:i.f:c} except this allows negative numbers.
{currency:i.f:c} Same as {double:i.f:c} except the mask is constructed based on currency formatting information of the underlying format provider or the culture. It typically has the currency symbol and also displays the group characters.
{currency:-i.f:c}Same as {currency:i.f:c} except this allows negative numbers.
Literal

All other symbols are displayed as literals; that is, they appear as themselves.  


NOTE: You can also escape the mask with {LOC} character sequence to indicate that symbols in the following table should be mapped to the associated symbols in the underlying culture settings.

CharacterDescription
$Currency symbol
/Date separator
:Time separator
,Thousands separator
.Decimal separator
+Positive sign
-Negative sign

Automation Options

Automation options change the behavior of the indexing application to help streamline how quickly index operators can process documents by removing unnecessary or redundant data keying actions.  Automation options are divided into general options an advanced options.

General Automation Options

Default value

Default values define a data source that should be used to populate the field when a new data record is initialized.  By default fields are not assigned a default value, and will default to a blank value, or the appropriate default for the data type.

TypeDescription
NoneNo default value will be assigned. Refer to the table below for default values by data type.
Custom ValuePrompts for a custom default value to be assigned. The value entered must be valid for the selected data type.
Document Page CountDefaults to the total page count for the current document.
Document Type NameDefaults to the name of the current document type. As an alternative to using this value in a data field, the output XML for each document also contains the selected document type name.
Today's DateDefaults to today's date.
Today's Date/TimeDefaults to today's date and the current time.
User IDDefaults to the indexing users identifier, which corresponds to the Queue ID from which the document is being processed.
User NameDefaults to the indexing users user name.
User Display NameDefaults to the indexing users display name.
User First NameDefaults to the indexing users first name.
User Last NameDefaults to the indexing users last name.
User Email AddressDefaults to the indexing users email address.

Each field type has a fallback value that will be used when no acceptable default is defined.

TypeValue
Text, MemoAn empty string.
Number, Currency, Whole Number, Decimal0
Date/TimeNo value provided, expressed as an empty string
BooleanFalse


Sticky

Fields with the sticky attribute set will default to the value entered in the same field on the previous document, carrying forward the same value until it is changed.  Sticky fields are a good choice when a metadata field is read from a one of the first documents in a set, and then remains static for the next several documents before changing again.

Combining the sticky setting with the Required and Skip options will enable users to ignore the field unless it is blank, and the user may click into the field manually when the value needs to be changed.

In addition to holding values manually entered by the user, sticky fields will also maintain any default value for the field or any value imported from the document metadata.

Hidden

Hidden fields will not be displayed in the user interface during index processing.  This is useful for when an external application populates and exports data to PSIfusion that should be left intact and unmodified by the user.  This field data can then be exported from PSIfusion upon document completion and used by the external application that picks up the resulting documents.

Use hidden fields for this purpose when the index operator does not need, or should not be allowed; to view the data in the field.  If the user should see the data, but be restricted from editing it, you should use the Read Only option instead.

Skip

Skip fields will be treated as a tab stop when the index operator is using either the tab or enter keys to navigate the list of fields.  The field will be skipped and focus will stop on the next non-skip field, or the save button, if there are no non-skip fields remaining.  The exception to this rule if the skip field is marked with one or more validation options and does not pass validation.  In this case focus will stop on the field as if the skip option were not set.

Read Only

Read Only fields are displayed in the user interface during index processing, however they are not editable.  This is useful for when an external application populates and exports data to PSIfusion that should be left intact and unmodified by the user.  This field data can then be exported from PSIfusion upon document completion and used by the external application that picks up the resulting documents.

Use read only fields for this purpose when the index operator needs to view the data in the field, but should not be allowed to change it.  If the user should not see the information, you should use the Hidden option instead.

Synchronized

Synchronized fields work similarly to Sticky fields, but instead of copying the value from the previous document, the value is copied across all data records in the current document.  This option is only effective when Indexing Documents with Multiple Records, and will have no affect in other scenarios.

When the index operator changes the field value on any record for the current document, all records on the document will be updated with the new value.

Advanced Automation Options


Image 2015-06-16 at 1.48.14 PM.png
Map to List

Selecting the map to list option enables the current field to be linked to a list defined within the PSIfusion organization.  Lists are an easy way to provide a list of suggested values for the field to the index operator.

Default values and imported metadata values will be matched to the list, and the appropriate list value will be selected, if it exists.  

The available lists for the current field will be restricted to those lists that conform to the data type for the current field.  If you have defined a list that is not showing up in the Map to List drop down control, ensure that the data type for the list and the data type for the field match.

To learn about defining lists and optionally connecting them to external data sources, please refer to the Lists article.

Limit Field Value to List Entries

This option is only enabled after the Map to List option has been enabled.

Limiting a field value to the available list entries converts the list backed field into a Constrained Value List (CVL).  Fields with this option set will fail validation if the field value does not correspond to one of the available list values.

Adding a Field

Clicking the Add button will add a new field to the field list, using default attributes, validation and automation options.  You must populate the field name before the document type will validate and allow saving.

Removing a Field

Selecting a field from the field list and clicking the Remove button will remove the selected field from the list.  If the field is mapped to a list the list definition is left unchanged.

 This action is not reversible, and no backup of the associated field validation and automation settings is performed.  To restore the removed field you will have to add a new field and recreate the settings manually.

Field Order

The order fields are displayed in the administration interface is also the order the fields will be rendered in the index application interface.  If you wish to reorder the fields for the document type, select a field you wish to move and use the Up and Down buttons to adjust the field position.

Repeat this for each field you wish to move, and save the document type to persist the changes.

Summary

After configuring the fields for the document type, you may optionally define one or more Lookups.  Please proceed to the next section of this guide where we will demonstrate how to configure PSIfusion to make use of external data sources


Next: Lookups


On this page:


In this section:


Related items: