Editing

Overview

Protocol editing allows you to modify draft protocols and create new versions of published protocols. Understanding when to edit a protocol versus creating a new version is critical for maintaining data integrity and regulatory compliance.

Only draft protocols can be edited directly. Published protocols are immutable—to make changes, you must create a new draft version, modify it, and publish the new version. This versioning approach ensures that completed tasks always reference the exact protocol definition used for data collection.

For a complete understanding of how protocol versioning works and why it matters, see Protocol Versioning.

Editing vs. Versioning

Edit a draft protocol when it hasn't been published yet and no tasks have been created.

Create a new protocol version when the protocol is already published or tasks exist. Published protocols are immutable—you cannot edit them directly.

For a complete understanding of protocol versioning, see Protocol Versioning.

Editing Draft Protocols

Draft protocols can be edited at any time until they are published.

Editing Protocol Notes

To edit a draft protocol's Notes:

1. Navigate to the group level in Flywheel
2. Click the Protocols tab
3. Locate the draft protocol in the list (status shows "Draft")
4. Click the ellipsis menu (Protocol Actions) and select Edit Notes
5. Click Edit in the toolbar
6. Modify the protocol Notes:
   • Description: Update the description (maximum 500 characters)
7. Click Save

Changes to Notes are saved immediately and do not require republishing.

Editing Form Schema

To edit the form schema in a draft protocol:

1. Open the draft protocol as described above
2. Click Open Editor icon in the row

1. The Monaco editor opens with the current JSON
2. Make your changes to the form schema:
   • Add, remove, or modify form fields in the fields array
   • Update field label and helperText properties
   • Change validation rules using JsonLogic
   • Change requiredWhenVisible property on individual fields
3. Click Save to check for errors, making any corrections and then save.

The draft protocol retains the same protocol label but incorporates your changes.

Editing E-Signature Requirements

To change e-signature settings in a draft protocol:

1. Open the draft protocol for editing
2. Modify the esignature_config section:
   • Change the required flag to true or false
   • Add, remove, or modify signature reasons
3. Validate and save the protocol

Editing Completion Tags

To change automatic tagging behavior:

1. Open the draft protocol for editing
2. Modify the completion_tags array
3. Add or remove tags as needed
4. Ensure tags follow Data Tag naming conventions
5. Validate and save the protocol

Creating a New Protocol Version

When you need to modify a published protocol, you create a new draft version based on the published version.

Step 1: Create and Edit Draft Version from Published Protocol

1. Navigate to the group level in Flywheel
2. Click the Protocols tab
3. Locate the published protocol you want to revise
4. Click the Draft New Version icon for the protocol

1. The Monaco editor opens with the current JSON
2. Make your changes to the form schema:
   • Add, remove, or modify form fields in the fields array
   • Update field label and helperText properties
   • Change validation rules using JsonLogic
   • Change requiredWhenVisible property on individual fields
3. Click Save to check for errors, making any corrections and then save.
4. A new draft version is created based on the published protocol

The new draft version:

• Has the same protocol label as the published version
• Can be edited freely
• Does not affect existing tasks or the published version

Step 2: Publish the New Version

1. Click Publish
2. The new version receives the next sequential version number (v2, v3, etc.)
3. The new version becomes immediately available for creating new tasks
4. Existing tasks continue using their original protocol version

Impact on Existing Tasks

Protocol versions ensure that existing tasks always use the protocol version they were created with, regardless of new versions you publish.

For a detailed explanation of how protocol versions affect tasks in different states and mixed-version scenarios, see Protocol Versioning.

Key Points for Editors:

• Publishing a new protocol version does NOT update existing tasks
• To use a new version, you must delete old tasks and recreate them
• Tasks using different versions can coexist safely

Deleting Draft Protocols

You can delete draft protocols that are no longer needed.

To delete a draft protocol:

1. Navigate to the Protocols tab
2. Locate the draft protocol
3. Click the ellipsis menu (Protocol Actions)
4. Select Delete Draft
5. Confirm deletion in the dialog

Important Notes:

• Only draft protocols can be deleted
• Published or archived protocols cannot be deleted (they may be referenced by tasks)
• If you delete a draft version, you can create a new draft version from the published version

Best Practices for Protocol Editing

Version Management

• Use meaningful version notes: Document what changed and why in the protocol description or notes
• Maintain version history: Keep published versions archived rather than deleting them
• Plan version timing: Publish new versions at study milestones to minimize confusion
• Communicate changes: Notify all readers when new protocol versions are published

Making Changes

• Test thoroughly before publishing: Use test projects to validate changes before production use
• Make incremental changes: Avoid large, sweeping changes that make versions hard to compare
• Preserve backward compatibility when possible: If feasible, design changes that do not drastically alter data structure
• Document rationale: Explain why changes were necessary for future reference

Managing Multiple Versions

• Archive obsolete versions: Archive old versions after all tasks using them are completed
• Track which versions are in use: Monitor which protocol versions have active tasks
• Communicate version requirements: Clearly specify which version sites should use for new tasks
• Plan transition periods: Allow time for readers to complete old tasks before focusing on new versions

Multi-Site Studies

• Coordinate version releases: Ensure all sites use the same protocol version for the same study phase
• Communicate ahead of version changes: Give sites advance notice before publishing new versions
• Provide training on changes: Ensure readers understand what changed in new versions
• Monitor version adoption: Track which sites have transitioned to new versions

Common Editing Scenarios

Adding a New Optional Field

Scenario: You need to collect additional data that was not in the original protocol.

Approach:

1. Create a new draft version from the published protocol
2. Add the new field object to the fields array with appropriate key, type, label, and options properties
3. Set requiredWhenVisible: false or omit it (field is optional by default)
4. Add the field key to the defaults object with an appropriate default value
5. Test the new version
6. Publish as v2

Result: New tasks use v2 with the additional field. Existing tasks use v1 and do not show the new field. Data analysis must account for the field being absent in v1 tasks.

Correcting Validation Rules

Scenario: A field's min/max range is incorrect and allows invalid data.

Approach:

1. Create a new draft version
2. Update the field's validation array with JsonLogic rules to enforce correct min/max ranges
3. Update the helperText to indicate the valid range
4. Test with both valid and invalid values
5. Publish as v2

Result: New tasks enforce correct validation. Review data from v1 tasks for values outside the correct range.

Removing a Field

Scenario: A field is no longer needed or was included by mistake.

Approach:

1. Create a new draft version
2. Remove the field object from the fields array
3. Remove the field key from the defaults object
4. Test to ensure form renders correctly
5. Publish as v2

Result: New tasks do not show the removed field. Data from v1 tasks includes the field. Ensure task report and analysis scripts handle the field's presence or absence.

Changing Field Type

Scenario: A field was defined as text but should accept only numeric values with validation.

Approach:

1. Create a new draft version
2. Keep the field type as text (numeric validation can be applied to text fields)
3. Add a validation array with JsonLogic rules to enforce numeric values and min/max ranges
4. Update the helperText to indicate the field expects numeric input
5. Test extensively with both valid numeric and invalid non-numeric inputs
6. Publish as v2

Result: New tasks use the correct type. Data from v1 tasks contains the field as the original type. Data analysis must handle type differences when combining data from both versions.

Troubleshooting

Cannot Edit Protocol

Possible causes:

• Protocol is published (not draft)
• You lack group read/write permissions
• Protocol is archived

Solutions:

• Create a new draft version if the protocol is published
• Request group read/write permissions from your administrator
• Restore archived protocols to published status before creating new versions

Changes Do Not Appear in Tasks

Possible causes:

• Tasks reference the old protocol version
• Draft changes were not published
• Browser cache is showing old form

Solutions:

• Verify which protocol version the task uses (check task details)
• Publish the draft protocol if changes should be used
• Refresh the browser and clear cache

Validation Fails After Editing

Possible causes:

• JSON syntax errors introduced during editing
• Removed required schema properties
• Invalid field types or configurations

Solutions:

• Use the Monaco editor's error highlighting to locate problems
• Validate incrementally after each change to isolate issues
• Compare with the previous version to identify what changed

Related Topics

• Protocols Overview
• Protocol Versioning
• Creating Protocols
• Creating Tasks