Participant Upload

Owned by Aaron Leitner
Mar 28, 2024
5 min read

There are many ways to create participant records in Way to Health. This how-to guide will explain how to upload a list of participants from a CSV file.

 

https://waytohealth.atlassian.net/wiki/spaces/WTHST/pages/450789480/Upload+a+List+of+Participants#Upload-a-list-of-participants

Participant Upload Configurations

  • A list of existing (if any) Participant Upload Configurations can be found on the Participant Upload Configurations admin page. This page can be accessed by navigating to Manage Study > Participant Upload Configurations from the nav bar.

    Screen Shot 2024-03-26 at 12.25.32 PM.png

  • From this page Participant Upload Configurations can be created, edited, disabled/enabled, and deleted

    Screen Shot 2024-03-26 at 12.26.15 PM.png

Creating a new Participant Upload Configuration

  1. From the Participant Upload Configurations admin page click the “+ New Configuration” button

  2. Provide a name (and optional description if desired) for the new configuration

  3. Select if this configuration should create and/or update participants when a file is uploaded

    1. If Participant Re-enrollment is enabled for the study it will also be available here. Re-enrolling participants through this feature will first update them with any new data contained in the upload file and then re-enroll/restart the participant based on configuration settings

  4. Defining what data will be included in the upload file(s)

Possible Upload Fields

  • First name

  • Last name

  • Username

  • Email address

  • Text number

  • Voice number

  • Phone numbers (if multiple phone numbers is turned on in advanced settings)

  • Address fields

    • Street Address

    • Street Address 2

    • City

    • State Region (ex: PA, NJ)

    • Postal Code

  • Date of birth

  • Time zone (ex: -5.0, -6.0)

  • External ID

  • Additional info

  • Social Security Number (format XXX-XX-XXXX)

  • Preferred language (locale)

  • MRN

  • CSN

  • Provider NPI

  • Notification preferences

    • Notify text

    • Notify email

    • Notify voice

  • Payment preference

  • Clincard Number

  • Participant ID (for identifying existing participants only, can not be updated)

  • Arm

  • Status

  • Start date

  • Scheduled start date

  • Variables (only certain types)

  • Study group Categories (each study group category can be used as a field to assign the participant to a single Study group within that category)

  1. Click the blue “Save Configuration” button

    1. Any validation issues will be displayed and must be addressed before the configuration can be saved.

Editing an existing Participant Upload Configuration

  1. From the “Participant Upload Configurations” admin, choose which configuration to edit and click the blue pencil icon to the right of the configuration name (under the “actions” header)

  2. Make the desired changes to the upload configuration

  3. Click the blue “Save Configuration” button

    1. Any validation issues will be displayed and must be addressed before the configuration can be saved.

Enabling/Disabling a Participant Upload Configuration

Disabling

  1. From the “Participant Upload Configurations” admin, choose which configuration to disable and click the yellow “power off” icon to the right of the configuration name (under the “actions” header)

    1. When a configuration is disabled it can not be used to upload a participant data file and will not be displayed as an available upload configuration on the Participant Uploads page

Enabling

  1. From the “Participant Upload Configurations” admin, choose which configuration to enable and click the green “power on” icon to the right of the configuration name (under the “actions” header)

Deleting a Participant Upload Configuration

  1. From the “Participant Upload Configurations” admin, choose which configuration to delete and click the red trash can icon to the right of the configuration name (under the “actions” header)

    1. Note: only configurations that have not yet been used can be deleted

 

Upload Participants

Once one (or more) Participant Upload Configurations have been created they can be used to upload a list of new/existing participants. The Participant Upload page can be found by navigating to Manage Participants > Upload Participants.

A list of available upload configurations is visible on the left hand side of the Upload Participants page

Participant upload file templates

  1. Select which upload configuration to use and click “Download Template”

  2. A CSV file will be downloaded containing all of the required headers for the selected upload configuration

Uploading a participant data file

  1. Select which upload configuration to use and click “+ New Upload”

  2. An upload modal will appear in the center of the screen

    1. Requirements for acceptable files can be found in the blue box.

    2. Here is an example of an acceptable file (CSV).

       

  3. Click “Choose File” button.

  4. Select the CSV file from your computer.

  5. You can choose to do a Dry Run to see how many participants would be created or updated. Click “Submit”.

    When you choose Dry Run, you’ll get a banner which validates what would happen. See example below.

     

  6. If you are ready to process the file, uncheck “Dry Run” and click “Submit”. For the actual upload, you will also see a banner which validates what happened.

  7. Navigate to Manage Participants > Participants to access the newly created records. Participants will be set to a status based on the configuration of your enrollment flow. In the example below, all participants uploaded have been set to a status of “Enrolling” because they have not completed all enrollment steps.

  8. You can review profile fields from the General Info tab and variable values in the Variable History tab to validate data has been updated.

Things to Know

  • Participant Upload Configurations

    • Name is required and must be unique per study

    • Description is optional

    • Actions

      • Create Participants

        • Newly uploaded participants (no match found off of Unique ID field) will have an account created and be enrolled in the study

      • Update Participants

        • Participants that already exist in the study (matched off of unique ID field) will be re-enrolled/restarted if they are in one of the selected statuses

      • Re-enroll Participants

        • Only available if study has Allow Re-enrollment enabled from the advanced settings page

        • Re-enroll behavior (re-enroll vs restart) is also configured in advanced settings

          • If “Prompt the user for re-enrollment reasons and act accordingly” has been selected in advanced settings an option for the upload configuration to re-enroll or restart participants will be displayed

        • Participants that already exist in the study (matched off of unique ID field) will be re-enrolled/restarted if they are in one of the selected statuses

        • Re-enrolled/restarted participants will also have their accounts updated with any new data contained in the upload

    • Field Mapping

  • Uploading files

    • If participant MRN is being used in CSV upload, update the column format to be category: custom and type: 000000000 (with the # of 0s corresponding to the length of each participant’s MRN) to prevent excel from stripping the leading 0s.