Run a protocol amendment

An amendment is a protocol change that lives as a new published design version. Subjects already enrolled do not move to it automatically: they are moved by an explicit migration operation following a plan — always the diff and a dry-run first, then execution.

Who and when

Data manager — the “move subjects to a new design version” permission (subject.migrate_version). The new design version is created and published by holders of version permissions (studyversion.*), with review and approval by another person.

The task comes up when the protocol changes after enrollment has started: fields or visits are added, checks are tightened, answer lists change.

Before you start

• The new design version has been created, reviewed and is Published — see Publish a version. An amendment needs two versions: the one subjects are on now, and the new published one.
• Sites that should create new subjects on the new version have been moved to it — see Add sites.
• Open Setup → the Amendments tab (/studies/{studyId}/amendments). If there is only one published version, the screen says “An amendment needs a second design version”.

Steps

0:000:00

Subject migration to a new design version: the classified diff, the dry run and audited execution

1. Create a plan. Click New plan, choose the Source version (from), the Target version (to) and the Plan scope — Whole study or Single site (staged rollout). Click Create plan. The plan computes the diff by OID identity and freezes the mapping — by itself this changes nothing in the data.

2. Review the diff (step “1. Version diff”). Changes are grouped by class — from cosmetic to breaking; breaking changes are expanded by default. If the plan shows Blockers, resolve them: set an explicit value mapping or choose another target version (with a new plan).

3. Run the dry-run (step “2. Dry-run (no changes)”) with Dry-run. Assess the impact report, the Consequences of the migration panel and the Per subject breakdown. No data changes.

4. Execute the migration (step “3. Execution”): click Execute migration. The “Execute the migration vX → vY?” dialog repeats the totals; tick “I understand the consequences: signatures are removed, SDV is reset, queries open and close automatically” and click Migrate.

5. Check the result. The Per-subject results table shows “Migrated”, “Failed” or “Skipped” for each subject; the Who is on which version block shows how many subjects are on each design version. While the plan is executing, click Refresh to see progress.

Finish subjects after a failure

If some subjects did not migrate (the plan is Failed), click Retry migration — a re-run only processes the remaining subjects; already migrated ones are untouched. A single subject can be moved with Migrate again in its row.

What happens

• Subjects switch to the target version; auto-effects are applied per change class: signatures are invalidated (Invalidated), SDV is reset to Pending, queries open and close automatically, and forms may go back to in progress.
• Values with no place in the new version go to the archive (“orphaned”) — nothing is deleted.
• Every auto-action is recorded in the audit trail with the system reason “migration vX→vY” — no separate reason field is required.
• The plan goes through Draft → Dry-run done → Executing → Completed (or Failed ).

If it doesn’t work

• “An amendment needs a second design version” — the new version is not published yet. Create and publish a draft on the Design screen (Go to Design).
• “Source and target versions must differ” — choose different versions.
• “Dry-run first: the cost of the amendment must be seen before executing” — execution is unavailable until a successful dry-run.
• “The plan has blockers — migration is unavailable” — a breaking change on live data without an explicit mapping, a removed code still used by data, an unpublished target version, etc. Resolve the blockers or create a plan for another target version.
• No “Amendments” tab, hint “You cannot move subjects to a new design version” — you lack subject.migrate_version. Ask your administrator.
• Totals don’t match the per-subject breakdown — the totals are from the last run; run the dry-run again.

Next

Publish a versionWhere the new design version for an amendment is created and published.

Sign dataRestrictive and breaking changes invalidate signatures.

Manage queriesMigration opens and closes queries automatically.

Lock the dataFinish the migration before the database close.

More details

An amendment starts in Design

The new version itself is created and published as a draft on the Design screen — with review and approval by another person (segregation of duties). The Amendments section comes into play when there are two versions: the one subjects are on now, and the new published one they need to move to.

The migration plan

A migration is described by a plan: source version → target version.

• Source — the version subjects are on now (published or already superseded).
• Target — the new published version the sites run on.

A plan can cover the whole study or a single site — for a staged, site-by-site rollout of the amendment.

1. Draftdry-run
2. Dry-run doneexecute
3. Executing
   • some subjects failed to migrateFailed
   all subjects migrated
4. Completed

Migration plan statuses: execution ends either with a full migration or with Failed; a re-run only processes the remaining subjects.

Change classes

The plan classifies every change by its cost to existing data:

Class	What it means for collected data
Cosmetic	Safe: labels, order, presentation. Data and signatures are unaffected.
Additive	New fields, forms, visits. New fields arrive empty; existing data does not change.
Restrictive	Tightening (requiredness, ranges, SDV): value conflicts are possible; signatures become invalid and require re-signing.
Breaking	Fields disappear or change type — data gets orphaned (moved to the archive, nothing is deleted). Explicit mappings or confirmation are required.

Within each class you see the specific changes by OID (e.g. “field became required”, “data type changed”, “visit added”).

Blockers. If breaking changes come without explicit mappings or confirmation, the plan shows blockers. Until they are resolved, execution is unavailable: without explicit mappings or confirmation the platform does not rewrite data. A removed code that is used by data requires an explicit “old → new” mapping — silent reassignment is not allowed.

Dry-run: the impact report

The dry-run computes an impact report on real data — without a single change and shows what the amendment will cost.

Indicator	Meaning
Subjects in scope	how many subjects the migration affects
Carried over	values move as they are
Transformed	values are converted by the mapping
Orphaned (archive)	values with no place in the new version go to the archive (not deleted)
New required empty	new required fields that will arrive empty
Forms going back to in progress	forms that will no longer count as complete

The Consequences of the migration panel names the side effects directly:

• Signatures to be invalidated — how many signatures will drop and need re-signing;
• SDV to be reset — how many verifications return to “pending” (and how many medical review flags);
• Queries — how many queries will close and how many will open automatically.

The Per subject breakdown shows exactly who will get orphans and lose signatures.

Idempotency

The operation is idempotent and resumable: if some subjects did not migrate, a re-run only processes the remaining ones — already migrated subjects are untouched.

The “who is on which version” census

The Who is on which version block shows how many subjects are on each design version. It directly answers the question that in older EDCs was the source of irreproducible exports: you always have an exact, auditable picture of which subject sees which definitions.

Finish the migration before the database close

Unmigrated subjects are an obstacle to the final lock. Run the migration before the pre-lock review so the cleaning report comes out clean. See Lock the data.