Open

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.  

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).

Open

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.

Case Data integration with the Data Dictionary

The latest update to the Data Dictionary integrates with CommCareHQ's Case Data page.

This integration allows you to use the data dictionary to configure the way case properties are displayed on the case data page. It is possible to rearrange case properties, organize them into collapsible groups, assign labels, and display descriptions. 

The screenshot below displays an example of the case data page. In this example, the data dictionary was used to configure the way the case properties are presented. We can see different data sets represented in different tables, with the black "i" icon, that provides additional information about the case property when hovered over.

All properties in the data dictionary show up on CommCareHQ's Case Data page, whether they were saved in Case Management or otherwise. The "---" indicate that no value has been set. Blank means the property has been set to an empty string ("") - often when it's been cleared out deliberately by a user.

Case properties that exist but were not saved using Case Management will show up in an "Unrecognized" category until they're added to the Data Dictionary. The “Unrecognized” category will only show up if Case Property Groups exist in the Data Dictionary.

If Case Property groups exist, but a property isn't part of any group, it shows up in the "Uncategorized" category.

To edit the case data page through the data dictionary, navigate to Data Dictionary located under Data tab in CommCareHQ. Once the relevant dictionary is selected, you will see multiple options per case property, as displayed in the screenshot below.

From here, you can use the arrows on the left to rearrange the properties, assign properties to different Case Property Groups, which will group and tabulate them, and add relevant labels and descriptions. 

Case Data Export integration with Data Dictionary

When you create a new Case Data Export for a specific case type,