Visit Form Builder
Complete reference for designing, configuring, previewing, and publishing eCRFs in Clinical Study Manager
URL
/visit-form-builder— fullscreen visit form (eCRF) builder
Purpose
This page is where you design electronic case report forms (eCRFs) for your license. You add fields from a palette, arrange them on a 12-column canvas, configure every field property, save drafts, preview respondent behavior, and publish when ready. Published eCRFs can be attached to visits in the Visit Flow Builder and used for visit data capture.
eCRFs are license-scoped and study-independent. You do not need an open research study to author one. Once published, a form is final and opens read-only in this builder.
Use a desktop-width browser. On small screens the builder shows a Desktop Version Required notice and does not open the canvas.
What you can do
- Start from a blank form or a quick-start template (welcome dialog when you have no saved forms)
- Drag or click field types from the left palette onto the canvas
- Select a field and edit its properties in the right panel
- Rearrange fields by drag-and-drop; place fields side-by-side with column span and column start
- Duplicate or delete selected fields; undo, redo, and jump through session history
- Switch canvas viewport width (desktop, tablet, mobile) and set per-viewport appearance overrides
- Preview the form as a respondent would see it (requires a submit button and valid Keys)
- Save a draft eCRF (and Save As) from the File menu
- Open an existing form or template from the File menu
- Start a new form, duplicate a field, or clear the canvas from the menus
- Publish a saved draft when validation and permissions allow (published forms are read-only)
- Exit back to Clinical Study Manager home
Permissions
Page access — Requires a signed-in user with Clinical Study Manager access and Design eCRFs. Without that permission you are redirected away from this route.
| Permission | Purpose |
|---|---|
Design eCRFs | Opens this page and enables editing, save, open, new form, and related draft controls. |
Publish eCRFs | Enables Publish on a saved draft that passes readiness checks. |
Without Design eCRFs, the route is blocked. If that permission is missing while you are already on the page, or the form is already published, the builder stays in read-only mode and editing actions are unavailable.
Publish also requires Publish eCRFs, a saved form, and publish readiness (see Publish readiness). Tooltips explain when the control is unavailable. Published eCRFs open read-only and cannot be republished from this page.
Workspace
Three panels plus an app bar. Menus, preview, and publish details follow the map.
| Area | Role |
|---|---|
| App bar | Exit, menus, title, history, viewport, preview, publish |
| Fields palette | Field types you can add |
| Canvas | Arrange and select fields |
| Properties | Configure the selected field |
App bar
| Control | What it does |
|---|---|
| Exit Form Builder | Returns to /. |
| File / Edit / View | See Menus. |
| Form title (center) | Current form name. |
| Undo / Redo / History | In-session edit history. |
| Viewport toggles | Desktop / tablet / mobile design width. |
| Help | In-app help and tour. |
| Preview | Respondent-style view — see Preview. |
| Publish | Publishes a ready draft (or shows Published) — see Publish. |
Fields palette
Left panel. Click or drag onto the canvas. Disabled in read-only mode.
| Group | Fields |
|---|---|
| Typography | Text block |
| Input Fields | Text, Text Area, Number, Email, Telephone |
| Selection Fields | Select, Checkbox, Checkbox Group, Radio Group, Switch |
| Date & Time | Date Picker |
| Buttons | Submit, Reset |
Canvas
12-column form surface.
- Empty canvas shows a drop target until the first field is added
- Click to select (outline + type badge); hover shows delete (X)
- Drag to reorder; drop zones on top / bottom / left / right for stacking or same-row layout
- Viewport width controls how wide the design area appears
Properties
Right panel for the selected field. Empty or read-only: No Component Selected. Otherwise only sections for that field type appear — see Property sections and Field types. The first three collapsible sections open by default.
Menus
File
| Action | What it does |
|---|---|
| New | Blank form; may ask to discard unsaved changes. |
| Open | Opens a saved draft or published form for this license. |
| Open Template | Loads a quick-start template. |
| Save | Saves the draft (first save asks for a Name). Needs at least one field. |
| Save As | Saves a copy as a new form. |
| Publish | Same gating as the header Publish button. |
| Exit | Leaves the builder and returns home. |
Save and related edit actions require Design eCRFs and a non-published draft.
Edit
| Action | What it does |
|---|---|
| Undo / Redo | In-session history (also on the app bar). |
| Duplicate | Copies the selected field. Disabled with no selection or read-only. |
| Clear | Removes every field. Disabled when empty or read-only. |
View
| Action | What it does |
|---|---|
| Viewport options | Same as the app-bar toggles: desktop (lg), tablet (md), mobile (sm). |
| Preview | Same readiness as the header Preview button. |
Preview and publish
Preview
Shows the form as a respondent would fill it. Exit from the header when finished.
Stricter than publish: needs a Submit button plus a non-empty unique Key on every respondent field. When blocked, the tooltip lists what is missing.
Publish
Available when the form is saved, publish readiness passes, and you have Publish eCRFs. Confirm by typing the form name exactly. Publishing is final: the eCRF becomes read-only.
Welcome dialog
When the license has no saved forms yet and you are not read-only:
- Start with a blank form
- Quick Start templates: Patient Registration, Appointment Request, Medical History Form, Telemedicine Consultation
If forms already exist, use File → New or File → Open Template.
Read-only mode
Editing locks when:
- The form is published — “This form is published and cannot be changed.”
- You lack
Design eCRFs— “Unauthorized: insufficient permissions”
You can still browse; you cannot add, edit, delete, save, or clear fields.
Property sections
Not every field shows every section. When a section is listed for a field type below, these are the controls inside it.
Data Options
Shown for fields with choice lists (Select, Radio Group, Checkbox Group).
- Preview of up to five current option labels and values
- Manage Options opens a dialog to add, edit, or remove options
- Every option has a Label (shown to respondents) and a Value (stored when selected)
- Radio Group and Checkbox Group also support Label Description (helper text under each option)
- Checkbox Group also shows a checkbox per option for the default checked state
- Changes apply only after you click Save Options
Input
Common controls (availability depends on field type). Key appears for all respondent fields (everything in the form category except Submit/Reset), even when other Input controls are limited.
| Control | Meaning |
|---|---|
| Key (required) | Stable field identifier stored as the form field key. Used when data is captured, submitted to EDC, and shown in study field snapshots. Must be unique within the form. Example placeholder: bp_systolic. |
| Value | Default value shown before the respondent edits. For Select/Radio, choose from the option list. For text-like fields, free text. |
| Checked | Default on/off for Checkbox and Switch (yes / no). |
| Placeholder | Hint text inside empty inputs, text areas, selects, and date pickers. |
| Description | Helper text associated with the field (separate from the label). |
| As Card | When yes, choice controls render inside a card chrome. Can differ per viewport. |
| Card Layout | horizontal or vertical arrangement when As Card is on. |
| Icon | Optional Lucide icon on text-like inputs (and buttons under the Button section). After picking an icon: Stroke Width (0.5–3) and Position (left / right). |
Label & Description
| Control | Meaning |
|---|---|
| Show Label | yes / no. Can differ per viewport. |
| Label | Primary visible title for the field. |
| Label Description | Secondary text under the label (Checkbox, Switch). |
| Label Position | top, left, or right. Can differ per viewport. |
| Label Alignment | start, center, or end. Can differ per viewport. |
Button
Shown only for Submit and Reset.
| Control | Meaning |
|---|---|
| Content | Button text (defaults: “Submit” / “Reset”). |
| Type | submit or reset (HTML button type). |
| Variant | Visual style: default, outline, ghost, or link. |
| Icon | Same icon picker, stroke width, and left/right position as Input icons. |
Appearance
Layout on the 12-column canvas. Both controls can differ per viewport.
| Control | Meaning |
|---|---|
| Column Span | How many columns the field occupies (1–12). Default is 12 (full width). |
| Column start | Starting column: auto or 1–12. Use with span to place fields on the same row. |
Validation
| Control | Meaning |
|---|---|
| Required | yes / no. Marks the field required at capture time. Available on every respondent field that exposes Validation. |
| Conditions | Additional rules joined with AND. Click + Add condition, pick an operator, enter a value, or remove a row. Operators depend on the field type (see each field below). |
Field keys (expert rules)
The Key is the business identifier for captured data—not the internal component id on the canvas.
Rules that always apply
- Every respondent field needs a non-empty Key before preview or publish.
- Keys must be unique within the form.
- Text blocks and buttons do not use Keys.
- Prefer stable, readable keys (
vitals_systolic,ae_severity). Changing a Key after a form is used in live studies can break continuity of study field snapshots that reuse the same key across visits.
Reserved keys (cannot publish)
These prescribed-medication keys are product-owned. Drafts may temporarily contain them, but publish is rejected if any respondent field uses one:
prescribed_medication_nameprescribed_medication_administration_methodprescribed_medication_dosageprescribed_medication_frequencyprescribed_medication_start_dateprescribed_medication_end_date
Study-wide key consistency (after attach)
When the same Key appears on more than one eCRF in the same visit flow, those forms must agree on component type, required flag, and validation. Disagreement fails study activation. Design Keys carefully before publishing forms you intend to reuse across visits.
Viewport overrides
The canvas viewport toggles (desktop / tablet / mobile) change the design width and which override values you are editing.
Some appearance controls show a small monitor icon:
- Gray icon — the value is the same across viewports
- Blue icon — hover to see
sm,md, andlgvalues when they differ
Controls that support per-viewport overrides include As Card, Show Label, Label Position, Label Alignment, Column Span, and Column start. Content such as Key, option lists, and most Input text apply to all viewports.
Field types
For each type: what respondents see, which property sections appear, and which validation operators are available.
Interactive demos below approximate respondent behavior. They are docs previews—not the live Visit Form Builder UI.
Text block
Palette: Typography · Category: content (layout / instructions only)
Rich text for headings, instructions, and static copy. Not a respondent field—no Key, no Validation, and it does not count toward “at least one respondent field” for publish.
Visit instructions
Record vital signs before the physical exam. Use the fields below for systolic and diastolic blood pressure.
- Confirm subject identity
- Note any protocol deviations
In the builder, edit this content with the WYSIWYG toolbar (headings, lists, bold, and more).
Edit content on the canvas with the WYSIWYG toolbar:
- Hierarchy: Paragraph, Heading 1–3
- Lists: Bullet list, Numbered list
- Text styles: Normal, Muted, Small, Large, Lead
- Marks: Bold, Italic, Underline, Strikethrough
- Alignment controls
- Code block and Blockquote
Properties: Appearance only (Column Span, Column start).
Text
Palette: Input Fields · Single-line text input
Key example: field_key
Properties: Input · Label & Description · Appearance · Validation
Input controls: Key, Value, Placeholder, Description, Icon (with stroke / position)
Label controls: Label, Label Position, Label Alignment, Show Label
Validation operators: Min length, Max length, Contains, Does not contain (plus Required)
Text Area
Palette: Input Fields · Multi-line text
Properties: Input · Label & Description · Appearance · Validation
Input controls: Key, Value, Placeholder, Description (no icon)
Label controls: Label, Label Position, Label Alignment, Show Label
Validation operators: Min length, Max length, Contains, Does not contain (plus Required)
Number
Palette: Input Fields · Numeric values
Uses the same Input property set as Text (including Icon). Stored and validated as a number field.
Key example: field_key
Number fields support min/max and comparison validation in the builder.
Validation operators: Min value, Max value, Greater than, Less than, Equals, Greater or equal, Less or equal (plus Required)
Palette: Input Fields · Email addresses
Same property set as Text. Built-in email input type; use Contains / Does not contain for extra string rules if needed.
Key example: field_key
Validation operators: Contains, Does not contain (plus Required)
Telephone
Palette: Input Fields · Phone numbers
Same property set as Text.
Key example: field_key
Validation operators: Min length, Max length (plus Required)
Select
Palette: Selection Fields · Dropdown
Stored value: option1
Option Label is shown to respondents; Value is what gets stored.
Properties: Data Options · Input · Label & Description · Appearance · Validation
Input controls: Key, Value (pick default from options), Placeholder, Description
Label controls: Label, Label Position, Label Alignment, Show Label
Data Options: Manage option Label / Value pairs (no per-option description or default-checked column)
Validation: Required only (no extra condition operators)
Checkbox
Palette: Selection Fields · Single checkbox
Default Show Label is no so the checkbox label/description carry the meaning.
Properties: Input · Label & Description · Appearance · Validation
Input controls: Key, Description, As Card, Checked
Label controls: Label, Label Description (no position / alignment / show-label toggles)
Validation: Required only
Checkbox Group
Palette: Selection Fields · Multiple checkboxes
Selected: option1
Respondents can select multiple options. Default checked state is set per option in Manage Options.
Properties: Data Options · Input · Label & Description · Appearance · Validation
Input controls: Key, Description, As Card, Card Layout
Label controls: Label only
Data Options: Label, Label Description, Value, and default Checked per option
Validation: Required only
Radio Group
Palette: Selection Fields · Single choice among options
Stored value: option1
Properties: Data Options · Input · Label & Description · Appearance · Validation
Input controls: Key, Value (default selection), Placeholder, Description, As Card, Card Layout
Label controls: Label, Label Position, Label Alignment, Show Label
Data Options: Label, Label Description, Value
Validation: Required only
Switch
Palette: Selection Fields · Toggle
Same configuration pattern as Checkbox (Label + Label Description; Checked; As Card; Required).
Date Picker
Palette: Date & Time
Default placeholder: “Pick a date”.
In the builder this is a date picker control; here a native date input stands in for the interaction.
Properties: Input · Label & Description · Appearance · Validation
Input controls: Key, Placeholder, Description (no default Value / Icon)
Label controls: Label, Label Position, Label Alignment, Show Label
Validation: Required only
Submit
Palette: Buttons · Submits the form in preview / runtime
Not a respondent field (no Key). Default content “Submit”, variant default.
A Submit button is required before Preview enables in the builder.
Properties: Button · Appearance
Required for Preview — without a Submit button, Preview stays disabled even if Keys are valid. Publish does not require a Submit button; it only needs at least one respondent field and valid Keys.
Reset
Palette: Buttons · Clears respondent input values
Not a respondent field. Default content “Reset”, variant outline. Optional for both preview and publish.
Reset clears respondent input values; it is optional for preview and publish.
Properties: Button · Appearance
Field type quick reference
| Field | Respondent? | Data Options | Extra validation operators |
|---|---|---|---|
| Text block | No | — | — |
| Text | Yes | — | min/max length, contains / not contains |
| Text Area | Yes | — | min/max length, contains / not contains |
| Number | Yes | — | min/max, greater/lower, equals, ≥ / ≤ |
| Yes | — | contains / not contains | |
| Telephone | Yes | — | min/max length |
| Select | Yes | Label + Value | Required only |
| Checkbox | Yes | — | Required only |
| Checkbox Group | Yes | Label, description, value, checked | Required only |
| Radio Group | Yes | Label, description, value | Required only |
| Switch | Yes | — | Required only |
| Date Picker | Yes | — | Required only |
| Submit | No | — | — |
| Reset | No | — | — |
Publish readiness
Hover Publish when it is disabled to see the blocking reasons. Server and UI share these checks:
| Check | Message |
|---|---|
| Empty form name | Enter a form name before publishing. |
| No respondent fields | Add at least one respondent field. |
| Missing Key | Fill out the required Key for every field. |
| Duplicate Key | Each Key must be unique within the form. |
| Reserved Key | Respondent fields cannot use reserved prescribed-medication keys. |
Also required before Publish enables:
- Form already saved (“Save the form before publishing.”)
Publish eCRFs(“You don't have permission to publish eCRFs.”)- Form not already published (“This form is already published.”)
Confirmation dialog: type the form name exactly, then confirm.
Menus and lifecycle (summary)
- Draft — editable with
Design eCRFs; save updates the same form after first name. - Preview — temporary respondent view; needs Submit + valid Keys.
- Publish — irreversible for v1; form opens read-only afterward.
- Open published — inspect only; use Save As / New if you need a new editable draft based on another form’s structure via templates or duplication of fields before publish.
Related guides
- Create an eCRF form — step-by-step design, save, and publish
- Create a visit flow — attach published eCRFs to visits
- Visit Flow Builder — visit schedule template builder