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 https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143955800

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

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: https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2213544088

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

The question properties window is displayed.

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

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

• 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

The form tools menu will be displayed.

Question Property Tools

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

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

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

• 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

Frequently Asked Questions

Q: How do I edit the source code of a form?
A: To edit source XML:

1. Navigate to the Form Builder.

2. Click the Form Tools menu dropdown.

3. Select Edit Source XML.

4. Click Update Source when finished.

Q: Can I copy a form from one application to another?
A: Yes. Download the form locally from its original location and upload it to the new location.

To copy a form to a different application

1. Login to CommCare

2. Navigate to the Dashboard

3. From the Applications section, click an application name

4. From the left navigation panel, click the gear icon next to title of the form of interest

5. Click the Actions tab.

6. In the XForm section, click Download.

7. Open the destination application.

8. Add a new form.

9. Repeat steps 4-5.

10. In the XForm section, click Upload.

11. Choose the form that was downloaded from the source application.

Note: Case save and load properties are preserved with this method. If only certain questions are needed from a particular form, the copy and paste method should be used to paste them into the new form.

Q: Can I use a different program to create my form?

Yes, please see .

For best practices for application creation and tips from our global Field Managers see .

Form Building Tips & Tricks

Command Bar in Form Builder

To assist with application building efficiency, we created a feature for use in formbuilder that allows you to add questions via a command bar interface. You can now quickly add questions to your form without having to use your mouse!

How to Use

To open the command bar when in form builder, you can use the following shortcuts:

• For Mac: ⌘ + ;

• For Windows: Control + ; 

Once the command bar is open, you can enter a command and press <Enter> to execute it. Currently there are two command types: Add a New Question and Jump to Question.

Add a Question

To Add a New Question, there are three parts to the input:

1. Question Type

   1. This refers to the various question types used in CommCare (i.e. Text, Integer, Date, etc.).

2. Position (optional)

   1. This command will allow you to dictate where the question is placed in the form. There are currently 4 commands:

      1. Before: Used to put a question before another one

      2. After: Used to put a question after another one

      3. In: Used to place a choice in a Multiple Choice or Checkbox question or inside a Group based question (Groups, Repeats or Question list)

      4. First In: Used to place a choice in a Multiple Choice or Checkbox question or inside a Group based question (Groups, Repeats or Question list)

   2. If you do not specify a position the new question will be added after the currently selected question

3. Question ID (optional)

   1. This is the question you would like to place the question type near, relevant to the position you input in the second step.

   2. The currently selected question will be used if you do not specify a Question ID.

   3. This section will always start with #.

When entered in the command bar, the format will look like:

<Question Type> <position>  #form/<question_id>

Jump to Question

For the Jump to Question command, there is one part to the input: the question path. When entered in the command bar, the format will look like:

#form/<question_id>

Example: Add a New Question

We have a registration form in an application tracking the outcome of a woman’s pregnancy. We want to get information regarding the mother’s age, but forgot to add a question asking it. Let’s do that now.

Using the shortcut (Control + ;  for Windows or ⌘ + ; for Mac)  will open a command bar at the top of the question tree:

Selecting the bar that states “Enter Command” will open a drop-down window with the various question types you can add to a form:

 (Note: This field should be auto-selected after using the shortcut) 

Since we want to ask about the mother’s age, we will want to add an integer question. We’ll also want to place the question after the ‘Village Name’ question (question_id = village_name). So, we’ll want to enter the following into the command bar:

• Integer after #form/village_name

Once we input this text and hit enter, an Integer based question will be added to formbuilder. Since we used the after position, it will appear after the question, “Village Name”

After adding the question, you should automatically have the new question selected so that you can continue using your keyboard to fill out the Display Text.

Notes/Caveats

• Each command will auto-fill so you can use your arrow keys to move up and down the list to select the appropriate question type, position or #form/<question> that you want to select.

• Hitting <Tab> will auto-complete the current argument and move the cursor so you can start typing the next argument.

• When entering a command, it is not necessary to type out each argument entirely. For example, to add a new label after the current question one can simply type Ctrl+; to open the command bar, then L so Label is the top/selected option in the auto-complete list, then <Enter> to execute the command.

• In and First In are used for multiple choice, checkbox or group based questions.

• When using Jump to Question it is not necessary to type the exact question path. Instead you can type # followed by part of the question ID or path. For example:
  Ctrl+; #age <Enter>

Using Excel to Build CommCare Forms

Have a very long survey that you’d rather put into an Excel file before uploading in the form designer? You can use XLSForm, a free, online form-building tools that allow you to design your form in an Excel file, and then copy the created XML code into the CommCareHQ form designer. You can work on the Excel file offline and then upload it later.

You can see detailed instructions on how to set up the Excel file here. 

Warning

There are many XLSForm advanced formatting options that will not work with CommCare. Please review the Known Limitations section below carefully before building forms using XLSForms!

This tool (XLSForm) is provided by a third party, and it is not within the responsibility of the Dimagi/CommCare support team to maintain or support.

Overview

Build your form in Excel (following the instructions on ) and then upload it to XLSForm ( ). You can then download the XForm and upload it into our form builder on HQ.

As you build your form you can test it online using the validation tool: https://opendatakit.org/use/validate/

1. To load into CommCare, download the xform, a file that will end in .xml 

2. Once in the app builder on CommCareHQ, create a new blank form. You can then upload the xform directly on the form settings page by clicking on the gear icon for the respective form, then selecting the "Actions" tab and "Upload".

Notes while building your form

• We strongly recommend that you test this with a short form before building a huge form so that you are comfortable with the process.

• If you are familiar with XML, you may notice some differences in syntax between the XML generated and CommCare’s language – Don’t worry! Noticeable differences are validation writing and writing for display conditions (what XLSForm calls “relevancy”). As all of these tools are based on the same standard, CommCare HQ will automatically fix the minor differences from FormHub syntax to meet our syntax requirements.

• To avoid issues with itext and how CommCare deals with languages make sure to specify the language in the header. For example, if your app is only in English then make sure to put "label::en" instead of just "label" - if you do CommCare will add two languages (default and English).

• To keep using "data" as the ID of each form (the CommCare standard), please be sure to name your excel file "data". CommCare may not recognize the "settings" tab of the Excel file described XLSForm.

• Labels (called "notes" in the other tools) are often treated as text questions when the form is uploaded to CommCare. There are 2 easy ways to address this issue. #1 You can change the question type from Text to Label in the CommCare form builder. This is a known issue and will eventually be fixed.  #2 If you use the question type "acknowledge" then CommCare will interpret that as a label with the checkbox confirmation turned on.

• You can test your forms online using https://opendatakit.org/use/validate/

Using non-Latin languages and alphabets in the XLSform-XML process

If you choose to use XLSform's ability to handle multiple languages, by reading the XLSforms documentation and adding additional columns to contain the additional language content, please note the following:

• The XLSform documentation tells you to create additional columns and give those new columns headers like label::English.  However, if your purpose is to eventually paste that XML into CommCare, then you need to be careful about what the title of the language you use in those column headers. For commcare use, you should not use the full language name like "English," but instead must use the "short language codes," such as en and tha, that are shown in the little "Languages" pull-down menu in CommCare's left nav bar. Therefore your additional column headers will look like label::en  or required_message::tha.

• If your additional language content uses alphabets other than the latin character set, you will have to be careful about the way that you handle the process of copying your finally converted XML file into CommCare. Normally, many users would simply double-click the XML file that they had downloaded from the converter, select-all and copy, and then paste that XML into the CommCare forms editor. However, on Windows, it is likely that the default application that loads when you double-click the XML document will not display the non-latin character set correctly, and will therefore paste as gibberish into your CommCare form. If this happens, then, when you download the XML document from the converter, open it in a text-editing application that is more able to handle non-latin alphabets (one example is the Notepad++ app for Windows.) This app will correctly handle the non-latin characters in the XML, and then you can successfully cut-and-paste from that app into the CommCare form editor.

Known Limitations

There are some things that don't work well when uploading a Formhub form to CommCare; these are active efforts to make these more compatible

• You may get an error message when uploading your form that CommCare xmlns will be added. You can ignore this message. If, once inside the Form Builder, you see a persistent error message about the Form Name make any minor change in the form, save, and refresh the page.

• When first opening your form to edit you may see a message that says "id is not defined." Just click "ok" and then make any minor change in the form, save, and refresh the page.

• If you have multiple languages in your Excel form but not in your CommCare app, any additional languages that are not already in your app will be deleted.  Before uploading anything go to the application -> languages and make sure all languages are added. On the languages page you will see that each language has a 2 or 3 letter code (English = en; Hindi = hin). In your Excel file you must use those codes in the headers. So for English you would use "label::en" as the header for the label column on both tabs of the Excel file. These are case sensitive.  Alternatively you can upload the xform with one language, add the additional language, and then use Bulk Translation to add additional languages.

• Both tools described here uses the name of you Excel file as the root of all of the xpaths in your form. So if you call your file "survey" then your data will look like /survey/question4 instead of /data/question4. You cannot change this after uploading into CommCare. We recommend that you name your excel file "data" if you want to be consistent.  

• The "add other option" for multiple choice questions will generate the "other" question with the correct question ID but will not generate the correct skip logic.

• You may also notice some extra "hidden values" at the bottom of your form after using the Excel tools. You should delete these.  These hidden values are formhub, uuid, meta and instanceID.  

• Advanced features link hint text, multimedia, read-only, and complex logic may not be well supported.

Shortcut for creating the XLSForm format from CommCare's Export Form Contents

You may end up with an Excel form that is formatted like Export Form Contents as generated in CommCare, where all of the choices and questions are on one page. Below is a process to simplify breaking it into two pages.

The two parts of the process are:

1. Split the choices from the questions (e.g. if the question is "What block do you live in" then the choices would be "Manjhanpur", "Mooratganj", "Kaneli", etc); and

2. Format the sheets to match what XLSForm wants.

Here are the steps

1. Create a new column in excel that is the name of the question for the choices. To do this, you can use an if statement. If you have the question names in column C and the type of question in column H, then it would bethe following: =if(H3="Select Item",C3,C2) . This way, if you have a question, it will copy the question name, and if you have a choice, it will copy the value above it, which will be the question name from its question.

2. Create a new column in excel that equals 1 if the row is a choice and 0 if the row is a question.

3. Copy the two new columns that you created and paste special values them on top of themselves.

4. Sort the newly created column of 0's and 1's for question to split the questions and choices. Then copy the choices to their own sheet.

5. On the new choices sheet, get rid of the columns that you don't need anymore. Then change the column headings to match the format required.

6. Go back to the sheet with the list of questions. Use find and replace to change the names we have used for question type with what xforms uses (e.g. select_one rather than single select, text rather than text question. So find and replace all "single select" with "select_one").

7. Create a new column in excel. In this column, if the type of question is select_one or select_multiple, then the value should be "type nameofquestion". If it is any other type, then it should just be the type of question.

   1. For example, if the type of question is select_one and the name of question is consent, then the value in this column should be "select_one consent". If it is a text question, then this value should be text. To do this, if the question name is in column B and the type of question is in column C, starting from the 3rd row, you can use =if(OR(C3="select_one",C3="select_multiple"), C3&" "&B3, B3).

8. Change the names of the columns to match the format  for xforms and delete any that you don't want. You will need to delete the validations if you have not edited them for xforms format.

9. Upload the form following the instructions above

Quickly Referencing Form Questions & Case Properties with Hashtags

The below is a primer on how to reference form questions and case properties using the hashtag shortcut.

When in doubt, you can always drag and drop questions or case properties from the windows on the left of the form builder. But if you want to go for speed, here's how the hashtags work

Let the Autocomplete Dropdown Help You Out

You don't have to know the exact format of the hashtag reference in order to use hashtags. Just enter # and start typing to narrow down results. An autocomplete dropdown will appear that displays the best matches to what you've typed.

Autocomplete finds matches by case property name, question ID, and question text.

Reference Form Questions

References to form questions always start with #form. They follow the format:

Let's say I want to reference the question with the id "favorite_color". The reference would be:

Reference Case Properties

References to case properties always start with #case. They follow the format: 

Let's say I want to reference the case property "case_name". The reference would be: 

NOTE: If your app has multiple case types, this reference can only access case properties in the case type defined in your form's module. 

Child Cases

If your current module's case type is a child case, you can also reference case properties of the parent case. References to the parent case follow the format:

Let's say I want to reference the case property "case_name" of my parent case. The reference would be:

It is also possible to reference your parent's parent. For example, if you have three modules: household, family, baby, where "family" is a child case of "household", and "baby" is a child case of "family". In the baby module, you can reference the name of the household (my "grandparent" case) using the following format:

Let's say I'm in a form in the "baby" module, and I want to reference the name of the household. The reference would be: