Custom Field Templates
Custom field templates define the structure of the metadata captured on documents. Each template is a collection of field entries — individual columns of data such as dates, reference numbers, line items, or lookup values. Templates are typed (Grid, Grid Link, or Filter) and are offered on the documents of the document types they allow.
Before creating a template, identify the required field names, field types, and whether the template needs to support multiple entries (one-to-many) or shared linked entries (many-to-many). See Custom Field Relationships for guidance on template types.
Who configures this
Users with the Manage Document Custom Fields permission. The Custom Fields area is accessible from New > Custom Fields & Configuration > Custom Fields.
Before you start
- Determine the template type (Grid, Grid Link, or Filter) before creating the template. Template type affects how data is stored and displayed.
- Identify all required field names and field types before building the template. Changing field types after data has been captured is validated against existing data and may be rejected.
- If the template will use LookupList or LookupListMulti field types, build the lookup lists first. See Lookup Lists.
- Decide which document types should show the template. A template is shown on a document only when the document's type is in the template's Allowed Document Types; a template with none is shown on no document.
Edit Custom Fields panel
The Edit Custom Fields panel lists the custom field templates in the database. It is opened from New > Custom Fields & Configuration > Custom Fields.
'Edit Custom Fields' panel, searched for a template
| Control | Description |
|---|---|
| Create New Template | Opens the template editor to configure a new custom field template. |
| View inactive | When checked, inactive templates are included in the list. By default, only active templates are shown. |
| Search templates | Filters the template list by template name. |
| Add Group | Creates a group at the top level of the list. Templates can then be moved into groups. See Organising Templates into Groups. |
'Edit Custom Fields' panel with a template group
Each template card in the list shows:
| Element | Description |
|---|---|
| Template name | The name of the template. Click the card to open the template editor. |
| Type badge | The template type: Grid, GridLink or Filter. |
| Date | The date the template was created. |
| Deactivate / Activate | Deactivates or activates the template (see below). |
Deactivate and activate a template
Deactivate takes the template out of use without deleting it or its data. An inactive template is hidden from the default list of templates, so the rest of the Portal does not offer it, and it is shown in the Edit Custom Fields panel, marked INACTIVE, only while View inactive is checked. Activate puts it back.
An inactive template
Template editor
Clicking Create New Template opens the Create New Custom Field Template editor. Clicking an existing template card opens the Edit Custom Field Template editor. Both use the same layout: a settings sidebar on the left and the field entries on the right.
Template editor
Toolbar
The toolbar at the top right of the editor contains the following controls:
| Control | Description |
|---|---|
| Help | Starts a guided tour of the editor. |
| Auto Import Columns | Creates field entries from the columns of an Excel file. See How to import field columns from Excel. |
| Propagate Changes to Views (wrench icon) | Shown for a saved template. Asks you to confirm, then updates the views built on the template, so that they pick up the template's current fields. The editor reports View propagation completed. when it is done. See How to propagate a template's changes to its views. |
| Delete Custom Field Template | Deletes the template. Shown for a saved template. Templates that have existing data associated with them should be deactivated rather than deleted. |
| Export Template Definition | Downloads the template's structure as a file named <template name>_template.json, for use when importing into another template. The file does not include the template's Allowed Document Types. |
| Import Template Definition | Fills the editor with the structure from a definition file exported earlier. Nothing is saved until Save Template. |
A saved Grid Link template also has two tabs above its field entries, Fields and Row security, for users with the Group and User Admin permission. Row security grants the register's rows to users and groups. See Register row security.
Custom Field Information
| Field | Description |
|---|---|
| Template Name | The name of the template. Required — the template cannot be saved without a name, and a name another template already uses is refused. |
| Template Type | Sets the type of template: Grid (one-to-one or one-to-many), Grid Link (many-to-many), or Filter. See Custom Field Relationships. |
| Display Mode | Sets how the template is presented when capturing data: Grid (a table) or Form (a series of fields). |
| Allow Multiple Entries | Lets users add more than one entry for the template. Shown for Grid templates only. |
AI Settings
| Field | Description |
|---|---|
| AI Extraction Prompt | A prompt directing AI extraction for the template as a whole. Describes the extraction task and any relevant instructions. Maximum 10,000 characters. |
| Process Pages Independently | When enabled, each page of the document is sent to the AI separately rather than as a single combined prompt. Shown for Grid templates only. |
| Process As Image | When enabled, each page is passed as an image alongside the page text during AI extraction. |
| Auto Extract On Upload | Marks the template to be read by AI when a document is uploaded. See Auto Extract On Upload. |
| Use Only Extracted Tables | When enabled, AI extraction draws only from tabular data extracted from the document. Useful for structured documents such as invoices. |
Auto Extract On Upload
Auto Extract On Upload works as part of the workspace's Default Upload Extraction. The template is read when a document is uploaded while Default Upload Extraction is switched on (at least one standard field, OCR or image embeddings is enabled there). The template is read only for documents of its Allowed Document Types, and not for a document that already has rows for the template. Set up Default Upload Extraction first: see Default Upload Extraction.
Access Options
| Field | Description |
|---|---|
| Allowed Document Types | The document types whose documents show this template in the Custom Fields section of Document Details. Use Select All or Clear All to manage the selection. A template with no document types is shown on no document. |
AI Settings and Access Options
Advanced Options
These options are for use with support from Docwize staff.
| Field | Description |
|---|---|
| View Name | An alternative view for this template. |
| Column Name Renderer | A Query Builder view that supplies the template's column names. |
| Limit Rows By Query | Grid Link templates only. Selects a saved Query Builder view to restrict which rows are offered when linking entries to the document being edited. Leave blank to offer every row. |
Adding field entries
Field entries define the individual columns of data captured by the template. The add-entry row at the top of the field entries area contains:
| Control | Description |
|---|---|
| Field Name | The name of the field entry (for example: Invoice Date, PO Number, Line Amount). |
| AI Extraction Notes | Instructions for the AI to follow when extracting data into this specific field. |
| Field Type | The data type for this field. See Field types below. |
| Add Field Column (+) | Adds the configured field entry to the template. |
Field types
The Field Type list offers the types below. Next to Field Type in an expanded field entry, the Field Type Guide (question-mark icon) opens a guide that describes each type with an example, opened at the type of the field you are on.
Field Type Guide
| Field Type | Description |
|---|---|
| Text | Short single-line text, such as names, codes and titles. |
| FreeText | Multi-line plain text, stored as typed. |
| Notes | Rich-text formatted notes (bold, lists, inline formatting). |
| Notepad | Like Notes, and also keeps a plain-text copy of the same text. |
| Numeric | Decimal number value. |
| WholeNumber | Integer (whole number) value. |
| Currency | Monetary value. The option Currency symbol (display only) shows a symbol before the amount; the stored value stays a plain number. |
| Date | Date value, chosen with a calendar. |
| DateTime | Date and time value. |
| Checkbox | True/false toggle. |
| URL | A web address, displayed as a clickable hyperlink. |
| Signature | Digital signature capture. |
| Image | An image file (PNG, JPEG or another image type, up to 5 MB), shown as a thumbnail with Replace and Remove. Clicking the thumbnail opens the image full screen. |
| GeoLocation | Geographic location value (latitude and longitude). |
| Hidden | Stores data but is not displayed to users when the template is viewed. |
| Combo | An editable dropdown: the user can type a value or pick one. |
| MultiValue | Allows several free-text values to be entered for one field. |
| LookupList | Single-select dropdown populated from a lookup list. See Lookup Lists. |
| LookupListMulti | Multi-select dropdown populated from a lookup list. |
| ContactsLookup | Lookup value sourced from the Contacts module. |
| CustomDataLookup | A dropdown powered by a custom query or data source. List Name (if applicable) names the source. |
| VirtualCustomFieldLookup | Resolves a value through a virtual interface query when the field is shown. |
| Lookup | Fills in a value by matching a key against a source template. Set Source Dictionary (the template), Value Field (return), Key Field (match on) and Match Against (a document field or a field of this template). |
| Calculated | A read-only field computed from other columns on the same row. |
| MatrixCalculation | A read-only result worked out from two other fields of the template, by a matrix you define in the editor. See Defining the matrix of a MatrixCalculation field. |
| LinkedColumn | Links this column to a column in the same or a different template. The target template and column are selected when the field is configured. |
| CustomFieldReference | Links this column to rows in another custom field template, enabling related data from different templates to be grouped and viewed together on a document. Choose the Referenced Template. |
| GridLinkReference | Creates a relational reference to a row of a Grid Link register. Choose the Referenced Template; rows are linked by row ID unless Custom Join Columns pair a Source Column with a Target Column. Tick Display Value on the register's field to show a human-readable value (for example an employee name) rather than an internal identifier. |
| SequentialRef | Generates a unique, incrementing sequential reference code for each record (for example, INV-0001). The format is set on the field, for example INV-$SEQ4$. For document-level reference numbers combining static text, dynamic metadata fields, and an auto-incrementing sequence, see Reference Number Template instead. |
Expanded field entry options
Each field entry that has been added to the template can be expanded by clicking the chevron (∧) on the right of the entry. The following options are available:
An expanded field entry
| Field / Control | Description |
|---|---|
| ⠿ (drag handle) | Reorders the field entry by dragging. Changes the order fields appear in the template. |
| ∧ / ∨ | Expands or collapses the field entry options. |
| Delete (bin icon) | Deletes the field entry from the template. |
| Field Name | The name of this field entry. Editable after the field has been added. |
| Field Type | The data type. Changing the type on a field that already contains data is validated against existing data before the change is applied. |
| Caption (Optional) | An optional label displayed alongside the field when the template is in use. |
| AI Extraction Notes | Extraction instructions specific to this field. Maximum 5,000 characters. |
| Required | When enabled, this field must be completed before the document or record can be saved. |
| Load On Demand | When enabled, lookup values for this field are loaded only when the field is opened, rather than at page load. |
| Extraction Page Identifier | When enabled, the field records the page number from which AI extraction occurred. Relevant when extracting data on a per-page basis. |
| Template Section | Optional. Assigns the field to a named section within the template, useful when organising fields in record layouts. |
| Display Value | Grid Link templates only. Marks the field as the value that names a row wherever rows are listed or picked. |
| Lookup List, Refetch behavior | LookupList and LookupListMulti fields only. See Lookup Lists. |
| Validation rules | The rules a value must pass. See below. |
| Matrix | MatrixCalculation fields only. The two fields the result is worked out from, and the rows that decide it. See Defining the matrix of a MatrixCalculation field. |
Further options appear for some field types, as the table of field types above names them.
Validation rules
A field entry of most types has a Validation rules panel. The panel rejects invalid values as they are entered and when the row is saved. Which rules it offers depends on the type:
| Field types | Rules |
|---|---|
| Numeric, WholeNumber, Currency | Minimum value, Maximum value, Must be a multiple of, Maximum decimal places, and three tick boxes: Allow zero, Allow negative values and Whole numbers only (no decimals). |
| Text, FreeText, Notes, Notepad, URL, GeoLocation | Minimum length (characters), Maximum length (characters), a Format preset (email address, web URL, letters and numbers only, letters only, digits only, no spaces), a Custom pattern (regex) and Trim spaces before validating and saving. |
| Date, DateTime | Earliest allowed date and Latest allowed date (fixed), Earliest - days from entry and Latest - days from entry (relative, In the past or In the future; for example "Earliest 7, In the past" allows dates up to a week old; setting one clears the fixed date for that bound, and the other way round), and the toggles Reject dates in the past and Reject dates in the future. |
| MultiValue, LookupListMulti | Minimum selections and Maximum selections. |
| LookupList, Combo, ContactsLookup, CustomDataLookup, Lookup, VirtualCustomFieldLookup | The custom error message only. |
Every panel also has Custom error message (optional), shown to users in place of the default when a value fails any rule, and a box to try a value. Type a value into the box and the panel says whether it Passes the current rules, or Would be rejected and why.
Validation rules, with a value tried against them
A value already saved before a time-relative rule was added, or before time passed, is not retroactively rejected just because the rule's boundary has since moved past it.
Defining the matrix of a MatrixCalculation field
A MatrixCalculation field shows a result that is worked out from two other fields of the same template, for example a risk rating from Likelihood and Impact. You define how in the Matrix section of the expanded field entry.
The Matrix section of a MatrixCalculation field
| Control | Description |
|---|---|
| Axis A field, Axis B field | The two fields the result is worked out from. Each list offers the other fields of the template, and the two must be different fields. |
| Matrix rows, Add | Adds a row. Add one row for each combination of the two fields. |
| Operator | Chosen separately for each of the two fields: Equals, where the value must be exactly the condition, or In. |
| Condition (labelled with the field's name) | What the field's value is compared with. In takes a range of whole numbers such as 1-3, or a list such as Low,Medium. A range must run from the lower number to the higher. |
| Result | The value the field shows when the row matches. |
| Result colour | The colour behind the value on a document. A new row starts white, which shows no colour. |
| Delete (bin icon) | Removes the row. |
The field shows the result of the first row whose two conditions both match, so put the more specific rows first. When no row matches, or either of the two fields is empty, the field is empty.
Save Template saves the template and then its matrix. A MatrixCalculation field needs at least one row and two different fields of the template as its axes: the editor names the field that needs them and does not save the template until it has them.
On a document that shows the template, the field is shown in a box of the matching row's colour. The information icon beside the field shows the whole matrix as a table.
A MatrixCalculation field on a document
How to create a custom field template
| Step | Description |
|---|---|
| 1 | Navigate to New > Custom Fields & Configuration > Custom Fields. |
| 2 | Click Create New Template. |
| 3 | Enter a Template Name and select the Template Type and Display Mode. Enable Allow Multiple Entries if the template requires multiple rows per document (Grid templates). |
| 4 | Configure AI Settings and Access Options as required. Choose the Allowed Document Types that should show the template. |
| 5 | In the field entry row, enter a Field Name, add AI Extraction Notes if relevant, and select the Field Type. Click Add Field Column (+) to add the field to the template. |
| 6 | Repeat step 5 for each required field entry. Use the drag handle to reorder entries as needed. Expand an entry to set its caption, Required, validation rules and other options. |
| 7 | Click Save Template. The editor closes when the template has been saved. |
Example: creating a Grid Link custom field template
How to import field columns from Excel
Auto Import Columns builds field entries from a spreadsheet: the header row names the columns and the first row of data under it decides each column's type. It reads an Excel file, not an exported template definition (use Import Template Definition for that).
| Step | Description |
|---|---|
| 1 | In the template editor, click Auto Import Columns. |
| 2 | In Custom Field Auto Importer, click Upload Excel File. |
| 3 | In Excel Data Transformer, click the upload area (or drag and drop) and choose the file. Choose the sheet with the tabs at the bottom if there are several. |
| 4 | Click the pin icon at the start of the header row, then click Finish. |
| 5 | Check the Detected Columns. Change a column's type (Text, Whole Number, Decimal Number, Currency or Date/Time) or remove a column you do not want. |
| 6 | Choose the Import Mode: Add New Columns Only (the default: columns the template already has are skipped), Add New & Update Types, or Replace All (Destructive), which removes every column the template has first. |
| 7 | Click Import Columns. The columns are added to the editor; click Save Template to keep them. |
Detected Columns and the import mode
Example: importing field columns from an Excel file
How to define a matrix
| Step | Description |
|---|---|
| 1 | Open the template in New > Custom Fields & Configuration > Custom Fields, or click Create New Template. Make sure it has the two fields the result is to be worked out from, for example two WholeNumber fields. |
| 2 | Add a field with the Field Type MatrixCalculation and click the chevron (∧) to expand it. |
| 3 | In Matrix, choose the Axis A field and the Axis B field. |
| 4 | Click Add under Matrix rows for each combination. Choose the Operator for each field, enter the conditions, the Result, and the Result colour. |
| 5 | Click Save Template. The matrix is saved after the template. |
Example: defining the matrix of a MatrixCalculation field
How to propagate a template's changes to its views
Propagating updates the views built on a template, so that they pick up the template's current fields.
| Step | Description |
|---|---|
| 1 | In New > Custom Fields & Configuration > Custom Fields, click the template's card to open it. |
| 2 | Click Propagate Changes to Views (wrench icon). |
| 3 | Read the confirmation and click Propagate Changes. Cancel closes it without changing anything. |
| 4 | Wait for View propagation completed. |
The confirmation before views are rebuilt
Example: propagating a template's changes to its views
Troubleshooting
| Risk | Detail |
|---|---|
| Template cannot be saved | A template name is required, and it must not be the name of another template. The editor says so beside Template Name. A MatrixCalculation field also needs at least one matrix row and two different fields of the template as its axes. |
| Field type change rejected | Changing the type of a field that already contains data is validated against existing data. If existing data is incompatible with the new type, the change is not applied. |
| Template not appearing on documents | The template must be active, and its Allowed Document Types must include the document's type. A template with no allowed types is shown on no document. |
| Inactive template not visible | Inactive templates are hidden by default. Check View inactive in the Edit Custom Fields panel to confirm the template exists but is inactive, and click Activate. |
| LookupList field shows empty dropdown | The lookup list referenced by the field must be saved and return values for what has been entered in the form. See Lookup Lists. |
| A template is not read on upload | Auto Extract On Upload works while Default Upload Extraction is on, and for the template's Allowed Document Types. See Default Upload Extraction. |
Related configuration
- Custom Fields overview — introduction to the custom fields configuration sequence
- Custom Field Relationships — how template types relate to documents
- Lookup Lists — configure lookup lists used with LookupList and LookupListMulti field types
- Manage Registers — view and populate Grid Link templates
- Default Upload Extraction — the tenant setting Auto Extract On Upload depends on