New Sample Form How To

Owned by Karen Lapthorn
Last updated: Jan 31, 2024 by Audrey Perdew
6 min read

This document is intended for a Data Manager who is building a REDCap sample collection form for a consortium that wishes to also use the Biospecimen Shipment Tracker. Additional steps must be taken beyond the creation of the sample collection form to ensure a connection between the REDCap form and the Tracker.

Need additional help? Reach out via the RDCRN Service desk.

Create a UAT version of the new sample collection form

  1. Review the provided specifications for the REDCap Data Collection Forms. This document will show fields that are used in the Tracker and how they must be named.

  2. Create a UAT (user acceptance testing) version of the sample collection form in the RDCRN Production REDCap instance. This will be used to test the passing of data between the new REDCap form and the test Tracker. Clearly name the project Consortium Name – Protocol Number ***UAT***, examples:

    1. CEGIR - 7801 ***UAT***

    2. CPIC - 1086 ***UAT***

Add the correct REDCap service account to the REDCap Project

  1. If a consortium has not yet used the Tracker, a special REDCap service account first must be created. The account is used by the Tracker to send shipment notes back into REDCap. An hourly job that connects to Shippo also uses this service account to update shipment statuses.

  2. Each of these accounts is formatted consistently with the exception of the consortium name, e.g. svc.rc-specimentracker.test@rdcrn.org

  3. To request a new service account, use the RDCRN Helpdesk Portal to make your request. Select the option for the Biospecimen Tracking Tool and enter the information below for the request. Be sure to replace the sections in red with the correct information.

    1. Summary: REDCap Service account for ConsortiumName

    2. Description: Please create a new REDCap service account for ConsortiumName to be used with the Biospecimen Tracker.
      The account should be: svc.rc-specimentracker.consortiumname@rdcrn.org

  4. If the service account already exists or after a new one has been created, add the new service account to the REDCap Project with the correct user rights:

    1. API Export and Import rights (an API token will need created by a REDCap administrator)

    2. ‘Full Data Set’ Export Rights for the Biospecimen instruments

    3. Remove all other access to the database including Data Entry Rights

Update the Biospecimen Tracking Configuration - ** UAT COPY ** project with values related to the new form(s)

  1. Each consortium has its own settings in a separate Arm. Locate the correct Arm and add a new record using the protocol number. The records in this project are RDCRN protocols. It asks for information about the REDCap projects involved in specimen tracking for that protocol.

  2. Protocol Information: This form is to facilitate management of the Configuration database. The consortium variable will autofill. The Study Title field can be used for more user-friendly identification of the protocol if desired.

  3. Specify Identifier Form: This form is to configure the recordid variable of the protocol’s REDCap project(s). This form requires four pieces of information:

    1. REDCap Project ID

      1. This can be found in the URL of the project. For example, this project has an ID of 60:
        https://devrc.rarediseasesnetwork.org/redcap_v9.5.29/ProjectSetup/index.php?pid=60.
        This is the static, unique identifier of the REDCap project.

    2. REDCap Project Name

      1. For example, Consortium Name – Protocol Number ***UAT***

    3. REDCap Record ID Variable Name

      1. The variable name, not the label, needs to be entered here, i.e. record_id, localid, subjid, etc.

    4. REDCap Form Name

      1. The form name of the REDCap instrument that the recordid variable is built in. This is the form name as found in the data dictionary or codebook, e.g. participant_identifiers instead of Participant Identifiers

    5. Added June 2021: Should a Subject ID/Local ID be included in the Biospecimen Tracker?

      1. Answering Yes here will open the configuration to pass a Subject ID into the Tracker, most commonly the Local ID. Not all consortia will want these IDs to be exposed in the Tracker, and some may want to use an ID other than the Local ID.

    6. Added June 2021: Subject ID/Local ID REDCap variable name

      1. Enter the variable name, not the label, of the ID variable that should be displayed in the Tracker, i.e. localid, guid, etc.

    7. Added June 2021: Subject ID/Local ID REDCap form name

      1. The form name of the REDCap instrument that the Subject ID variable is built in. This is the form name as found in the data dictionary or codebook, e.g. participant_identifiers instead of Participant Identifiers

    8. Mark the instrument as Complete

    9. This is a repeating form. In the event that a protocol spans multiple REDCap projects, there should be one instance of the form per project.

  4. Specify Collection Form: This form is to configure the sample collection form(s) for the protocol. It requires the REDCap project ID, project name, and form name of the instrument(s) following the same entry conventions as the Specify Identifier Form. This is also a repeating form. There should be one instance per specimen form. The instrument must be saved as Complete for the corresponding collection form to display in the Tracker.

  5. Site List: List of all possible sites (origin sites and destination sites) that are part of a valid shipping route.

    1. The CCHMC project manager assigned to the consortium can help gather this information.

    2. Site names will appear in a dropdown in the Tracker when the user is indicating the Origin site for the shipment as well as the Destination site.

    3. One or more email addresses can be added to the Email Contacts for a site. These email addresses will receive alert emails from the Tracker when shipments are created, received, or updated. Email addresses are not required but can be useful for users. Contacts will only receive alerts for the sites they are listed under. Once email addresses are added, those users will receive emails (including in UAT) for any test orders you or others place.

  6. Shipping Routes:

    1. The CCHMC project manager assigned to the consortium can help gather this information.

    2. For each Origin site, indicate all possible Destination sites. This information drives the logic in the Tracker for when the user must select a Destination site after indicating the Origin site.

    3. This is a repeating form. An instance should be completed for each Origin.

Add users to REDCap project and update User Rights.

  1. Add users who need to Create Shipments with minimum User Rights:

    1. At least ‘Remove tagged identifiers’ Export Rights for the Biospecimen instruments

    2. API Import/Export Rights (an API token will need created by a REDCap administrator)

      1. Using the user’s personal API token allows the Specimen Tracker to comply with REDCap user permissions. That is, users will only have access to the same projects and data in the Tracker as they do in REDCap.

      2. Notes and shipping status (the [sampleready] variable) are updated in REDCap using the user’s import API

  2. Add users who need to receive shipments with minimum User Rights:

    1. API Import (an API token will need created by a REDCap administrator)

      1. Notes and the receipt status of the samples are imported back into the sample’s REDCap log

      2. *Notes entered in the Tracker will be visible to all users on that project. PHI should not be included as part of these notes.

Enter test samples into the UAT version of the new sample collection form and review the UAT version of the Tracker

  1. After entering some test data, load the UAT version of the Tracker: https://uatspecimentracker.rarediseasesnetwork.org/home/

  2. While on the Create Shipment page, you should see the test samples in the Tracker. (Search by SampleID if needed). Confirm all values are showing as expected:

    1. The sample row will display the Sample ID, Parent Sample ID (if applicable), SubjectID/LocalID (if configured to show) Protocol, and Sample Date.

    2. Review the column titled “Tags” to confirm values for any Sample Tags if those optional fields were included in the sample collection form.

    3. Use the 3 dots to expand the row of the sample to confirm values for Sample Type, Sample Date, Sample Time and/or Sample Description if those optional fields were included in the sample collection form.

Consortium users are welcome to use the UAT form and Tracker to test for themselves

The UAT version of the Tracker is available for Consortium users to test the new sample collection form. Documentation and a video on how to use the Tracker are available on the RDCRN public Confluence site.

Once Testing is complete, copy the sample collection form to create a Production version of the form.

  1. A separate, Production version of the form must be created. The UAT version should remain as well in case future changes to the form are needed.

  2. The configuration values entered into the Biospecimen Tracking Configuration - ** UAT COPY ** project will need to be entered again into the Biospecimen Tracking Configuration project.

  3. The REDCap Service Account and Tracker users must be added to the Production project.

  4. The Service Account and Tracker users must have Import/Export API tokens.

Requesting API Tokens and Configuration Database Project Access

To request API tokens for the service accounts and REDCap project users, use the RDCRN Helpdesk Portal to make your request. Select the option for REDCap Help and enter the information below for the request. Be sure to replace the sections in red with the correct information.

  1. Summary: API Token for Biospecimen Tracker

  2. Description: Please create a new API token(s) for User List to be used with the Biospecimen Tracker for REDCap Project Name.

Please follow the above steps to request access to either the Biospecimen Tracking Configuration - ** UAT COPY ** project or the Biospecimen Tracking Configuration project.

  1. Summary: Biospecimen Tracker Configuration Project Access

  2. Description: Please add User List to the Project Name project(s) with User Rights (if specific user rights need specified).