Building a Protocol with the Protocol Builder

Overview

The Protocol Builder creates a reader task protocol in a guided dialog with four steps, instead of in the protocol JSON. Use it to set up the protocol's general settings, annotation labels, viewer configuration, and form, then review and publish the protocol.

Prerequisites

• A group that reflects your study, with one or more projects for the study data
• Group Read/Write permissions for the group where you want to create the protocol
• A plan for the form readers complete, the annotation labels they use, and whether the protocol requires electronic signatures

Start a New Protocol

1. Navigate to the group where you want to create the protocol.
2. Click the Protocols tab.
3. Click Create Protocol.

The Create New Protocol dialog opens at the General step. The dialog header shows the four steps in order: General, Labels, Form, and Review & Publish.

Use Next Step and Previous Step to move between steps. You cannot move to the next step until you complete the required fields on the current step. Click Save Draft at any step to save your work and finish later.

Step 1: General

1. Enter a Name of up to 32 characters.
2. Select the protocol Type:
   • Read: Creates one Reader Task per container.
   • Double Read + Adjudication: Creates two Reader Tasks and one Adjudicator Task per container. See Creating Double Read with Adjudication Tasks.
3. Optionally, enter a Description of up to 250 characters.
4. To require readers to sign the task when they submit it, turn on Require E-Signature, then add the signature reasons readers can select. Drag the reasons to change their order. For more information about e-signatures, see E-Signatures for Tasks Manager.
5. Optionally, in Completion Tags, search for or create the tags that Flywheel applies to the task's parent container when the task is completed. Use completion tags to trigger downstream automation, such as gear rules and Data Views.
6. Click Next Step.

Step 2: Labels

The Labels step defines the annotation labels readers use in the V3 Viewer, and the viewer configuration.

Add annotation labels

1. To start from labels you already have, select Import from Existing. To start with an empty table, select Add New Labels.
2. For each label, enter the Annotation Label and Key, then select a Color in the color picker.
3. Click Add Label to add a row. Delete or drag rows to change the labels and their order.

Configure the viewer

In Viewer Config, set:

• Show Output Values: Displays output values next to annotations in the viewport.
• Map to Active Label: Applies the current active label to each new annotation, so readers do not choose a label for every annotation.
• File Browser: Choose whether readers can open other files from the V3 Viewer file browser:
  • Disabled: Readers cannot browse other files. This is the default for new protocols.
  • Enabled for Subject: Readers can browse files in the task's subject.
  • Enabled for Session: Readers can browse files in the task's session.

Click Next Step.

Step 3: Form

The Form step, Attach a Form, attaches the form that readers complete. Forms are saved and managed at the group and site level. The list shows the forms that match the protocol type, with their Name, Version, and Modified by.

To attach an existing form:

1. Search the list for the form.
2. Click Attach in the form's row.

To create a new form:

1. Click Create Form.
2. Write the form in the JSON editor. A preview of the rendered form appears next to the editor. For the form schema, see Protocol Form Technical Reference.
3. Save the form. It is attached to the protocol.

To work with a form in the list, open the form's options menu, then select View in Editor, Duplicate, or Download.

After you attach a form, a summary card shows the form's name, whether it is a draft or published, and a preview. To change the form, click Edit.

Update to a newer form version

When a newer version of the attached form is published, the summary card shows Update Available.

1. Click Update Available. The Current Version and New Version of the form appear side by side, with the differences between them.
2. To use the newer version in this protocol, click Update to Latest.

Updating the form version changes only the protocol you are editing. It does not publish the protocol.

Click Next Step.

Step 4: Review & Publish

1. Review the summary of the General, Labels, and Form steps. To change something, click Previous Step.
2. Click Publish.

When you publish the protocol, Flywheel also publishes the attached form if it is still a draft. The published protocol appears in the group's Protocols list. You can now select it when you create tasks.

Work with a Protocol's JSON

The protocol JSON editor remains available on sites with the Protocol Builder. To open a protocol's JSON, open the protocol's actions menu in the group's Protocols list, then select View in Editor. The same menu also has View, Copy, Download, and Archive. For the JSON format, see Creating Protocols.

Related Topics

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