How to create a form template?
A form template is created from the Form Templates page. Click the + (add) button at the top right, enter a Name (required) and an optional Description, then click Save. You are taken directly to the template's detail page.
A newly created template automatically starts with an empty Draft version (v1). This first version is where you design the form schema before publishing it.
The form template detail page
The form template detail page is where you manage a template and all of its versions. It is organized into three areas:
- Header — shows the template name and provides the Create version button and the action menu (three-dot icon).
- Version navigation bar — a row of version chips, each labelled with its number and status (Draft, Published, or Archived). Click a chip to switch to that version.
- Version content card — displays the selected version's schema (the list of fields) and its version-specific actions.
- Sidebar — shows the template description, its tags, and creation information.
How to edit the template name and description?
The template name and description are editable inline at any time, regardless of the status of its versions. Click on the name in the header, or on the description in the sidebar, type the new text, and click away to save.
The name and description belong to the template as a whole — they are shared across all of its versions. The schema (the fields) is what differs from one version to another.
How to design the form schema?
The schema of a form template is the ordered list of fields that the form will contain. You design the schema by editing a Draft version — published and archived versions are read-only and cannot be modified.
On a draft version, the version content card shows a table of the current fields with their label, type, whether they are optional, their default value, and additional information. You can:
- Add a field — use the Add field button below the table.
- Edit a field — use the menu on a field row to change its configuration.
- Delete a field — use the menu on a field row; a confirmation is requested.
- Reorder fields — drag fields to change the order in which they appear in the form.
How to add a field?
Click Add field on a draft version to open the field editor dialog. For each field you define:
- Label — the human-readable name shown to the person filling in the form.
- Type — the kind of data the field accepts (see the table below).
- Optional — whether the field can be left empty. A field that is not optional must be filled in before the form can be submitted.
- Default value — an optional value pre-filled when a form is created from the template.
- Additional information — extra help text or type-specific options.
The field types are organized into a few groups. The simple types cover everyday values:
The lab-specific types let a field reference an object that exists in the data lab:
The remaining types cover structured and advanced content:
When picking a type in the field editor, you can search the type list by name to quickly find the one you need.
Click Save in the dialog to add the field to the draft. The new field appears in the schema table and can be reordered or edited afterwards.
How to add a table field?
A table field lets the form collect a repeatable set of rows, where every row has the same set of sub-fields. It is useful when a form needs to capture a variable number of similar items — for example, a list of samples, each with a mass and a volume.
To add a table field, choose the Table type in the field editor, then define the sub-fields that make up each row — each with its own label, type, and options, exactly like a top-level field. When filling in the form, the user can add and remove rows of the table.
How to add a formula field?
A formula field is a read-only field whose value is calculated automatically from an expression based on other fields in the form. The person filling in the form never types a value into it — it is recalculated every time the form is saved.
To add a formula field, choose the Formula type in the field editor and provide an expression. A formula field is always read-only and is never required when submitting a form.
Referencing fields
Inside an expression, the value of another field is referenced with a leading @ followed by the field key, for example @weight. Bare names (without @) are reserved for function names, so there is never any ambiguity — a field whose key is sum is still referenced as @sum.
@weight / (@height ** 2)
Arithmetic operators
+ - * / // (integer division) % (remainder) ** (power) ( ) (parentheses for grouping).
Comparisons and logic
== != < <= > >= for comparisons, and and or not for boolean logic.
Functions
The following functions are available. The numeric aggregate functions (sum, mean, median, min, max, count, stddev) accept either a single list of values or several individual arguments, and ignore empty values.
Aggregating a table field
From a formula field at the level containing a table field, the syntax @tableField[].subField resolves to the list of one sub-field's values across every row of that table field. Pass it to an aggregate function:
sum(@samples[].mass)
Per-row formula fields and outer references
A formula field placed inside a table field is calculated per row: there, @field refers to the sibling sub-fields in the same row. To reference a field from the level outside the table field, use a double @@:
@@factor * @mass
Examples
@price * @quantity
if(@score >= 50, "pass", "fail")
round(@total / @count, 2)
concat(@first_name, " ", @last_name)
Formula values are recalculated every time a form is saved.
Validating an expression
Next to the expression input, the validate button (the check-circle icon) checks your expression against the version's fields without leaving the field editor. It confirms that the syntax is correct and that every referenced field exists, so a mistyped field name or an unknown function is caught before you publish.
The result is shown right below the expression: a valid confirmation when the expression is correct, or an error message describing the problem otherwise. You can validate as many times as you like while adjusting the expression.
Authoring an expression with AI
Instead of writing the expression by hand, you can describe the calculation you want in plain language — and you can dictate that description using voice input. The AI generates a candidate expression, which is then validated against the version's fields exactly like a manually entered one. You can review and adjust the generated expression before saving the field.
How to test a draft version?
Before publishing, you can test a draft version to make sure the schema behaves as expected. From the draft version's menu, choose Test version.
The test dialog renders the form exactly as it would appear to someone filling it in. Enter sample values and click Test: the values are validated against the schema, formula fields are evaluated, and any errors are reported. Testing does not create a real form — it is only a preview of the schema.
How to publish a version?
A draft version is not usable to create forms until it is published. To publish, open the draft version and click Publish version, then confirm.
On publish, the schema is validated and the version is frozen — its fields can no longer be changed. The version receives a permanent version number, and from that point on, new forms can be created from it. Publishing guarantees that the schema a form relies on never changes underneath it.
How to create a new draft version?
Because published versions are frozen, you make schema changes by creating a new draft version. A template can have at most one draft version at a time.
- Create version — the button in the header creates a new, empty draft version.
- Create draft from this version — available in the menu of a published or archived version, this creates a new draft that copies the schema of that version. This is the usual way to make incremental changes: start from the previous version and adjust it.
Once you have edited the new draft, publish it to make it available. Existing forms keep using the version they were created from — they are not affected by the new version.
How to search for usage of a form template?
Before changing or removing a template, it is helpful to know where it is used. The Search usage entry in the template's action menu provides three options:
- View forms — lists all forms created from any version of this template.
- View notes — lists all notes that embed a form based on this template.
- View note templates — lists all note templates that reference this form template.
How to archive or unarchive a version?
A published version can be archived when it should no longer be used to create new forms. Open the published version and choose Archive version from its menu, then confirm.
Archiving does not affect forms that were already created from the version — they keep working normally. To make an archived version usable again, open it and choose Unarchive version from its menu.
How to delete a version?
A draft version can be deleted outright — open it and choose Delete version from its menu. This is useful to discard schema changes you no longer want.
A published version cannot be deleted; archive it instead. An archived version can only be deleted if no form was ever created from it. This protects the data lineage of existing forms.
