Introduction

Using this template, you can create participants, visits, and specimens in one go.

Note:

Only specimen custom fields are included in the template and registration or visit custom fields are not included.

Steps to import CSV

Go to the collection protocols list page, click on the 'Import' button, and select the option 'Biospecimen Data' OR

Go to the participants list page of the CP under which the participants, visits, and specimens have to be created, click on the 'More' button, and select the option 'Biospecimen Data'.

Select 'Master Specimens' from the 'Select Record Type' dropdown and click on 'Download Template File' to download the template file.

Enter all valid data in the template file as mentioned in the 'Data Dictionary' table.
Upload the filled template file in the 'Input Records File' field.
Select the correct 'Date and Time Format.'
Click on the 'Validate and Import' button.
Refer 'Import status' to check the status of the import job.
You can both create and update records using the master template. If data already exists, the record is updated with the input specified in the CSV file. Otherwise, a new record is created.

If the visit name is not specified, all specimens within the same "collection date" will be collected under one visit.
Specimen labels cannot be auto-generated if you are going to include rows for aliquots and derivatives within the same file. i.e If labels are auto-generated, you need to upload parents and children in two different imports to export the labels generated from the first upload and use them as parent labels for uploading children.

Sample CSV

Download

You need to enter the actual PPIDs and Specimen labels when the specific label tokens are not defined at any level (system, CP, SR).
When the tokens are specified at the collection protocol level, the PPID and specimen label can be left blank.
When entering the 'Event Label,' OpenSpecimen will correctly recognize and group the specimens into visits based on the participant.
Make sure all the dates use the same format throughout the BO file.
From v10.3 the master specimen template can also be used to only create/update participants and their respective visits, without any specimen data in it.
All the values for field type ‘Permissible Values’ are case sensitive e.g., Lineage, Laterality, Pathology status, etc.

Data Dictionary

Column name	Data type	Mandatory (Create)?	Description	Permissible Values	Validations

Column name	Data type	Mandatory (Create)?	Description	Permissible Values	Validations
Collection Protocol (CP) Short Title	String	Yes	Protocol under which participants should be registered		Collection Protocol should exist within the system.
PPID	String	No	Participant Protocol ID		Blank - The New participant with auto-generated PPID is registered. Existing - Specimens will get collected under participants of specified PPID. New participant PPID - The new participant with specified PPID will be registered.
Registration Date	Date	Depends			The visit date value is taken if the registration date is not specified and the visit date is specified. The collection date value is taken if the registration date and the visit date are not specified. From v10.3 if the registration date is mandatory if creating only new participants
First Name	String	No	First Name of the participant
Last Name	String	No	Last Name of the participant
Middle Name	String	No	Middle Name of the participant
Date Of Birth	Date	No	Date of Birth of the participant		Select the correct date format from UI based on the data in the file.
Death Date	Date	No			Select the correct date format from UI based on the data in the file.
Gender	String	No		Female Male Unknown Undifferentiated
Race#1	String	No	Add an extra column for the participant with multiple races. E.g. Race#1, Race#2, etc.	American Indian or Alaska Native Asian Black or African American Native Hawaiian or other Pacific Islander Not Reported Unknown White
Vital Status	String	No		Alive Dead Unknown Unspecified
Ethnicity	String	No		Hispanic or Latino Not Hispanic or Latino Not Reported Unknown
SSN	Integer	No	Social Security Number for US locale. National Identification Number for other countries.		It should be unique within OS.
eMPI	String	No	Enterprise Master Patient Index		It should be unique within OS.
PMI#1#Site Name	String	No	The site which issued the MRN		It should be an existing site within OS.
PMI#1#MRN	String	No	Medical Record Number (unique identification given by the site)		It should be unique within a site.
Event Label	String	Depends	Event Point Label from the protocol for which this event corresponds. E.g., baseline, surgery, etc.		If left blank, an unplanned visit is collected.
Visit Name	String	No	Auto-generated if left blank		It should be unique within OS.
Visit Date	String	No			If the visit date value is not specified, the system takes up the value of the collection date.
Collection Site	String	No	Maps to Visit site. It needs to be specified if no default is specified at the CP event level.
Visit Status	String	No		Complete Pending	Default: 'Complete'
Clinical Diagnosis	String	No		Permissible Values File - SNOMED Permissible Values File - ICD 10	Default: 'Not Specified'
Clinical Status	String	No		No Diagnosis / Control New Diagnosis Pre-Therapy Post-Therapy Pre-Operative Operative Post-Operative Remission Relapse, Primary Site Relapse, Distant Site Relapse, Not Specified Not Specified	Default: 'Not Specified'
Path. Number	String	No	Surgical Pathology Number		Default: 'Not Specified'
Visit Comments	String	No
Specimen Requirement Code	String	No	Code defined in collection protocol for the corresponding specimen requirement.		If this is not specified, specimens are created as unplanned specimens. For enabling CP encoding, please refer to the wiki page
Specimen Label	String	No	It needs to be specified when the auto label generation is OFF OR 'Manual Input' is set to 'Yes.'		It should be unique within the system
Barcode	String	No			It should be unique within the system
Class	String	Depends	Exception- conditional mandatory filed If 'Not specified' is selected in the 'type' field, in that case, the class field is mandatory.	Tissue Molecular Cell Fluid
Type	String	Depends		Permissible Values File	From v10.3 mandatory only if creating specimens else optional
Lineage	String	No		New Derived Aliquot	Default: New
Parent Specimen Label	String	No	Required when creating child specimens
Anatomic Site	String	No		Permissible Values File	Default: 'Not Specified'
Laterality	String	No		Left Right Not Applicable Not Specified	Default: 'Not Specified'
Pathological Status	String	No		Non-Malignant Non-Malignant, Diseased Pre-Malignant Malignant, Pre-Invasive Malignant, Invasive Malignant Metastatic Not Specified Clinically normal	Default: 'Not Specified'
Initial Quantity	Numeric	No	Default units: Fluid: ml Tissue: gm Cell: cells Molecular: µg		It should be greater than zero ("0")
Available Quantity	Numeric	No	Default units: Fluid: ml Tissue: gm Cell: cells Molecular: µg		It should be greater than zero ("0")
Concentration	Numeric	No	Concentration units are Cells: cells, Tissue: µg/ml Molecular: µg/ml		It should be greater than zero ("0")
Freeze/Thaw Cycles	Numeric	No	The number of cycles carried out.
Created On	Date & Time	No	Mandatory for child specimens.
Comments	String	No
Collection Status	String	No	Status of the specimen to be collected	Pending Complete Missed Collection Not Collected
Container	String	No	Name of the existing container.		The container specified should be existing. Suitable to hold the specimen (based on type and protocol) Should have available positions.
Row	String	No			Position within the container at which the specimen is to be stored. If left blank, the system will allocate the next available position
Column	String	No
Position	Integer	No	Use this column if you do not use "row" and "column."
Collection Date	Date & Time	Depends	Required for primary specimens.		From V10.3 collection date is mandatory while creating specimens else optional
Collection Procedure	String	No		Lavage Needle Aspirate Needle Core Biopsy Venipuncture Indwelling Catheter Surgical Resection Not Specified
Collection Container	String	No	Type of container used for specimen collection	ACD Vacutainer Citrate Vacutainer CPT EDTA Vacutainer Heparin Vacutainer No Additive Vacutainer Paxgene Serum Separator Vacutainer Sterile Specimen Container Streck Not Specified
Collector	Email address	No			Valid user
Received Date	Date & Time	No	Date when specimens were received at the lab. If not specified, the current date/time is being used.
Received Quality	String	No		Acceptable Thawed Frozen Quantity Not Sufficient Clotted Hemolyzed Lipemic Cauterized Hemorrhagic Damaged Unacceptable, Not Specified Not Specified
Receiver	Email address	No			Valid user

FAQ

Q. How to create parent and child specimens using the master specimen template when labels are auto-generated?

Enable 'CP Coding' from Settings
Add specimen requirement code at the CP level for all the parent and child samples.
Download the master specimen template from the user interface.
Add the required data in their respective columns and codes in the 'Specimen Requirement Code' column.
Create patient, visit, and primary specimens in one go using the master template, and for child specimens, create separate imports using a master template or specimen template.
If you receive information separately, it is easier to use separate templates: Participant registrations, Visits, and Specimens. The master template is used when participants visit, and specimens or visits and specimens under existing participants need to be created in one go.