How-toData manager

Set up edit checks

Edit checks are automatic data-quality control right at the moment of entry. They catch missing required fields, out-of-range values and logical inconsistencies between fields and forms. Checks are part of the design version: they are created in the Edit checks block of the Logic tab of the CRF builder.

Who and when

Data manager — the study designer (Study Builder) or the data manager with the “edit a design version” permission (studyversion.update). A check takes effect only after another person approves and publishes the version (studyversion.approve, studyversion.publish).

The task comes up while building the design — once the forms and fields exist — and during a protocol amendment, when a new check is needed.

Before you start

The design version is a Draft, and the form with the fields you need is already built.
Don’t write simple checks by hand: “field is required” and “value within range” are created by the system from the field’s Required and Min / Max value properties (see More details). Only rules that link different fields and forms are written by hand.
Decide what should happen when the check fires: accept the value and raise a query (almost always) or reject the value (only for the impossible).

Steps

0:000:00

Checks in the builder: a query accepts the value, a block rejects the impossible.

In the builder, open the form the rule belongs to and go to the Logic tab.
In the Edit checks block click Add check. The rule belongs to the open form: you don’t pick the form separately, and the builder assigns the rule’s data name (OID) itself.
Build the condition in the The check fires when block: rows of “field — condition — compare with”. Several rows are combined by choosing All conditions are met or Any condition is met. True means the check fired.
Make sure the condition shows “Expression is valid”, and try the rule out in the Try it on values block: enter sample values — you’ll see “Fires — a query would open” or “Does not fire for these values”.
Fill in the Message — the text a site operator sees when the check fires.
Choose What happens when it fires:
- Open a query — the value is saved and a query opens against it;
- Block entry — the value is not accepted;
- Info query — a soft query of informational severity.
For a query, set Query the field if needed — which field the auto-query attaches to (by default, the first field of the expression).
Click Create.

An existing rule is edited in place — clicking it in the Edit checks block opens the editor (Edit check); you can delete it there too.

Compare with another field or form

In a condition row, under Compare with, choose a field of this form instead of a value (number with number, date with date), or a field of another form — picking the Form, Form field and Visit. This is how “end date is not before start date” is built with the mouse, no formulas. For date fields the conditions read as words: is before · is not after · is after · is not before.

Write the rule as a formula

Whatever the visual builder cannot express (arithmetic, parentheses) is written in Advanced mode (formula) in the expression language:

num(HR) < 40 and is_empty(ref('F.DM', 'SEX'))

Fields of the open form are addressed directly by data name; the main functions are is_empty(...), num(...), days_between(...), ref('FORM', 'FIELD') (the three-argument form pins the visit). The full reference is in Skip logic and derivations.

Set the severity

The Advanced: severity and action link reveals Severity (“Info”, “Warning”, “Error”) and Action on firing (“Open a query” or “Block the save”) separately.

What happens

The rule is saved in the version draft; its creation is written to the audit trail (“Check created” in the design change log).
After the version is published, the rule runs on every value save:
- query — the value is saved and a query in the Open status is opened on the field automatically; when the data is corrected the auto-query closes itself, and repeated firing does not create a second query on the same field;
- block — the value is not saved (a 422 response), the field is highlighted and the rule’s message is shown; the whole write is rolled back.
Changing a rule after publication means a new design version.

If it doesn’t work

No “Add check” button — the version is not a draft or you don’t hold studyversion.update; the builder is open read-only.
“Create” is disabled — the condition or the Message is empty, or the expression has an error.
An error under the condition, e.g. “Field “…” is not found on the form” — the rule refers to a field that does not exist; pick the field from the list or fix the data name.
“The rule reads other forms only — pick the field of this form where the query should open.” — the query has nowhere to sit: set Query the field.
“The sandbox works for rules built visually.” — a rule in formula mode has no value try-out; test it in the preview.
The version can’t be submitted for review — a rule with a syntax error or a reference to a non-existent field passes neither import nor submission for review; open Problems.

Set up skip logic and derivationsDisplay conditions and the full expression-language reference.

Build forms in the CRF builderThe Logic tab, the property inspector and the form preview.

QueriesWhat queries opened by checks look like and how they are resolved.

Publish a version and launchChecking the design and handing the version over for review.

More details

System checks

The platform derives system checks itself from field properties:

a field is marked Required → a “field must not be empty” check;
a numeric field has a range (Min / Max value) → a “value must be within range” check; Range violation sets its behaviour — soft (record and raise a query) or hard (reject the value).

On the Logic tab they are gathered in the From field properties block — read-only. To change such a check, edit the field property in the inspector (untick Required or change the range), and the check changes with it.

Two behaviours: block and query

Checks run on every value save — quality control is built into the entry flow rather than deferred to a cleaning stage.

Type	What happens on entry	When to use
Block (stop)	The value is not saved, the field is highlighted and the rule’s message shown	Only for values that are certainly impossible: a future date, a value outside physical limits
Query	The value is saved, but the system automatically opens a query on the field	For anything questionable: a suspicious but possible value that needs clarification by the site

The platform’s philosophy: a block stops only what cannot be true. Everything else is a query. Data from the source matters more than an immediately “clean” screen: if a value is odd but possible, it should be accepted and a managed query opened, rather than forcing the coordinator to “fit” the entry to the rule. More on working with queries — in Queries.

Cross-field and cross-form rules

These are rules that cannot be derived from a single field: “if A, then B is required”, “end date not before start date”, “heart rate below 40 while the reason field is empty”. A rule is anchored to the open form — field names resolve relative to it; fields of another form are read with ref(). How “true” in a check differs from “true” in a display condition — see Skip logic and derivations.

Testing against data

The quickest way to make sure a rule catches what it should is to live through the form in the preview: enter values, the checks that fire are listed right under the form, and nothing is saved.

Checks can also be run against a real subject’s data — with the Check data… button on the subject page, for example to assess a new amendment rule on data already collected. Such a run only shows which checks would fire — it does not open queries and does not change data.