Skip to content

Creating a Protocol

Overview

Creating a protocol is the first step in standardizing data collection for your imaging study. Protocols define the form readers complete in the V3 Viewer specifically for the task. Well-designed protocols ensure consistent, high-quality data collection across all readers and sites.

This guide walks you through creating a new protocol from initial setup through publication. Before starting, familiarize yourself with JavaScript Object Notation (JSON) format basics and determine what data your study needs to collect.

Prerequisites

Before creating a protocol, ensure you have:

Projects: A Group set up to reflect your study and within that one or more Projects set up to manage the study data.

Permissions: Group Read/Write permissions for the group where you want to create the protocol

Planning: A clear understanding of:

  • What data readers need to collect (form fields)
  • Required vs. optional fields
  • Validation rules (value ranges, format constraints)
  • Whether electronic signatures (e-signatures) are required
  • Viewer configuration preferences (if any)

JSON Knowledge: Basic familiarity with JSON format, or access to example protocols you can adapt

Start with Examples

If you are new to protocol creation, start with an example protocol from a similar study and modify it for your needs. This is faster and less error-prone than starting from scratch.

Creating a New Protocol

To create a new protocol:

  1. Navigate to the group level in your Flywheel hierarchy
  2. Click the Protocols tab
  3. Click Create Protocol
  4. The Create Protocol dialog opens

Protocols tab showing Create Protocol button

Step 1: Enter Protocol Metadata

In the Create Protocol dialog, provide basic information about the protocol:

  1. Protocol Name (required): Enter a descriptive name
    • Use clear names that indicate the assessment type (for example, "Tumor Measurement Protocol" or "Diabetic Retinopathy Grading")
    • Maximum 32 characters
    • Name can include spaces and special characters
  2. Protocol Type (required): Select "Read"
    • Currently, only Reader Task protocols are supported
    • Future versions may support additional protocol types (Query, Form, Upload)
  3. Notes (optional): Enter a brief description of the protocol's purpose
    • Explain what data the protocol collects and when it should be used
    • Maximum 250 characters
  4. Click Create to proceed to the protocol editor

Create Protocol dialog with metadata fields

Step 2: Define the Form Schema

The protocol editor opens with the Monaco editor for editing JSON. You can either:

  • Start New File will start with an empty schema so you can build it from scratch, or
  • Open File will allow you to upload an existing JSON file.

Start New File or Open File dialog

Starting with an Empty Schema (New File)

If starting from scratch, begin with this basic structure:

Empty protocol editor

1
2
3
4
5
6
7
8
9
{
 "form": {
  "title": "Your Protocol File",
  "description": "Form to test validation.",
  "defaults": {},
  "fields": []
 },
 "esignature_config": null
}

This is a valid protocol that can be saved as a draft, but is basically empty.

Minimal valid protocol with esignature_config

Required Property

The esignature_config property is required in all valid protocols. If e-signatures are not needed for tasks using this protocol, set it to null as shown above. It cannot be omitted.

Uploading an Existing Schema (Open File)

To upload a JSON file:

  1. Click Open File above the editor
  2. Select your JSON file from your computer
  3. The editor populates with the file contents
  4. Review and modify as needed

Step 3: Add Form Fields

Form fields are defined in the fields section of the JSON. Each field specifies its type, label, and validation rules.

Technical Documentation

For comprehensive technical details on building form schemas, including advanced field types, validation rules, and JSON schema specifications, see Protocol Form Technical Reference.

Basic Field Types

Radio Button (Yes/No) Field:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "key": "tumor_present",
  "type": "radio",
  "label": "Tumor Present",
  "requiredWhenVisible": true,
  "options": [
    { "label": "Yes", "value": "yes" },
    { "label": "No", "value": "no" }
  ]
}

Text Field with Validation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "key": "longest_diameter",
  "type": "text",
  "label": "Longest Diameter (mm)",
  "helperText": "Enter a value between 0 and 500",
  "requiredWhenVisible": true,
  "validation": [
    {
      "logic": {
        "and": [
          { ">=": [{ "var": "longest_diameter" }, 0] },
          { "<=": [{ "var": "longest_diameter" }, 500] }
        ]
      },
      "message": "Value must be between 0 and 500"
    }
  ]
}

Text Area Field:

1
2
3
4
5
6
{
  "key": "comments",
  "type": "text-area",
  "label": "Comments",
  "helperText": "Maximum 500 characters"
}

Dropdown (Select) Field:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "key": "assessment",
  "type": "select",
  "label": "Overall Assessment",
  "requiredWhenVisible": true,
  "options": [
    { "label": "Complete Response", "value": "CR" },
    { "label": "Partial Response", "value": "PR" },
    { "label": "Stable Disease", "value": "SD" },
    { "label": "Progressive Disease", "value": "PD" }
  ]
}

Complete Example

Here is a complete tumor assessment protocol:

 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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
{
  "form": {
    "title": "Tumor Assessment",
    "description": "RECIST 1.1 tumor measurement form",
    "defaults": {
      "tumor_present": "",
      "longest_diameter": "",
      "shortest_diameter": "",
      "assessment": "",
      "comments": ""
    },
    "fields": [
      {
        "key": "tumor_present",
        "type": "radio",
        "label": "Tumor Present",
        "requiredWhenVisible": true,
        "options": [
          { "label": "Yes", "value": "yes" },
          { "label": "No", "value": "no" }
        ]
      },
      {
        "key": "longest_diameter",
        "type": "text",
        "label": "Longest Diameter (mm)",
        "description": "Measure the longest diameter of the target lesion",
        "helperText": "Enter value between 0 and 500",
        "validation": [
          {
            "logic": {
              "and": [
                { ">=": [{ "var": "longest_diameter" }, 0] },
                { "<=": [{ "var": "longest_diameter" }, 500] }
              ]
            },
            "message": "Value must be between 0 and 500"
          }
        ]
      },
      {
        "key": "shortest_diameter",
        "type": "text",
        "label": "Shortest Diameter (mm)",
        "description": "Measure perpendicular to longest diameter",
        "helperText": "Enter value between 0 and 500",
        "validation": [
          {
            "logic": {
              "and": [
                { ">=": [{ "var": "shortest_diameter" }, 0] },
                { "<=": [{ "var": "shortest_diameter" }, 500] }
              ]
            },
            "message": "Value must be between 0 and 500"
          }
        ]
      },
      {
        "key": "assessment",
        "type": "select",
        "label": "Overall Assessment",
        "requiredWhenVisible": true,
        "options": [
          { "label": "Complete Response", "value": "CR" },
          { "label": "Partial Response", "value": "PR" },
          { "label": "Stable Disease", "value": "SD" },
          { "label": "Progressive Disease", "value": "PD" }
        ]
      },
      {
        "key": "comments",
        "type": "text-area",
        "label": "Additional Comments",
        "helperText": "Maximum 1000 characters"
      }
    ]
  },
  "esignature_config": null
}

Complete protocol example in editor showing all fields

Setting Required Fields

Fields with requiredWhenVisible: true must be completed before readers can submit the task. Required fields are marked with an asterisk (*) in the form.

In the example above, tumor_present and assessment are required fields.

Step 4: Add E-Signature Requirements (Optional)

If tasks using this protocol require electronic signatures (available with Validated Instance), configure the esignature_config section:

Technical Documentation

For comprehensive technical details on e-signature configuration, including validation rules, reason ordering, and best practices, see Protocol E-Signature Technical Reference.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "form": {
    "title": "Tumor Assessment",
    "description": "RECIST 1.1 tumor measurement form",
    "defaults": {},
    "fields": [...]
  },
  "esignature_config": {
    "required": true,
    "reasons": [
      "Initial read per protocol",
      "Adjudication read",
      "Quality assurance review",
      "Protocol deviation review"
    ]
  }
}

When required is set to true, readers must select a reason from this list when submitting tasks. The reasons are displayed in the order provided in the protocol, with the first reason appearing first in the dropdown.

Step 5: Add Completion Tags (Optional)

To automatically tag containers when tasks are completed, add a completion_tags array at the root level of the protocol:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "form": {
    "title": "Tumor Assessment",
    "description": "RECIST 1.1 tumor measurement form",
    "defaults": {},
    "fields": [...]
  },
  "esignature_config": null,
  "completion_tags": ["tumor-measured", "baseline-complete"]
}

Tags must follow Data Tag naming conventions (lowercase, no spaces, use hyphens or underscores).

Validating Your Protocol

The editor itself will highlight errors when the text file does not meet a valid JSON file. As part of the save, the system will validate your protocol JSON to check for errors.

To validate:

  1. Click Save in the protocol editor toolbar
  2. Review validation results:
    • Saved Success: Sucessful save and editor closes
    • File could not be saved: Indicates problems that must be fixed

Protocol validation errors

Common validation errors include missing required properties like esignature_config:

Validation error showing missing esignature_config

Publishing a Protocol

When your protocol is ready for use in production tasks:

  1. Click Publish Protocol
  2. Confirm publication in the dialog
  3. The protocol receives version number v1
  4. The protocol becomes immediately available for creating tasks in all projects within the group

Before publishing, you will see both draft and v1 versions:

Protocol versions showing draft and v1

After publishing, the v1 version becomes available for use:

Published protocol v1

What Happens When You Publish

  • The protocol version becomes immutable (cannot be edited)
  • The protocol appears in the protocol selector when creating tasks
  • Tasks can reference this specific protocol version
  • After creating a task, the assigned user can begin to fill out the form.

Publishing is Permanent

Published protocols cannot be unpublished or edited. To make changes, create a new draft version of the protocol. See Protocol Versioning for details.

Test Protocols in a dedicated group and or project

Test your protocol before publishing:

  1. Create a test task in a non-production project
  2. Open the task in the V3 Viewer
  3. Verify form fields display correctly
  4. Check field labels, help text, and validation rules
  5. Test required field enforcement
  6. Submit the test task and review the captured data

Form rendered in V3 Viewer showing all protocol fields

Form Design Best Practices

Field Organization

  • Group related fields: Keep logically related fields together
  • Order by workflow: Sequence fields in the order readers complete them
  • Place required fields first: Users should complete critical fields before optional ones

Field Labels and Help Text

  • Use clear, concise labels: "Longest Diameter (mm)" is clearer than "Diameter"
  • Add units: Include units in labels or help text (millimeters, centimeters, etc.)
  • Provide context in help text: Explain what data to enter or how to measure
  • Avoid jargon: Use plain language unless all readers share specialized training

Validation Rules

  • Set realistic ranges: Use min/max values that make clinical sense
  • Require essential fields: Mark fields required only if truly necessary for analysis
  • Use appropriate field types: Numbers for measurements, booleans for yes/no, enumerations for categories
  • Limit free text: Free text is harder to analyze; use enumerations when possible

E-Signature Configuration

  • Provide clear reasons: Readers should understand why they are signing
  • Use consistent reason text: Standardize across protocols for easier audit trail review
  • Order the reasons: Order the reasons in the protocol the way you want them presented
  • Document requirements: Inform readers which tasks require e-signatures before they begin work

Common Protocol Patterns

Tumor Assessment

 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
40
41
42
43
44
45
46
47
48
{
  "form": {
    "title": "Tumor Measurement - RECIST 1.1",
    "description": "Target lesion measurement and response assessment",
    "defaults": {
      "target_lesion_present": "",
      "longest_diameter": "",
      "assessment": ""
    },
    "fields": [
      {
        "key": "target_lesion_present",
        "type": "radio",
        "label": "Target Lesion Present",
        "requiredWhenVisible": true,
        "options": [
          { "label": "Yes", "value": "yes" },
          { "label": "No", "value": "no" }
        ]
      },
      {
        "key": "longest_diameter",
        "type": "text",
        "label": "Longest Diameter (mm)",
        "helperText": "Enter value in millimeters",
        "validation": [
          {
            "logic": { ">=": [{ "var": "longest_diameter" }, 0] },
            "message": "Value must be 0 or greater"
          }
        ]
      },
      {
        "key": "assessment",
        "type": "select",
        "label": "Response Category",
        "requiredWhenVisible": true,
        "options": [
          { "label": "Complete Response", "value": "CR" },
          { "label": "Partial Response", "value": "PR" },
          { "label": "Stable Disease", "value": "SD" },
          { "label": "Progressive Disease", "value": "PD" }
        ]
      }
    ]
  },
  "esignature_config": null
}

Quality Assessment

 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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
{
  "form": {
    "title": "Image Quality Check",
    "description": "Assess image quality and usability for analysis",
    "defaults": {
      "image_quality": "",
      "artifacts_present": "",
      "usable_for_analysis": "",
      "quality_notes": ""
    },
    "fields": [
      {
        "key": "image_quality",
        "type": "select",
        "label": "Overall Image Quality",
        "requiredWhenVisible": true,
        "options": [
          { "label": "Excellent", "value": "excellent" },
          { "label": "Good", "value": "good" },
          { "label": "Adequate", "value": "adequate" },
          { "label": "Poor", "value": "poor" },
          { "label": "Non-Diagnostic", "value": "non-diagnostic" }
        ]
      },
      {
        "key": "artifacts_present",
        "type": "radio",
        "label": "Artifacts Present",
        "options": [
          { "label": "Yes", "value": "yes" },
          { "label": "No", "value": "no" }
        ]
      },
      {
        "key": "usable_for_analysis",
        "type": "radio",
        "label": "Usable for Analysis",
        "requiredWhenVisible": true,
        "options": [
          { "label": "Yes", "value": "yes" },
          { "label": "No", "value": "no" }
        ]
      },
      {
        "key": "quality_notes",
        "type": "text-area",
        "label": "Quality Notes",
        "helperText": "Maximum 500 characters"
      }
    ]
  },
  "esignature_config": null
}

Troubleshooting

Protocol Does Not Appear in Task Creation

Possible causes:

  • Protocol is still in draft status (not published)
  • You are creating tasks in a project that does not belong to the protocol's group
  • You lack permissions to view the protocol

Solutions:

  • Publish the protocol if validation passes
  • Verify the project's parent group matches the protocol's group
  • Check your group permissions

Validation Fails

Possible causes:

  • JSON syntax errors (missing commas, brackets, quotes)
  • Invalid field types or schema structure
  • Required schema properties missing

Solutions:

  • Use the Monaco editor's error highlighting to locate problems
  • Copy JSON to an external validator to identify specific line numbers
  • Start with a working example and make small changes

Form Does Not Display as Expected

Possible causes:

  • Field types do not match intended display (for example, using string instead of number)
  • Required fields not properly specified
  • Enumeration values malformed

Solutions:

  • Review field type definitions carefully
  • Test the protocol in a development environment before publishing
  • Compare with working examples from similar protocols