The following set of instructions will guide you from a new mobile phone just out of the box to a mobile phone ready to run your CommCare application. Instructions concerning the menu of the mobile phone assume that you are using the Nokia 2700 Classic – exact menu settings may differ on other phone models. The steps covered for each method should be followed exactly for successful installation.
Cliquez ici pour les instructions d'installation en français.
Please note: A more simplified versions of these instructions can be found here. If you encounter any difficulties installing CommCare using these simplified instructions, please proceed with the instructions found on this page.
Install a CommCare Application
CommCareHQ is most compatible with the Google Chrome web browser. Please download Chrome here.
This video will walk you through the installation steps. Detailed instructions are below.
Step 1: Set the Phone Date
Set the date of your phone to any date before Nov 2015 after Nov 2013. For example, set the date to be October 1, 2015.
(The last step of the install process is to correctly set the date again, but this step is necessary for the install process to work).
Step 2: Installing the Application
Option 1: Install from Application Files
- Login to your domain. Click on the "Applications" menu. Click on your Application that you would like to download and install. Navigate to the Release Manager.
- Locate the version number that will be used for deployment.
- Click on the "deploy" button.
- Choose "Download to Java Phone"
- Download the .jar and .jad files. Ensure they both have the same name (e.g. CommCare.jad and CommCare.jar, not CommCare (1).jad and CommCare.jar). The size of the jar file should be around 700 kb. The size of the jad file should be around 6-8kb. Usually these files will be saved to the 'Downloads' folder on your computer.
- Connect your phone to your computer. You can do this in a variety of ways:
- Option 1: Bluetooth
- Turn Bluetooth ON: Menu->Settings->Connectivity->Bluetooth->Bluetooth->On->Yes
- Change the phone's bluetooth name to something unique: Menu->Settings->Connectivity->Bluetooth->My phone's name->[enter name]->Ok
- Ensure bluetooth is enabled on your computer.
- Option 2: USB Cable
- Connect your phone to your computer using the USB cable (usually the phones come with one)
- If a pop-up screen says "Select USB Mode," select "Data Storage."
- Open the folder on your computer that represents the phone
- Option 3: MicroSD Card (Requires an SD card adapter)
- Remove the MicroSD card from your phone
- Put the MicroSD card into your computer's card reader (you may need an SD card adapter)
- Open the folder on your computer that represents the MicroSD card
- Option 1: Bluetooth
- Copy the files from your computer to the phone's SD card. If you have correctly connected your phone to the computer, the SD card should show up as a folder under My Computer.
- If you removed the SD card from your phone, put the MicroSD card back into your phone.
Option 2: Send to Phones via SMS
- Ensure the phone has GPRS connectivity and data credit
- Delete any existing CommCare apps from your phone's local memory
- Login to your domain. Click on the "Applications" menu. Navigate to the Release Manager.
- Locate the version number that will be used for deployment.
- Click on the "deploy" button.
- Select "Send to Phones by SMS"
- Type the phone number of the phone and hit "Send"
- The phone should receive a text message. Open it, and click the link in the message.
- Scroll down using the center button and until the selection is on the bit.ly link.
- Click on the center key or ‘Use’ to open the link.
- The phone will ask whether you would like to go to this web address. Select “Go to” and hit the center key.
- The Opera Mini mobile internet browser should open. Please wait a few moments while the phone connects to the internet. You should see an ‘E’ or ‘G’ symbol in a box in the top left hand corner of the screen if the network coverage is excellent or good. Network coverage needs to be present and stable in order for a user to successfully download the full application directly to their phone.
- Once loaded, the CommCare download should appear which displays the CommCare.jad file. The “Open” button will be already selected in blue. Press the center key to start downloading.
- The phone will start loading the information it needs to download the application.
- The phone will display an application notification asking you to ‘Accept’ and confirm the application download. Hit the center key to ‘Accept.’
- The phone will then begin to download the application via GPRS connection. This process could take hours to several seconds depending on the network connectivity.
- Once the download is complete, you will be asked if you want to close the browser and open the application. Hit the center key to answer ‘Yes’.
- You will be asked if you want to allow editing and adding data. This is one of the three application permissions that need to be set. You may answer ‘Yes’ for now and then return to complete the final application settings.
- CommCare should initialize, load resources and start-up correctly.
- If the application is downloaded using this method, the application automatically downloads into the ‘Games’ folder in the ‘Applications’ folder.
- Accept all download confirmations.
Option 3: Phone to Phone Installation
You can install a CommCare application from one phone to another without the need of a computer or Nokia software. This process is especially valuable if the application needs be re-installed in the field. Refer to the full tutorial here: Phone2Phone Installation.
Step 3: Installing Multimedia
Option 1: Source not on multimedia media manager
- Connect your phone to your computer (see Install Option 1 item 6 for details)
- Open the Memory card.
- Copy the multimedia folder from the computer into the phone's memory card. The multimedia folder must be in the top-level directory/the main memory card folder.
- OR, if your multimedia has been uploaded to the Multimedia Manager, you can download the media from CommCareHQ directly.
Option 2: Source is multimedia media manager
- From the Release Manager, click on Deploy.
- In the pop-up window, click on Download Multimedia
- If you see an orange button that says 'Download Incomplete Multimedia' it means the media associated with this application has not been uploaded to the Multimedia Manager in CommCareHQ.
This means that the application is missing references, so this zip will be incomplete. Please make sure all of your application's multimedia references are linked to media files before starting your Application, or it might be unstable. Please ask your application builder for these files and follow option 1 steps to install the media.
- Click on Download ZIP. The file will be downloaded as a ZIP and you will have to unzip the file in order to use it. By storing and transmitting it as a ZIP is a good idea so that you don't lose any of those media files!
Step 4: Store CommCare on local phone memory
We recommend storing CommCare from the phone's local memory because it's much easier to manage phone settings and it is safer and more secure opposed to storing the application in the memory card. If you installed via SMS the application will already be on local phone memory.
- To move CommCare files from the SD card to the phone’s memory, access the SD card on the phone’s “Applications” menu.
- Scroll to the application file called “CommCare”. This is the file which displays the CommCare logo.
- Press “Options” which is the left soft key button.
- Select “Move”.
- Now, you can select the location where you want to put the CommCare application.
- You may transfer the application file to either the Games or Collections folder. Select the “Games” folder OR select “Collections” folder. Keep the folder you choose consistent for all users.
Step 5: Setting Nokia Phone Permissions
Various actions (reading the file system, submitting data, etc.) require user permission before they can be performed on Nokia phones. You can configure the phone to always allow (or any other level of permission) these actions in order to make the application run more smoothly.
- Ensure that the application (not the multimedia folder) has been moved to the Games or Collections folder (on the phone's local memory) and not the Memory Card. The phone must be turned off and on after the app is moved/copied onto the phone's memory.
- Set the application's access to the phone's resources. Select the application, click on the left options key for options. Select Application Access. Configure the three permissions outlined below:
- >CommCare>Options>Application access
- Communication->Network access->Always allowed->Yes
- Communication->Connectivity->Always allowed-Yes
- Data access->Read user data->Always allowed->Accept
- Data access->Add and edit user data->Always allowed
More information on Nokia Phone Permissions can be found here: Nokia Phone Permissions
Step 6: CommCare First Start Up
Initializing the application:
Error upon first opening CommCare? Don't panic!
If you have a large application, you may get an "out of memory" error the first time you open CommCare. Don't Panic! Just try opening CommCare one more time and it should work. We are working to correct this but it only happens the very first time the application is opened on a phone.
- Locate and open the application on your phone.
- The application will self-initialize and load resources.
Step 7: Re-set the Phone Date
Set the phone's date to the correct date. We recommend using the setting that gets the date/time from the phone network.
Step 8: Test your Application
- If there is multimedia in the application, at start-up the application will validate whether the defined media files are all present on memory card. If not, the application will notify you which media files are missing.
Perform a test:
- Open the application.
- Open the registration form.
- Enter some details as a test entry.
- Check to make sure that at least one of the messages plays when you press the # key.
- Go through the registration form until the end.
- Open the subsequent form (one that is not the registration form) and make sure that the test client you just created is displaying in the case list view.
Perform a GPRS test:
- Log into the phone application as "admin"
- Click “Options” which is the left soft key button.
- Scroll down to “Network Test” and click.
- The network test will start automatically.
- The screen will say “Beginning test” and should shortly say “Connection open and configured”. However, continue waiting because the internet connection to our server hasn’t yet been verified. Remember to watch for the “G” or “E” in the top left hand corner of the screen which indicates the phone is accessing the mobile network.
- If the connection is successful, it will say “Received response code”.
- If the connection is NOT successful, it will say “IO Exception [error in HTTP operation]”.
Set a CommCare Shortcut
For easy access, you can set a shortcut to the CommCare application. Follow these instructions to do so.
- Menu->Settings->My shortcuts->Right selection key->Application list->CommCare
- Menu->Settings->My shortcuts->Left selection key->Camera (if needed)
Note: In some phone models, CommCare will not appear in the Application list unless all the application permissions are set and the application has been opened at least once.
Manage Multiple Applications
On Feature phones it is possible to install multiple CommCare applications.
Step 1: Make folders for the applications
Make a folder for each Application so that the user can distinguish among the applications. For example if you have two applications, one called Maternal Health, and one called Farm Survey, you would create a folder for each of those surveys within the Games Folder, My Apps or wherever you are storing the applications. Keep only the CommCare application in the folder so that it will be easy to identify and open.
Step 2: Merge the multimedia files
If the applications do not contain multimedia, or if only one of the applications contains multimedia, this step can be skipped.
If more than one application contains multimedia files, in addition to creating separate folders you must merge the multimedia files.
Choose one multimedia folder to become the "primary" file. Carefully copy and paste all of the media files from the other multimedia files into this primary file. This means taking all of the media files from each media-type sub folder (i.e. images, audio, video) and putting them into the corresponding folder in the primary file such that the file maintains the same file-path. In the end you should have one multimedia folder that contains the media files for all of the applications.