Managing Protocols with XNAT's Visits & Protocols Plugin

This document describes how to define protocols, assign them to projects and track visit data in accordance with the protocol.

It assumes you have correctly installed the plugin (or module if XNAT 1.6.5) as an administrator, or are a project owner for at least one project on the server.

Step-by-step guide to creating an XNAT Protocol

After installing the plugin, administrators or project owners can access the Protocol Management Wizard by selecting Tools > Manage Protocols from the XNAT menu bar.

  1. On a fresh installation, the protocol management page will be empty...

    To begin you will first likely want to start creating a new protocol. Skip to step 3 below in that case. The remainder of this tutorial describes that process.

  2. Or you may have an existing protocol (from a previously exported JSON protocol file) that you might wish to import. In this case you will be prompted to browse to the location of the file on your computer to select it. The file will be validated and automatically uploaded to the server to appear in the existing protocols section above. Upon selecting it then, you may edit the protocol as outlined in the steps below and re-save it or re-export it.

  3. The first step to creating a protocol from scratch is to name it and optionally describe it. Click the "Start New Protocol" button, fill in the details and click "Okay".

  4. You will be taken to the Protocol Editor which allows you you to configure several general options such as how to handle unexpected or missing experiments, visits or terminal visits. The behavior of each is described in detailed help dialogs by clicking the  icons besides them.

  5. Most importantly the Protocol Editor prompts you to begin constructing your protocol by adding visits...
    Click the "Add Your First Visit" button.

    Note: The first visit's offset is zero and cannot be modified. All future expected visit offsets will be relative to this one.

  6. After clicking "Okay" the first visit shows up in the Protocol Editor's experiment matrix and you are encouraged to start adding additional experiments or checking required experiment boxes under the first visit from the suggested experiment list. If these won't be utilized at all, you might hover over them and select the  to delete them or the  to edit them. Similarly to delete or edit an unwanted expected Visit Type, hover over the column heading to perform these functions.

  7. But let's click "Add Experiment" and notice that we can add more rows to this matrix specifying any of the defined data types in the system as an expected experiment while also requiring an optional subtype and associated experiment assessors.

    Click "Okay" and then click the "Add Visit" button again.

  8. Defining the subsequent visits is more interesting. In addition to the offset, a "visit window" specifying the duration before or after the targeted visit should be defined. You may also elect to automatically copy all of the required experiments from any previously defined visits. 

  9. Add the Second Visit as shown above to your protocol and repeat the process to add a third and final visit 240 days from the baseline with a -20/+20 day window as well.

    Your protocol should look something like this. If not, check the boxes under each visit corresponding to the experiments or assessors you require.

  10. Click "Save Protocol" for now. We'll briefly explore the other operations on the toolbar above to manage users, project associations and protocol notifications.

    The Edit Settings button on the toolbar allows you to modify the name and description you initially gave the protocol.

    Click the Edit Users button to add additional protocol owners to a white list allowing them to make changes to the protocol. Click the checkboxes of the available users on the system you want to add in the box on the right-hand side. Then click the "<< Add" button to make them protocol owners. You may similarly remove protocol owners from the list in the left-hand side by checking them and clicking "Remove >>". Click Okay to accept any changes on the unsaved protocol. In order for these user changes to take effect, you'll additionally need to Save the protocol. A new version of it will be created which will need to be re-associated with existing projects using the old version. This process is covered in the step 12 below! But first let's look at notification options...

  11. Protocol event notification options can be configured by clicking the "Notifications" button on the toolbar.

    Here you will select which types of subject visit events project owner's should get an email for.

    Most importantly however, you'll notice that you will want to add a valid email address, or comma separated list of email addresses to the "Default Notification Email(s)" field in this dialog box before clicking Okay.

    Managing Protocol Versions in the Protocol Manager

  12. The protocols you create in the Protocol Manager do nothing unless a particular version of the protocol is associated with a particular project or projects within the system. There are two ways to make these associations. As a system admin the most effective method is by updating protocol associations in bulk by clicking on the "View Projects" toolbar button. You'll see below that initially there are no projects currently associated with this protocol. You can click the "Apply Protocol To Projects" button in the dialog to open another dialog listing all projects on the system (if you're an administrator) ...or only all projects you own or are allowed to to manage otherwise.

    Select the checkboxes for projects you want to associate and click "Okay". The currently selected version of the current protocol you're viewing in the Protocol Manager is the one that will be associated after clicking "Okay" on the View Projects dialog box.

    If you want a different version of the protocol associated, close the View Projects dialog and select the appropriate version by hovering over the protocol version indicator in the upper right-hand corner of the Protocol Manager.

    It will turn into a dropdown listing all previous or newer versions of this protocol currently saved on the system. Select the one you want. Verify the appropriate changes you expect are evident on the Visit Types / Experiment list matrix, Protocol Owners List and Notifications options ...and then click the "View Projects" button again. This time select the checkboxes of the currently associated projects (presumably with different version numbers in the Protocol Version column) and click the "Update Protocol Version" button to set every selected project to the currently selected protocol version in bulk.

  13. An alternative to updating protocol associations or their versions in this manner would be to make the changes individually on each project.

    Navigate to the project page in your XNAT instance for the project you are interested in configuring. Again, as an administrator, or project owner with the Visits & Protocols plugin installed, you will now find the addition of a "Protocols" tab in the project summary section of the page...

    On that tab you may select the protocol and it's version to associate with the project from the respective dropdowns. Note: An XNAT administrator will see every project on the system. Otherwise, if you own the current project and your username has been added to the protocol's owner list will those protocols show up here for association.

    Click the "Set Protocol" button in that tab to apply the association. A green check mark indicates that the protocol has been successfully associated.

    Subject Visit Completion Status Dashboard

  14. Also on the project page a research coordinator can quickly see which subjects have completed specified experiments required by the protocol once subject visits have gotten underway and data has been collected.

  15. Experiments that have been satisfied for a visit will appear as a  icon and can be clicked on to take you to the experiment page. Expected visits will appear with an  icon. Clicking on it will take the user to the appropriate image upload page. If deviations are allowed by your protocol, they will appear as an  icon which can be hovered over for a quick deviation explanation.

  16. Visits are also broken down individually by tabs as you can see here...

This concludes the Protocol Management portion of the tutorial. To learn how to enter visit data and exceptions in compliance with the protocol, click here.

There is no content with the specified labels