Skip to content

Overview

Overview

Protocols define standardized data collection requirements for clinical trial imaging studies. Each protocol includes a form schema for structured data entry and optional viewer configuration for consistent image display. By standardizing what data is collected and how images are reviewed, protocols ensure data quality and consistency throughout your study.

Protocols are managed at the group level in Flywheel, allowing you to use the same protocol across multiple projects within a study. Each protocol can have multiple versions, and tasks always reference a specific, immutable version to guarantee consistent data collection even as protocols evolve.

Why Protocols Matter

In clinical trials, data quality and consistency are paramount. Protocols address several critical needs:

Standardization: All readers use the same form fields, validation rules, and viewer settings, reducing variability in data collection.

Reproducibility: Tasks reference specific protocol versions, so you can always reproduce the exact data collection environment used for any task.

Compliance: Protocol versioning and immutability support regulatory requirements for clinical trial data integrity.

Multi-Site Studies: All participating sites use identical protocols, ensuring consistent data collection across locations.

Quality Assurance: Standardized protocols make it easier to identify and correct data quality issues.

Protocol Components

Each protocol consists of several components that work together to define the data collection workflow.

Form Schema

The form schema defines what data readers collect when completing tasks. Form schemas are written in JavaScript Object Notation (JSON) format and specify:

  • Form fields: What questions readers answer (text, numbers, boolean, enumerations)
  • Field types: Data types and input controls for each field
  • Validation rules: Required fields, value ranges, and format constraints
  • Field organization: Grouping and ordering of fields in the form
  • Field labels and help text: User-facing descriptions of what data to enter

For example, a tumor assessment protocol might include fields for:

  • Tumor present (yes/no)
  • Longest diameter (numeric value in millimeters)
  • Overall assessment (enumeration: Complete Response, Partial Response, Stable Disease, Progressive Disease)

Electronic Signature (E-Signature) Requirements

Protocols can specify whether tasks require electronic signatures at completion. When enabled, e-signature requirements include:

  • E-signature required flag: Whether readers must sign when submitting the task
  • Reason list: Predefined reasons users select when signing (for example, "Initial read per protocol", "Adjudication read", "Quality assurance review")

E-signatures are only available when the Validated Instance module is enabled on your site.

Completion Tags

Protocols can specify Data Tags to automatically apply to containers when tasks are completed. Completion tags enable automation by:

  • Marking containers as "reviewed" or "processed"
  • Triggering downstream workflows via gear rules
  • Tracking which containers have completed specific assessments

For example, a protocol might tag containers with "tumor-measured" when readers complete tumor measurement tasks.

Protocol Lifecycle

Protocols move through three states during their lifecycle:

Draft

Definition: The protocol is being created or edited and is not yet available for task assignment.

Characteristics:

  • Can be edited freely
  • Can be validated to check JSON syntax
  • Cannot be used to create tasks
  • Only visible to users with group read/write permissions

Common Uses:

  • Initial protocol creation
  • Testing form schemas before deployment
  • Revising published protocols

Published

Definition: The protocol has been validated and is available for task assignment.

Characteristics:

  • Cannot be edited (immutable)
  • Available for creating tasks in all projects within the group
  • Visible to all users with group read permissions
  • Can be archived when no longer needed
  • Can be used as the basis for creating new draft versions

Common Uses:

  • Active data collection in ongoing studies
  • Reference protocols for completed studies
  • Standard operating procedures for routine assessments

Archived

Definition: The protocol is no longer available for new task assignments but remains accessible for completed tasks.

Characteristics:

  • Cannot be edited
  • Not available for creating new tasks
  • Existing tasks using this protocol version can still be completed
  • Visible for audit trail and reporting purposes
  • Can be restored to published status if needed

Common Uses:

  • Protocols superseded by newer versions
  • Protocols for completed study phases
  • Historical protocols retained for regulatory compliance

Protocol Versioning

Protocols use version numbers to track changes over time. Each time you publish a new version of a protocol, it receives a new version number (v1, v2, v3, etc.).

Why Versioning Matters

Task Immutability: Tasks reference specific protocol versions. If you revise a protocol after creating tasks, existing tasks continue using the original version while new tasks use the new version.

Audit Trail: Version numbers allow you to determine exactly what form and viewer configuration were used for any completed task.

Regulatory Compliance: Regulators can trace back to the exact protocol version used for data collection at any point in the study.

Version Management

  • Only one draft version can exist at a time for a protocol label
  • Published versions are immutable and cannot be edited or deleted
  • You can have multiple published versions of the same protocol label
  • Each version is independently managed (published or archived)

See Protocol Versioning for detailed information about creating and managing protocol versions.

Group-Level Management

Protocols are created and managed at the group level in Flywheel's hierarchy, not at the project level. This design supports multi-project studies where the same protocol is used across multiple projects.

Benefits of Group-Level Protocols

Consistency Across Projects: All projects in the group can use the same protocol, ensuring identical data collection.

Centralized Management: Protocol administrators manage protocols in one location rather than duplicating them across projects.

Simplified Updates: Publishing a new protocol version makes it immediately available to all projects in the group.

Reduced Duplication: One protocol definition serves multiple projects, reducing maintenance effort.

Permissions Model

Protocol management follows Flywheel's group-level permissions:

  • Group Read/Write: Can create, edit, publish, and archive protocols
  • Group Read: Can view and download protocols but cannot modify them
  • No Group Access: Cannot see or use protocols from the group

Tasks created in a project can only use protocols from that project's parent group.

Protocol JSON Format

Protocols use JSON (JavaScript Object Notation) format to define form schemas and configuration. JSON is a widely-used, human-readable format for structured data.

Basic Protocol Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "form": {
    "title": "Tumor Assessment",
    "description": "RECIST 1.1 tumor measurement form",
    "defaults": {
      "tumor_present": false,
      "longest_diameter": 0
    },
    "fields": [
      {
        "key": "tumor_present",
        "type": "radio",
        "label": "Tumor Present",
        "options": [
          {
            "label": "Yes",
            "value": true
          },
          {
            "label": "No",
            "value": false
          }
        ]
      },
      {
        "key": "longest_diameter",
        "type": "text",
        "label": "Longest Diameter (mm)"
      }
    ]
  },
  "esignature_config": {
    "required": true,
    "reasons": [
      "Initial read per protocol",
      "Adjudication read"
    ]
  }
}

This example shows a complete protocol with:

  • form: Contains the form definition with title, description, defaults, and fields
  • esignature_config: Optional configuration for electronic signatures

For detailed technical specifications:

JSON Validation

Flywheel validates protocol JSON when you save or publish protocols. Validation checks:

  • Syntax correctness (proper brackets, commas, quotes)
  • Schema structure (required fields present)
  • Field type definitions (valid data types)

Invalid JSON prevents protocol publication, ensuring only valid protocols are used for tasks.

Editing JSON

Protocols are edited using the Monaco editor, which provides:

  • Syntax highlighting for easier reading
  • Auto-completion for common schema patterns
  • Real-time error detection
  • Line numbers for troubleshooting

You can also develop and test protocol JSON outside of Flywheel using standard JSON editors and validators.

Protocol Best Practices

Protocol Design

  • Keep forms concise: Include only essential fields to minimize reader burden
  • Use clear field labels: Readers should understand what data to enter without additional instructions
  • Provide help text: Add descriptions for fields where the label alone may be ambiguous
  • Use appropriate field types: Choose field types that match the data (enumerations for categories, numbers for measurements)
  • Define validation rules: Set min/max values, required fields, and format constraints to ensure data quality

Version Management

  • Test before publishing: Validate and test draft protocols thoroughly before publishing
  • Document changes: Use protocol notes to describe what changed between versions
  • Plan version timing: Publish new versions at study milestones to minimize mid-study protocol changes
  • Archive obsolete versions: Archive old versions to keep the protocol list manageable, but only after all tasks using them are completed

Multi-Site Studies

  • Publish protocols early: Ensure protocols are finalized before sites begin task assignments
  • Communicate protocol versions: Clearly specify which protocol version each site should use
  • Avoid mid-study changes: Protocol changes during active data collection can introduce variability
  • Train readers on protocols: Ensure all readers understand the protocol requirements before starting tasks

Protocols and Tasks

Understanding how protocols and tasks interact is essential for effective study management.

Protocol-Task Relationship

  • Each task references exactly one protocol version
  • The protocol version is set when the task is created and cannot be changed
  • Tasks created at different times may use different protocol versions of the same protocol label
  • Completed tasks retain their protocol association for audit trail purposes

Protocol Requirements for Tasks

Before creating tasks, ensure:

  • The protocol is published (not in draft status)
  • The protocol version is appropriate for the current study phase
  • All readers are trained on the protocol requirements
  • The protocol's viewer configuration matches your study needs

Using Multiple Protocols

Projects can use multiple protocols simultaneously:

  • Different assessment types (baseline vs. follow-up)
  • Different imaging modalities (magnetic resonance imaging [MRI] vs. computed tomography [CT])
  • Different reader roles (primary read vs. adjudication)

Filter tasks by protocol to manage different assessment types separately.