How-toData manager

Build forms in the CRF builder

A design draft is assembled visually — in the CRF builder. Here you create forms, sections and fields, set their properties, and add codelists, edit checks and derivations — all on one screen, with no files or manual markup.

Who and when

Data manager — the study designer (Study Builder) or the data manager who holds the “edit a design version” permission (studyversion.update) on the study. Without it the builder opens read-only. Approving and publishing what you build is done by another person — see Publish a version.

The task comes up after you create the study and with every protocol amendment — on a new draft.

Before you start

There is a design version in the Draft status. If there is no design yet, click New design draft on the Design page.
The protocol is at hand: the list of forms and questions, units, ranges.
If the design is already prepared as a file, you don’t have to build it by hand — import it from a file following the template.

Steps

0:000:00

The CRF builder: forms, typed fields and form logic — visual, no code.

The design tree: version → forms → sections → fields; codelists are attached to choice fields separately.

Open the study’s Design section and click Open builder in the draft zone.
On the Forms tab of the left panel click Add form and enter a name. The builder assigns the data name (OID) itself.
On the Structure tab of the central panel click Add section — a meaningful part of the form. A section can be made a log: at entry time it turns into a table of rows (for example, a series of blood-pressure readings).
In the section click Add field and type the name in the composer row; set the type with a trailing command (see Quick entry).
Select the field and set it up in the Properties inspector on the right: Required, Unit, Min / Max value, Option list, Display condition (the full list is under More details).
For choice fields, create dictionaries on the Codelists tab: Add list → “code → label” pairs (for example, M → Male, F → Female).
Add the form’s logic on the Logic tab: edit checks and derivations.
Open Problems in the header and work through the findings — each leads to the place of the problem.
Go back to the Design page and click Preview: walk through every form with typical and boundary values.

The order of elements is changed with the Move up / Move down arrows or by dragging; a field can also be dragged into a neighbouring section. A form, section, field or list can be duplicated from the ⋯ menu next to it: the copy keeps its properties and the builder assigns it new OIDs.

Quick entry: the composer and clipboard paste

Add field opens an inline composer row right inside the section: type a name and press

Enter — the field is created and the row waits for the next one. The type is a trailing command (/number /date /time /choice /yesno /text), a unit goes in parentheses, choice options after a colon:

Weight /number (kg)
Date of birth
Smokes /yesno
Sex /choice: Male, Female

“Sex” gets its option list right away — there is no need to create it separately.

⌥Enter creates the field and opens its properties, Esc closes the composer. For a formula or fine-grained format tuning there is still the full dialog — a link under the composer row.

Clipboard paste: copy a list of questions from the protocol or Excel and paste it into the composer — each line becomes a field by the same grammar (with a confirmation of how many fields will be created).

Templates

The ⋯ menu of the central panel (and the empty draft) offers From template… — a gallery of ready-made blocks: Demography, Vital signs, Adverse event (with its own dictionaries), standard lists. Inserting twice is fine — data names get a suffix and references are rewritten. Your own form or list can be saved as a template from its ⋯ menu — a form travels together with the option lists it uses and becomes available across the organisation.

Delete and bring back

Deleting a field, section, form or list asks for no confirmation — instead a “Deleted · Undo” toast and ⌘Z bring it back with all properties, rules and its former position.

What happens

Every edit is saved at once — the header shows “Saving…” → “Saved”. There is no separate save button.
Every design change is written to the audit trail and shown in the Design change log on the Design page (“Field created”, “Form changed”, “Check created”…).
A field’s required flag and range immediately produce system checks — they appear in the From field properties block of the Logic tab.
The version stays in Draft until you click Submit for review. No site sees the changes yet: data is collected only against the published version.

If it doesn’t work

“Read-only” banner: “The version is no longer a draft” — the version is in review, approved or published. Any change to a published design is a new draft (an amendment); a version in review can be returned to draft.
“You cannot edit the design — view only” — you don’t hold studyversion.update on the study. Ask an administrator.
“Failed to apply the change” — the server rejected the edit; the reason is in the message text.
A field is marked “no codelist” — a choice field has no Option list selected.
“Minimum is greater than maximum — the bounds will not work” — fix Min / Max value.
Submitting for review is unavailable: “Design validation found N errors” — open Problems and fix the errors.

Set up edit checksSystem and cross-field checks — the Edit checks block of the Logic tab.

Set up skip logic and derivationsDisplay conditions, computed fields and the expression language.

Build the visit scheduleThe SoA matrix: visits, windows and form assignment.

Publish a version and launchReview, publication, UAT and go-live.

More details

Where to open the builder

The entry point is the study’s Design page. If there is no design yet, click New design draft, then Open builder in the draft zone. Next to it are SoA matrix (assigning forms to visits) and Preview (living through a form before publication). The same page opens a published version with View design — the builder then starts read-only.

The builder’s three panels

The screen is divided into three zones — left to right, from general to specific:

Panel	What’s in it
Left — the list	Two tabs — Forms and Codelists — and a search box. The Forms tab lists all forms of the draft; a click selects the form to work on. The Codelists tab holds the value dictionaries.
Centre — the form	The open form in two tabs: Structure (sections and fields in display order; each field shows its type — Text · Choice from list · Date …) and Logic (the form’s checks and derivations).
Right — the property inspector	Properties of the selected element — form, section or field. Everything that defines an element’s behaviour is set here.

The header holds the Problems button (with a count of findings) and the More (⋯) menu: CRF languages, plus export and Import JSON for moving a design as a file (see Import a design from a file).

Next to a field you see markers: condition — the field has a display condition, auto-filled — the system computes the value, blinded — the value is masked.

Data name (OID)

Every form, section and field has a data name (OID) — the column identifier in exports and the field’s address in rules. The builder generates it from the name (“Date of birth” → DATE_OF_BIRTH), and in the collapsed Technical details block of the inspector it can be renamed while the version is a draft: the system rewrites all references (conditions, checks, formulas) itself. After publication the data name is fixed for good. The SYS. prefix is reserved for system checks.

Field property inspector

Property	What it sets
Name	The field label as the coordinator will see it.
Section	Which section of the form holds the field; switching moves the field to another section (dragging does the same).
Option list	For the “Choice from list” type — the dictionary the value is picked from.
Required	An empty field counts as a gap — the system creates a “field must not be empty” check itself.
Unit	The unit of measure — shown next to the field.
Min / Max value	The bounds of acceptable values — the system creates a range check itself.
Range violation	Soft (record the value and raise a query) or hard (reject the value) — for a number with a range.
Max length	For text — a length limit.
Display condition	An expression over other fields of the form: true — the field is visible (see Skip logic and derivations).

Monitoring and blinding — Subject to SDV, Requires medical coding and Blinded (value is masked) — sit in the collapsed Advanced block. The collapsed Technical details block holds the Data name and the full Data type (Text · Integer · Number · Yes/No · Date · Partial date · Date and time · Choice from list …) — the type is usually set by the “Question type” when the field is created.

If a field takes part in checks or derivations, the inspector shows a Rules of this field block with the related rules; clicking a derivation opens its editor. A derivation target field carries the auto-filled marker: manual entry into it is closed and its data type cannot be changed.

Codelists

The Codelists tab holds the value dictionaries for “Choice from list” fields: “code → label” pairs. A list is created once and attached to any number of fields. Codes within a list must not repeat — the builder enforces this. A list can be duplicated from its ⋯ menu.

Form logic

The Logic tab holds the behaviour rules of the open form: a rule belongs to the form and is versioned together with the design — changing it after publication creates a new version. Blocks:

Edit checks — data-quality rules (“query” and “block”) that fire on entry. The Add check button; an existing rule can be changed (click it) or deleted. Details — Set up edit checks.
Auto-filled fields — computed fields the system fills itself from other fields. The Add derivation button. Details — Set up skip logic and derivations.
From field properties — checks the core creates itself from Required and range bounds. The block is read-only: these checks are changed through the field’s properties.

The expression editor checks the formula as you type: under the box you immediately see “Expression is valid” or the specific error, and which fields the expression depends on.

The Problems panel

The Problems button in the header carries a count of findings and opens the live Design problems report broken down into “Errors · Warnings · Info”. The builder continuously scans the draft and highlights gaps, for example:

the version has no forms or no visits;
a form is empty — it has no fields;
a form is not assigned to any visit (outside the SoA);
a choice field without a codelist;
the minimum is greater than the maximum;
a visit without forms, a codelist without options, a codelist not used by any field.

Each item leads to the problem: a finding inside the design opens the element in the builder (Show in the builder), and a schedule finding offers Open the SoA matrix. It pays to handle them while you build: the same checks are built into submitting the version for review — a design with errors does not leave the draft.

Form preview: try it out before publication

The Preview button on the Design page opens the form the way the coordinator will see it and lets you enter values and watch how the form reacts.

Skip logic (fields appear and hide by condition), derivations (computed fields recalculate instantly) and edit checks work — the ones that fire are listed under the form.
Format errors are highlighted as in real entry.
All of it is a dry run: the preview saves nothing, raises no queries and writes nothing to the audit trail. A banner above the form reminds you: “This is a preview — nothing is saved”. You can reset what you entered and start again.
A log (repeating section) is shown as a single row — in real entry there will be several.

CRF languages: single-language design by default

A multilingual CRF is needed by a minority of studies, so by default there is none: a new draft’s language list is empty, and an element’s name is the very text the site will see. There is no separate “Translations” link then.

Multilingual mode is opt-in: More (⋯) → CRF languages — tick the languages the CRF is collected in and save. After that a Translations screen appears in the design navigation, and publishing the version starts requiring an approved translation for each ticked language. While no languages are declared, the translation gate at publication is empty.

The ⌘K command palette

⌘K (or Ctrl+K) opens the command palette: create a form, section or field, insert a template, open Problems, the annotated CRF or export — without leaving the keyboard. Start typing the name of a field, form or list — the palette finds it anywhere in the version and opens it highlighted.

Review comments

At the bottom of the inspector lives the Review comments thread: a reviewer leaves a comment on the selected element (or on the version as a whole) without editing the design — commenting works in read-only mode too, on a draft and on a version submitted for review (permissions designcomment.read / designcomment.write). The author answers with edits and clicks Resolve on the comment; resolved comments turn grey and remain as review history. Unresolved comments show as a count on the Design page and give a warning next to the approve button — a warning, not a ban: the decision stays with the approver.