About the Feature

Data Dictionary provides a method for documenting case properties by grouping them, adding descriptions, labels and the expected data type. 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.

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

• Options for exporting and importing definitions to Excel.

• 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 data type, label, description, valid values, formats 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 mouse 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 mouse 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. 

Data Dictionary in Linked Project Spaces 

It is possible to synchronize the Data Dictionary across linked domains. In addition, 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 the downstream domain without the privilege of having access to the synchronized Data Dictionary definitions, but not to any Data Dictionary UI components, including the Data Dictionary admin page and app builder labels.

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

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

Bulk Manage Data Dictionary Definitions

Export Data Dictionary Definitions

In Data Dictionary, it is possible to export case property definitions for the current case type to Excel. This can be accomplished by selecting Export to Excel.

Upon export, an Excel file will appear as follows:

• In the sheet corresponding to the Case Type, you will find the following columns corresponding to Case Properties:

  • Label: the label of the property

  • Group: the property group, CommCare creates a new data dictionary property group and associates it with the Case Property;

  • Case datatype: the expected datatype;

  • Description: for a more detailed description of the property, it is useful to include validations, expected values, or relationships with other properties. 

  • Deprecated: accepts TRUE if the property is deprecated, FALSE otherwise.

An Excel file exported from the data dictionary is shown below. As there are no descriptions or groups in the data dictionary, the columns appear empty, and the label duplicates the property name.  Excel sheets were created for each type of case, and sheets with the suffix "-vl" will be created for each type. While the sheet with the property name describes each case property, the sheet with the suffix "-vl" describes each property that has multiple-choice data. 

Import Data Dictionary Definitions

Data dictionary definitions can be downloaded to Excel, updated, and then imported back into Commcare.  With this process, data dictionary definitions can be shared among different stakeholders, improving updates and accuracy. Furthermore, it allows for efficient changes to be made and keeps the application and data dictionary up-to-date.

Definitions can be imported by following these steps:

1) The first step is to initiate the import process. Select the Import from Excel option.

2) Prepare the file to import: CommCare will show a page for importing the Excel file, which includes the option for downloading the data dictionary definition since it is always a good idea to download the definition first. Here is an example of a file definition we are using for the same file that we downloaded from the export data definitions step. A new property will be added to the file definition by adding a new line.

Here is an example of an Excel file definition for a patient case type, each row has the case property and each column contains the property's details.

As shown in the image below, the Excel sheet patient-vl displays all properties of the patient case type marked as multichoice. 

3) Import the file: Select the file and select the "upload data dictionary" option. After the import is completed, commCare will display a message about the import. 

4) Check the updated definitions: On the left menu, click the Data Dictionary option to view the updated definitions.

FAQ

Can I import only the case properties definitions?

Commcare expects the Excel document to have two sheets, one with the case property and the other with the case property and the suffix vl. In the Excel file below, a sheet named person-vl was expected, but it wasn't found, resulting in an error message "Missing valid "household-vl" multi-choice sheet for case type household".