What this is, and who it is for
A rule is a study-level check that can look across forms and visits, unlike a field's own validation, which sees only its own value. "ALT above three times the upper limit of normal", "diastolic is not below systolic", "the visit date is after the consent date" are rules. Rules are written by the eCRF Designer in Build, are pinned into the version, and go live with it; changing a rule on a Live study is an amendment.
The checks every field already has (required, minimum and maximum, normal range, format, dates) are not rules: they are set on the field. See Validation, edit checks and their severities.
Where to find it
Study → Build → Visit–Form Mapping → Rules, in the Build workbench of a version that is in Build. The rules manager lists the version's rules; New rule opens the editor. Reading rules needs workflow.design, study.write or form.read; writing them needs workflow.design or study.write.
Held by: Organization Admin, Project Manager, eCRF Designer (workflow.design or study.write).
Once a version is Live its rules are read-only in the live design views; the same rules run in UAT and in Live.
What you can do
- Open the rules manager and choose New rule.
- Give it a code and a name (and, if you wish, a description) and choose its type, trigger and action.
- Build the when condition: pick a variable (a visit · form · field), an operator and a value or another field. Combine conditions with AND or OR; groups can be nested.
- Choose what happens and, for a block, a query or a flag, where: the field the message attaches to (the action's target).
- Save. A rule is active from the start; you can disable it, re-enable it or retire it.
One rule for every visit
A variable's visit can be ANY: it then means the visit of the record being saved. When a lab form is saved at visit V, the rule reads with V in that place, in its conditions and in its target, so one rule ANY · LB · ALT is above 168 → raise a query on ANY · LB · ALT checks ALT at every visit and puts each query on that visit's own record. The variable list offers ANY · form for each form collected at more than one visit. A condition may mix ANY with a named visit (this visit against baseline).
Every option
Anatomy of a rule
| Part | What it is |
|---|---|
| Code and name | Identify the rule; the code is what an automatic query shows as its name |
| Description | Optional |
| Type | edit_check, validation, derivation, conditional, safety, eligibility. Descriptive: it classifies the rule for review. What decides behavior is the trigger and the action |
| Trigger | When it runs |
| When | An AND/OR tree of conditions over fields, which may reference other forms and visits |
| Action | What happens when the condition holds, and its target |
| Status | active, disabled, retired |
Conditions
A condition compares a field with a value or with another field of the same participant. The operators are: eq (equals), neq, gt, gte, lt, lte, contains, starts_with, ends_with, in, not_in, empty, not_empty. Comparing with another field is available for eq, neq, gt, gte, lt, lte, contains, starts_with and ends_with, and the builder offers only fields that can be compared (numbers with numbers, dates with dates, text with text). A comparison is false when either value was never entered, so a rule fires only on data that exists. A rule that compares a field with itself is refused.
Triggers
| Trigger | When it runs | Runs today? |
|---|---|---|
on entry (on_entry) | As a field is entered | Yes |
on save (on_save) | When the record is saved | Yes |
at enrollment (at_enrollment) | When a participant is enrolled | No |
on schedule (on_schedule) | On a timer | No |
Actions
| Action | What it does | Runs today? |
|---|---|---|
block (block) | Refuses the save of the target record, with a message | Yes |
warn (warn) | Saves, and shows a warning | Yes |
raise query (raise_query) | Opens an automatic query at normal priority on the target field | Yes |
flag (flag) | Opens an automatic query at high priority on the target field | Yes |
derive (derive) | Calculates and writes a value | No |
show form (show_form) | Makes a form appear dynamically | No |
A block, a query and a flag act on one record, so they must name a target (visit, form, field). They apply to the record the target names and to no other: a rule whose block targets another form is applied when that form is saved, and never refuses an unrelated one.
The safeguard that matters
You cannot save an active rule whose trigger or action would never run, or whose block, query or flag has no target. The editor refuses it with the reason. This is deliberate: a safety or eligibility rule that looks active but never fires is worse than none, because it creates false assurance that a check is in place. If you need a calculation or a form that appears on a condition, use a field formula or conditional visibility on the form (see Formulas and calculations and Conditional logic), which do run.
What happens when rules fire on save
In order, on every save of a record:
- The rules run before anything is stored.
- Any block that targets the record being saved stops the save; the record is unchanged and the message names the rule. A block that targets another record is applied when that record is saved.
- Warn results are returned with the successful save.
- Raise query and flag results for the record being saved join the built-in field checks in one reconciliation pass, so a rule's query and a validation query open and close together and never contradict each other: a query closes itself when its check stops firing, as long as nobody has answered it (Work with queries).
What the system records
A rule's creation and each change are in the audit trail (rule.created, rule.updated) with who and when; a status change is recorded with it. Rules are never deleted: a retired rule is immutable and kept for audit. Every query a rule opens carries the rule's code, so the thread shows which rule raised it.
What you cannot do, and why
- Save a rule that can never fire (an unexecuted trigger or action, or no target): see the safeguard above.
- Edit a retired rule. It is immutable; make a new one.
- Delete a rule. It is retired instead, and kept.
- Change a rule on a Live study without an amendment. The design is sealed once a version is Live; a change goes through a new version, UAT and sign-off.
- Ask a rule to look at a value nobody entered. Such a comparison is false by design.
Lifecycle
| From | Can move to |
|---|---|
| active | disabled, retired |
| disabled | active, retired |
| retired | (none: final) |
Compliance Q&A
No. Rules are frozen into the version's snapshot when it is submitted to UAT, tested in a cycle, signed off by three people and released; a change to a Live rule is a new version that goes through the same gates, and a retired rule is kept. The creation and every change of a rule is in the audit trail.
Evidence: server/src/modules/study/rules/domain/rule-lifecycle.tsserver/src/modules/study/versions (frozen snapshots, ADR 0012)audit events rule.created and rule.updated
No. An active rule whose trigger or action the engine does not run, or whose block, query or flag has no target, cannot be saved. Limits: at enrollment and on schedule triggers and the derive and show form actions exist in the data model and are refused, so there is no rule-driven derivation or dynamic form; use a formula or conditional visibility on the form.
Evidence: server/src/modules/study/rules/domain/rule-lifecycle.ts (unexecutableReason)
Related
Design forms · Validation, edit checks and their severities · Work with queries · Enter visit data · Statuses