Survey Templates

Survey Templates define the structure and behaviour of surveys. As an administrator, you configure field groups, field types, validation rules, and conditional logic to create surveys tailored to your business needs.

Template Structure

A survey template consists of:

Survey Template
├── Name, Category, Description
├── AI Prompt (template-level guidance)
├── Unit Pronunciations (custom TTS dictionary)
├── STT Context (speech recognition vocabulary)
├── Check Items (reusable field patterns)
├── Field Groups (logical sections)
│   ├── Group settings (collapsible, repeatable, nested)
│   └── Reference images (up to 5 per group)
└── Fields (data to collect)
    ├── Field type and validation
    ├── Options and voice shortcuts
    ├── Conditional display rules
    ├── Calculated formulas
    ├── Default values
    └── Photo hints and location pins (placed by hand, never asked by voice)

Check Items (Reusable Field Patterns)

Check Items are the way to handle repeating field patterns in inspection forms and surveys. Instead of manually creating the same set of fields for each check item, you define a field pattern once and add check items that reference it. Fields are generated automatically at runtime.

When to Use Check Items

Use check items when a template has 3 or more items that each require the same set of fields. For example, a pressure vessel inspection where each component (Shell, Nozzle, Insulation) needs: Condition (select), Anomaly (text), Anomaly Class (select), and Comments (textarea).

How It Works

Define a field pattern — specify the fields that each check item will have (e.g., "Condition" select, "Comments" textarea)
Add check items — each item has a name (e.g., "Shell", "Nozzle") and references the field pattern
Fields are materialised automatically — at runtime, each check item generates one field per pattern field, following the naming convention "{Item Name} - {Field Label}" (e.g., "Shell - Condition")

Creating a Field Pattern

In the left panel, find the Field Patterns section
Click New Pattern to open the pattern editor
Enter a pattern name (e.g., "Inspection Check")
Add fields — each field defines one survey field that will be generated per check item:
- Label: Display name (e.g., "Condition")
- Key: Unique identifier, auto-generated from label (e.g., "condition")
- Type: Field type (select, text, textarea, number, etc.)
- Configure options, validation, voice labels, and AI prompts as needed
Use the {name} placeholder in AI prompts — it will be replaced with the check item name at runtime

Editing a Field Pattern

When you edit a field pattern, all check items are updated automatically. Because fields are materialised at runtime from the pattern definition, changes to options, validation, types, or any field property take effect immediately for every check item — no manual mass update step needed.

Adding Check Items

Check items can be added in two ways:

Via the AI Template Builder:

Upload a document and the AI automatically identifies repeating check items
The AI creates the field pattern and check item list from the document structure
Add or remove items by asking the AI: "Add brake light inspection" or "Remove the exhaust check"

Via the manual template builder:

Find the field pattern in the Field Patterns section
Type a name (e.g., "Shell") in the add input and click Add
Use Bulk mode to add multiple items at once (one name per line)

Requiring a Comment on Failed Items

Inspection check items usually pair a result (e.g. Acceptable / Not Acceptable) with an optional comment. By default the voice assistant skips the comment when you give a passing result, so you can breeze through acceptable items — but you often want the comment to be mandatory when an item fails.

To enforce this, open the field pattern, expand the comment sub-field, and turn on "Required when…". Add a condition such as Result equals Not Acceptable. Now:

When the result is Not Acceptable, the comment becomes required — the voice assistant asks for it and the survey can't be finalised until it's filled.
When the result is Acceptable, the comment stays optional and is skipped as before.

The rule lives on the field pattern, so it applies to every check item that uses it. The AI Template Builder also adds this automatically when it recognises a pass/fail-with-comments inspection pattern (it leaves plain Yes/No checklists alone and never overrides a rule you've set).

This is different from conditional visibility (show/hide a field) — "Required when…" controls whether a field must be filled, not whether it's shown.

Generating a Conditional Summary

For field patterns with check items, click the Summary button to auto-generate a conditional summary calculated field:

Select the trigger field (e.g., "Condition") and the condition (e.g., "is not empty")
Select the value field (e.g., "Comments") — the data to include in the summary
Choose a target group and field name
Click Generate — creates a calculated field with one entry per check item

This completes the pipeline: field pattern definition → check item list → report aggregation.

Key Benefits

Compact storage — 50 check items are stored as 50 compact rows, not 200+ individual field definitions
Automatic updates — editing the field pattern instantly updates all check items
AI-friendly — the AI Template Builder can generate and maintain large check item lists (50+ items) efficiently
Deterministic field IDs — field IDs follow the pattern ck__{item-id}__{field-key}, making data references stable and predictable

Creating a Template

Navigate to Survey Templates in the services menu
Click New Template
Enter the template name, category, and description
Add field groups to organise your survey
Add fields to each group
Configure validation and conditional logic
Save the template

Field Groups

Field groups organise related fields into logical sections. Groups appear as collapsible sections in the form view and are announced as context during voice surveys.

Groups, repeating groups and office-only fields

Group Settings

Setting	Description
Name	Display name for the section
Description	Optional helper text
Collapsible	Allow users to collapse/expand the section
Repeatable	Allow multiple instances of this section

Best Practices for Groups

Keep groups focused — aim for 3-8 fields per group
Use descriptive names — "Equipment Details" rather than "Section 1"
Order matters for voice — fields are presented in order during voice surveys; place identifying fields first
Assign all fields to groups — fields without a group appear in an "Other Fields" section

Repeatable Groups

Use repeatable groups when the count of items varies per survey — rooms in a building, equipment items to inspect, tasks completed.

Visual Overview

┌─ Room 1: Kitchen ──────────────────────────┐
│  Room Name: [Kitchen]                        │
│  Blinds Product: [Roller blind]              │
│  Fabric: [Nordic Grey]                       │
│                                              │
│  ┌─ Window 1 ─────────────────────────────┐ │
│  │  Width: [1200] mm    Height: [800] mm   │ │
│  └─────────────────────────────────────────┘ │
│  ┌─ Window 2 ─────────────────────────────┐ │
│  │  Width: [900] mm     Height: [1400] mm  │ │
│  └─────────────────────────────────────────┘ │
│  [+ Add Window]                              │
└──────────────────────────────────────────────┘

[+ Add Room]

Configuration

Setting	Description	Default
Repeatable	Enable dynamic instance creation	Off
Instance Label Template	Template like "Room {n}" — the `{n}` is replaced with the instance number	Group name + number
Label Source Fields	The fields whose values name an instance, checked in the order listed	A field named "Label", then "Name"
Allow Zero Instances	Users can skip the group entirely	On (min 0)
Maximum Instances	Limit how many can be added, from 1 to 100	50

Zero-Instance Groups (Optional Items)

Some repeatable groups represent items that may not exist in every survey:

Defects — a quality inspection may have zero defects
Issues — an equipment check may find no issues
Exceptions — a compliance audit may have no exceptions

Enable "Allow Zero Instances" for these groups. This changes the behaviour:

Voice UX — AI asks "Are there any defects?" before creating the first instance
Form UX — shows a "No [Items]" button for explicit confirmation
Display — shows "None recorded" when skipped

To require at least one instance (e.g., tasks in a task report), disable "Allow Zero Instances".

Instance Labelling

Instances are labelled automatically based on field values or the template:

Resolution order:

The first of the group's Label Source Fields that has a value
If no label source fields are chosen: the value of a field named "Label", then one named "Name"
Instance Label Template with {n} replaced (e.g., "Room 1", "Room 2")
Fallback: "Group Name 1", "Group Name 2"

Once label source fields are chosen, the "Label" and "Name" fields are no longer used unless you list them.

Best practice: Include a "Label" or "Name" field at the start of repeatable groups so surveyors can provide meaningful labels like "Kitchen" or "Master Bedroom".

Items known by a serial or tag. Put {id} in the Instance Label Template and choose the field that holds the identifier under Label Source Fields. "Bolt {id}" reads "Bolt A128" once the serial is given, and "Bolt 7" until then. If two items are given the same identifier, the value is still saved and the surveyor is told "A128 is already Bolt 1."

Voice UX for Repeatable Groups

After completing all fields in an instance, the AI asks:

"Room 1 complete. Add another room?"

Users navigate between instances by label ("go back to the kitchen"), by number ("go to room 2"), or relatively ("previous room" / "next room").

Nested Groups

Create parent-child hierarchies for complex structures:

Room → Window
Building → Floor → Room
Vehicle → Component → Inspection Point

Configuration

Create the parent group with "Repeatable" enabled
Create the child group with "Repeatable" enabled
Set the child group's Parent Group to the parent

Nesting Rules

Only repeatable groups can be parents
No circular references — a group cannot be its own parent or ancestor
One level of nesting recommended — keep hierarchies simple for usability
Child groups inherit parent context — fields know which parent instance they belong to

Voice UX for Nested Groups

The AI includes nested context in prompts:

"Kitchen, Window 2: What's the opening width?"

Example flow:

AI: "What room is this?"
You: "Kitchen"
AI: "Kitchen. What blinds product?"
You: "Roller blind"
AI: "Kitchen: Let's add the first window. Opening width?"
You: "1200 millimetres"
AI: "Opening height?"
You: "800"
AI: "Kitchen, Window 1 complete. Add another window?"
You: "No"
AI: "Kitchen complete with 1 window. Add another room?"

Batches

Use a batch for a set of like items tested together: 12 bolts, 8 fire doors, 20 rooms. A batch lets the tester work one instrument at a time. They check the markings on every bolt, then the hardness of every bolt, instead of finishing bolt 1 before starting bolt 2. The report still reads one item at a time.

When to Use a Batch

The number of items is known at the start ("batch of 24")
Swapping tools takes longer than moving to the next item
Every item gets the same tests

For items found one by one as the survey goes, such as defects, use an ordinary repeatable group.

Setting Up a Batch

A batch is a repeatable group at the top level of the template. Each test is a child group under it. Select the parent group and scroll to Batch in its settings.

Setting	What it does
Items at the start	A new survey starts with this many items, numbered from 1. The survey never asks "add another?".
Question that sets the number of items	A number field asked once per survey, such as "How many bolts in this batch?". Its answer sets the number of items. The field must sit outside any repeatable group.
Passes	Which tests are collected together across every item. Set each child group to Pass 1, Pass 2 and so on, or leave it at Not in a pass.
Pass N name	What the assistant says when the pass starts: "Pass 2, hardness".

You can set a starting number, a count question, or both. With both, the survey starts at the fixed number and the question changes it.

The number of items can't go above the group's Maximum Instances.

How Passes Work

A pass is one trip down the whole batch for one set of tests. With markings in pass 1 and hardness in pass 2, the survey asks markings for bolts 1 to 12, then hardness for bolts 1 to 12.

A group left at Not in a pass is asked last, after every pass. The builder tells you which groups these are.
The parent group's own fields appear in the list as "Bolt (its own fields: …)". Put them in Pass 1 if they include the serial or tag, so items are called by it from the start.
With no passes set, the survey asks every test for item 1 before moving to item 2, as an ordinary repeatable group does.
If the builder shows a warning under the passes, Fix the pass list repairs it.

Changing the Number of Items

When the count question is answered again during a survey:

A higher number adds empty items at the end.
A lower number removes empty items from the end.
An item that already has answers is never removed. The survey refuses the change and names the item.

What the Surveyor Sees

Voice — the assistant names the item with each question ("Bolt 7: Length?") and announces each pass. It moves to the next item by itself. See Batches in the Voice Assistant.
Web form — a batch has a By pass / By item switch. By pass shows a grid with one row per item and one column per field, and a tab for each pass.
Mobile form — By pass shows one item at a time with that pass's fields. See Batches in the Mobile App.

In the grid, Enter moves down to the next item and Shift+Enter moves up. Enter on the last item carries on to the next pass.

When one value applies to most of the batch, enter it once and choose Fill N blanks with … on that column. It fills only the items with no value. An item that already has a value keeps it.

Best Practices

Name each pass after the instrument or test — "hardness", "dimensions". The name is spoken at the start of the pass.
Ask the identifier in pass 1 — later passes can then say "Bolt A128" instead of "Bolt 7".
Keep each pass short — one to three fields per item keeps the rhythm quick.
Use the count question when batch sizes vary — a fixed number suits a template that always tests the same quantity.

Field Types

Type	Use Case	Voice Behaviour
Text	Short text (serial numbers, names)	AI asks, user speaks
Textarea	Long text (descriptions, notes)	AI asks, user speaks longer response
Number	Numeric values (measurements)	AI asks, user speaks number
Boolean	Yes/No questions	AI asks yes/no question
Select	Single choice from options	AI asks, user picks one
Multiselect	Multiple choices from options	AI asks, user picks several
Date	Date values	AI asks for date
Time	Time of day (24-hour clock)	AI asks for time, user speaks naturally
Rating	Star ratings (1-5 scale)	AI asks for rating

Two more field types are placed by hand and never asked for by voice: Signature (a signing pad) and Location pin (marking the observation on an attached drawing). See Location Pin Fields.

Any of the types in the table above can also be calculated — deriving their value from a formula instead of user input. See Calculated Fields.

Field Type Selection Guide

Need to capture...
├── A single word/phrase → text
├── A paragraph or detailed notes → textarea
├── A measurement with units → number (with unit property)
├── A yes/no answer → boolean
├── One choice from a list → select
├── Multiple choices from a list → multiselect
├── A specific date → date
├── A time of day → time
├── A quality/condition score → rating
└── Where an observation is, on a drawing → pin (location pin)

Field Settings

Setting	Description
Name	Display name — should be natural language
Required	Must be completed before survey can be submitted
Description	Helper text shown below the input in form mode and used by AI for context
Unit	Measurement unit for number fields (e.g., "PSI", "mm")
AI Prompt	Instructions for the AI when asking for this field
Voice Label	Short label spoken by TTS instead of the field name (optional)
Voice Aliases	Short names a surveyor may say for the field in offline voice (optional)

Voice Label (Short TTS Prompt)

Some fields need descriptive names for display and reports but shorter prompts for voice. The Voice Label overrides the field name in voice prompts only.

When to use Voice Label:

Paired fields where the name repeats context (e.g., "Comments on Seats and seat belts" with voice label "Comment")
Fields with long descriptive names that are awkward when spoken as questions
Any field where the voice prompt should differ from the display label

How it works:

Form and print — shows the full field name ("Comments on Seats and seat belts")
Voice prompt (TTS) — says the voice label ("Comment?")
AI context — the AI sees both the full name and the voice label, so it understands user responses in context
Falls back to the field name when no voice label is set (backward compatible)

Configuring in the builder:

Select a field in the field editor panel
Find the "Voice Label" input below Description
Enter a short label (e.g., "Comment")
Leave empty to use the field name as usual

Voice Aliases (Offline Voice)

Voice Aliases are short names a surveyor might say for a field, such as "width" for "Opening width in mm". Offline voice reads them as it reads the field's name, so "width 300" saves to that field. Online voice doesn't use them.

Find Voice Aliases (Optional) under Voice Label, type a name, and press Enter. Add as many as you need.
The builder warns you, without blocking the save, when an alias matches another field's name, voice label, alias or option.
Leave it empty and nothing changes.

Paired Field Pattern (Checklist Templates)

For inspection checklists where each check item has a Pass/Fail result followed by a comment field, set the voice label to "Comment" on each comment field and add template-level AI prompt coaching for compound utterances:

PAIRED FIELDS PATTERN: Each check item (Pass/Fail) is followed by a Comment field.

"Fail, brake light out" — save BOTH result and comment in one call

"Pass, skip comment" — save result and skip the comment

"Pass" alone — save result only, system prompts "Comment?" next

This lets inspectors say "Pass, skip comment" to breeze through passing items, or "Fail, brake light out" to capture both in one breath.

Naming Tips for Number Fields

Include the unit in the field name when known. This makes the expected input immediately clear:

Instead of	Use
Oil temperature reading	Oil Temperature in degrees C
Pressure value	Operating Pressure in PSI
Distance measurement	Distance in metres
Weight	Net Weight in kg

Using Field Descriptions

The description property is displayed below form inputs and used by the AI as additional context. Use it to clarify:

Field Name	Good Description
Operating Pressure in PSI	Normal range: 30-150 PSI
Serial Number	Format: XX-123456 (2 letters, dash, 6 digits)
Condition Rating	1 = Critical replacement needed, 5 = Like new
Installation Date	Date the equipment was first commissioned

Time Fields

Time fields capture a time of day, stored in 24-hour HH:MM format (e.g., "14:30"). The system automatically converts a wide range of spoken and typed formats.

Voice Input Conversions

User Says	Saved Value
"two thirty PM"	14:30
"9:30 AM"	09:30
"fourteen hundred" or "1400"	14:00
"noon" or "midday"	12:00
"midnight"	00:00
"3 o'clock"	03:00
"3 PM"	15:00

Form Input

In form mode, a native time picker is displayed. The value is always stored in 24-hour HH:MM format regardless of how it's entered.

Best Practices

Use clear field names like "Start Time" or "Inspection Time"
Add a description if context helps (e.g., "Time the inspection was carried out")
The AI automatically converts natural time expressions — no special configuration needed

Select and Multiselect Options

Adding Options

Click Add Option to create choices
Enter the display text for each option
Order options logically (most common first)

Voice Shortcuts (Aliases)

For technical fields with long option names, add voice shortcuts so users can speak abbreviations:

Example: Connection Type Field

Option	Aliases
Electric Fusion (Arc) Weld / Spiral Weld (0.8)	"arc", "spiral", "fusion"
Electric Resistance Weld (1.0)	"resistance", "erw"
(Double) Submerged Arc Weld (1.0)	"submerged", "saw"

Click the Aliases button next to each option to add shortcuts.

Alias Design Guidelines

Include common abbreviations — "ERW" for Electric Resistance Weld
Include partial matches — "spiral" for an option containing "Spiral Weld"
Include industry terms — "SAW" for Submerged Arc Weld
Avoid ambiguous aliases — don't use "arc" if multiple options contain "arc"
Case insensitive — all alias matching is case-insensitive; no need to add variants

Option Count Guidelines

Options	Voice UX	Recommendation
2-3	Excellent	AI can list all options naturally
4-6	Good	AI asks without listing; user likely knows the domain
7-10	Acceptable	Use aliases heavily; consider AI prompt guidance
10+	Poor	Consider splitting into hierarchical fields

Code Input Fields

For text fields that capture codes (registration marks, serial numbers, part numbers), enable the Code Input option. This allows users to dictate using the NATO phonetic alphabet and number words.

When to Enable Code Input

Field captures alphanumeric codes (serial numbers, registration marks, part numbers)
Users may spell out codes character by character
Codes contain mixed letters and numbers

Voice Input Conversions

User Says	Saved Value
"Alpha Bravo Charlie one two three"	ABC123
"Golf Bravo one two three Alpha Bravo"	GB123AB
"Sierra November dash one two three four"	SN-1234
"Hotel hyphen Mike four two"	H-M42

Supported conversions:

Phonetic alphabet — Alpha to A, Bravo to B, through Zulu to Z
Number words — zero through nine (plus "niner" aviation form)
Homophones — to/too to 2, for to 4, won to 1, ate to 8, oh to 0
Symbols — hyphen/dash to -, slash to /, dot/point to ., underscore to _

Output is always UPPERCASE for consistency.

Configuring in the Builder

Select a text or textarea field
In the field configuration panel, find "Text Options"
Toggle on "Code Input"

Calculated Fields

Calculated fields derive their values automatically from formulas referencing other fields. They are never prompted for — the value is computed in real time as dependencies are filled in.

When to Use Calculated Fields

Scenario	Example Formula	Result Type
Totals / subtotals	`{quantity} * {unit_price}`	number
Pass/fail determinations	`IF(AND({brake_test} == "pass", {emissions} <= 100), true, false)`	boolean
Risk scores	`IF({severity} > 3, "High", IF({severity} > 2, "Medium", "Low"))`	text
Summary text	`CONCAT({location}, " - ", {condition})`	text

Configuring Calculated Fields

Create a field with the desired result type (number, boolean, text, etc.)
Enable the "Calculated" toggle in the field configuration panel
Enter the formula expression in the formula editor
Review validation feedback — the editor shows parse errors, missing references, and cycle warnings

Formula Syntax

Field references — wrap field IDs in braces: {field_id}

Operators:

Arithmetic: +, -, *, /
Comparison: ==, !=, >, <, >=, <=
Logical: &&, ||, !

Built-in Functions

Function	Description
`IF(condition, then, else)`	Conditional — returns `then` if truthy, `else` otherwise
`SUM(a, b, c, ...)`	Sum of numeric values (skips nulls)
`AVERAGE(a, b, c, ...)`	Arithmetic mean (skips nulls)
`MIN(a, b, c, ...)`	Minimum value
`MAX(a, b, c, ...)`	Maximum value
`COUNT(a, b, c, ...)`	Count of non-null values
`AND(a, b, ...)`	True if all arguments truthy
`OR(a, b, ...)`	True if any argument truthy
`NOT(value)`	Logical negation
`CONCAT(a, b, c, ...)`	String concatenation (nulls become empty)
`ROUND(number, decimals?)`	Round to N decimal places (default 0)
`ABS(number)`	Absolute value
`TEXTJOIN(separator, val1, val2, ...)`	Join non-empty values with separator (skips nulls and empty strings)

Null Propagation

If a dependency field hasn't been filled in yet, the calculated field shows "(not yet calculated)". The value appears once all dependencies have values. Division by zero returns null — no crash, no error.

Evaluation Chain

Calculated fields can reference other calculated fields. The engine evaluates them in topological order — if field C depends on B which depends on A, it evaluates A, then B, then C automatically.

Circular dependencies are blocked at save time. The template builder shows an error if a cycle is detected.

Voice and Form UX

Voice — AI never prompts for calculated fields. Use AI Prompt on the calculated field to guide how the AI reads back the result (e.g., "After all tests are complete, tell the surveyor the overall result")
Form — displayed as read-only with a purple accent and "Calculated" badge. Values update in real time as dependencies change

Hidden Calculated Fields

Mark a calculated field as Hidden to make it evaluate without appearing in the survey form. Hidden fields are excluded from:

The form view (web and mobile)
PDF reports and print preview (web and mobile)
Progress percentage calculations
The AI voice assistant — the AI won't read or prompt for them

Hidden fields are useful as intermediate calculations that feed into a visible summary. This keeps each formula small and debuggable rather than combining everything into a single large expression.

Configuring:

Enable the "Calculated" toggle
Enable the "Hidden from form" toggle that appears below it
Enter the formula expression as normal

Conditional Summary Mode

For inspection-style surveys where many items share the same pattern (trigger field + comment field), Conditional Summary provides a point-and-click alternative to formula expressions.

Instead of writing CONCAT(IF({seat_status} == "Fail", CONCAT("Seats: ", {seat_comment}, "\n"), ""), ...), you configure a list of entries in the UI:

Entry	Include When	Value From	Label
1	`seat_status` equals "Fail"	`seat_comment`	Seats
2	`lamp_status` equals "Fail"	`lamp_comment`	Warning Lamps
3	`switch_status` equals "Fail"	`switch_comment`	Switches

The system evaluates each entry, collects matching values with their labels, and joins them with the configured separator (default: new line). Empty values are automatically skipped.

Supported "Value from" field types: text, textarea, number, select, and multiselect. Select field values are included as their selected option text.

Configuring:

Create a text or textarea field and enable "Calculated"
Change the Mode from "Formula Expression" to "Conditional Summary"
Click Add Entry for each trigger/value pair
Configure settings: include labels, label separator, line separator

Trigger operators:

Operator	Use When
Equals	Trigger field matches a specific value (e.g., "Fail")
Does not equal	Trigger field is anything except a value (e.g., not "Pass")
Is not empty	Trigger field has any value
Is empty	Trigger field has no value

Settings:

Setting	Default	Description
Include labels	On	Prefix each line with the entry label
Label separator	`:`	Text between label and value (e.g., "Seats: Worn fabric")
Line separator	New line	How to join multiple entries

TEXTJOIN for Aggregation

TEXTJOIN(separator, val1, val2, ...) joins non-empty values with a separator, automatically skipping nulls and empty strings. This is cleaner than nested CONCAT + IF patterns when aggregating multiple fields.

Example: Combine three optional comment fields into one summary:

TEXTJOIN("\n", {comment_1}, {comment_2}, {comment_3})

If comment_1 = "Worn fabric", comment_2 is empty, and comment_3 = "Intermittent", the result is:

Worn fabric
Intermittent

Inspection Template Pattern

For templates like vehicle inspections (MOT VT29), equipment audits, or quality checks, where each section has 5-15 check items with conditional comments, use one of these patterns:

Pattern A: Conditional Summary (recommended for most cases)

Create a single calculated field per section in Conditional Summary mode. Each check item's trigger/value pair is an entry in the list. No formula syntax needed.

Section: Interior
├── Seats Status [select: Pass/Fail]
├── Seats Comment [text, conditional on Fail]
├── Warning Lamps Status [select: Pass/Fail]
├── Warning Lamps Comment [text, conditional on Fail]
├── ...
└── Interior Summary [calculated, conditional summary mode]
    → "Seats: Worn fabric\nWarning Lamps: ABS light stays on"

Pattern B: Hidden per-row calcs + TEXTJOIN (for complex logic)

When each row needs custom logic (e.g., different conditions per item, or combining multiple fields per row), use hidden intermediate calculated fields:

Section: Interior
├── Seats Status [select: Pass/Fail]
├── Seats Comment [text, conditional on Fail]
├── _seat_line [calculated, HIDDEN]
│   → IF({seat_status} == "Fail", CONCAT("Seats: ", {seat_comment}), "")
├── Warning Lamps Status [select: Pass/Fail]
├── Warning Lamps Comment [text, conditional on Fail]
├── _lamp_line [calculated, HIDDEN]
│   → IF({lamp_status} == "Fail", CONCAT("Lamps: ", {lamp_comment}), "")
├── ...
└── Interior Summary [calculated, visible]
    → TEXTJOIN("\n", {_seat_line}, {_lamp_line}, ...)

Each hidden calc is a simple one-liner. The visible summary just joins them. Adding a new check item means adding one hidden calc and one TEXTJOIN argument.

When to use which:

Criteria	Conditional Summary	Hidden calcs + TEXTJOIN
All items follow same pattern	Best choice	Works but more effort
Items have different trigger logic	Limited	Best choice
Need to combine multiple fields per row	Not supported	Best choice
Number of items	Any (scales well)	Any (scales well)
Formula knowledge needed	None	Basic

Best Practices for Calculated Fields

Use ROUND() for currency and measurement calculations to avoid floating-point issues
Keep formulas readable — prefer IF(condition, "Pass", "Fail") over deeply nested expressions
Limit dependency chains to 3 levels max for clarity
Calculated fields are strictly read-only — don't use them for values users should override
For 5+ conditional items, prefer Conditional Summary mode over nested CONCAT(IF(...)) formulas
Use hidden intermediate calcs to decompose complex formulas into small, testable pieces
Name hidden calcs with an underscore prefix (e.g., _seat_line) to visually distinguish them from user-facing fields

Default Values from Job Line Metadata

Survey templates can configure fields to be pre-populated from the linked Job Line's metadata when a survey is created.

When to Use Metadata Defaults

Field Purpose	Metadata Key	Benefit
Inspection date	`scheduled_date`	Auto-fill from job schedule
Surveyor name	`assignee_name`	Auto-fill from assigned team member
Job reference	`job_ref`	Include in report header automatically
Site/task title	`job_line_title`	Pre-populate survey title

Available Metadata Keys

Key	Description	Data Type
`job_line_title`	Job line title	Text
`job_line_description`	Job line description	Text
`job_line_notes`	Job line notes	Text
`job_line_status`	Current job line status	Text
`scheduled_date`	Scheduled date	Date
`completed_date`	Completion date	Date
`assignee_name`	Assigned team member name	Text
`job_ref`	Parent job reference number	Text

Configuring in the Builder

Select a field in the field editor panel
Scroll to "Default Value" section
Choose "Job line metadata" from the Default Source dropdown
Select the metadata field you want to use

Type Compatibility

Metadata Type	Compatible Field Types	Notes
Text fields	text, textarea, select	Direct assignment
Date fields	date, text	Date fields receive ISO date string
Any text	number	Attempts numeric conversion

The UI shows warnings when metadata types may not match field types well.

Voice UX Behaviour

When a field has a metadata default:

AI: "The inspection date is set to January 15th. Would you like to change it?"

Pre-filled fields count as "completed" in progress calculations. Users can override any pre-populated value.

Static vs Metadata Defaults

Default Type	Use Case
None	Field starts empty — user provides all input
Static	Fixed default value (e.g., status = "Pending")
Job line metadata	Dynamic value from linked job line

Validation Rules

Number Fields

Rule	Description
Min	Minimum allowed value
Max	Maximum allowed value

Example: Temperature field with min: -40, max: 300

Text Fields

Rule	Description
Pattern	Regular expression for format validation

Example: Serial number pattern: ^[A-Z]{2}-\d{4}$

The AI will ask users to re-enter values that fail validation.

Conditional Logic

Show or hide fields based on previous answers. This keeps surveys focused by only asking relevant questions.

Creating Conditional Rules

Select the field to make conditional
Click Add Condition
Choose the trigger field, operator, and value
Set whether to Show If or Hide If the condition is met

Available Operators

Operator	Description
Equals	Exact match
Not Equals	Does not match
Contains	Text contains substring
Not Contains	Text does not contain substring
Greater Than	Numeric comparison
Less Than	Numeric comparison
Between	Range check
Is Empty	Field has no value
Is Not Empty	Field has a value

Multiple Conditions

Combine conditions with AND/OR logic:

AND — All conditions must be true
OR — Any condition must be true

Best Practices

Keep dependency chains short (A to B to C max — avoid longer chains)
Don't hide required fields without alternatives
Don't create circular dependencies
Test all conditional paths before publishing

AI Prompts

Customise how the AI asks for each field using AI prompts.

Template-Level Prompt

Set overall behaviour for the entire survey:

"You are helping complete an HVAC equipment inspection. Be efficient and professional. For measurements, confirm values outside normal ranges."

Field-Level Prompts

Override behaviour for specific fields:

For confirmation-critical fields:

"Always confirm the serial number by reading it back. Ask user to spell out ambiguous characters."

For measurement fields:

"If value seems unusually high/low, confirm before saving. Normal range is 30-150 PSI."

For technical select fields:

"Ask for weld type. Accept common abbreviations. Don't list all options unless user asks."

Unit Pronunciations (Custom TTS Dictionary)

The system automatically converts common unit symbols to spoken forms for text-to-speech:

Symbol	Spoken
degrees F, degrees C	"degrees Fahrenheit", "degrees Celsius"
PSI, kPa	"P S I", "kilopascals"
mm, cm, ft	"millimetres", "centimetres", "feet"
rpm	"R P M"
V, W, kW	"volts", "watts", "kilowatts"
Hz, kHz	"hertz", "kilohertz"

For unusual symbols not in the built-in table, add custom pronunciations:

In the Template Properties panel, scroll to "Unit Pronunciations (Optional)"
Enter the unit symbol exactly as it appears in your field's unit property
Enter the spoken pronunciation you want TTS to use
Click + to add the entry

Example custom entries:

Symbol	Pronunciation
mOhm	milliohms
dBm	decibel milliwatts
kN/m squared	kilonewtons per square metre

Custom pronunciations apply before built-in patterns and work across both web and mobile voice modes.

STT Context (Speech Recognition)

The system automatically extracts vocabulary from your template to improve speech-to-text accuracy. This includes field names, select options, voice aliases, and terms from AI prompts.

When to Add Manual Terms

For specialised vocabulary not captured automatically, add terms to the STT context:

Brand names and model numbers (e.g., "Sheer Flow 201")
Industry standards and codes (e.g., "API 1104", "ASME B31.8")
Chemical formulas and refrigerants (e.g., "R-410A")
Company-specific terminology

You don't need to add field names, select options, or voice aliases — these are extracted automatically.

Configuring in the Builder

In the Template Properties panel, scroll to "STT Context (Optional)". The editor has three sections:

Additional Terms — individual vocabulary words or phrases:

Type a term in the input field
Click + or press Enter to add it
Each term appears as a removable badge

Domain Context — key-value pairs for broader context:

Enter a key (e.g., "organisation", "equipment", "industry")
Enter a value (e.g., "Acme Pipeline Services")
Click + to add

Background Text — free-form text:

Enter any additional context in the text area
This is sent to the speech engine as-is

Manual terms are merged with the auto-extracted vocabulary and sent to the speech recognition engine on both web and mobile.

Context Budget

The speech recognition system accepts approximately 8,000 tokens of context. If you have extensive manual terms, prioritise the most critical vocabulary.

Reference Images

Add images to field groups to help users during surveys.

When to Add Images

Equipment nameplates showing where to find data
Condition examples (Good, Fair, Poor ratings)
Safety information and access points
Technical diagrams for complex equipment

Adding Images

Select a field group
Click Add Reference Image
Upload the image (up to 5 per group)
Add a descriptive caption

Caption Guidelines

Good captions help the AI find and display the right image:

"Nameplate location on XYZ-2000 series units"
"Example of corrosion requiring Poor rating"
"Refrigerant pressure gauge reading location"

During voice surveys, users can say "show me the nameplate" and the AI will display the matching image.

Photo Hints

Photo hints prompt the voice assistant to ask the inspector to take a photo at specific points during a survey. Unlike reference images (which show the inspector how to do something), photo hints tell the inspector what to photograph as evidence.

When to Use Photo Hints

Scenario	Example Hint
Equipment identification	"Take a photo of the equipment nameplate"
Damage documentation	"Take a photo of the damaged area"
Before/after evidence	"Take a photo of the installation before starting work"
Condition assessment	"Take a photo showing the overall condition of the unit"
Safety compliance	"Take a photo of the safety label"

Writing Good Photo Hints

Photo hints are spoken to the inspector before the field question is asked. The inspector has no context about which field is coming next, so the hint text must be fully self-descriptive.

Quality	Example	Why
Good	"Take a photo of the equipment nameplate"	Describes exactly what to photograph
Good	"Take a wide-angle photo of the full equipment setup"	Clear subject and framing
Bad	"Take a photo of this field"	Inspector doesn't know which field
Bad	"Photo"	No description of what to capture
Bad	"Take a photo"	Too vague — what should they photograph?

Configuring Photo Hints

On a field:

Select a field in the field editor panel
Find the "Photo Hint" input below AI Prompt
Enter the hint text (e.g., "Take a photo of the equipment nameplate")
Leave empty if no photo is needed for this field

On a group:

Select a group in the group editor panel
Find the "Photo Hint" input above Reference Images
Enter the hint text (e.g., "Take a wide-angle photo of the equipment before recording details")

Voice UX Behaviour

When the AI reaches a field with a photo hint:

AI: "Before we record the serial number, take a photo of the equipment nameplate." [Camera opens — inspector takes photo] AI: "OK, what's the serial number?"

When entering a group with a photo hint:

AI: "We're starting the equipment inspection. Take a wide-angle photo of the equipment setup." [Camera opens — inspector takes photo] AI: "First, what's the equipment type?"

Voice Commands for Photos

Inspectors can also request photos at any time during a voice session:

"Take a photo"
"Take a picture of the damage"
"Photograph this"
"Snap this"

The AI will open the camera and attach the photo to the current field context.

Best Practices

Use sparingly — only add photo hints where a photo genuinely adds value to the inspection record
Be specific — describe the subject clearly ("the nameplate", "the damaged section", "the overall setup")
Field-level vs group-level — use field-level hints for specific items (nameplate, label) and group-level hints for overview shots before a section
Don't duplicate — if a reference image already shows what to look at, a photo hint captures evidence of what was found

Location Pin Fields

A Location pin field lets the surveyor mark where an observation is, on a drawing or photo attached to the survey. The designed report then shows that drawing with a numbered marker per observation and a legend.

Pins are placed by hand in form mode on the phone. The voice assistant never asks for one, and pins don't count towards the progress percentage — like photos and signatures.

Full surveyor walkthrough in Drawings & Pins →

When to Use a Location Pin

Add one when where an observation is matters as much as what it is:

Scenario	Example
Condition survey	Each defect marked on the building's floor plan
Equipment audit	Each asset marked on the plant-room schematic
Site inspection	Each observation marked on a photo of the elevation
Drainage / utility work	Each finding marked on the relevant page of a drawing set

Don't add one when a text field already answers the question ("Room", "Panel reference"). A pin costs the surveyor a placement step, so it should earn it.

Adding the Field

Select the repeatable group that holds the observations — "Defects", "Findings", "Rooms".
Drag Location pin from the field palette into the group.
Name it for the surveyor: "Location on plan" reads better than "Pin".
Set Required if every observation must be pinned before the survey can be completed.

The field belongs on the group whose instances the markers should number. Put it on the "Defects" group and each defect gets its own marker.

Required Pins

A required pin is satisfied by one pin on any sheet. The surveyor doesn't have to pin the observation on every drawing attached to the survey.

When a required pin is missing:

The observation's card shows a "Pin needed" warning badge.
The form footer counts them — "2 location pins needed".
Complete is refused, naming the observation and the field. The same refusal appears on the phone, in the web completion dialog, and if the surveyor asks the assistant to finish.

What the Surveyor Sees

The field reads Place pin, then Pinned on 1 sheet / Pinned on 3 sheets once used.
Tapping it opens a full-screen placement view with every sheet on the survey.
If no sheets are attached yet, the field is inactive and says "Add a sheet in the Sheets section first."

Sheets are attached per survey, not per template — there's nothing to configure here for them.

Best Practices

One pin field per group. Two on the same observation confuse the badge and the report legend.
Put it near the end of the group — the surveyor records what the defect is first, then where it is.
Only make it required when every observation genuinely needs one. A required pin blocks completion, and a sheet isn't always available.
Pair it with findings. When an observation carries a survey finding, the report legend picks up that finding's classification and severity automatically.
Name it in plain words. The name appears on the card, in the legend and in the completion refusal.

Template Review Checklist

Before publishing a template, verify the following:

Voice UX

Data Quality

Required fields are marked appropriately
Number fields have reasonable min/max validation
Select options are mutually exclusive and exhaustive
Text fields with known formats have pattern validation

Conditional Logic

No circular dependencies between fields
All conditional paths are reachable
Required fields aren't hidden without alternatives
Dependency chains are 3 levels or less

Calculated Fields

All calculated fields have valid formulas or conditional summary configs (no parse errors)
No circular dependencies between calculated fields
Calculated fields have AI prompt guidance for voice readback
Formulas tested with edge cases (zero, null, boundary values)
ROUND() used for currency/measurement outputs
Hidden calculated fields are marked hidden (not just visually suppressed via conditional rules)
Conditional summary entries all have a label, trigger field, and value field configured
Sections with 5+ check items use Conditional Summary or hidden calc pattern (not deeply nested formulas)

Check Items

Repeating field patterns (3+ instances) use check items, not manual duplication
Field pattern keys are descriptive (e.g., "condition", "comments")
Voice shortcuts and options configured at field pattern level (not per-item)
Conditional summaries generated for patterns with 5+ check items

Repeatable Groups

Instance label templates use {n} placeholder
Maximum instances set to a reasonable limit
First field in repeatable group is a "label" or "name" field
"Allow Zero Instances" enabled for optional groups (defects, issues)
"Allow Zero Instances" disabled for mandatory groups (tasks)
Nested groups have Parent Group correctly set

Batches

The batch is a top-level repeatable group with each test as a child group
A starting number or a count question is set
Each pass has a short spoken name
The identifier field, if there is one, is in Pass 1
No pass warnings show in the builder

Location Pins

The location pin field sits on the group whose observations the markers should number
Only one pin field per group
"Required" is set only where a sheet will always be available
The field name reads well on the card, in the report legend and in a completion refusal

Default Values

Fields that should match job line data have metadata defaults configured
Metadata default types are compatible with field types
Static defaults set for fields with known constant starting values

Completeness

All fields have clear, descriptive names
Fields with non-obvious expectations have descriptions set
All fields belong to a group
Groups have meaningful names and descriptions
Reference images have descriptive captions

Testing

Template Versioning

A template moves through three statuses: Draft, Published and Obsolete. You build and test a Draft, then click Publish to make it available for new surveys.

Once a template is Published, its structure is locked: the header shows Structure locked, and you can't add, remove or change fields, groups, field patterns or check items. You can still edit details such as the name and description.

Changing a Published Template

To change the structure of a template that's in use, make a new version:

Open the Published template and click New Version
If the template has report designs, choose Carry layouts to copy them onto the new version as Drafts, or Don't carry to start without one
Edit the new version. It's a Draft with the next version number (for example 1.3 after 1.2), with the same fields, groups and reference images
Click Publish when it's ready

Publishing the new version marks the previous Published version Obsolete. An Obsolete template can't be edited and isn't offered for new surveys. Surveys already started on it keep working, and keep the version they started with.

Reference images still being checked for viruses when you create the version aren't copied, and you see a message saying so. Upload them again on the new version.

Approving a Template for Use

When you click Publish on a Draft, the Approve this template for use dialog opens. It says that publishing locks the template structure and retires any Published version with the same label.

Tick I confirm I have reviewed this template and approve it for use. The Publish button stays unavailable until you do. Click Cancel to go back without publishing.

Your acceptance is recorded when you publish. Save any unsaved changes first: you can't publish while the template has unsaved edits.

Deleting a Draft

To remove a Draft you no longer need, such as a new version you've decided against, open it, click the More actions button (⋯) at the top right and choose Delete. Its reference images and report designs are deleted with it. This can't be undone.

Only Drafts can be deleted. A Draft that a survey has used can't be deleted, and a Published template is retired by setting it to Obsolete instead.

Publishing and Permissions

Templates must be published to be available for new surveys
Set visibility to control who can access the template
Assign templates to specific team members or roles