Uploads

CRF data may be uploaded from CSV files. Roles with permission to upload can access this feature via the Upload link in the top menu.

What are CSV files?

Comma separated value (CSV) files are plain text spreadsheet type files consisting of columns (fields) and rows (data). Columns are separated by , (comma). For example this CSV file:

Block identifier, Block size, Sequence within block, Treatment, Gender, Site
1,8,1,Active,Male,1
1,8,2,Placebo,Male,1
1,8,3,Active,Male,1
1,8,4,Active,Male,1
1,8,5,Placebo,Male,1
1,8,6,Active,Male,1
1,8,7,Placebo,Male,1
1,8,8,Placebo,Male,1

represents this dataset:

Spreadsheet programs (like Excel or Numbers) can save sheets or tables as CSV files – look for this option in the Save as... or Export to... facility.

Requirements for CSV files

All uploaded CSV files must:

• Have a header in the first row consisting of field names or labels
• Enclose field values containing a comma with " (double quotes)
• Convert double quotes to two double quotes if a field value contains both commas and double quotes. For instance, the value Penicillin, brand name "Amoxycillin" must be converted to "Penicillin, brand name ""Amoxycillin""" in the CSV file. If the field value does not contain a comma, there is no need to convert double quotes. For instance Penicillin (brand name "Amoxycillin") is valid.

Randomisation lists

If the randomisation method for the trial uses a list, the Designer role will see a Randomisation list option in the responses for the What data records are in the CSV? question. When this option is chosen, additional help is shown on the page, and a template CSV file becomes available for download.

Randomisation lists must contain columns for:

• Treatment group, Treatment
• Each stratification factor (if any)

and the values must exactly match the treatment groups and stratification groups listed on the specification page. If the list is stratified by site, the CSV file must contain a Site column containing site identifiers (not the site names). Sites will be created for any new site identifiers encountered in the uploaded list.

Optionally randomisation lists may contain columns for:

• Sequence (1, 2, 3...) to explicitly denote the list order. If not provided, a sequence number is generated from the natural order of the uploaded list.
• Block information – Block identifier , Block size and Sequence within block . Blocked lists usually contain these columns and they will be stored if uploaded for record keeping purposes. Note that they are not used in any way by the randomisation system, and there is no requirement to upload a blocked list.

Upload and preview

Once a valid list is uploaded, a preview is shown of the rows to be imported. To complete the upload, the declaration must be agreed to and the Confirm upload button pressed.

If the upload is not completed the preview will remain available in the past uploads section. It can be completed at a later date via the preview screen.

Replacing the randomisation list

Provided no randomisations have taken place yet, the uploaded list can replace any existing randomisation list held by the system. Tick the Replace existing list option to do this.

In Red Pill version 28 and later, the randomisation list can be replaced at any time. Earlier versions of Red Pill only allow unused rows in the existing list to be replaced once randomisation has started. This is achieved by uploading a new list with sequence numbers that match unused rows in the existing list. It is unusual to replace a randomisation list once a trial has started except for adaptive designs, and it is recommended that statistical advice is taken before doing so.

Extending the randomisation list

The randomisation list can be extended by uploading a new list at any time. Sequence numbers (if provided) must not match any existing rows. The new list will be appended to the end of the current list. A preview of the entire list is shown before confirmation of upload.

Code (kit) lists

If the randomisation system is blinded, the Designer role will see a Code list option in the responses for the What data records are in the CSV? question. When this option is chosen, additional help is shown on the page and a template CSV file becomes available for download.

Code lists must contain columns for:

• Treatment group, Treatment
• Kit code, Code . Must be unique
• Kit block, Kit block

and the treatment group values must exactly match those listed on the specification page.

Optionally, code lists may contain columns for:

• Sequence (1, 2, 3...) to explicitly denote the list order. If not provided, a sequence number is generated from the natural order of the uploaded list.
• Kit type, Kit type . Not all trials have kit types enabled. If your trial does not have different kit types, you won’t see kit types in the code list.
• Batch, Batch
• Expiry date in dd/mm/yyyy format, Expiry date
• Expiry buffer in days, Expiry buffer
• Kit status . Must be one of 'Unmade', 'New', 'Quarantined', 'Lost', 'Damaged', or 'Destroyed'
• Location . Must be one of 'Manufacturer', 'Distributor', 'Site', or 'Other'
• Site containing site identifiers (not the site names). Sites will be created for any new site identifiers encountered in the uploaded list.
• Notes

Upload and preview

Once a valid list is uploaded, a preview is shown of the rows to be imported. To complete the upload, the declaration must be agreed to and the Confirm upload button pressed.

Replacing the code list

Provided no randomisations have taken place yet, the uploaded list can replace any existing code list held by the system. Tick the Replace existing list option to do this.

Once randomisation has started, only unused rows in the existing list can be replaced. This is achieved by uploading a new list with sequence numbers that match unused rows in the existing list. It is not recommended that the treatment group or kit codes are changed when doing this, and warnings will be shown if the new list would affect them. It may be useful, however, to bulk update batch numbers, expiry dates and site locations with an uploaded list.

Extending the code list

The code list can be extended by uploading a new list at any time. Sequence numbers (if provided) must not match any existing rows. The new list will be appended to the end of the current list. A preview of the entire list is shown before confirmation of upload.

CRF data

Data for existing forms in the CRF may be bulk uploaded by Administrators instead of being entered manually. This may be useful for uploading data from laboratory results or other data collection systems for instance.

Providing at least one participant has been created, the Administrator role will see a list of forms in the responses for the What data records are in the CSV? question.

Note that it is not possible to upload data to participant entry, withdrawal or randomisation forms.

Prepare the CSV file for upload

First choose the form to upload data to under the What data records are in the CSV? question. The expected field (column) headings will then be shown in the 'CSV format help' section. The CSV file to be uploaded must have these column headings in the first row of the file. A template file can be downloaded by clicking the Download CSV template button. The type of data allowed in each column follows the same rules as for data entry. Values for categories must exactly match the value shown on the form. To see category values ("enum" types) and the type of data expected for each column, view the data dictionary for the form concerned.

Each row in the CSV must start with the participant identifier for an existing participant. If the target form can be completed once per participant, the CSV row will create the form or update the existing form for the matching participant. If the target form is a multiple entry form, each CSV row will create a new form for the matching participant.

Upload the CSV file

Select the CSV file from your computer and click the Upload button. The file will be validated using the same rules as apply when performing data entry manually, with the following differences:

• Validation overrides are not supported
• Soft range checks (usually shown as popup warning messages) are not displayed
• Form completion messages are not shown

Any errors will be shown on the preview page, and a file with errors may not be uploaded. You must fix the errors in your CSV file and re-upload. Once the file has been uploaded, the forms created by the upload can be viewed at any time from the preview page of the uploaded file. In addition, a link is shown when viewing the form to the related upload.

Repeating sections

If a form has a repeating section, the CSV file may also repeat rows as many times as necessary to record all data. Repeat the rows in the CSV for each repeating section entry, but leave the first column (Patient ID) and columns for the rest of the form empty.

File limits and storage

All uploaded CSV files that pass initial checks and can be previewed are stored in the system. They are encrypted using AES-256 at rest. There are limits on the size of individual CSV files that may be uploaded and the total storage space available. The limits for your system may be viewed on the specification page. Contact Sealed Envelope support if you need to raise these limits.

Permissions

Only roles with the 'Import randomisation and code list from uploaded CSV files' permission are able to upload lists and view the lists that have previously been uploaded. By default this permission is given to the Designer role and will unblind the user.

Only roles with the 'Import CRF data from uploaded CSV files' permission are able to upload CRF data from CSV files. By default this permission is given to the Administrator roles. 

Administrators can view permissions on the the specification page.