Amendments and subject migration
An amendment is a protocol change that lives as a new published design version. Already-enrolled
subjects do not move to it automatically: they are moved by an explicit migration operation per
a plan, and always — first the diff and the dry run, then execution. The migration console is the
Amendments item in the study navigation, in the “Closeout” group (the
subject.migrate_version permission); it can also be reached from the version history on the
design screen.
Migration plan: from and to
Section titled “Migration plan: from and to”A migration is described by a plan: source version → target.
- Source — the version subjects are on now (published or already superseded).
- Target — the new published version the sites work on.
Creating a plan only computes the diff and fixes the mapping by matching OID identifiers — by itself it changes nothing in the data. Plans go through statuses: Draft → Dry run complete → Running → Completed (or Failed).
Step 1. The diff of changes
Section titled “Step 1. The diff of changes”The plan classifies each change by its cost to existing data — from safe to breaking. The diff expands by class, each with a clear explanation of the consequences:
| Class | What it means for collected data |
|---|---|
| Cosmetic | Safe: labels, order, display. Data and signatures are not affected. |
| Additive | New fields, forms, visits. New fields arrive empty; existing data does not change. |
| Restrictive | Tightenings (required-ness, ranges, SDV): value conflicts are possible; signatures become invalid and will require re-signing. |
| Breaking | Fields disappear or change type — data is orphaned (goes to archive, nothing is deleted). Explicit mappings or a confirmation are required. |
Breaking changes are expanded by default — they cannot be skipped. Within each class you can see the specific changes by OID (e.g., “field became required”, “data type changed”, “visit added”).
Step 2. Dry run
Section titled “Step 2. Dry run”The dry run computes an impact report on real data — without a single change. It shows what the amendment will cost.
The summary counts:
| Metric | Meaning |
|---|---|
| Subjects in scope | how many subjects the migration will affect |
| Carried over | values move across as is |
| Transformed | values are converted per the mapping |
| Orphaned (archived) | values with no place in the new version go to archive (are not deleted) |
| New required empties | new required fields that will arrive empty |
| Forms becoming Incomplete | forms that will stop counting as complete |
A separate amber panel, “Migration consequences”, names the side effects directly:
- Signatures will be invalidated — how many signatures drop and will require re-signing;
- SDV will reset — how many verifications return to the “awaiting” status (and how many medical-review flags);
- Queries — how many queries will close and how many will open automatically.
There is also a per-subject breakdown — you can see exactly who will have “orphans” and signature losses.
Step 3. Execute
Section titled “Step 3. Execute”Execution switches subjects to the target version and applies the auto-effects by class (signature invalidation, SDV reset, auto open/close of queries) with a full audit.
-
Create a plan: choose the source and target versions. The plan will compute the diff.
-
Study the diff by class, and resolve blockers (if any).
-
Run the dry run and assess the impact report and the consequences panel.
-
Click “Execute migration” and confirm your understanding of the consequences — subjects are moved to the new version.
The operation is idempotent and resumable: if some subjects did not migrate (status “Failed”), a re-run finishes only the remaining ones — already-migrated subjects are not touched. The per-subject results (migrated / failed / skipped) are visible in the table.
The “who’s on which version” census
Section titled “The “who’s on which version” census”After migration, the plan shows a “Who’s on which version” block — how many subjects are on each design version. This is a direct answer to the question that, in legacy EDCs, was a source of irreproducible exports: you always have an exact, auditable picture of which subject sees which definitions.