Tabular Import Walkthrough

Mapping a Data Dictionary to a Tabular Import Properties File

The Three Files Involved

• Data Dictionary (.xlsx) — exported from the study build; lists every item on the target form along with its Item Name, Item OID, Item Group Name, and Item Group OID. This is the “answer key” for the mapping. This does not need to be uploaded for the import but is referenced when creating the mapping file.
• Data file (.csv.) — the actual data to import, one row per subject/form. In this example: Test_Tab_Import_date_formats_100023.csv.
• Mapping properties file (.properties) — tells the importer which study/event/form to import into, and maps each data file column header to an ItemGroupOID.ItemOID. In this example: template_tabular_import_mapping_TEST12SEP2023.properties.

Step 1: Point the Import at the Right Study, Event, and Form

At the top of the Data Dictionary, the Form, Event, and Study rows each show a display name followed by the OID in parentheses, for example “Inclusion and Exclusion(F_INCLUSIONAND).” Pull the OID out of the parentheses and drop it into the matching key in the properties file.

A detail worth noting is the StudyOID is written as S_CBTEST(TEST) rather than just S_CBTEST. This will not be visible on the Data Dictionary itself and usually needs to be confirmed from study runner.

Step 2: Map Each Data Column to an Item

Every column header in the data file (other than the two special ones covered in Step 3) needs its own line at the bottom of the properties file, in the format:

ColumnHeaderInDataFile=ItemGroupOID.ItemOID

The Item Group OID and Item OID both come directly from the Data Dictionary — Item Group OID is in the “Item Group OID” column, and Item OID is in the “Item OID” column, joined with a period.

A common point of confusion: the column header in the data file (“Arm,” “Thrombectomy”) does not need to match the Item Name in the dictionary (“STUDY_ARM,” “thrombectomy”) — the mapping line is what connects them. The client can name their data file columns however makes sense for their own records.

Step 3: Handle the Special Columns

These columns get their own dedicated properties file keys instead of an ItemGroupOID.ItemOID mapping, because they describe the subject and the event rather than an item on the form:

Supported date formats for EventStartDateHeader are yyyy-MM-dd, dd/MM/yyyy, or ddMmmyyyy (e.g., 01Oct2023) — worth checking against whatever format their source data file is actually using.

If the client is importing into a common event that repeats (for example, a repeating "Follow-up Visit" event rather than a one-time "Screening" event), they also need to include EventRepeatKeyHeader=EventRepeatKey in the properties file, with a matching EventRepeatKey column in the data file. This tells the importer which occurrence of the repeating event (1st, 2nd, 3rd, etc.) each row belongs to, so rows aren't accidentally created in or applied to the wrong repeat. This key is only needed for repeating events — it can be left out entirely when importing into a non-repeating event, as in this example.

Step 4: Set the Remaining Configuration Options

A few more keys control import behavior and are not tied to the Data Dictionary at all — they're just study preferences to confirm with the client:

• Delimiter — only matters for .txt files; ignored for Excel/CSV.
• FormWorkflowStatus — “initial data entry” or “data entry complete” for forms created by the import.
• ReasonForChange — the audit log reason used if the import updates an existing complete form.
• IgnoreUnmappedColumns — set to “yes” if the data file may contain extra columns that shouldn't be imported; “no” will cause the import to fail if any column is left unmapped.
• MatchCriteria / MatchAction — optional; only needed if the client wants the import to skip or update existing records rather than always creating new ones.

Putting It Together

Once Steps 1–4 are done, the mapping section of the properties file for this example looks like:

StudyOID=S_CBTEST(TEST)

StudyEventOID=SE_SCREENING

FormOID=F_INCLUSIONAND

FormVersion=1

ParticipantIDHeader=ParticipantID

EventStartDateHeader=StartDate

Arm=IG_INCLU_IN_6244.I_INCLU_STUDY_ARM_935

Thrombectomy=IG_INCLU_IN_6244.I_INCLU_THROMBECTOMY_1141

ICF=IG_INCLU_IN_6244.I_INCLU_ICF_9291

Followups=IG_INCLU_IN_6244.I_INCLU_FOLLOWUPS_2588

Confound=IG_INCLU_EX_3578.I_INCLU_CONFOUND_6428

Eligible=IG_INCLU_EX_3578.I_INCLU_IS_SUBJECT_ELIGIBLE_1647

Checklist for the Client

• Review a current Data Dictionary for the exact form/event/version you're importing into — OIDs can change if the form is rebuilt.
• Every data file column that maps to an item needs a line: ColumnHeader=ItemGroupOID.ItemOID.
• ParticipantID and event-date columns use their own dedicated keys, not the OID mapping format.
• If importing into a repeating event, add EventRepeatKeyHeader=EventRepeatKey and a matching column in the data file so each row lands in the correct occurrence.
• Set IgnoreUnmappedColumns deliberately — don't leave it on the default if you're not sure every column is mapped.
• Double-check date formatting in the source file against the three formats the importer accepts.