Skip to content
Open Data Capture

How to Upload Data

Open Data Capture can import records for a form instrument from a CSV file. Each row of the file becomes one record of that instrument for a subject in the currently selected group.

Upload is an experimental feature. The Upload Data item appears in the navigation only after an admin turns on Enable Uploader under Admin Panel > App Settings, and only for accounts that can read subjects and create instrument records. The default Group Manager and Standard User roles both have those permissions.

Steps

  1. Login to Open Data Capture

    First, login to your instance of Open Data Capture. If you do not see Upload Data in the navigation, ask an admin to turn on Enable Uploader under Admin Panel > App Settings and to check that your account can read subjects and create instrument records.

  2. Select Your Group

    Next, select the group the records belong to with the group switcher at the top of the sidebar (or at the top of the menu on a small screen). If your account belongs to only one group, the switcher shows that group’s name and there is nothing to choose. Switching group ends the current session.

    It is very important that you select the correct group. Uploaded records always go to the current group, and each subjectID in the file is read as an ID within that group, so with the wrong group selected the rows are recorded for different subjects.

  3. Open Upload Data

    Select Upload Data in the navigation. This will reveal a page displaying all the form instruments that are available in the current Open Data Capture instance.

  4. Select Instrument to Upload to

    Select an instrument you would like to upload data to by clicking on its title within the displayed table. This action will bring you to the upload page for the selected instrument.

  5. Select the Username for the Records

    On the upload page, select the username to associate with these records for audit and traceability, or N/A. The Filter users by group select only narrows the list of usernames; it does not change the group the records go to. Choose a user who belongs to the current group, otherwise the upload fails.

  6. Following Proper Upload Format

    In order to properly upload data to the selected instrument, the data must follow a certain format. A sample of the instrument’s data format can be seen by clicking the Template button. Once the template is downloaded, one can fill it with external data. The template includes pre-filled columns and sample data that specify data types for each field.

  7. Uploading Using Dropzone

    Once a template is filled, it can be dragged and dropped into the file dropzone. After this, click the submit button to verify the data. If the data follows the correct syntax, it is submitted to the instrument’s data table; otherwise, an error is displayed indicating which field is filled incorrectly.

  8. Uploading specific Zod Data

    Some forms may have Zod field types that are challenging to represent in a standard CSV format. Therefore, specific notations must be used to ensure the upload feature can properly parse the data.

    • Fixed-Choice Data

      If a form has a field that accepts only certain values, such as a score of 0, 1, 2 or 3, the template lists them separated by ”/”:

      • 0/1/2/3

      Enter exactly one of the listed values, written as it appears in the template. Any other value is rejected, and the error names its column and row.

    • Set Data

      If a form has a field that accepts a set of data, such as a multi-option checklist with options a, b, and c, the proper notation for the data would be:

      • SET(a,b)
      • SET(a,b,c)
      • SET(a)

      This format allows the upload feature to correctly interpret the selected options.

    • Record Array Data

      Record array data is a custom form of data entry for when there can be multiple records for one column field. For example, the types of scans and their info in an MRI form would be record array data. If a record contains a set of questions/ data fields A, B, and C, the proper notation for data entry would be as follows:

      • RECORD_ARRAY(A: dataEntryForA, B: dataEntryForB, C: dataEntryForC ;)

      If the record array question contains multiple records the data entry would look like so:

      • RECORD_ARRAY(A: dataEntryForA, B: dataEntryForB, C: dataEntryForC ; A: dataEntryForA2, B: dataEntryForB2, C: dataEntryForC2 ;)

      Note that every ”,” notates a new entry in the record, whilst every ”;” notates a new record in the record array

    • Record Data

      If a form has a field that asks the same question about a fixed list of items, such as a mood rating for monday, wednesday and friday, the proper notation gives each item and its value separated by ”:”:

      • RECORD(monday: 3, wednesday: 4, friday: 2)

      The template lists the items and the values each one accepts, for example RECORD(monday: 1/2/3/4, wednesday: 1/2/3/4, friday: 1/2/3/4). An item that is not in the template is rejected.

    • Optional Data

      Whenever data is optional within a form it can be left empty and still be properly submitted. Any optional data column in the csv template will have an “(optional)” tag attached to its sample data entry, which means any entry in the column can be left blank. This is usually done in that case of when one column value depends on another. For example, a sessionFailed column would be followed by an optional reasonForFailure column.

Sample CSV Data

This section will present how to properly fill in a template csv from the upload feature. Say we download the following csv template that looks like this below:

subjectIDdatestringQuestionsetQuestionoptionalQuestionrecordArrayQuestion
stringyyyy-mm-ddyes/noSET(A/B/C, …)A/B (optional)RECORD_ARRAY(testString: A/B/C, testNumber: number;)

Starting with the first column we have subjectID, which is the subject’s ID within the current group, with no $ or whitespace. This field is required. Only custom subject IDs are supported for now: an ID generated from personal information does not match the existing subject and creates a new one.

The second column contains the date of which in instrument was done by the subject, which follows yyyy-mm-dd format. This field is to be filled for each row.

The third column is a string entry consisting of two possible options (yes/no).

The fourth column is a field which takes in a set of entries, where the options are A, B or C. The set can have all these option within it, however it does not accept duplicates. So an entry such as SET(A,A,C) would fail, but the entry SET(A,B,C) would be valid.

The fifth column is an optional string field with the possible options of A or B. This field can hold either A, B, or can remain empty.

Finally, the sixth column is a record array field. This record array object can have the fields testString and testNumber entered within it. These internal field values are entered by including the fieldname and its corresponding value separated by a ”:”. In addition, a record array can also have multiple entries for each internal field within it as long as the new entry is separated by a ”;”. With that in mind, valid entries for this column would be RECORD_ARRAY(testString: A, testNumber: 1;) or
RECORD_ARRAY(testString: A, testNumber: 1; testString: 1, testNumber: 2;), etc.


A valid CSV file that follows this template can be seen below:

subjectIDdatestringQuestionsetQuestionoptionalQuestionrecordArrayQuestion
testID1232025-01-07yesSET(A, B, C)BRECORD_ARRAY(testString: A, testNumber: 2; testString: B, testNumber: 3;)
testID1112025-01-06noSET(C, B)ARECORD_ARRAY(testString: B, testNumber: 22; testString: A, testNumber: 1;)
testID1112025-01-03noSET(A, C)RECORD_ARRAY(testString: B, testNumber: 12; testString: B, testNumber: 13;)