List Values (Data Field/Data Column Property)

This article is about the current version of Grooper.

Note that some content may still need to be updated.

2025

You may download the ZIP(s) below and upload it into your own Grooper environment (version 2025). The first contains one or more Batches of sample documents. The second contains one or more Projects with resources used in examples throughout this article.

About

"List Values" is a set of configurable properties for {DataFieldIcon}} Data Field and {DataColumnIcon}} Data Columns. When enabled and configured, List Values alters how users interact with Data Field input boxes and Data Column cell input boxes in a Data Viewer. It allows Grooper designers to set a list of values users can pick from a dropdown selection. Instead of a "free type" input, it users can pick from the list when reviewing the field.

The items in the selection list can be generated in one of three ways (or a combination of the three):

A local list
A referenced Lexicon
A list generated by a lookup (such as a Database Lookup or an XML Lookup)

The selection list can be "permissive" or "restrictive".

Permissive lists are the default behavior.
- Permissive lists lets users type in values that are not present in the selection list.
- Permissive lists will accept values collected by the Data Field's Value Extractor that are not present in the selection list.
Restrictive lists are enabled by enabling the "Restrict to List" property.
- Restrictive lists prevent users from typing anything in the input box. They can only select an item from the selection list.
- Restrictive lists will ignore values returned by the Data Field's Value Extractor if it is not present in the selection list.

Benefits

List Values assist users reviewing data collected by Extract in a Data Viewer.

They speed up data entry.
- It's a lot quicker to pick something from a list than type something in box.
- In the case of permissive lists, it gives users quicker access to commonly input values.
They cut down on errors.
- Users will not mistype something if they don't have to type it.
- In the case of restrictive lists, this will prevent users from entering an invalid value.

Basic functionality

Local Entries lists

Put simply, "List Values" are a list of values users can select when editing a field. The easiest way to do this is by editing the List Values "Local Entries" property. This will add a list of selection values local to the specific Data Field or Data Column.

Editing the Local Entries list is good for Data Fields that have a limited set of possible answers.
Data Fields used to collect OMR values is a common use case. The Local Entries list will have one entry for each checkbox label.
Example: A "Marital Status" field with options for "Single", "Married", "Divorced" and "Widowed".

To edit a Data Field or Data Column's Local Entries list:

Select the Data Field/Data Column in the node tree.
Locate the "List Values" property near the bottom of the property grid and expand it.
Open the "Local Entries" editor (Press the "..." button).
Enter each item in the selection list. New entries are separated by new lines in the list.
- Example list for a "Marital Status" field:

Single
Married
Divorced
Widowed

Press "OK" when finished to exit the Local Entries editor.
Press the "Save" button to save changes to the Data Field or Data Column.

Referenced Lexicons

If you have a larger list of selection values, or a list that is used by other nodes in Project, you should consider referencing a dictionary Lexicon when configuring List Values.

Lexicons are a type of node that can be added to the Grooper node tree. They store list entries and can be referenced throughout Grooper for a variety of purposes.
Lexicons are referenced by List Values using the "Included Lexicons" editor.
Example: A Lexicon that contains entries for US states could be used for a "State" Data Field.
- Furthermore, because it is its own node in the node tree, the Lexicon could also be referenced by a Data Type extractor that needs to match state names on a document.

To edit a Data Field or Data Column's Included Lexicons:

Select the Data Field/Data Column in the node tree.
Locate the "List Values" property near the bottom of the property grid and expand it.
Open the "Included Lexicons" editor (Press the "..." button).
- This will bring up a reference editor. You will be able to select Lexicon nodes in the Content Model's Local Resources folder (if present), the Project, and any referenced Projects (if present).
Select one or more Lexicons from the editor (check the box next to their name).
Press "OK" when finished to exit the Included Lexicons editor.
Press the "Save" button to save changes to the Data Field or Data Column.

Advanced functionality

Include Lookup Results: Using a lookup to populate the list

Example "County" list when "State" is "Delaware".

Example "County" list when "State" is "Hawaii".

When the "Include Lookup Results" option is enabled, the field will use the results of a lookup (such as XML Lookup) to generate the selection list.

This is helpful for use cases where the possible entry values for Field B change based on Field A's value.
Example: A "State" lookup field could be used to generate list values for a "County" field using this mechanism.

⚠

BE AWARE: Set the Lookup Specification's "Conflict Disposition" to "Ignore"

The "Conflict Disposition" determines what happens when the Lookup Specification returns multiple hits (multiple rows for Database Lookup, multiple records for XML Lookup or Web Service Lookup, or multiple lines for Lexicon Lookup).

You must set the Lookup Specification's "Conflict Disposition" to "Ignore" in order to use a lookup to generate a selection list for a Data Field/Data Column.
In normal lookups (for field population/validation), Grooper is designed to alert you if the lookup produces multiple hits.
However, in this case, we want to ignore that warning to include all results in the selection list.

Example "Include Lookup Results" setup using an XML Lookup

To use XML Lookup to generate a field's list values:

Drag the XML file to the Project (or a folder in the Project).
Select the Data Element you want to add XML Lookup to.
- Commonly lookups are added the Data Model. However, lookups may be added to Data Sections and Data Tables as well.
  - If added to the Data Model, XML Lookup will execute once for the document instance.
  - If added to a Data Section, XML Lookup will execute for each section instance.
  - If added to a Data Table, XML Lookup will execute for each row instance.
Open the "Lookups" editor (Press the "..." button).
Press the "Add" button and select "XML Lookup".
Using the "Source" button, select the XML file you added to the Project in Step 1.
Open the "Record Selector" editor (Press the "..." button).
Enter an XPath expression to select an XML node from the source XML file.
- The Record Selector is crucial to XML Lookup. The lookup will fail if no record is selected.
- Use field variables (%FieldName) to insert "lookup fields".
- The lookup field(s) value will be inserted into the XPath when XML Lookup runs.
- Example: //state[@name='%State']/counties/county would select <county> XML nodes in a hierarchy of <state><counties><county> nodes where the <state> node's name attribute is the Grooper extracted value for a "State" Data Field.
Open the "Value Selectors" editor (Press the "..." button).
Press the "Add" button to add a new Value Selector.
In the "Path" editor, enter an XML selector that selects an attribute or child XML element whose value you want to collect. When XML Lookup runs, the Value Selector's "target field" will be populated with the selected attribute or element's text.
- Example: @name would select an XML attribute named "name".
- In cases where the Record Selector selects XML elements whose inner text you want to use for List Values, enter the dot expression (.) to select the element's text.
Open the "Target Field" dropdown and select the corresponding Data Field in the Data Model. When XML Lookup runs, the Data Field you select will be populated with the attribute or element's text selected by the Value Selector's Path.
- Example: "County" Data Field
- Most typically, one XML Lookup will be used to generate one Data Field's list. This means you'll only need a single Value Selector. However, you could add multiple Value Selectors if multiple fields selection lists change depended on the lookup field's (or fields') value(s).
Press "OK" when finished to exit the Value Selectors editor.
Set the "Conflict Disposition" to "Ignore".
- The selection list will not be generated if not set to "Ignore". Multiple lookup hits are what we want in this case. Telling Grooper to "ignore" the conflict will allow all lookup hits to be used to populate the list values.
When finished configuring the XML Lookup, press "OK" to exit the Lookups editor.
Save changes to the Data Element.
Navigate to the target Data Field/Data Column selected in step 11.
At the bottom of the property grid, expand the "List Values" settings.
Enable "Include Lookup Results" by changing it to "True".

Value Interpretation

The "Value Interpretation" property determines how lookup style Lexicons behave in the Data Viewer.

Lookup Lexicons list entries as key-value pairs separated by an equals sign (i.e. key=value)
The Value Interpretation mode will determine how the Data Viewer interface renders the list.
- None - Users will be shown the "key" entries in the selection list.
- DisplayValue - Users will be shown the "value" entries in the selection list.
  - Be aware this will affect the Data Field's value too. The Data Field will record the "value" component of the key-value entry.
- Remarks - Users are shown the "key" entries in the selection list, and a "Search List Value" button will appear next to the Data Field.
  - The "Search List Value" button will open a window to search for items in the selection list.
  - Furthermore, the "value" component of the key-value entries show up as description remarks. This is helpful to give your users more information about the values they are selecting from the list.

Example

In this example, the following is added to the "Local Entries":

S=Single
M=Married
D=Divorced
W=Widowed

Depending on the "Value Interpretation" mode, the user's experience will differ.

Value Interpretation: None

The "key" component of the key-value list entries is selectable.

Value Interpretation: DisplayValue

The "value" component of the key-value list entries is selectable.

Value Interpretation: Remarks

A "Search List Values" button appears.

Pressing this button brings up a search interface.

Notice the "value" component of the key-value list entries are in the "Remarks" column. This acts as a description for the value the user selects (which is the "key" component of the key-value entry in the list).

Other features

Restrict to List

While technically not a "List Values" setting, the "Restrict to List" property is only used in conjunction with List Values. Enabling "Restrict to List" will only allow values from the selection list to be selected (whether a local list, referenced Lexicon or list populated by a lookup).

This can help prevent data entry errors.
If a user only has a limited set of values they can choose from, they cannot enter an invalid value not present in the List Values.
The Restrict to List feature is not appropriate for selection fields that have an "Other" option. This will prevent users from free typing a value.

To enable the "Restrict to List" property:

Select the Data Field or Data Column in the node tree.
Configure "List Values" if not already done.
- The "Restrict to List" property will not appear until List Values has been configured and is either populating a list from Local Entries, Included Lexicons or Include Lookup Results.
Enable "Restrict to List" by turning it to "True".