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.

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

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

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. 

Deprecating & Delete Case Types and Case Properties

You can use the Data Dictionary to manage and delete case types and case properties

You can delete case types or case properties using the Data Dictionary. This is useful when a project space has many case type and case properties which were created in error but are actually not relevant to you. A deleted case type will no longer be selectable as a filter in the reporting filtering menu, and will not be a case type filter option for case exports/imports. 

You can delete a case type in the Data Dictionary in following conditions:

• There is no case data stored for the case type in the project space

• There was case data stored for the case type but all of the case data of that case type is now archived

Should I deprecate or delete?

• One major difference between deprecating a Case Type and deleting a case type from the Data Dictionary is that you can only delete a case type which doesn’t have associated data with it but you can deprecate a case type even if it has data associated with it. 

• You can un-deprecate a deprecated case type but there is no way to undelete a deleted case type. You can however, always add the deleted case type back to the Data Dictionary. 

Delete Case Type

Summary

You can delete a case type from the Data Dictionary by following these steps:

• Click on the "Data" menu item and then select "Data Dictionary" from the left pane 

• Then click on the case type to be deleted in list of available case types.

• Finally, click on the button to delete the case type.

Please note, a case type cannot be deleted if there are cases that use this case type.

Restoring a Deleted Case Type

You cannot restore the deleted case type from the Data Dictionary. You can however, simply create the deleted case type again. Alternatively, if the case type is being used by an application, making an update to the application will cause the case type to automatically be created in the Data Dictionary.

The Impact of Deleting a Case Type

Once a case type is deleted from the Data Dictionary

• All the features using the case type filter dropdown option will not include deleted case types as available options, This includes features like Case Lists, Case List Explorer, Case Data Exports etc.

• It will not be possible to create a new case data export using a deleted case type.

  • Existing exports using deleted case types will not be affected.

• Users will not be able to import deleted case types using Excel.

• A new automatic rule cannot be created using a deleted case type. Existing rules using deleted case types will not be affected.

• All case properties defined under this case type in the Data Dictionary will also be deleted. 

  • The Application using the case type remains unaffected.  When a case type is deleted from the Data Dictionary the underlying case properties can still be referred back in an application. And if the case type is added back to Data Dictionary, the deleted case properties  will automatically added back to data dictionary configuration of that case type

Delete Case Property

Summary

You can delete a case property from the Data Dictionary by following these steps:

• Click on the "Data" menu item and then select "Data Dictionary" from the left pane.

• Then click on the case type that contains the case property you would like to delete.

• Click on the bin icon next to the case property that should be deleted.

• Finally, click on "Save".

Please note, a case property cannot be deleted if there are cases that use this case property.

Restoring a Deleted Case Property

You cannot restore the deleted case property from the Data Dictionary. You can however, always add the case property back which you had deleted initially. 

The Impact of Deleting a Case Property

Once a case property of a case type is deleted from the Data Dictionary : 

• Deleted case property will not be available for configuration of reports using features like Case Data Export setups and Case List Explorer. 

  • While setting up a Case Data Export for a case type, the deleted case property will not be available to be included in the configuration of export. 

  • While using Case List Explorer, the deleted case property will not be available to be included in the selected columns. 

• Existing exports using deleted case properties will not be affected.

• Custom descriptions for the case property will no longer show up in the form builder or case exports.

• Any validation rules set up on this case property will no longer be applied on case imports.

Deprecating / Restoring Case Types

You can deprecate case types or case properties using the Data Dictionary . This is useful for when you don't want to delete historical case types or case properties but you wish to hide them.

It is possible to publish new releases and submit forms with an application using deprecated case types. However, it's recommended to transition to non-deprecated case types for better compatibility and performance in the long run.

Showing Deprecated Case Types

Deprecated case types are not shown by default when loading the Data Dictionary. You can show deprecated case types by clicking on the “Show Deprecated Case Types” button.

Deprecating a Case Type

You can deprecate a case type by following these steps:

• Click on the "Data" menu item and then select "Data Dictionary" from the left pane 

• Then click on the case type to be deprecated in list of available case types.

• When you select the deprecate option, you will be informed of how many modules use this case type and the impact of the deprecation.

•  Click on the confirm button to deprecate the case type, and it will be marked as deprecated, as shown in the below example. 

Restoring a Case Type

• To restore a case type once it has been deprecated, select the case type from the case type list in the Data dictionary

• Then click  on the "Restore Case Type" button 

The case type will be restored and will no longer be tagged as deprecated.

The Impact of deprecating a Case Type

Below is a list of the impact that deprecating a case type has:

• The reports case type filter dropdown option will not include deprecated case types as available options.

• It will not be possible to create a new case data export using a deprecated case type. Existing exports using deprecated case types will not be affected, but a deprecated tag will appear next to the export.

• Users will not be able to import deprecated cases using Excel. If importing multiple cases in a single Excel file, only the cases belonging to case types that have not deprecated will be imported.

• A new automatic rule cannot be created using a deprecated case type. Existing rules using deprecated case types will not be affected, but a deprecated tag will appear next to them.

• A warning banner will be shown when building a new release on an application that uses one or more deprecated case types. The warning will not prevent a user from making a new build on the application.

• A warning banner will be shown on the case details page for a case that has a deprecated case type. 

Deprecating / Restoring Case Properties

You may deprecate case properties or case group properties by selecting the deprecate icon next to each of the definitions for the property.

You can view deprecated properties by clicking the "Show Deprecated" button. 

Once the button has been clicked, the deprecated properties will be displayed. Upon activating the button, the option to restore the deprecated properties will be displayed.

Effects of Deprecating Case Properties

• Deprecated case properties will not be displayed in a new Case Data Export unless you select the option to see deprecated properties.

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;

  • 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. There are tabs for each for each case type within the project space. 

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

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 team case type, each row has the case property and each column contains the property's details.

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. 

• If an invalid case property name or case type name is included in the import spreadsheet, appropriate error messages will be displayed until all issues are resolved. You can refer to the screenshot below for an example.

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