Data Dictionary
The Data Dictionary provides a method for documenting case properties by grouping them and adding descriptions and labels. By doing so, it is easier to visualize and contextualize the property within the context of the case.
The documentation of case properties will aid in understanding their purpose and possible behaviour, facilitating collaboration, troubleshooting and maintenance.
- 1 The Data Dictionary Administration Page
- 2 Data Dictionary during Application Building
- 3 Managing the Data Dictionary
- 3.1 Manually Add New Case Properties to the Data Dictionary
- 3.2 Add Case Property Group
- 3.3 Add/Remove Properties to the Case Property Group
- 3.4 Setting Data Types for Import Validation
- 3.5 Importing Cases with Import Validations
- 3.6 Case Data integration with the Data Dictionary
- 3.7 Case Data Export integration with Data Dictionary
- 4 Deprecating & Delete Case Types and Case Properties
- 5 Bulk Manage Data Dictionary Definitions
The Data Dictionary Administration Page
The Data Dictionary administration page provides access to all items in the Data Dictionary. All case types and properties are readily accessible including the following features:
Importing and exporting case type definitions.
Deprecating and adding case properties.
Deprecating and adding case property groups.
Deprecating and adding case types.
Note: Linked Project Spaces
It’s possible to synchronize the Data Dictionary across Linked Project Spaces . An upstream domain with the Data Dictionary privilege may push its case type definitions to a downstream domain without the privilege. This scenario will result in a downstream domain which does not have access to the Data Dictionary UI (Admin page and App builder functions) having access to synchronized data dictionary definitions.
Getting Started
To access the data dictionary admin page, follow these steps:
1. Using the Main Menu, choose Data (1), then View All (2).
2. Choose the Data Dictionary option on the left menu of the Data Page
3. You will be directed to the Data Dictionary page, similar to the image below
The left-hand menu shows all the case types in the domain and highlights the definition of each.
On the main page, the following items are included:
Name of the case type.
Deprecated case properties button that displays deprecated properties for the current case type. The default display conditions do not show the deprecated case properties.
Each property includes the label, description and the option to archive the case property.
An option to add a new case property.
The ability to add a new case properties group.
Data Dictionary during Application Building
View Descriptions in the Form Builder
Hover your cursor over the case properties in the App properties section of the form builder to view the case property definition as saved in the Data Dictionary.
If the case property is referenced in the form question, the description can also be viewed by hovering the cursor over the property.
View Descriptions in the Application Summary
Upon selecting the case summary, each property in the case will be displayed with its description underneath.
View and Add Descriptions when saving a Property to the Case
When a case property contains a description, it will be displayed beneath the name of the property. If that description is updated, it will be reflected in the data dictionary as well. Each time a new property is added to the case, it will be added to the data dictionary. In the event that the description of a property is updated, the update will also be reflected in the data dictionary.
Managing the Data Dictionary
Any time a new application is created, or a question-to-property mapping is saved in the Case Management of a form, the Data Dictionary is automatically updated to reflect the latest case types and property mappings.
Manually Add New Case Properties to the Data Dictionary
A new case property can be added to a case type in the Data Dictionary in two different ways:
Firstly, this can be accomplished by adding new rows to the case export Excel file and then importing this file into the Data Dictionary.
The second option is to fill in the text box next to the "Add Case Property" button at the bottom of the page (see the below image), and then click "Add Case Property" to create a new entry. After creating all your case properties in this manner, click the button
to complete the process.
It is advised to create and save case properties in small batches.
If an error is made during the process, simply refresh the page and the unsaved changes will be removed.
Click the button at the top right of the page to complete the process.
Add Case Property Group
Case properties can be grouped using the Case Property Group. You can manage which case properties are associated with the Case Property Group by dragging and dropping them into or out of the group. Click the button at the top right of the page to complete the process.
Add/Remove Properties to the Case Property Group
The Case Property Group can be used to group case properties. To manage which properties are associated with the Case Property Group, drag and drop case properties into or out of the group. To complete the process, click the button at the top right of the page.
Setting Data Types for Import Validation
You have the ability to set data types for case properties in order to enforce specific formats and values during case import. This helps keep your project’s data clean and standardized over time.
When saving a data type for a case property, depending on the selected type, CommCare HQ will check that the values you’re inserting meet the criteria of the data type (see below for the complete list of validations). These validations only occur on case import, not during data collection.
The list of valid data type options and their validations are outlined below:
Data Type | Validation Criteria | Example(s) |
|---|---|---|
Date | YYYY-MM-DD | 2025-01-31 |
Number | Integer or Decimal | 23 or 12.4 |
Multiple choice | User defined | 1 → “Yes” 2 → “No” The above key value pairs means CommCare HQ will validate all imported case properties to make sure it matches either “1” or “2”. “Yes” and “No” are simply display text. |
GPS | Lat Lon (optional Elevation, Precision) | Valid: 42.123 -71.456 42.123 -71.456 100 42.123 -71.456 100 5 -42.123 -71.456 -10 5.5 Invalid: 42.123 +71.456 (plus sign) 42.123 (Missing longitude) 66° 34' N 23° 27.5' E (Not decimal) |
Phone number | 5 or more digits (optional (), ., +, or -) | (555) 123-4567 +1 555-123-4567 12.34.56.78 |