Lookup Lists
A lookup list is a named set of values that fills a dropdown field in a custom field template. Examples include a list of equipment to inspect, project codes, or constrained options for AI extraction such as yes / no / unsure. A lookup list takes its values from a virtual view, a query built in the Query Builder, so the values can come from a register, from documents or from any other data the Query Builder can read, and can change as that data changes. The list can also narrow itself to the values that fit what has already been entered in other fields of the same form.
Who configures this
Users with access to the New module. The Lookup List Builder is accessible from New > Custom Fields & Configuration > Lookup List Builder.
How a lookup list works
| Part | What it does |
|---|---|
| Virtual view | The query the list reads. It returns one row for each choice, with two columns: Key and Value. |
| Key | What is stored in the field when a choice is picked. |
| Value | What the user sees in the dropdown. |
| Other fields of the form | The view can use what has been typed in other fields as filters. Each field's name, in lower case with an underscore for a space, is the name of a runtime input of the view: a field called Site supplies a runtime input called site. While the field is empty the filter is left out and the list is not narrowed. |
For example, a Grid Link register of equipment has the columns Asset Name, Asset Tag and Site. A virtual view over it returns Asset Tag as Key and Asset Name as Value, and keeps only the rows whose Site matches the runtime input site. A lookup list built on that view fills an Equipment dropdown, and once the user has entered a Site the dropdown offers only that site's equipment.
Before you start
- Build the virtual view in the Query Builder first, and name its two columns Key and Value. See Query Builder.
- If the values come from a register, create and fill the register first. See Manage Registers.
- To narrow the list by another field, give the view a filter that reads the runtime input named after that field.
Lookup List List panel
The Lookup List List panel shows every lookup list in the database. It is opened from New > Custom Fields & Configuration > Lookup List Builder.
Lookup List List panel
| Control | Description |
|---|---|
| Create Lookup List | Opens the Manage Lookup List editor to configure a new lookup list. |
| A list's card | Opens that list in the Manage Lookup List editor. |
Manage Lookup List editor
The Manage Lookup List editor opens when creating a new lookup list or selecting an existing one from the panel.
Manage Lookup List editor
| Field | Description |
|---|---|
| List Name | The name of the lookup list. It is the name shown when the list is assigned to a field. |
| Virtual View | The query the list reads. Choose the view that returns Key and Value. A list always takes its values from a virtual view. |
| Custom Field Test Template | Optional. Choose a template to show its form on the left, so the view can be tried with values typed into that form's fields (see below). It does not become part of the list. |
| Reload List | Runs the view and shows its rows in the grid, as Key and Value. |
| Row Count | The number of rows loaded. |
| Save Changes | Saves the lookup list. |
Trying the list with values from a form
Choose a template in Custom Field Test Template to show its fields. Type a value into a field, for example Site, and click Reload List: the grid shows only the rows the view returns for that value, which is what a user will be offered once that field holds the value.
The list narrowed by a value typed in the test form
How to create a lookup list
| Step | Description |
|---|---|
| 1 | If the values come from a register, create the register template and add its rows. See Manage Registers. |
| 2 | In the Query Builder, build a virtual view that returns the columns Key and Value, and, if the list is to depend on another field, a filter on the runtime input named after that field. See Query Builder. |
| 3 | Navigate to New > Custom Fields & Configuration > Lookup List Builder and click Create Lookup List. |
| 4 | Enter a List Name and choose the Virtual View. |
| 5 | Click Reload List to confirm the values appear, then click Save Changes. The list is now in the panel. |
Example: creating a lookup list
How to use a lookup list in a field
A lookup list is used by a LookupList field (one value) or a LookupListMulti field (several) of a custom field template.
| Step | Description |
|---|---|
| 1 | Open the template in New > Custom Fields & Configuration > Custom Fields, or create one. See Custom Field Templates. |
| 2 | Add a field and set its Field Type to LookupList or LookupListMulti. Expand the field. |
| 3 | In Lookup List, choose the list. Only saved lists are offered. |
| 4 | Choose Refetch behavior, which decides when the dropdown reads its list again as the form changes: All changes (the default), Selected fields (then Refetch on field changes names the fields) or None. |
| 5 | Click Save Template. Make sure the template's Allowed Document Types include the document types that should show it. |
A LookupList field in the template editor
On a document, the field is a dropdown. It shows each choice's Value, and stores the choice's Key. The first choice, (empty), clears the field. When the view filters on another field, the dropdown reads its list again as that field changes, so it offers only the values that fit.
The dropdown on a document, offering only the equipment of the site entered
Example: giving a field its lookup list and picking a value on a document
Troubleshooting
| Risk | Detail |
|---|---|
| No values appear after clicking Reload List | The view returned no rows. Check the register or the data the view reads, and the view's filters. If a test form is open, a value typed in it can narrow the list to nothing. |
| Rows appear but Key and Value are empty | The view's columns are not named Key and Value. Rename them in the Query Builder. |
| The dropdown on a document offers nothing | The list returned no rows for the values already entered in the form. Clear a field that the view filters on, or check that rows exist for that value. |
| Reload List says to choose a virtual view | The list has no virtual view yet. Choose one in Virtual View. |
| Lookup list not offered in a field | The lookup list must be saved before it can be chosen in Lookup List. |
| The template does not show on a document | Its Allowed Document Types must include the document's type. |
Related configuration
- Custom Fields overview — introduction to the custom fields configuration sequence
- Custom Field Templates — add a LookupList or LookupListMulti field
- Manage Registers — hold the rows a list can read
- Query Builder — build the virtual view the list reads