This page outlines recommendations for designing and building useful CommCare applications. These are compiled from collective experience in app construction and are only recommendations. Individual projects could vary substantially and the overall best practice is to go through extensive user testing and piloting to identify and correct language, media, or work flows that are confusing.
We have created an excel template that we like to use as an application spec. It's proven useful for defining and sharing the proposed application before starting to build it. If you choose to build your application first in the form builder/HQ, you can now generate a document very similar to the application spec. This is found in the form builder under “advanced” -> “export form contents.” You can then select all and copy the contents into an Excel document. Exporting or working with the content in an Excel document makes it easy to show the overall structure of a form, which is useful for sharing and discussing.
Download the Example Spec
Question ID and Case Property Naming
Have descriptive and consistent naming for your Question IDs and case properties. They are used in data exports and when doing case configuration.
- Descriptive: Use something like date_of_birth not dob. CommCare allows for long names if you want to be descriptive. Another person should be able to looks at your names and understand the data.
- Be consistent with casing (i.e. always use lower case)
- Use the same name for the same question in different forms and the same case property name in different forms
- User underscores instead of spaces (as spaces are not allowed)
To test your Question IDs, choose "export form contents" under Tools to view all questions in your form.
Naming Conventions: Menus and Forms
Users will navigate the application using form and menu names.
- Names should clearly describe what the menu or form does
- They should be short names (fit on one line of the phone's screen)
- Use the same name for forms with similar functions (ex. registration in different modules)
Case management is what makes CommCare uniquely useful for front line workers. Some important things to consider:
- Show properties that will help user find the case they want
- Add sorts(Case List Sorting) and hidden properties to help user search for the item they want.
- It is possible to have several case properties displayed in the case list, but should consider the device type you are using. Phones have smaller screen sizes, and therefore will be able to display fewer properties in the case list, whereas tablets have a more space on the screen to show more properties. In general, 3 to 4 properties is a good number to display in the case list.
- Can show more properties than case list.
- Add properties that will help user make sure they've picked the right case
- Add properties that will help user before opening a form for the case
- Use the Format option to display case properties correctly for the user. See Case List and Case Detail Configuration.
- Use ID Mapping if displaying any case properties that store item values. This will make sure friendly text is shown.
- Saving and loading of case properties into the form is an important aspect of case management
- In the event that you are saving and/or loading case properties into specific hidden values, consider organizing those hidden values into question groups called ''save'' and ''load'' respectively. This will help you stay organized with the movement of case properties.
Before deciding to include multimedia in your application, think carefully through what the goal of multimedia will be in your application. Some applications may not need multimedia (pure data collection or advanced users who don't need support).
- Writing a good audio script:
- Audience: Is the audio for the person using the phone or the beneficiary. This changes the message and phrasing of the audio messages.
- Counselling vs. Support: Do you want to use audio to help user answer a question (for low literate users) or as counselling for the beneficiary
- Language and Dialect: Try record audio from someone who speaks the local language/dialect. Use simple language that users/beneficiaries will understand.
- Validate the audio script: Before you start with the actual recording process, welcome feedback about the audio messages with your field team. Modify the phrasing of the audio messages based on feedback from FLWs, field staff and sector specific experts. Here are some things you can gather feedback on:
- Verify local expressions being used are relevant, understandable and correct.
- Confirm that the information in script coincides with field practices. If not, dispel any discrepancies.
- Ensure comprehension of technical words, such as medical concepts.
- Selecting the voice/speaker:
- Good qualities of a speaker include:
- Native speaker of desired language
- Clear voice and enunciation of words
- Understanding of where to put emphasis in a phrase
- Reads messages naturally
- Speaks at a good pace (not too fast, not too slow)
- Other considerations for persuasive behavior change communication include:
- perceived influence or authority in certain kinds of voices (i.e. perceived education, or age of the speaker)
- preference for male or female speakers
- Ask speaker or a couple selected speakers to record a few messages. Compare the messages recorded by each and discuss with your team which voice(s) you would like to use in the application.
- Good qualities of a speaker include:
- Prepare ahead with your speaker:
- Share the audio script with the speaker a couple of days prior to the recording if possible.
- Let the speaker familiarize themselves with the text and give them an opportunity to ask questions.
- If possible, make the person who developed the script available to answer questions.
- In most cases all small discrepancies with the script is noticed at this point can be revised immediately before the real recording starts.
- Time allocation for recording: FLWs might not be used to doing such recordings, or are taking time off from their regular work to work with you. They need ample breaks between recordings. Given these reasons, recording may take longer than you expect, so allocate more time for recording than you might expect. Let the speaker know how much time is expected for the recordings. Plan breaks.
- We recommend you select a high quality microphone/recording device.
- We discourage using laptop microphones. The audio is usually very poor and processing such as noise removal may not be able to improve the quality of recordings made through a laptop microphone.
- Some headphone microphones may be suitable.
- We suggest you test the quality of the audio recording for 1-2 files before purchasing the device and recording the full audio set. Test out the files on the mobile phone you will be using if possible.
- Some recording devices are highly sensitive and pick up background noise easily. If this is the case with your device, we suggest covering the mouth piece with foam or a cloth. This will help reduce background noise to a large extent.
- If your recording device records audio files in different audio formats, we suggest you switch the format to mp3 mode on the recording device itself. CommCare applications are compatible with the mp3 format only. Recording the files in this format from the beginning, will save time later on.
- If you are using existing media that you want to integrate into CommCare, there are online tools available to convert the audio files from one format into mp3 format.
- If you forgot to save the audio files in the mp3 format as you recorded them, you can change the format at the time of processing. Once processing is complete, you may export them in the mp3 format.
- Record a short test take before starting to ensure equipment is functional and audio quality is good.
- Carry extra batteries on recording day!
- Recording Set-up:
- Bring two printed copies of the audio the messages on paper: one for the speaker and one for the project staff to follow along. Project staff can listen for missed words or mistakes. You may also number the messages in large font for ease of reference.
- The mouth piece of the microphone should be directly in front of the recording person, it should not be too close to her mouth also. The front face of the microphone should be facing the person whose voice is being recorded.
We recommend that the person who is recording the audio files (the one holding the device, not the person who’s voice is being recorded), use headphones attached to the device to listen to the voice as it is recorded. We have found this is a helpful in determining the clarity of the recording, and will indicate to you whether any background noise or interferences were also captured. Be careful not to use a headphone that has a microphone attached to it, this sometimes creates a disturbance as two microphones are working simultaneously at the same time.
Depending on the pronunciation of the speaker you may need to adjust the position of the recorder. Generally, a 45 degree angle downwards from the mouth works well. Additionally, a 1 inch gap between the mouth and the recorder is recommended. Common problems with positioning of the equipment:
- If recorder is too close to the mouth, you will likely see large sound peaks that are harder to remove for sounds like "bh", "ph" for example.
- If recorder is too close to the mouth, you capture breathing in the script which is hard to remove or reduce in the processing phase.
- If recorder is too far from the mouth, you capture other sounds (like your voice or breathing or those of people sitting around you) that you do not intend to.
- Tips for the speaker during the recording:
- Have the speaker speak clearly and slowly — slower than feels natural, with good annunciation, discernible breaks between words, and plenty of pauses.
- Have him/her speak slightly louder than usual ("project") but not so much that it sounds unnatural
- Have them read each phrase in order with a short pause after each (~3 seconds).
- Have them read the number (in English, if possible) before each phrase, with a short pause (~1 second) between the number and the phrase.
- The numbers will aid greatly in identifying which phrase is which, especially if they were recorded in a language other than your own.
- Do several takes. It's ok. Third time's the charm sometimes!
- Recording Environment:
- Pick a quiet place with little background noise or disturbances.
- Both recorder and 'speaker/talent' should remove all accessories which may interfere with the recordings (ex. jewelry, keys, phones). It will be very difficult to remove disturbances in the processing stage.
- If recording outdoors, find shade. If in a room, find a well-ventilated room.
- Make sure you bring sufficient water to the recording session for your speaker.
- Processing: For processing steps see Recording Audio for CommCare.
- Managing a large number of audio files: There are many ways one could manage a large number of audio files. Here are some tips to make it easier:
- Have the speaker or the recorder say the number or title of the audio message that is being recorded at the beginning of each message. Or you can create a sound effect (i.e. a clap or tap on the table) during the recording itself that will denote the start and end of recording different messages or the perfect message. You will visually see this sound peak at the time of processing.
- Approach 1: Record all the phrases in one take (one audio file). Don't use a separate file for each phrase. If the recording is interrupted with background noise and the speaker messes up, let the recorder keep running and continue on when possible, starting with that same phrase.
- Approach 2. Record a separate file for each audio message in your script. Read out the message number at the beginning if you do this.
- Regardless of which approach you take, first splice out the best audio recordings for each message. These are your rough cuts. Name them according to the question ID/keyword in the Definition File. You can do individual or bulk processing of audio files in Audacity. Instructions here: Recording Audio for CommCare
- Local Images: Use a local illustrator so that images appear local to the area.
- Unique Images: If images are being used for low-literate user support, try make each image unique. This will be less confusing.
- Test Images: Test images! Images you may understand may be confusing to beneficiary or user. For example, a digital thermometer picture may not be understood by all your users.
If data is important for you application, design your questions and case properties accordingly. Thinking through what you want in the data will help inform the application.
- If using case exports, add indicators you care about to the case (either by calculating them in forms or just saving some form questions to the case)
- Depending on what you need to track, decide on subcases for children, referrals, etc. vs. storing all data in a single case type
- Test your exports! While building the app, test the exports to make sure that you're capturing data you need and nothing that isn't essential For example, date that form is filled out and user ID is automatically captured.
- Turn on CommCare Sense Mode For most applications, this will result in a simpler user experience for low literate users. Some advanced features may be hidden (ex. Saved/Incomplete forms on CommCare Android)
- Turn on Two-Way Sync: This will let ensure that if cases are reassigned, the user will be able to load them on their phone.
- Setup Daily/Weekly Sync: If you're using case sharing, make sure you have daily or weekly sync on your phones so that users have a fresh version of any cases.
- Set Text Input for Java Phones: Set to Native for non-english typing or full screen for QWERTY.
- For Java Phones, set CommCare version to the latest available (indicated by a *)
- For multilingual applications make sure each of the following is translated:
- Question labels/display text in a form
- Names of forms and modules
- Any information displayed in the case list and detail (including ID mapping)
- User Interface translations (User Interface Translations) for your language. Common language (ex. back, form is loading) should be updated.
- Set the default language of your application before creating your released build. Drag and drop the languages and put the default language at the top.
Overall Form Structure
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 (see the Beginner's Guide)
- Consider including a success/you're done with the form label as your last question. This can be particularly useful on J2ME phones by giving the user an opportunity to correct any errors and make it clear to the user that the form is ending..
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.
While selecting a question type may seem very straight forward, there are some interesting usability issues associated with different questions that are important to consider.
Text input is the most time-consuming and error-prone type of question. Wherever possible replace text questions with single select questions. If there are a lot of options for a response, consider breaking it down into several shorter lists (i.e. first ask which village, then depending upon that answer ask which part of the village). Text input questions are especially difficult for any illiterate user and can be intimidating for many users. Where possible these questions should not be required and there should be a workaround to gather the information.
Numeric Input (Integer, Decimal)
Make sure you choose carefully whether you want an integer or decimal number in you data and choose the question type accordingly.
Keep in mind that neither integer nor decimal questions keep leading zeros. If you need to maintain leading zeros choose Phone Number/Numeric ID Question Type
If you need to have a number of a specific length (i.e. for an ID number), put a string-length constraint on the question (see Common Logic and Calculations)
- Many applications have lots of yes/no questions. Keeping the order of these consistent makes it easier for the user to navigate through the forms more quickly. However, varying the position means that the user has to pay more attention to the actual answer.
- If a single select question dictates what the next question will be (if yes show question A, if no show question B) it is best to make the single select question required.
- On J2ME phones add the appropriate numeral before each display text (i.e. the first option should have "1." before it so the user knows which button to push)
Multi-select questions allow the users to choose more than one answer from a list. While this may seem relativley straight forward we have found that the use of these question types can be extremely confusing and error prone:
- On J2ME phones the check box for multi-select questions can be very difficult to see and the multi-select question type confusing to use. The user has to select each answer individually and then navigate to the bottom of the list of choices to select “done.” This is very different from how the other question types work, so users sometimes end up selecting and then un-selecting the same choice in their attempt to complete the question.
- On smartphones (ODK), when swiping from one question to another some users accidentally select additional options from the list.
As such, we recommend that you minimize the use of multi-select questions by doing the following:
- Break multi-select questions into a series of single select questions. A multi-select question with four options, "Which pregnancy danger signs are you experiencing, if any?" can become four, quick, single-select questions asking yes/no if the user is experiencing each symptom. This is worth doing if there are up to 4-5 options and if it is useful for the client or user to be asked these questions directly.
- Overall, it is best practice is to have 1 yes/no such as 'is patient experiencing symptoms' and then multiple single select yes/no questions for all the symptoms. This will make the form longer, however, is more user-friendly. Having single select yes/no questions for each symptom also forces the user to really acknowledge each symptom; sometimes if they are in a list, they will not carefully read all the choices.
If you do choose to use a multi-select question, we strongly recommend that you do the following:
- Keep the list short enough so that it all shows up on one screen. If you have to scroll to get to the bottom of the list, the user will often miss those options. If your list is too long consider breaking it into more than one question.
- You could also consider preceding it with a single-select question so that the multi-select question is only displayed if applicable.
If "none" is one of your choices make a validation condition that prevents user from selecting "none" in addition to other options (see Common Logic and Calculations). And then make sure you add a descriptive validation message!
- If you are going to add a GPS question make sure that GPS works well on your phone in the areas you will be working. Don't make GPS questions required unless you're sure you can get them every time.
- Consider what the user should do if they can’t get a GPS reading while they are in the field. This could include a follow up question that is displayed if the GPS question is left blank, and asks the reason.
Minimize repeating logic and question content. Instead, whenever possible, create a hidden property that performs the calculation once and refer to the output of this variable wherever is required.
- Labels used for displaying the value of hidden properties: create a hidden property called debug and set its Calculate Condition to true() or false(). Set the Display Condition of the debug label to /data/debug
- If the answer to a question needs to be stored in a different form field and case property based on a logic condition, only include the question in the form once, then create a hidden property for each form or case property that needs to get populated. Set its Calculate Condition to point to the actual question being displayed and set the Display Condition to point at the logic that decides if that particular form/case property needs to be populated. Do not repeat the same question multiple times. Using hidden properties ensures that the form is easier to maintain and simpler to translate because a change only needs to be made to one question rather than multiple questions.
- Create hidden properties even for simple calculations, in particular all calculations that include "magical" constants. For example, if multiple questions need to know if a child's age is under 60 months, create a property named child_under_5_years and set its Calculate Condition to /data/child_age_in_months <= 60. This approach ensures that if this number changes, it's easy to update one hidden property. Furthermore, it makes obvious what that particular piece of logic does - it checks that the age is under 5 years based on the age on months. It's always easier to read a variable name rather than trying to understand a logical statement.
Creating a validation condition for input-type questions can be very useful as a way to minimize the risk of users entering erroneous data. However, you should keep the following in mind:
- Validation conditions should always be accompanied by descriptive constraint messages that will clearly inform the user what they need to correct. You can also add audio to constraint messages. For example, you may want to put a limit on a birth date to make sure the user doesn't accidentally put a date in the future. But if you don't put a constraint message the user may not understand why their answer was not accepted. This can be very frustrating for the user.
- You want to be careful about your validation - if a user enters data in the field that doesn't fit your validation rule, this could prevent your app from being used. Make sure that your conditions are realistic and consider allowing an extra margin on your allowed values to permit extreme cases.
- You can make very "smart" display logic but it is critical that the trainers and field staff understand that logic very well. Otherwise they, along with the users, may be very confused by why certain questions show up in some cases but not others.
Required questions prevent the user from moving forward in the form without entering or selecting a value. Be careful when specifying a question is required - if the user of the application cannot determine the value for a particular question (ex. they are transcribing from a paper form and the particular value is not filled in), this can prevent them from submitting any data. If necessary, you can add a follow-up question that asks why a particular value was blank.
The types of questions that generally need to be required are ones that "name a case" or that determine what subsequent questions will be displayed.
The very "smart" display logic that help to train the staff understand that logic very well.