This page provides a future looking and historical mapping of changes that affect the support of compatibility of CommCare mobile app with features, devices, or historical versions.

It also provides a map of what options are available to manage changes.

Change Management Paths

Depending on the type of compatibility change, users have different options for ensuring a smooth transition

Android Version Compatibility

As the Android operating system grows, occasionally changes that are made to support the newest version of the OS will make it impossible to continue supporting a previous version. We make every effort to continue support of the newest version of CommCare Mobile on legacy devices for as long as is reasonably possible, but eventually cannot continue supporting older versions without sacrificing essential security or feature needs for newer phones.

Impact and Expectations

After one of these changes, devices running the now-unsupported versions of the operating system will not be able to see CommCare mobile on the Google Play Store, or be able to update existing installs of CommCare mobile to the newest versions.

Devices will continue to be able to run any version of CommCare mobile before the release which deprecated support, but features included in newer versions of CommCare will be unavailable.

Options and Actions

Compatible versions of CommCare can still be sideloaded onto mobile devices by installing the mobile app directly using the .APK package file. 

Dimagi maintains a full library of CommCare Releases to ensure the appropriate app is made available.

On CommCare HQ, the advanced setting CommCare Version can be set to the latest version that is installed on devices. That setting will prevent the web site from configuring applications which are incompatible with the defined version of CommCare.

CommCare Upgrade Compatibility

Each version of the CommCare mobile application stores and manages local databases, files, and other data in a very specific format. When an upgraded version of the app runs for the first time it needs to understand all of the data formats for previous versions to "migrate" the data to be compatible with the new version. 

We make every effort to maintain full compatibility with older installed versions of the mobile application until the older version are fully unused.

Impact and Expectations

Once support is dropped for upgrade compatibility, CommCare will not be able to run successfully if a device is upgraded directly from the unsupported version of CommCare to the newer version of the app, and data will not be able to be recovered. Unfortunately we have no mechanism to prevent devices from performing upgrades from incompatible versions.

Example: CommCare 2.0.0 is installed on a mobile device. The user navigates to the play store, and chooses to update to CommCare 2.100.0. Upon starting CommCare 2.100.0 they see a message that their old installation is incompatible and could not be recovered, and CommCare starts "fresh" as if no apps were installed.

Options and Actions

When a cease in upgrade compatibility in announced, the best option is to upgrade any devices to the newest version immediately, that will ensure that installs remain compatible with new releases.

In the rare case that an install must be upgraded which is already incompatible with CommCare's newest version, there are three paths which can be followed to ensure safe operation of the app

1. Submit and Reinstall - All local data on the device is submitted to CommCare HQ. Once the data is safely on the server, the legacy version of CommCare is uninstalled entirely, and the new version is installed from scratch. User data is restored on login.

2. Intermediate Upgrade - A sideloaded copy of CommCare which is supports upgrading from the legacy version, and is supported by the latest version of CommCare can be installed before applying the new update. Dimagi maintains a full library of CommCare Releases to ensure the appropriate app is made available.