The Data Import Tool can be used to import data from a csv file to update or create records in your project.
Jump to:
- Accessing the Data Import Tool
- Uploading a File with the Data Import Tool
- After Uploading
-
IMPORTANT NOTES
Accessing the Data Import Tool
You can find the Data Import Tool on the left-hand panel under "Applications".
The Data Import Tool page includes helpful language about how to upload a file. We will summarize that information here, along with some additional notes, but please read the instructions laid out on the page as it may contain information that we will not include here.
Uploading a File with the Data Import Tool
First, select your import option. Choose whether to import your file real time or whether to import it as a background process. Importing in real time will prevent a partial import and return errors immediately after processing - background imports are more suitable for larger files that would not process in a real time import, but they may take longer and can result in partial imports.
Then, choose your file.
The formatting of your csv file should match the formatting of a raw export of your data from REDCap. Metadata, such as variable names or event names (for longitudinal data) should be in snake_case formatting. This is the name of your field or event that is all lowercase with underscores to represent spaces.
Where to find column names
In Designer:
In Codebook:
Where to find event names
In Project Setup:
In Codebook:
To see an example of how your csv file should be formatted, try exporting a simple subset of data. There are a few settings that will change how your export/import is formatted:
- Longitudinal data
Data from different events will be stored in separate rows. As long as you have your [record-name] field in the export (for most studies, this will be [record_id]), you will also have the [redcap_event_name] column which will specify which event the row of data corresponds to.
- Repeating Instruments
Similar to longitudinal data, reports and exports store repeating instances of forms on different rows. This would introduce two new columns to your csv file, redcap_repeat_instrument and redcap_repeat_instance. The redcap_repeat_instrument column will contain the name of the repeating instrument, and the redcap_repeat_instance column would contain the numeric instance (1, 2, 3, etc.) of that form for that row of data. Each instance will have its own row. If you are importing new repeating instrument data and you do not care about the instance number, you can instead use the value "NEW" in redcap_repeat_instance, which will inform the system that the instances of data should be auto-numbered.
Choose whether to display the comparison table. This option is only available with real-time imports. The comparison table allows you to review your import data against any existing data in the location where it is being imported. See the example below.
Gray text indicates that the data in your import file matches the existing data, therefore there will be no change to that data. Black text is an indicator that the data in your import file is new to the location it is being imported into. (Red text) will only ever appear in the company of black text, which displays the data that will be overwritten if you finalize the import.
If your project has auto-numbering enabled, you will also have the option to auto-number/overwrite record IDs.
If all the records in your file should be new records, and there are not specific record names they should have, then this may be a viable option. Otherwise, keep this setting disabled so that the import will retain the record names you've generated and either update or create the appropriate records.
If your import file has intentionally blank cells that should overwrite data in your project, you might consider modifying the "overwrite data with blank values" dropdown.
Finally, if you may modify the file format settings (if necessary).
When you are ready, select "Upload File".
After Uploading
If you are importing in real time, you will be immediately notified of any errors once the file has processed. None of the file will be uploaded as long as any errors are present. See the screenshot below for an example of an error message.
If you are using a background import process, you will be brought to this page. You may refresh the table to keep track of progress. You may also select "Halt import" at any time if the import must be cancelled. You will receive an email notification when your import is completed.
IMPORTANT NOTES
Calculated fields cannot receive import data. Including calculated fields and their values in your file will not harm the process, but the import process will ignore the value. This is because calculated fields are intended to be processed by the REDCap application from the calculation in the field, not from an imported value.