You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 11 Next »

Since CommCare is an engine for running individual applications, there are two things that could be meant when referring to updating an existing application CommCare installation. We'll refer to them as

  • Software Upgrade: The process of replacing the actual installed application binary (CommCare 1.3.0 to CommCare 1.3.1, for instance)
  • Content Update: The process of replacing a specific deployment's resource and content files (Version 34 on the release manager to Version 38)

This page provides a guide on how to perform each of these processes, and some of the gotchas which could come up when doing so

CommCare Software Upgrade

CommCare is changed over time to add new features and fix bugs in previous code. You'll need to upgrade the binary application files in order to take advantage of those features, or get the bugfixes. Some features will be available simply by upgrading the CommCare software. Others may also require updating the application's resource files (See Content Update below) to enable the features.

Each CommCare application has three version numbers in the format A.B.C where each stands for the following types of changes

  • A: Major Version
    • Structural updates to how and what data is stored by the application. Existing content will need to be re-created or updated to the new format, the old content format can't be used.
  • B: Minor Version
    • Additions to how and what data is stored by the applicaiton to enable new features. Existing apps will still work, but may need to be re-installed. User data should be restored from the server.
  • C: Maintenance Version
    • Bug fixes and minor changes. Other than replacing the existing binary, no other changes are generally necessary.
So CommCare Version 1.3.2 has a major Version of 1, a minor version of 3, and a maintenance version of 2. How to update your CommCare installation will depend on the platform (j2me v. Android) that you are currently running on, how the application was installed, and what CommCare version is currently installed.

Upgrading on J2ME

There are two ways to upgrade a J2ME app. The main supported method is for the new version to be re-installed and then data restored from the server.  You may also utilize an unsupported upgrade method called "In-Place" Upgrades under specific circumstances as detailed under Advanced Upgrades. In order to upgrade to a new major version, remember that you will first need to migrate your content to the new version as well.


  1. Ensure that connectivity is available on the device
  2. Log in on the phone with the existing version, and make sure that there are no pending forms awaiting submission to the server
  3. Remove the existing installation on the device
  4. Install the new version of CommCare, and configure all device permissions as necessary
  5. Start up CommCare, and choose to restore user data from the server. Enter the name and password of the user and recover their data from HQ.

Upgrading on Android

New releases of CommCare ODK on Android will be provided by the Android Market, as long as the application was installed from there. The app can be configured to update automatically or upgrades can be chosen manually. Since Android phones will install CommCare through the market, only the latest of each supported major release will generally be available. Specific major and minor versions can always be downloaded manually from Dimagi's build server, but shouldn't be necessary, since the newest minor version should be compatible with all previous minor versions (IE: CommCare 2.2.1 shouldn't have any problems running applications build for CommCare 2.0.3)

Major Version (1.N.N -> 2.N.N)

The process for a major version upgrade is to install the new CommCare ODK application for the market and install the new application into it.

Minor Version (1.1.N -> 1.2.N)

Minor version upgrades may require the application to re-fetch resources or user data from the remote server when run the first time after an upgrade. CommCare should be started immediately after an upgrade (while data is available) to handle any changes which might need connectivity.

Maintenance Version (1.1.1 -> 1.1.2)

No manual steps should be necessary.

Content Update

Updating CommCare is the process of getting the version of your applications resources (XForms, Translations, menus) onto a device. This is what needs to happen if you've changed your application on CommCare HQ and want to get that version distributed out.

The most thorough way to update an application is to do a complete re-install, and then restore the user's data from the server. This tends to be fairly straightforward on J2ME, and generally fits with how most people use that workflow, but is rarely a good workflow for CommCare ODK. 

The itself application can fetch new resources and update your application depending on a few considerations, which are outlined here

Making Releases ("Starring" Builds)

Since you can make a build of your app at any time for testing purposes, it is important to be able to mark which version of your application you want to see put on devices in the field when they update. We refer to this as releasing a build. In CommCareHQ, you can do this by clicking on the empty star next to a build once you've had a chance to test it out and make sure that everything is working as expected. This signifies that the app is ready to be installed.

When looking for updates, CommCare apps will look at the latest, released build. If an application is already updated to (or was installed with) the newest build which has been starred, it won't update, even if newer (unstarred) builds have been created. If the latest released build's version is lower than the installed build, an update will not occur. If, for example, the last release was version 70, the currently installed build is version 73 (for testing and development) and there exists a newer unstarred build 74, the app will not attempt to update. If 74 is released, the current build will update the next time it checks.


CommCare can be configured to 


CommCare Versions

Advanced Software Upgrades

Since CommCare's resources are almost always included with the application files, upgrading CommCare often happens at the same time as the Application Resources are updated, and as such a full re-installation should be used to update both at the same time (see note below).  This method of upgrading is not fully supported, but can be used by experts.

In-Place Upgrade

In-Place upgrades basically involve installing the applicaiton onto the phone without first removing the old version. This is possible using the OTAPhone-to-Phone, and Memory Card installation techniques. It is never recommended unless you are using a completely offline deployment, or in specific future use cases where OTA installation is being used to manage remote upgrades.

The below are guidelines for the minimum that should be required when performing an upgrade. Keep in mind that the safest way to upgrade an app is to always follow the full re-installation instructions.

Major Version (1.N.N -> 2.N.N)

Major version bumps will first require the migration of your application's resources to the newest version using CommCare HQ. Once a build of the app is available on the newest version is available, you should follow the full re-installation instructions.

Minor Version (1.1.N -> 1.2.N)

Minor version bumps shouldn't require any changes to your application resources (although they will often permit you to include new features in them), simply create a new build with the existing resources and perform a full re-installation

Maintenance Version (1.1.1 -> 1.1.2)

Maintenance releases are generally designed to be safe for an in-place upgrade on top of the old app (generally in order to correct bugs with OTA upgrades, although this feature isn't widely usable yet). However, a full re-installation is still recommended.


  • In CommCare 1.N (and currently the 2.0 alpha, although it should be fixed before release), your application's resources will not be updated if you install "in place" a previous installation by replacing the old .jar and .jad files with new versions.
  • No labels