Click on the magnifying glass to the right. Starting typing a topic you wish to learn about

Edit Data Dictionary + Impact of Data Dictionary changes

Owned by Mary Irion
Last updated: Feb 02, 2023 by Alyssa Hill
5 min read

When uploading a data dictionary file, everything essential will be overrode! 

  • All instruments that are needed for your project, need to be included in the data dictionary file being uploaded

  • Make sure you don't just upload a single instrument, this will result in data loss

  • Read all considerations listed below before editing your Data Dictionary

Initial Considerations

Each row in a Data Dictionary spreadsheet corresponds to a field in your data entry form. The order of questions in a Data Dictionary file defines the order they appear in the database.

Column

Column Name (Row 1)

Description

Required?

A

Variable / Field Name

Lists the variable name

Yes

B

Form Name

Lists the auto generated form name

Yes

C

Section Header

Lists header that appears above question

No

D

Field Type

Lists field type, which is one of the following:

text, notes, calc, dropdown, radio, checkbox

yesno, truefalse, file, slider, or descriptive

Yes

E

Field Label

Label that appears on forms / surveys

Yes

F

Choices, Calculations, OR Slider Labels

Lists the choices, calculation, or slider labels.

Separates choices with |

Required for the following field types:

calc, dropdown, radio button, and checkbox

G

Field Note

Text that appears below answers

No

H

Text Validation Type OR Show Slider Number

Used to validate text questions and the type

of data it will hold

(E.g. date_mdy, number, phone, etc.)

No

I

Text Validation Min

 

No

J

Text Validation Max

 

No

K

Identifier?

Has 1 if question is marked as an identifier

No

L

Branching Logic (Show field only if...)

Lists branching logic

No

M

Required Field?

Lists 1 for yes

No

N

Custom Alignment

(Where the answers or text box is located,

if left empty, automatically is RV)

RV = Right / Vertical

RH = Right / Horizontal

LV = Left / Vertical

LH = Left / Horizontal

No

O

Question Number (surveys only)

 

No

P

Matrix Group Name

 

Required for Matrix fields

Q

Matrix Ranking?

 

No

R

Field Annotation

 

No

The Data Dictionary is a spreadsheet in CSV format representing the structure of your instrument database. Your Data Dictionary contains the metadata used to construct your data collection instruments. It captures the same information as the Online Designer, but displays it in a more concise format.

  • Changes you make with the Data Dictionary are not propagated in real time to your project; changes are not committed until you upload the modified Data Dictionary file.

  • Changes for development databases will take effect immediately, but changes to production databases will need to be reviewed and approved by the REDCap administrator before they take effect. The new structure will apply to both new and existing records.

Once your project is in Production you can make changes using the Data Dictionary. However, there are potential data loss ramifications. Take precaution by saving a copy of your project data so it can be retrieved in the case of data loss.

The REDCap project will store backup copies of previous data dictionaries in case a reversion is needed; but it does not store backup copies of project data.

Commonly requested changes & considerations to be mindful of:

Reference the "Best Practices" Knowledge Article which provides a detailed chart of the impact specific changes will have on your project. This is relevant to users whose project is in Production mode where real data collection has already began.

Commonly requested changes and considerations to be mindful of:

Deletion of Field annotations:
Different consequences result depending upon the action tag being modified.  For example:

  • If you remove the @DEFAULT action tag, this will not affect any existing data that has been saved (i.e. the instrument was opened either in survey mode and submitted, or in data entry mode and marked "saved" when exiting).

  • If  @hidden-survey is removed, questions will show in survey instruments

  • There are far too many action tags to be able to list  the impact of data dictionary changes in this article.  Think through what the action tag does and possible ramifications. Always export your data for retrieval purposes

Changing Field Calculations:

  • Changing field calculations is a bit tricky, but as long as you do not modify the fields included in the calculation, you can always revert the calculation back. If you have existing saved data for a calculation on certain records, and then change the calculation, the existing saved data will not reflect the new calculation unless you open that record, open the instrument, and allow redcap to re-calculate.

Branching Logic Changes:

  • Branching logic changes are also tricky.

    • If you'd like to remove branching logic from a question, this action will not affect any data.

    • If you'd like to add new branching logic to a question, you'll want to think about if that question has existing data for existing records. If so, assure your existing records will meet the new logic, otherwise their data will be at risk for deletion. If you determine the existing records will not meet the new logic, then we recommend you download existing data before submitting new logic.

    • If you'd like to modify existing logic, you'll also need to consider if there are existing data for existing records that may not meet the new logic.

Changing field types:

  • Changing from radio<>dropdown is fine.

  • Changing from radio/dropdown<>checkbox is not fine because data results are stored differently.

  • Changing from calculation<>text will delete data.

  • Changing from text>note is fine, but note>text may delete data via truncation.

Changing variable names (rename a field)

  • This will simply create a new field with the new name and the old field will no longer exist (and neither will the data). Do not do this!

Renaming the instrument

  • Don't use data dictionary to rename the instrument name. The instrument status data will be lost if using data dictionary to rename the instrument. Instead, you can rename the instrument in the Online Designer.

How to edit the Data Dictionary: ​

  1. Go to “Project Setup”

  2. Click on “Data Dictionary” (circled in red in image below)

  3. On the next page, click on “Enter Draft Mode” (this step only applies if your project is in Production Mode//skip this step if your project is in Development)

  4. To download current data dictionary and edit it, do the following:

    1. Click on "1.) Download the current Data Dictionary "

    2. Open and edit this data dictionary on Excel

    3. Save it as a CSV file

  5. Next, go back to REDCap, scroll to bottom of the Data Dictionary page, and click on “Browse”.  Then select the data dictionary CSV file you saved

  6. Next click “Upload File”.  This will then take you to a page that summarizes if the upload was successful or not.  If it wasn’t successful, it will inform you why.  If it was successful, click on “Commit changes” > review your changes in the Online Designer.

The below steps only apply if your project is already in Production

7. Review the changes made by clicking on "View detailed summary of all drafted changes", this is located in the yellow box at the top of the "Data Dictionary" page and/or the "Online Designer" page

8. Once you have made all the changes, next submit the changes. Do this by clicking on “Submit Changes for Review”, this is located at the top of the "Data Dictionary" page and/or the "Online Designer" page (circled in red in image below). 

9. The changes will then be reviewed someone on the REDCap Support Team.  You will receive an email that either says the changes have been approved or an email that warns you of errors that may happen if the changes are approved.