Skip to content

Versioning

Overview

Protocol versioning is a core feature of Tasks Manager that ensures data integrity and regulatory compliance throughout your clinical trial. Each time you publish a protocol or create a new version, the system assigns an immutable version number. Tasks reference specific protocol versions, creating an unbreakable link between collected data and the exact form schema, validation rules, and viewer configuration used during data collection.

This versioning approach guarantees that you can always reproduce the exact data collection environment for any completed task, regardless of how many times you have revised the protocol since then. For regulatory submissions and audits, this traceability is essential.

For step-by-step instructions on editing protocols and creating new versions, see Editing Protocols.

Why Protocol Versioning Matters

Data Integrity

Problem Without Versioning: If protocols were editable, you could not determine which version of a form was used to collect historical data. A field that existed when data was collected might be removed later, making the data appear incomplete or invalid.

Solution With Versioning: Each task references a specific protocol version. Even if you publish ten new versions, tasks created with version 1 always reference version 1, preserving the exact context in which data was collected.

Regulatory Compliance

Clinical trial regulations require demonstrating that data collection procedures were followed consistently and that any changes were tracked and justified. Protocol versioning provides:

  • Audit Trail: Every protocol version is timestamped and tracked
  • Immutability: Published versions cannot be edited or deleted
  • Traceability: You can trace back to the exact protocol definition for any completed task
  • Change Documentation: Version comparison shows exactly what changed between versions

Study Evolution

Studies evolve over time. You may need to:

  • Add new data fields as the study protocol is amended
  • Correct validation rules that allowed invalid data entry
  • Update viewer configurations for consistency across sites
  • Remove fields that proved unnecessary or confusing

Protocol versioning allows you to make these changes while preserving data integrity for previously collected data.

How Versioning Works

Version Numbering Scheme

Protocol versions use sequential numbering: v1, v2, v3, and so on.

First Publication:

When you publish a protocol for the first time:

  1. The protocol receives version number v1
  2. The protocol becomes immutable (cannot be edited)
  3. The protocol is available for creating tasks
  4. The protocol appears in the protocol selector with "v1" appended to its name

Subsequent Versions:

When you create and publish a new version:

  1. You create a draft version based on a published version
  2. You edit the draft version
  3. When you publish the draft, it receives the next sequential version number (v2, v3, etc.)
  4. The new version becomes immediately available for new tasks
  5. Old versions remain available for existing tasks (whether completed or in any other state)

When New Versions Are Created

New versions are created manually by users, not automatically by the system.

You create a new version when:

  • You need to modify a published protocol
  • You want to add, remove, or change form fields
  • Validation rules require updating
  • Viewer configuration needs adjustment
  • E-signature requirements change

The system does not automatically create versions when protocols are used or when tasks are completed.

Version Immutability

Once a protocol version is published, it becomes immutable:

  • Cannot be edited
  • Cannot be deleted
  • Cannot have its version number changed
  • Remains permanently available for audit and reference

This immutability ensures that tasks always reference the exact protocol definition used during data collection.

Version Dependence

Only the latest published version is available for task creation:

  • The prior version v1 remains for prior tasks while the latest published v2 is used for new task creation
  • You can have one published versions active at a time
  • Tasks reference their version permanently, regardless of version status changes

Task-Protocol Relationships

Understanding how tasks and protocol versions relate is essential for managing your study.

Tasks Reference Specific Versions

Key Principle: Each task references the exact protocol version specified at task creation. This reference never changes.

When Tasks Are Created:

  1. You select a published protocol version from the protocol selector
  2. The system creates tasks with a permanent reference to that version
  3. The tasks always use that version's form schema and validation rules

Implications:

  • If you create 100 tasks using "Tumor Assessment v1" and later publish "Tumor Assessment v2", the 100 tasks continue using v1
  • Publishing a new version does not retroactively update existing tasks
  • Each task's form and validation rules are determined by its protocol version

Version Consistency Guarantees

The protocol version reference guarantees that:

  • Form fields match: The task always displays the fields defined in its protocol version
  • Validation rules apply: The same validation rules used at task creation apply when completing the task
  • Data structure is stable: Export formats match the protocol version's field definitions

Tasks in Different States

To-Do Tasks:

  • Reference the protocol version specified at creation
  • Not affected by new protocol versions
  • If you need them to use a new version, you must cancel them and recreate them

In Progress Tasks:

  • Use the protocol version they were created with
  • Readers see the form and viewer configuration from that version
  • Publishing new versions does not affect work in progress

Completed Tasks:

  • Permanently reference their original protocol version
  • Form responses are stored with the protocol version identifier
  • Task Reporting records the specific version used

Mixed Version Scenarios

It is common and acceptable to have tasks using different protocol versions simultaneously:

Example Scenario:

  1. You create 200 tasks using "RECIST Assessment v1"
  2. Readers complete 100 tasks
  3. You discover a validation error and publish "RECIST Assessment v2"
  4. You create 50 new tasks using v2

Result:

  • 100 completed tasks reference v1
  • 100 to-do/in-progress tasks reference v1
  • 50 new tasks reference v2
  • All three groups coexist correctly
  • Data export identifies which version each task used