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

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.

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 like "Room {n}" — the `{n}` is replaced with the instance number	Group name + number
Allow Zero Instances	Users can skip the group entirely	On (min 0)
Max Instances	Limit how many can be added	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:

Value of field with ID label (if exists and non-empty)
Value of field with ID name (if exists and non-empty)
Instance label template with {n} replaced (e.g., "Room 1", "Room 2")
Fallback: "Group Name 1", "Group Name 2"

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".

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?"

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

Any of these types 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

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 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

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 session 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

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

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

Templates are versioned automatically. When you edit a template:

Existing sessions continue using the version they started with
New sessions use the latest version
Version history is preserved for auditing

Publishing and Permissions

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