Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Since Updating 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

  • Upgrading: The process of replacing the actual installed application binary (CommCare 1.3.0 to CommCare 1.3.1, for instance)
  • Updating: The process of replacing a specific deployment's resource 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

Upgrading CommCare

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

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 apps will need to be re-created in the new format entirely, the old resources 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. You only need to be concerned about the highest level updated when determining the steps. When updating from version 1.2.1 to version 1.3.2, the upgrade is a Minor version upgrade only, the Maintenance upgrade is irrelevant in terms of steps which need to be taken
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 new version can be re-installed, or the new version can be installed "in place" on top of the old version. Since Content is the process of updating an installed application to a newer version of the application that has been released from CommCareHQ.

Info
titleNote: Updating the CommCare software is different from updating a CommCare application!

There are two components to CommCare:

1- the CommCare software which is the the shell of the program. CommCare mobile client is the same for all projects.

2- the CommCare content which is often referred to as the "application" (forms, case management, multimedia, etc.)

These instructions are for the application content component. For instructions on updating the CommCare software, see this page.

Tip
titleMaking Changes to Application Content

Before deploying changes to your application you may want to read Making Changes to a Deployed Application which outlines how changes can affect data exports or application usability.

 

Table of Contents

Releasing New Versions and Updates

Once you have lots of versions they will all be listed as follows:

Image Added

The main function to be aware of is the Latest Released label. Once an application is marked as "Released" it means that when a mobile worker updates the application on their phone, CommCareHQ will send the most recent released version. You should be able to update your phone without re-installing your application with these steps:

  • Make a new version of the application on CommCareHQ
  • Click on "Released", and notice that the version that you clicked this on has "Latest" next to it
  • Update the mobile app (see below)

There are several other actions on this page:

  • View More - this button will allow you to see older versions, which are hidden by default.
  • Revert - this will restore your application on CommCareHQ to its state at the time of a version. For example, if you accidentally deleted a module, you can go revert to a version of the application that had the module.

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 marked as "Latest Released", it won't update, even if newer (unreleased) 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 unreleased build 74, the app will not attempt to update. If 74 is released, the current build will update the next time it checks.

Determining Your Current App Version

On CommCare Android you can view the current app version by choosing About CommCare from the settings menu either before or after logging in.

Image Added    Image Added

You can also determine the deployed version on CommCareHQ by using the Application Status Report in the Manage Deployment Reports.

Application Update Settings

Auto-Update

CommCare can be configured to check for updates on a regular schedule. This is specified by the Auto Update Frequency setting in the Advanced Settings section of the Application Settings. When set to auto-update, CommCare will attempt to check CommCareHQ for new resources on a daily or weekly schedule. This check occurs in the background, immediately after login. If updates are found, they will be downloaded and applied the next time the user logs in. Users can cancel updates being downloaded by navigating to "Settings -> Update App" on the mobile device.

If the app can't contact the server, it will try again on a future login.

Advanced Feature: Update Target Options: Allows you to turn on Developer Mode and use the Latest Saved State of your app without making a full release.

Manual Update

A manual update can also be initiated from the CommCare mobile application. 

Updating CommCare on Mobile

Android

Option 1 - Normal Update (Recommended Workflow): This option is the normal update workflow for apps, and is recommended in most scenarios. Your device will need to have a network connection in order to update this way.

  1. Log into CommCare (it is not possible to update CommCare when using Demo mode)
  2. From the CommCare home screen, open the settings menu by pressing the three dots in the upper right-hand corner (or your phone's Settings button) 
  3. Select Update App and CommCare will look for a new version, and download it if available. The version of the app that is downloaded will be the most recent starred build.
  4. When the download is complete, select the green update button to complete the upgrade process and log you out of the app
  5. Once the app is updated, you will see a message that reads "App update was successful" and you can log in again to start using the new app version

Image Added

Option 2 - Offline Update: This option is primarily useful in scenarios where you know that you will not have a network connection when performing the update. Note that you WILL still need a connection to download the .ccz file initially (step 3 below). This option may also be useful if you want to update to a specific version that is not the latest starred build, or (for advanced users) to update to a .ccz that you have edited locally.

  1. Connect your phone to the computer. Open the phone's SD card. (Sometimes phones will have two SD card folders - one in internal memory and one that is the actual physical SD card. In this case try using the internal SD card first).
  2. Make sure you have a file browser on your phone (This should come automatically with all devices). If you do not, you can download one from the Play Store (ex. Amaze File Explorer). 
  3. On HQ, go to the Deploy page for your app, find the build you want to update to, and then press the "Deploy" button for that build.
  4. Select "Offline Install" on the Download to Android menu that appears, and then click to download the file "CommCare.ccz". 
    Image Added
  5. Copy the downloaded .ccz file to your phone. 
  6. From the CommCare home screen, open the settings menu by pressing the three dots in the upper right-hand corner (or your phone's Settings button)
  7. Select Update App. If you do not have a connection, the app update screen will say "No network connectivity". However, you can open the settings menu on that screen (the three dots in the upper right-hand corner), and then select Offline Update.
  8. Choose the .ccz file that you just downloaded. If you cannot find the file, you may need to tell your device to "show internal storage" or "display advanced devices", which should be in the settings drop down when you open the initial file selection from CommCare. If this doesn't work, install Amaze File Explorer and select the file that way.
  9. Select Update App once more to start the update process.

CommCare for Feature Phones

Remote update is not well supported on feature phones; in general you should expext to simply remove the old version of the app and install the new version.

There is a update feature which sometimes works in areas with very good connectivity: Login as "admin" or a user with admin rights, and from the home screen navigate to Settings -> Check for Updates or in the login screen go to Options -> Tools -> Check for Updates

 

Expand
titleTechnical Details and Naming Conventions

When new features are added they are generally added to Major and Minor updates to CommCare. If an application on HQ is moved to a higher Minor or Major version number (1.2 -> 1.3 for instance), an application's resource files won't be able to be downloaded by an older version of CommCare.  

 

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

...

full re-installation

...

 should be used to update both at the same time (see note below)

...

Full Re-installation

  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.

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

Notes

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

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.

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.

Updating Your Application Resources

pending.

to-include: 

  • Auto-Update
  • Release "starring"
  • CC Spec V's