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
Review the provided /wiki/spaces/RDCRN/pages/141689198. This document will show fields that are used in the Tracker and how they must be named.
Create a UAT (user acceptance testing) version of the sample collection form in the RDCRN Production REDCap instance (https://rc.rarediseasesnetwork.org). 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:
CEGIR - 7801 ***UAT***
CPIC - 1086 ***UAT***
...
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.
Each of these accounts is formatted consistently with the exception of the consortium name. Examples of accounts already created:
svc.rc-specimentracker.cegir@rdcrn.org
svc.rc-specimentracker.bvmc@rdcrn.org
svc.rc-specimentracker.dscTo 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.
Summary: REDCap Service account for ConsortiumName
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
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:
API Export and Import rights (an API token will need created by a REDCap administrator)
‘Full Data Set’ Export Rights for the Biospecimen instruments
Remove all other access to the database including Data Entry Rights
, e.g. svc.rc-specimentracker.
cpic@rdcrn.orgtest@rdcrn.org
...
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.
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.
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:
REDCap Project ID
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.
REDCap Project Name
For example, Consortium Name – Protocol Number ***UAT***
REDCap Record ID Variable Name
The variable name, not the label, needs to be entered here, i.e. record_id, localid, subjid, etc.
REDCap Form Name
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
Added June 2021: Should a Subject ID/Local ID be included in the Biospecimen Tracker?
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.
Added June 2021: Subject ID/Local ID REDCap variable name
Enter the variable name, not the label, of the ID variable that should be displayed in the Tracker, i.e. localid, guid, etc.
Added June 2021: Subject ID/Local ID REDCap form name
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
Mark the instrument as Complete
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.
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.
Site List: List of all possible sites (origin sites and destination sites) that are part of a valid shipping route.
The CCHMC project manager assigned to the consortium can help gather this information.
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.
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.
Shipping Routes:
The CCHMC project manager assigned to the consortium can help gather this information.
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.
This is a repeating form. An instance should be completed for each Origin.
...
Add users who need to Create Shipments with minimum User Rights:
At least ‘Remove tagged identifiers’ Export Rights for the Biospecimen instruments
API Import/Export Rights (an API token will need created by a REDCap administrator)
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.
Notes and shipping status (the [sampleready] variable) are updated in REDCap using the user’s import API
Add users who need to receive shipments with minimum User Rights:
API Import (an API token will need created by a REDCap administrator)
Notes and the receipt status of the samples are imported back into the sample’s REDCap log
*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
...
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.
Summary: API Token for Biospecimen Tracker
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.
Summary: Biospecimen Tracker Configuration Project Access
Description: Please add User List to the Project Name project(s) with User Rights (if specific user rights need specified).