This page provides an overview of how to navigate using CommCare Android, describes different types of settings you can consider, and presents question types that are only available on CommCare ODK (not in J2ME).
This guide assumes that you have already installed CommCare ODK.
One major decision in how to configure CommCare ODK is Sense Mode. Sense Mode, when turned on, disables advanced features that may be confusing to new users, especially form management. Below, those features which are disabled in Sense Mode are indicated. More detail can be found on the page about CommCare for low-literate users.
Getting to Know CommCare for Android Smartphones
There are some tricks to effectively navigating in CommCareODK, and some features that are not easy to find. Below are some of the key features you may find useful.
What does "ODK" mean?
CommCare for Android is sometimes referred to as CommCareODK. ODK stands for Open Data Kit, an open-source project for mobile data collection using the XForm standard. CommCare for Android is closely integrated with ODK. If you have used ODK in other projects, CommCareODK will look very familiar to you. Here in the CommCare Help Site, CommCareODK, CommCare for Android, and CommCare for Smartphones, all refer to the same thing!
Your Android Device
There may be a number of buttons on your Android device, but as pictured below there are three buttons that are important for using CommCare.
- Menu Key: The Menu key usually looks as pictured above, but may also look like three dots stacked vertically. This button is used to access settings and menus.
- Home Key: This button will bring you back to the phone's home screen.
- Back Key: Is used to return to the previous screen.
Getting Started with CommCareODK
1- After clicking on the CommCare icon, you will reach the log-in screen:
Here you will need to enter a username and password (see left image). Note that unlike J2ME CommCare, there is no "admin" login. There is a demo mode- to enter demo mode you only need to push the phone's setting button. You can get information on how to create and manager users here. Please note the following:
- The first time you "Log In" you must have internet connectivity. After pressing “Log In” for the first time, there will be a few moments during which CommCare makes sure that the information on your phone is up-to-date with the server (see right image)
- After you log in the first time, even if you log out and then log back in (with the same username) you do NOT need internet connectivity.
- The username of the last user to log in will remain in the “username” box, even after logging out.
The Home Screen
The main screen (“home screen”) of CommCare ODK has several important features clearly visible (note the above shows CommCareODK with form management active on the left, and with Sense Mode on the right):
Get Started: This is where your users will go in order to access the forms and submit data.
Form Records (Note: In CommCareHQ both “incomplete” and “saved” forms are disabled, as in the image on the right, above.):
- Incomplete: stores forms that are only partially complete, or have not been submitted in their final form. By clicking here you will get a list of incomplete forms. You can choose a from the list to open and complete it.
- Saved: stores forms that have been recently submitted to the server. You can select a form from the list in order to review the data. Pending forms (submitted but not successfully reached the server) will be displayed on the top.
Sync with Server: forces to phone to synchronize with data on the server. The text below the button will tell you if there are pending forms. If there are a lot of pending forms the text will turn red to alert the user. If you have forms you want to force the phone to submit, you can press “sync with server.” However, you will have to press it again after the forms have been submitted in order to actually sync and for the “last synced” time and date to update.
Log Out of CommCare: Logs the user out so that the data on the phone is secure.
You can translate many parts of the home screen into most languages. See our page on user-interface translations to learn more.
Home Screen Settings
LEFT: If you click on the “options” button on your phone (often looks like a box with lines, or three dots) you will access the home page settings menu:
- Settings allows you to access some advanced tools (see next slide)
- Update CommCare tells the device to check CommCareHQ to see if there is a more recent starred build. If there is, CommCare will update (connectivity required) and you will need to log-in again.
- Call Log shows a record of all calls/messages that originated from CommCare ODK.
- Clear User Data: if you choose this, it will delete all of the current users’ data and bring you back to the log-in screen.
- About CommCare provides some legal info about CommCareODK
- Force Log Submission forces CommCareODK to submit technical metadata to the server. This can be useful to the software team when troubleshooting problems. A CommCare team member could request you to do this if there is a recurring bug in the software.
Navigation Within Forms
When you open a form you will get the landing screen (left) that shows users how to navigate within a form by swiping the page. When you try to skip a required question, or enter a value that is outside of the permitted range, a message will alert you that you must correct your answer. If you press the options button/soft key, you will see four advanced options displayed at the bottom of the screen:
- Save Form
- Go To Prompt
- Change Language
- Change Settings
- Pressing “Save Form” (left) will store the form as incomplete in its current state. You will be able to access this incomplete form from the home screen
- Go To Prompt calls up a list of all the questions/labels in the form. If you have already entered values they will be displayed below the question text.
- You can scroll up and down to review your answers, and is the preferred way to quickly review a form prior to submitting.
- You can click on any question in order to go directly to it and update/enter a value
- Go To Start brings you to the first page of the form, and Go To End brings you to the last page where you can submit the form
- Go Up is only applicable in repeats.
- Change Language allows you to toggle between the display text languages.
- Choosing Settings presents several additional options:
Settings includes the following options:
- Link to the Open Data Kit website (ODK)
- Text Font Size for changing the size of the display text. You only have to do this once in an app and all forms will default to the text size you have chosen
- Default to Finalized should be left as is
- Show Splash Screen is currently not activated
Exiting a Form
- Save Changes: stores a version of the form as incomplete. This can later be opened and updated
- Ignore Changes: deletes any changes you made/data you entered and brings you back to the home screen
- Cancel: brings you back to the form you were working on
This section goes through some common question types either because they are unique to CommCareODK or because there is important information on how to use the question types.
Single select questions are fairly easy- you simply select the desired option and the circle will show as filled. If you hold you finger continuously on an option you will get a pop-up screen that says "Edit Prompt: Remove Response." If, for example, you accidentally answered a question that you wanted to leave blank, you can remove your choice through the "remove response" tool. It is also common for users to "accidentally" get the remove response message by holding their finger too long when selecting an option.
Image Question (captures an image)
CCODK cannot accept large image files. Anything greater than 1MB could cause issues including slow syncing and failure to upload the picture to CCHQ.
The best rule of thumb is to use a small (< 1MB) file size when taking pictures within CC. VGA files seem to work particularly well. You may have to manually adjust this in your camera app if you prefer to take larger size pictures outside of CommCare.
If you are looking at a report in CCHQ and you either can't find an image you know you captured, or you see an image file name but it is not linked to anything, make sure that you did not take a very large image.
Using Multimedia (Images, Audio) in Your ODK App
For instructions on how to use and install multimedia in CommCare click here. When you add an audio or video file you can play it by selecting the button in the upper right-hand corner:
Generating a QR code in your form
In the place of an image, a question can be configured to display a QR code which contains text that is dynamically set in the form.
To configure a question to display a QR code in the Form Builder, find Add Other under the question's Content header, and click "custom". When prompted for a content type, enter qrcode, then enter the text you want to be encoded in the QR code into the new label.
If you want the code to contain data from the form (like a case ID or a computed value), you can use advanced <output> features as outlined in the Hidden Value Calculations Tutorial. You can test the content by displaying it first in a question's normal label if needed.
This feature is only available in CommCareODK 2.8 or higher.
Using Multimedia (Images, Audio) in Your ODK App
When you reach a GPS question, the user will be presented with a "Record Location" button. Upon selecting the button, a loading screen will indicate the accuracy of the GPS coordinates. When accuracy gets to 5 m the coordinates will automatically be captured and displayed on the screen. If you do not need such high accuracy, you can record the location earlier. Once the location is displayed in your form, you simply swipe to go on to the next screen. Selecting "Record Location" again will re-initiate the GPS capture process and can overwrite the first set of coordinates.
Case List and Details
In CCODK case list view it is important not to put too much text or data in the case list as this will make it very difficult to navigate through the case list. Below you can see examples of a case list (left) and case details (right). Click here for more information on case lists.
In CommCareODK you can use "hint text" which will appear in a smaller font underneath your display text. To add hint text in the app builder, open the "Advanced Properties" tab and put your text in the "hint" field.