Data Field

Can be one of the following types:

The 'Value Type' property defines the primitive data type for this Data Field, such as string, number, date, or boolean. This setting controls how values are extracted, validated, formatted, and displayed in the UI.

Common Storage Types

• String: For general text, names, IDs, and codes.
• Integer/Decimal: For whole numbers, currency, and numeric values.
• Date/DateTime: For dates and timestamps.
• Boolean: For true/false or yes/no fields.

Each Storage Type may expose additional sub-properties for formatting, parsing, or value constraints.

Configuration Guidance

• Choose a type that matches the expected data (e.g., use 'Decimal' for currency, 'Date' for invoice dates).
• Any value extracted or entered that cannot be converted to the selected type will result in a validation error.
• The value type affects how default values, calculated values, and validation expressions are interpreted.
• Changing the value type may require updating related properties, such as formatting or list values.

Example:
Set 'Value Type' to Date to ensure only valid dates are accepted and formatted correctly.

> Tip: Use the drop-down to explore available Storage Types and review their sub-properties for advanced configuration.

Can be one of the following types:

The 'Value Extractor' property determines how a Data Field locates and extracts its value from a document.
Assigning a Value Extractor enables a wide range of extraction strategies, including pattern matching, list lookups, OMR (optical mark recognition), barcode reading, and referencing other extractors.

Extraction Types

• Text Parsing Extractors: Use regular expressions or value lists (such as a Lexicon) to extract text-based values.
• OMR Extractors: Extract values from checkboxes or marked areas on forms.
• Barcode Extractors: Read values encoded in barcodes.
• Zonal Extractors: Extract text from a specific region of a document.
• Reference Extractor: Reuse extraction logic by referencing another Value Extractor object.

Configuration Guidance

• When set to 'none', a drop-down menu of available extractor types is shown.
• Selecting an extractor type opens a configuration dialog with relevant settings and preview panels.
• Once an extractor type is chosen, it must be reset before selecting a different type.
• For reusable extraction logic, use the "Reference" type and point to a shared Value Extractor object.
• For simple, field-specific extraction, configure the extractor directly on the Data Field.

Usage Notes

• The output of the Value Extractor is used as the field's value and is subject to further validation and formatting.
• For Data Columns, extraction behavior may depend on the parent Data Table's extraction method.
• Sub-properties and advanced options are available by expanding the property in the UI.

For more details, see the documentation for Value Extractor, Data Field, and Lexicon.

The 'Minimum Confidence' property sets the lowest acceptable confidence score for values extracted by the field's Value Extractor.
If an extracted value's confidence is below this threshold, the field is left empty or marked as an error and flagged for human review, based on configuration.

How It Works

• Each extracted value is assigned a confidence score between 0 and 1.
• If the confidence is less than 'Minimum Confidence', the value is considered unreliable and the field enters an error state.
• During Data Review, users are prompted to review and correct low-confidence values.
• If 'Keep Low Confidence Hits' is enabled, low-confidence values are retained but still require review.

Configuration Guidance

• Increase 'Minimum Confidence' to require higher certainty for automated extraction.
• Lower the value to allow more results to pass without review, but at the risk of accepting less reliable data.
• Typical default is 0.2 (20% confidence).
• Use in combination with 'Keep Low Confidence Hits' to control whether low-confidence results are discarded or kept for review.

Usage Notes

• Applies to all extraction types, including pattern match, OMR, barcode, and zonal extractors.
• For array fields, only results meeting the confidence threshold are included unless 'Keep Low Confidence Hits' is enabled.
• Setting a high threshold may increase the number of fields requiring manual review.

The 'Keep Low Confidence Hits' property controls whether values extracted with a confidence score below the 'Minimum Confidence' threshold are retained or discarded.

How It Works

• When enabled, all extracted values are kept, regardless of their confidence score.
• Values below the 'Minimum Confidence' are marked as errors and require human review during Data Review.
• When disabled, only values meeting or exceeding the 'Minimum Confidence' are kept; lower-confidence results are discarded and the field is left empty.

Configuration Guidance

• Enable this property if you want to present all possible extraction results to users, even those with low confidence.
• Disable to filter out unreliable results and reduce the number of fields requiring review, at the risk of missing some possible values.
• Use in combination with 'Minimum Confidence' to fine-tune the balance between automation and manual review.

Usage Notes

• Applies to all extraction types, including pattern match, OMR, barcode, and zonal extractors.
• For array fields, this setting determines whether low-confidence results are included in the output collection.
• Retained low-confidence values are always flagged for review and must be confirmed or corrected by a user.

For more information, see the documentation for Value Extractor and Data Field.

Can be one of the following types:

The 'Sub-Element Name' property allows you to extract a specific sub-component from a complex value returned by the Value Extractor.

This is commonly used when the Value Extractor produces structured results with multiple named parts (sub-elements).
For example, an address extractor might define sub-elements such as "Address", "City", "State", and "ZIP".
By specifying a sub-element name (e.g., "City"), only that component will be used as the field's value.

When to Use

• The Value Extractor returns results with named groups (such as regular expression named groups).

How It Works

• When a Value Extractor produces results with sub-elements, this property becomes available as a drop-down list of group names.
• If set, only the specified sub-element is extracted and assigned to the field.
• If left blank, the entire value is used.

The 'Placeholder' property specifies the hint text shown in the input control for this Data Field when no value is present.

This text appears as a light, grayed-out prompt in the UI, helping users understand what type of information is expected or providing an example format.

How It Works

• The placeholder is visible only when the field is empty and not read-only.
• It disappears as soon as the user enters a value.
• Use this property to provide guidance, examples, or required formats (e.g., "MM/DD/YYYY" for a date field).

Configuration Guidance

• Keep placeholder text concise and relevant to the field's purpose.
• Use placeholders to clarify expected input, especially for fields with specific formats or requirements.
• Do not use placeholder text as a substitute for field labels or tooltips; it is intended as a brief, inline prompt.

Can be one of the following values:

The 'Alignment' property controls the horizontal alignment of the field's value within its input control or display cell in the user interface.

This setting affects how text and values are positioned, especially in data entry forms, review screens, and data grids.

The 'Display Width' property specifies the horizontal size, in pixels, of the input control or display cell for this Data Field in the user interface.

This setting is primarily used to control the appearance and layout of fields in data entry forms, review screens, and data grids.
For fields that are part of a Data Table, this value determines the width of the corresponding column.

Configuration Guidance

• Set a value that provides enough space for typical input without excessive empty space.
• For text fields, use a width that accommodates the expected length of the value (e.g., 200 for names, 100 for codes).
• For numeric or date fields, a smaller width is usually sufficient.
• The default value is 100 pixels if not specified.

Class names defined here may be used from style sheets, to set CSS properties for multiple elements using a single selector.

Example Use Cases

• Highlighting Required Fields: Assign a class such as required-field to visually distinguish fields that must be completed by the user.
• Conditional Formatting: Use dynamic class assignment to flag fields with missing or invalid data, or to indicate extraction confidence.
• Section or Table Styling: Apply a class to a Data Section or Data Table to style entire groups of fields, rows, or columns.
• Custom Themes and Branding: Combine 'CSSClass' with global or local style sheets to implement organization-specific branding, accessibility adjustments, or dark mode support.
• Workflow Indicators: Use class names to visually indicate workflow states, such as approved, pending-review, or rejected.

Best Practices

• Consistency: Define reusable class names in your style sheets to promote consistent appearance and behavior across your solution.
• Separation of Concerns: Use 'CSSClass' for presentation and UI logic, not for storing business data.
• Avoid Conflicts: Choose class names that do not conflict with built-in Grooper or third-party CSS to prevent unintended side effects.
• Dynamic Logic: Leverage dynamic class assignment for data-driven UI changes, such as highlighting based on extraction results or user actions.

Additional Notes

• The 'CSSClass' property is available on all Data Elements, including Data Fields, Data Sections, Data Tables, and Data Models.
• CSS class names are case-sensitive and must conform to standard CSS naming conventions.
• For more information and advanced scenarios, see the documentation for "CSS Data Viewer Styling".
• Use the 'CSS' property on a Data Field Container to define custom style rules that reference your class names, or include external style sheets at the Data Model or Content Type level for broader styling control.
• In addition to static class names, you can assign dynamic CSS classes to containers by including a string variable named "CSS_Class" on a Data Model, Data Section, or Data Table. This enables conditional styling based on data values, extraction results, or business logic. For example, you might highlight fields with validation errors or flag rows based on extracted content.

Overview

The 'Visible' property determines if a Data Element—such as a Data Field, Data Section, Data Table, or Data Model—is displayed in the Grooper Data Grid and other user interface components. When set to false, the element is hidden from the UI, but it remains part of the data model and can still participate in extraction, validation, and automation processes.

Behavior and Inheritance

• UI Presentation: If 'Visible' is set to false, the element and its children are not shown in the data entry or review panels. This is useful for fields that are used for internal calculations, lookups, or automation but should not be exposed to end users.
• Data Processing: Hidden elements are still included in extraction, validation, and export operations unless explicitly excluded by other configuration.
• Inheritance: The visibility of a parent element (such as a Data Section or Data Table) affects its descendants. If a container is hidden, all child elements are also hidden in the UI, regardless of their individual 'Visible' settings.
• Overrides: The 'Visible' property can be overridden for specific Content Types using property overrides, allowing you to tailor the UI for different document types or business scenarios.

Example Use Cases

• Internal Fields: Hide fields used for intermediate calculations, lookups, or automation that do not require user review.
• Conditional UI: Use property overrides to show or hide fields based on the Content Type or document classification.
• Simplified Data Entry: Hide advanced or rarely used fields to streamline the user experience for most users, while making them available for administrators or special workflows.
• Section and Table Visibility: Hide entire Data Sections or Data Tables to control the visibility of groups of related fields.

Best Practices

• Use the 'Visible' property to reduce UI clutter and focus user attention on relevant data.
• Combine with property overrides to create context-sensitive user interfaces for different document types.
• Remember that hidden elements are still processed during extraction and validation unless excluded by other means.

> Note: The 'Visible' property only affects user interface presentation. It does not remove the element from the data model or prevent it from being used in automation, scripting, or export.

Can be one of the following types:

The 'Display Label' property allows you to specify a custom label for this Data Field that will be shown in the user interface instead of the default field name.

This is especially useful for presenting user-friendly or context-specific labels, supporting localization, or providing dynamic labeling based on label sets.

How It Works

• If set, the display label appears in the UI (such as data entry forms and review screens) in place of the field's code name.
• If left blank, the field's name is used as the label.
• Enter /auto to enable dynamic labeling based on label sets, allowing the label to change depending on the document context or user selection.
• The display label is primarily used in the web client and may not affect all UI components.

Usage Notes

• The display label does not affect the field's code name, data binding, or extraction logic.
• This property is for presentation only and is ignored by backend processes.
• If label sets are not configured, /auto will fall back to the default field name.

Can be one of the following types:

Defines how autocomplete suggestions are presented and managed for a Data Field during user entry.

Overview

When assigned to a Data Field, this object enables a pop-up list of suggestions as the user types. Suggestions can be sourced from:

• Values extracted from the document using a Value Extractor (set via 'Entry Extractor').
• Pre-defined entries in a Lexicon (set via 'Entry Lexicon').
• User-provided values, which can be stored for future suggestions (controlled by 'User Training' and 'Training Lexicon').
• Recently used values, tracked per field type.

Key Features

• Dynamic Suggestions: Use a Value Extractor to populate suggestions from the current document's content.
• Static Suggestions: Reference a Lexicon to provide a managed list of allowed or recommended values.
• User Training: Allow users to add new values to the autocomplete list, either manually or automatically, and optionally store them in a separate Lexicon.
• Browser Integration: Control browser-level autocomplete behavior using 'Suggest Mode', which maps to the HTML autocomplete attribute.
• Highlighting: Optionally highlight values entered manually by users in the document view.
• MRU (Most Recently Used): Maintains a per-type list of recently used values to prioritize common entries.

Configuration Guidance

• Assign an AutoCompleteSettings object to a Data Field via the 'AutoComplete' property.
• Set 'Entry Extractor' to extract suggestions from document content, or 'Entry Lexicon' to use a static list.
• Enable 'User Training' to allow users to add new entries, and specify 'Training Lexicon' if user entries should be stored separately from the main Lexicon.
• Adjust 'Suggest Mode' to control browser-level suggestions (e.g., disable for sensitive fields).
• Enable 'Auto Highlight' to visually mark new user-entered values in the document.

Example Use Cases

• Invoice Number Field: Use a Value Extractor to suggest invoice numbers found in the document, and allow users to add missing numbers to the Lexicon.
• State/Province Field: Reference a Lexicon of valid states, and disable user training to restrict input to known values.
• Name Field: Enable browser suggestions for previously entered names, and allow user training for new names.

Related Types

• Value Extractor: Used to extract dynamic suggestions from document content.
• Lexicon: Stores static or user-trained autocomplete entries.
• Data Field: The field to which these settings are applied.

For best results, configure the properties to match the data entry needs and security requirements of your field.

Can be one of the following types:

Configures how multi-line text input and display is handled for a Data Field.

Overview

Use this object to control the appearance and behavior of fields that accept or display multiple lines of text, such as comments, addresses, or descriptions.

Key Features

• Set the number of visible lines in the input area using 'Display Lines'.
• Enable or disable word wrapping with 'Word Wrap' to control how long lines are displayed.

Configuration Guidance

• Assign a MultiLineSettings object to a Data Field to allow users to enter or view multi-line text.
• Adjust 'Display Lines' to provide enough space for typical input without excessive scrolling.
• Enable 'Word Wrap' for fields where long lines should be wrapped within the visible area.

Example Use Cases

• Address Field: Set 'Display Lines' to 3 and enable 'Word Wrap' to allow entry of multi-line addresses.
• Comments Field: Increase 'Display Lines' for longer user comments or notes.

For best results, configure these settings to match the expected length and format of user input for your field.

The 'Tooltip' property provides contextual help or guidance to users interacting with this field in the user interface.

Use this property to display instructions, hints, or validation requirements that assist users in entering correct data.

• Tooltips are shown as hover text in the UI.
• For best results, keep tooltips concise and focused on the specific needs of the field.
• You can include formatting, examples, or warnings as needed.

Example: > Enter the invoice number as it appears on the document. Format: INV-12345

The 'ReadOnly' property controls whether this field can be edited by users during data entry or review.

• When enabled, the field's value is displayed but cannot be changed in the UI.
• Use this for fields that are calculated, system-generated, or should not be modified by end users.
• Read-only fields are often used for audit information, calculated totals, or values populated by automation.

Example: > Set 'ReadOnly' to true for a field displaying the extraction timestamp.

The 'Required' property determines whether this field must have a value for the document to be considered valid.

• If enabled, the field will be set to an error state if left empty, and users will be prompted to provide a value.
• This is a static requirement; for conditional requirements, use the 'IsRequired' property with an expression.
• If both 'Required' and 'IsRequired' are set, the field is required if either condition is true.

Example: > Enable 'Required' for fields such as "Invoice Number" or "Date" that must always be present.

The 'Sticky' property causes the value entered for this field to be retained and automatically applied to the same field in subsequent documents during data review.

• Use this for fields where the value is likely to remain the same across multiple documents, such as batch-level metadata or operator initials.
• When enabled, users do not need to re-enter the value for each document; it is pre-filled from the previous entry.
• This improves efficiency and consistency for repetitive data entry tasks.

Example: > Enable 'Sticky' for a "Reviewed By" field to carry the operator's name across all documents in a batch.

The Require Validation property enforces human review for this Data Field during data entry or data review workflows.

When enabled, the field is initially placed in an error state—even if a value is present or extracted automatically.
The error state is cleared only after a user enters the field and then leaves it (i.e., the field receives and then loses focus), ensuring that a human has reviewed the value.

How It Works

• If Require Validation is true, the field is marked as requiring review regardless of extraction confidence or other validation.
• The field remains in an error state until a user interacts with it (enters and leaves the field).
• This property is useful for fields that must always be confirmed by an operator, such as critical data points or fields with regulatory requirements.
• If both Require Validation and Required are enabled, the field must be reviewed and cannot be left empty.

Configuration Guidance

• Enable for fields where human oversight is mandatory, even if extraction is highly accurate.
• Use in combination with Required for mandatory fields, or alone for optional fields that still require review.
• Consider using for fields with high business impact, legal significance, or frequent extraction errors.

Usage Notes

• The review requirement is enforced in the data review UI and compatible clients.
• This property does not affect extraction or validation logic, only the review workflow.
• If not enabled, the field will only require review if other validation rules (such as Required or Min Confidence) are not met.

The Inherit Position property controls whether this Data Field should inherit and display the positional context of its parent instance (such as a table row or section) in the user interface.

When enabled, the field's UI and data review experience will emphasize the position of the parent element (for example, the row number in a Data Table or the instance number in a Data Section). This is useful for fields that are part of repeating structures, where the context of the parent instance is important for data entry, review, or validation.

Usage Guidance

• Enable for fields within repeating groups (tables or sections) where the position or order of the parent instance is relevant.
• The property is not available for fields defined at the root of a Data Model.
• When disabled, the field will not display or emphasize the parent instance's position.

Example Scenarios

• In a table of line items, enabling Inherit Position on a field will help users identify which row or item they are editing.
• In a repeating section (such as multiple addresses), this property can help clarify which instance a field belongs to.

Can be one of the following types:

The SpellCorrection property allows you to assign a Spell Corrector to this field, enabling automatic repair and correction of OCR and spelling errors in extracted values.

When configured, the SpellCorrector will:

• Apply general OCR repair options (such as fixing character case and ambiguous characters) to the field's value.
• Optionally use a custom Correction Extractor to identify and replace specific spelling errors or common OCR misreads.

Usage

1. Assign a Spell Corrector object to this property.
2. Configure the SpellCorrector's options:
   • Enable RepairCase to fix case errors (e.g., "iNVOICE" → "INVOICE").
   • Enable Disambiguate to resolve ambiguous OCR characters (e.g., 'O' vs. '0').
   • Set CorrectionExtractor to a Value Extractor that matches and corrects common spelling or OCR errors (e.g., "lnvoice" → "Invoice").

During extraction and validation, the SpellCorrector will process the field's value, improving data quality and reducing manual correction.

Example:

• Assign a SpellCorrector with a Pattern Match CorrectionExtractor to fix common OCR misreads in invoice numbers.
• Enable RepairCase for fields that should always be uppercase.

Can be one of the following values:

Specifies how the value's character casing is enforced for this field at runtime.

This setting is only applied to fields with a string value type. The selected casing is enforced during field validation and formatting, ensuring that user-entered or extracted values conform to the specified casing before being stored or displayed.

Examples:

• If set to Upper and the user enters "abc123", the value will be stored as "ABC123".
• If set to Lower and the value is "InvoiceID", it will be stored as "invoiceid".
• If set to Normal, the value is stored as entered or extracted.

Overview

The 'Rubberband OCR Profile' property specifies the OCR Profile to use when performing "rubberband" OCR operations on this Data Element. Rubberband OCR refers to user-initiated or programmatic extraction of text from a specific, interactively selected region of a document image—typically by drawing a rectangle ("rubberbanding") around the area of interest in the Grooper Data Grid or other UI components.

Behavior and Inheritance

• Profile Selection: If set, this property determines which OCR Profile is used for OCR processing when a user selects a region for ad-hoc text extraction. If not set, the system will use the parent element's 'RubberbandOcrProfile', or fall back to a default profile if none is specified in the hierarchy.
• Granular Control: Assigning different OCR Profiles to individual Data Fields, Data Sections, or Data Tables allows for fine-tuned OCR settings based on the content, language, or expected quality of specific document regions.
• Overrides: The 'RubberbandOcrProfile' property can be overridden for specific Content Types using property overrides, enabling document-type-specific OCR strategies.

Example Use Cases

• Mixed-Language Documents: Assign a different OCR Profile to fields or sections that contain text in a different language or script.
• Specialized Zones: Use a custom OCR Profile for regions with unique formatting, such as barcodes, handwriting, or low-quality print.
• User-Driven Extraction: When users manually select a region for OCR in the UI, the specified profile ensures the most accurate recognition for that context.

Best Practices

• Assign a OCR Profile only when the default or inherited profile is not optimal for the specific data element.
• Use property overrides to adapt OCR settings for specialized document types or scenarios.
• Test the effectiveness of different profiles on representative samples to ensure optimal extraction accuracy.

> Note: The 'Rubberband OCR Profile' property only affects OCR operations performed via region selection (rubberbanding) in the UI or automation. It does not impact standard extraction logic unless that logic explicitly invokes rubberband OCR.

The Default Value property allows you to specify a VB.NET expression that determines the initial value for this Data Field when a new Field Instance is created.
This is useful for pre-populating fields with static values, system information, or values derived from the document or environment.

The expression must produce a value compatible with the field's 'Value Type'. If the result cannot be converted to the correct type, the field will be set to an error state.

How It Works

• The expression is evaluated when a new Field Instance is created.
• The result is assigned as the initial value for the field, unless a value is already present.
• If the expression fails to evaluate or produces an invalid value, the field is set to an error state.

Examples

• Default to a literal string value:
  "None"

• Default to a literal numeric value:
  25.00

• Default to the current date and time:
  DateTime.Now

• Default to the current date:
  DateTime.Today

• Default to the current user name:
  Environment.UserName

• Default to the current machine name:
  Environment.MachineName

• Default to the MIME type of the document:
  Folder.NativeMimeType

• Default to the name of the Content Type assigned to the document:
  ContentTypeName

• Default to the "Subject" metadata element of a PDF file:
  DirectCast(Handler, PdfMimeTypeHandler).Subject

• Default to the filename associated with a File System Link:
  DirectCast(Link, FileSystemLink).Filename

• Default to the filename associated with a File System Link without the extension:
  IO.Path.GetFileNameWithoutExtension(DirectCast(Link, FileSystemLink).FilePath)

• Default to the name of the 2nd directory level associated with a File System Link:
  Link.GetPathSegment(1)

• Default to the sender associated with a Mail Message:
  DirectCast(Handler, MailMimeTypeHandler).From

• Generate a unique identifier:
  Guid.NewGuid

Usage Guidance

• Use this property to automate the population of fields with common or system-derived values.
• The expression can reference document context, environment variables, or other accessible properties.
• For fields that should always have a starting value, set a default to reduce manual entry and improve consistency.

For more information, see the documentation for Field Instance and Storage Type.

The Calculated Value property allows you to define a VB.NET expression that computes the value for this Data Field based on other fields, similar to a formula in a spreadsheet.
The result of this expression can be used to validate the field, automatically populate its value, or both, depending on the 'Calculate Mode' property.

The expression must produce a value compatible with the field's 'Value Type'. For example, if the field is a decimal, the expression should evaluate to a decimal value.
If the expression produces an invalid value that cannot be converted to the field's type, the field will be set to an error state.

How It Works

• The expression is evaluated in the context of the current Field Instance.
• The result is compared to the field's value, or used to set the value, depending on 'Calculate Mode'.
• For numeric fields, the 'Calculate Tolerance' property can be used to allow for rounding or minor differences.
• If the expression fails to evaluate, the field is set to an error state with a calculation error message.

Simple Examples

LINQ Examples

Expressions may use LINQ syntax to access information in collections, such as tables and multi-instance sections.

Usage Guidance

• Use this property to automate calculations, enforce business rules, or derive values from other fields.
• The expression can reference any field in the same Data Model or Data Section.
• For fields that should always be calculated, set 'Calculate Mode' to 'Always Set' and consider making the field read-only.
• For validation-only scenarios, set 'Calculate Mode' to 'Validate'.
• For numeric fields, use 'Calculate Tolerance' to allow for rounding or minor differences.

For more information, see the documentation for 'Calculate Mode', 'Calculate Tolerance', and Field Instance.

Can be one of the following values:

The Calculate Tolerance property specifies the maximum allowed difference between the field's actual value and the value produced by its Calculate Expression.

This property is only applicable to fields with a numeric value type and when a Calculate Expression is defined.
If set to 0, the field value must exactly match the calculated value for validation to succeed.
If set to a positive number, the field value is considered valid as long as the absolute difference between the actual and calculated values does not exceed this tolerance.

Usage Guidance

• Use this property to allow for rounding differences, minor calculation variances, or acceptable error margins in numeric fields.
• Set to 0 to require an exact match between the field value and the calculated value.
• Set to a positive decimal value (e.g., 0.01 for currency fields) to permit small differences.

Example

• If the calculated value is 100.00 and Calculate Tolerance is 0.05, then any value between 99.95 and 100.05 will be accepted.

Notes

• This property is ignored for non-numeric fields or if no Calculate Expression is set.
• If the difference exceeds the specified tolerance, the field is set to an error state and a calculation error message is displayed.
• The tolerance is applied after any formatting or rounding specified by the field's value type.

The Is Valid property allows you to define a custom validation rule for this Data Field using a VB.NET expression.
The expression is evaluated for each Field Instance at validation time. If the result is false, the field is set to an error state and the error message from 'Validate Message' is displayed.

If no expression is set, only basic type validation is performed (such as checking for required values or correct data type).

How It Works

• The expression is evaluated in the context of the current Field Instance.
• If the result is true, the field is considered valid.
• If the result is false, the field is marked as invalid and the error message from 'Validate Message' is shown to the user.
• If 'Validate Message' is blank, a default error message is displayed.

Usage Guidance

• Use this property to enforce business rules, value ranges, cross-field dependencies, or custom logic.
• The expression can reference other fields in the same Data Model or Data Section.
• Supports all VB.NET operators, functions, and syntax available in Grooper expressions.

Examples

• Require a value between 1 and 100:
  (Value >= 1) And (Value <= 100)

• Ensure a date is not in the future:
  Invoice_Date <= DateTime.Today

• Require a total to match the sum of line items:
  Total = Line_Items.SumOf("Line Total")

• Disallow special characters:
  Not Value.Contains("~")

Notes

• The expression must return a Boolean value (true or false).
• If the expression fails to evaluate, the field is set to an error state with a generic error message.
• For conditional required logic, use the 'Is Required' property instead.

For more information, see the documentation for 'Validate Message' and Field Instance.

The Validate Message property lets you define a custom error message for this Data Field when the 'Is Valid' expression returns false during validation.

This property accepts a VB.NET expression that evaluates to a string. The result is shown to users as the validation error message for the field instance.
If left blank, a default error message is displayed when validation fails.

How It Works

• The expression is only evaluated if 'Is Valid' is set and returns false.
• The result of the expression is displayed as the error message in the UI.
• If the expression fails to evaluate, a generic error message is shown instead.

Usage Guidance

• Use this property to provide clear, actionable feedback to users about why a value is invalid.
• The expression can reference other fields or values in the document, allowing for dynamic, context-aware messages.
• Supports string interpolation and formatting for including field values or calculations in the message.

Examples

• Display a static message:
  "Dates prior to 1901 are not allowed."

• Generate a dynamic message using field data:
  $"Cannot exceed Line Total of {Line_Total:c}."

• Reference another field:
  $"Value must be less than {Maximum_Allowed}."

For more information on string interpolation, see the VB.NET string interpolation documentation.

If no message is specified, a default error message will be displayed.

The IsRequired property allows you to specify a dynamic expression that determines whether a value is required for this field at runtime.

• If set, this expression takes precedence over the static 'Required' property.
• The expression is evaluated for each Field Instance during validation. If it returns true and the field is empty, the field will be set to an error state.
• Use this to implement conditional requirements, such as "required only if another field has a certain value."
• If both 'Required' and 'IsRequired' are unset or false, the field is considered optional.

How it works:
During validation, if the field is empty and 'IsRequired' is set, the expression is evaluated in the context of the current instance.
If the result is true, the field is marked as required and an error is shown if no value is present.

Example Expressions:

• Document_Type = \"Invoice\"
  (Field is required only for invoices.)
• Amount > 0
  (Field is required only if the amount is greater than zero.)

The FieldValueLexicon class provides a managed list of valid or suggested values for a Data Field, supporting both static and dynamic sources.

Overview

Use this object to define a set of allowed or recommended values for a field, such as dropdown choices, picklists, or lookup results.
The list can be populated from local entries, referenced Lexicons, or dynamically from external data sources using lookups.

Key Features

• Static Entries: Add values directly or reference other Lexicons to build a list of choices.
• Dynamic Lookup: Enable 'Include Lookup Results' to populate the list from external data sources at runtime.
• Display Options: Use 'Value Interpretation' to control how value/description pairs are presented to users (e.g., as display values or tooltips).
• Integration: Assign a FieldValueLexicon to the 'List Values' property of a Data Field to enforce or suggest valid entries.

Configuration Guidance

• Add or import entries to define the set of valid values for your field.
• Enable 'Include Lookup Results' to supplement or replace static entries with values from a database or other external source.
• Adjust 'Value Interpretation' to control whether the value component is used for display, as a description, or ignored.

Example Use Cases

• State/Province Field: Reference a Lexicon of valid states to restrict input to known values.
• Vendor Field: Enable lookup results to provide a list of vendors from an external system.
• Reason Codes: Use value/description pairs to show user-friendly labels with additional context in tooltips.

For best results, configure the entries and options to match the data validation and user experience requirements of your field.

The Restrict To List property enforces that only values present in the field's List Values (or defined choices) are accepted for this Data Field.

When enabled:

• Users can only select or enter values that match an entry in the associated Field Value Lexicon or the field's defined choices.
• Free-form typing or entry of values not in the list is not permitted in the UI.
• During extraction and validation, any value not found in the list will result in a validation error.
• This property is commonly used for dropdowns, picklists, or fields with a controlled vocabulary (e.g., state codes, status values, reason codes).

When disabled:

• Users may enter any value, but suggestions or autocomplete may still be provided from the list.
• Validation will not restrict input to the list, but other validation rules may still apply.

Usage Guidance

• Enable for fields where only a specific set of values is valid or allowed.
• Use in combination with the List Values property to define the allowed entries.
• For open-ended fields (such as comments or names), leave this property disabled.

Example Scenarios

• Restricting a "State" field to valid US state abbreviations.
• Limiting a "Status" field to "Active", "Inactive", or "Pending".

Notes

• This property is only available for fields configured as a choice or with a non-empty List Values.
• If the field's Value Type is itself a choice type, this property is not shown (the restriction is always enforced).
• The list of allowed values is managed via the List Values property or the field's value type definition.

For more information, see the documentation for 'List Values' and Field Value Lexicon.