Forms

What it does

Forms are the structured screens used to capture information consistently — intake, assessments, clinical observations, and custom registration-style flows. Authors build forms in the drag-and-drop builder; clinicians and clerks fill, review, edit (amend), or void submissions. Fields are tied to concepts where clinical meaning matters.

Where to find it

• Forms home — /forms
• Form definitions — /forms/definitions
• Form builder — /forms/builder
• Submissions — /forms/submissions (also linked from a published version)

📸 Screenshot: the Forms list (forms-list).

📸 Screenshot: the form builder (forms-builder).

📸 Screenshot: submissions list (forms-submissions).

Common tasks

Bind an approval workflow (routable forms)

1. Open Form builder for a domain/engine form (/forms/builder?id=<formId>) or Form definitions detail for a structured form.
2. In Approval workflow, choose a published workflow from the Form approvals category whose subject type is Form submission. Save the binding.
3. After publish, the form list shows a Routable badge when a workflow is bound. Submissions auto-start approval routing when processed.

Revise and resubmit after rejection

1. Open Submissions and select an item whose routing status is Rejected (returned by an approver).
2. Choose Revise and resubmit — the runtime form opens prefilled (?resubmit=<submissionId>).
3. Adjust answers and submit. The platform voids the rejected row, creates a replacement linked in the chain, and re-enters stage 1 on the same workflow instance.

Fill in a form

1. Open a published form (from Forms, a workflow task, or a patient/clinical entry point).
2. Complete the fields. Cascading lookups and computed values update as you go.
3. Submit. If any answer breaks a rule (required blank, number out of range, failed cross-field rule), the server returns all problems at once — nothing is saved. Fix the highlighted fields and submit again.

Clinical observation forms usually also ask for encounter location (department → unit → care location) and signatories (encounter providers). Those blocks are required when the form is configured for observations.

Answer a dictionary-search field (and what to do when there is no match)

A dictionary search field is a type-ahead over the whole concept dictionary — start typing and pick the matching term. Enter takes the top match, so the quickest path is always the coded one.

When the search finds nothing, what happens next depends on how the author set the field up:

• Coded-only fields say so: "No match. This field accepts dictionary terms only." That is not a broken search. Do not retype it into another field or into a comment — ask a terminology steward to add the concept, and record what you can in the meantime.
• Fields that allow unmapped answers additionally offer one highlighted action at the bottom of the list: Record "…" as an unmapped term. You have to click it (or arrow down onto it and press Enter) — pressing Enter in the search box never takes it, by design.

An unmapped answer is shown with an Unmapped chip and the line "Sent for terminology review", and it keeps that chip everywhere it is displayed afterwards, including a reopened submission. It is stored exactly as you typed it (up to 255 characters — a term, not a narrative; put detail in a comment), counted, and reviewed so recurring terms can be added to the dictionary. Until then it cannot be counted or reported alongside coded answers, so prefer a coded answer whenever one exists.

Build or edit a form (administrators)

1. Open Form builder (/forms/builder).
2. Drag fields and containers onto the canvas. Set label, field key, required, validation, and lookup sources.
3. Choose the owning module and backing table name — locked after first publish.
4. Add rules: visibility/required conditions, computes, cross-field checks, repeating (table) groups where needed.
   • On a dictionary search field you may switch on Allow unmapped answers. It is off by default and should usually stay off. Leave it off wherever the value's whole worth is that it can be compared — lab analytes, allergy substances, immunisations — because an unmapped term cannot be counted, cohorted or reported beside coded ones. Switch it on only where a missing concept would otherwise stop care being recorded at all (an "other findings" question, say). The toggle exists on dictionary-search fields only: a dropdown already has the right escape hatch, which is an Other answer in its answer set plus a conditional follow-up field.
5. Save the draft, Preview, then Publish. Publishing creates a new version; past submissions keep the schema they were entered with.

Explain a field with a tooltip

Every control has a Tooltip property. Whatever you write there appears behind a small ? next to the field's label; the reader clicks it to open the explanation and clicks again to close it. It works the same when someone is filling the form and when they are reading a form already filed.

The tooltip editor takes formatting — bold, italic, underline, bulleted and numbered lists — so a dosing rule or a list of exclusions reads as one. Use it for the explanation that would clutter the form if it were on screen all the time.

Tooltip or help text?

• Help text is plain and always visible under the field. Use it for the short instruction everybody needs — "date of the first dose".
• A tooltip is formatted and hidden until asked for. Use it for the longer explanation only some people need — what counts as a positive result, when to escalate, which patients are excluded.

A field with an empty tooltip shows no question mark at all, so leaving it blank costs nothing.

⚠ Pasting into the tooltip keeps the words and drops the formatting of wherever you copied from. That is deliberate: text pasted from a document or a web page carries fonts, colours and tracking markup that would not be kept anyway, and this way you see immediately what the tooltip will really look like. Re-apply bold or lists with the toolbar.

Browse definitions and versions

Form definitions lists every form with status and version. Open a definition to manage drafts, publish, or jump to View submissions for that form.

Review a submission

1. Open Submissions (/forms/submissions).
2. Open a row to see answers rendered against the schema snapshot for that version (read-only view).

Edit (amend) a submission

1. On the submission view, choose Edit when available.
2. The runtime form opens prefilled (?edit=<submissionId>). Correct values and submit.
3. The platform voids the previous submission and creates a replacement (amend) for domain/engine and clinical-observation forms. Custom-handler forms may update in place when their handler supports edit — otherwise you will see a clear error until that handler is implemented.

Void a submission

1. On the submission view, choose Void.
2. Enter a reason (required). The submission is hidden from normal lists; reporting tables keep an audit trail of the void.

Tips & limitations

• Publishing never rewrites history — always a new version.
• A form can only capture concepts that exist in the dictionary when the field requires one.
• Which forms you see can depend on your roles and home department/unit (form visibility). See Visibility & consent and Workforce engagements.
• Where a form's answers are stored is shown on the builder's Submission routing panel, and it is set in the builder itself — either an owning module and table name, or a registered submission handler for forms that create several records at once (registering a patient writes a person, a patient, identifiers and addresses). It is fixed once the form is published, because the storage already holds data, so plan it before you publish.
• A form can only route to a handler the platform has registered. You cannot point a form at an arbitrary web address — that was never supported and is deliberately not coming.
• If a submission fails, its raw answers are always kept, so nothing has to be re-keyed. Retry is available for failures the server marked retryable; Override forces a non-retryable failure through and appears only when an administrator has enabled FORM_OVERRIDE_SUBMISSION_ENABLED for your tenant or facility.

---

When something looks wrong

What you see	What it usually is
A form is not offered on a patient screen	Its visibility is scoped to roles, units or departments that exclude you
A published form cannot be edited	Edit a draft version and publish that
A field's answers are empty	The answer list is concept-backed and the concept set is empty in this scope

For the causes common to every screen — a missing menu item, an empty list, a refusal — see Why a screen will not work.