General Guidance

• Take advantage of calculations in forms to minimize errors. For example, if you are asking for a birth date, add a label afterwards that shows the calculated age. This may highlight an error in date entry if the age appears different than what the user expected.

• Use labels to force the user to stop and verify their information. You can add a label that shows the user data they entered and encourages them to verify if it is correct. See Common Logic and Calculations.

• Use groups to prevent writing the same display logic (and having to update it) for related questions. Groups also make it easier to manage large forms in the designer

• Don't try to do too much in one form. If you make a simple form that is easy to use it has a higher probabilty of success than a complex one that tries to tackle too much.

Getting Started

1. Login to CommCare.

2. Navigate to the Dashboard.

3. From the Applications section, click an application name or click new application.

Open

4. From the left navigation panel, click a form name. 

Open

The question tree for the form is displayed.

Form Builder Tools

Question Tree

The question tree displays all contents of a form and allows for editing and adding questions. It is structured in a branched view for ease of navigation.

Open

1. Navigate to an application of interest.

2. Open the Form Builder.

3. From the question tree, click the Add Question drop-down.

4. Select the question type of interest.

Note: The drag-and-drop method can be used to organize questions in the question tree after they are created. The question tree can be displayed by question ID rather than language by changing the Display setting in the Form Tools menu.

Question Types

There are several question types available for use in forms that capture data in multiple ways. Some require advanced formatting skills.

Please see for a full list of information: List of Question Types in CommCare.

Question Properties

After adding questions, the content, structure, and function of the questions are controlled with properties.

To access question properties

1. Navigate to an application of interest
2. Open the Form Builder
3. From the question tree, click a question of interest

Open

The question properties window is displayed.

Open

Note: More than one user can make changes to a form simultaneously. CommCare will prompt users to overwrite current changes or revert to the last saved version of the form if this occurs. When managing form properties, it is recommended that changes are saved often. CommCare will prompt mobile users to save changes prior to exiting a form in an application.

Display Text: text displayed to mobile users

Note: If the form will be deployed in more than one language, a field is displayed for each language.

Question ID: unique ID for questions displayed in reporting features but not visible to mobile users

Note: Responses to form questions are reported in relation to question IDs.

Open

Requirement: marks questions mandatory so they cannot be unanswered
Note: Users receive an error message if a required question is skipped.

Form Tools

Once questions are added to a form and properties are set, form tools can be used to manage views, export data, edit source code, etc. Some functions in this menu are appropriate for use by advanced users only. 

To access form tools

1. Navigate to an application of interest

2. Open the Form Builder

3. Click the menu icon next to the form name

Open

The form tools menu will be displayed.

Open

• Copy: Copies a question or group of questions.

  • This tool can be used to move single or multiple (CTRL +SHIFT) questions to a different portion of a form or into a separate form. If a question is copied into a group where a question ID is already in use, "copy-1-of-" will be prefixed to the Question ID, while the Labels and Choice Values/Labels will remain the same.

• Display: changes the question tree to display by question id rather than language (default)

• Expand All: opens all groups and choices for multiple choice and checkbox questions

• Collapse All: hides all groups and choices for multiple choice and checkbox questions

• Display: language of the Question Tree

• Expand Editor: opens the editor in full screen mode

• Export Form Contents: exports questions and properties to Microsoft Excel. Learn more at https://dimagi.atlassian.net/wiki/x/uCXKfw.

• Edit Source XML: opens form XML code for editing. This is feature is recommended for advanced users only.

• Form Properties: displays properties of forms such as Form ID

• Find usages: searches question or case property references within a form by question ID

• Edit Bulk Translations: opens form translations in a new window that can be copied and edited in Microsoft Excel. Learn more at Bulk Application Translations | Edit Bulk Translations for Forms.

Question Property Tools

Open

Open

• Question Type menu: changes a question type

• Delete: deletes a question or group of questions

• Show menu: displays options for sections of form properties to be displayed or hidden

• Logic: controls when questions are asked and what questions are valid

• Display Condition: (also referred to as skip logic) determines conditions under which questions are displayed

• Validation Condition: ensures responses meet specified constraints

  • Default value: displays a value upon accessing a form question which can be changed by the user

  • Required Condition: determines conditions under which questions are required. Only functional if the Required checkbox is enabled.

• Media: add audio, image, and video files to questions

Advanced: used for formatting applications using advanced features such as writing XML code for logic

• Validation Error Message: displays a message when a user response does not meet specified constraints
  Note: Messages are specific to the deployed language of the form.

• Data parent: links a form question as a child of another question

• Appearance Attribute: defines an appearance for questions
  Note: This is especially helpful for advanced formatting.

📖Learn more at https://dimagi.atlassian.net/wiki/x/NzXKfw.

• Comment: a field to add notes about application design choices (Example: question purpose, hidden value explanation)
  Note: Comments are only visible as a bubble above Question Properties in the Form Builder.

• Hint Message: displays a message below label text to provide clarification to a question
  Note: Messages over two lines of text are cut off after the character display limit is reached. Users can click a message to see full text.

Open

• Help Text: provides additional information about questions
  Note: Users will click the information icon to see full text.

Open

Open

• Add Help Media: displays media to aid users in responding to questions

• Add Other Content: text displayed to users
  Note: Display text should be included for each language of application deployment.

▫   Short: abbreviated version of display text

▫   Long:  long version of display text

Form Settings

All forms also have behind the scenes Form Settings. Learn more at