Update Your Application

This page describes the process of updating your CommCare application to a newer version in CommCare. It also explains how to manage and release different versions of your CommCare application.

1 Releasing & Managing Application Versions
2 Steps to Release a New Version of the Application
3 Ways to Update an Application
4 Updating CommCare Application on Android

Important to Note!

Updating the software means updating the entire CommCare program, while updating the application means updating the content specific to your project within CommCare.

To learn how to update CommCare software, please visit Upgrading to the Latest Mobile Version.
To learn how to update a CommCare application, please follow this Wiki page.

Releasing & Managing Application Versions

This section covers how to manage and release different versions of your CommCare application.

Releasing a new version of an app in CommCare is necessary for several reasons:

Bug Fixes: To fix any issues or bugs in the previous versions that may affect the app's performance or user experience.
New Features: To add new functionalities or improve existing ones, enhancing the overall capability of the app.
Content Updates: To update forms, case management workflows, multimedia, or other content to reflect changes in project requirements or data collection needs
Security Improvements: To address any security vulnerabilities and ensure the app remains secure for users and data.
User Feedback: To incorporate suggestions and feedback from users to make the app more user-friendly and efficient.
Compatibility: To ensure compatibility with the latest versions of the CommCare platform and mobile operating systems.

By releasing new versions, you ensure the application remains up-to-date, functional, and effective in meeting the needs of its users and the project goals.

Steps to Release a New Version of the Application

Step 1: If there are any pending updates to be released, a pink flag labeled “Updates Available to Publish” will appear. Click on the app name at the top left to navigate to the Versions tab page.
Step 2: The Versions tab page will display (many, if multiple versions exist) versions of the application. Click on the ‘Make New Version’ button to release the latest application build.
Step 3: Depending on the app's size, it will take a few seconds to create a new version of the app. By default, the released version stays in “In Test” mode. To switch to Released mode, click the ‘Released’ button. (The released button will be locked if Release Mode Functionality is enabled).Release Mode Functionality
Step 4: The app will be publicly released with the new version. The label in teal color ‘latest’ will appear next to it, indicating it's the most current version of the app. You can now share it with the project team to manually update the app or it will be automatically updated using the Auto-Update Application functionality.

Releasing New Version of an App without Release Mode

Ways to Update an Application

CommCare offers various settings to manage application updates efficiently. CommCare can be configured to check for newly released versions on a regular schedule through the Auto Update Frequency option. While a Manual App Update in CommCare will allow users to manually check for and install updates to their application.
To know more about different ways of updating an application, go through this link: Ways to Update an Application

Updating CommCare Application on Android

Updating the CommCare application on Android involves installing newer versions of the app to benefit from bug fixes, new features, and security enhancements. To learn more about it, click here : Updating CommCare Application on Android

Technical 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, 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 application onto the phone without first removing the old version. This is possible using the OTA, Phone-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.

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.