Upgrading Aggregate

Need for Upgrading

It is important to upgrade to newer ODK Aggregate versions as they come out. You don't need to do this immediately, but this should be something you do at least once a year.


ODK Briefcase's pull and push functionality provides a mechanism to transfer data between upgrade-incompatible versions of Aggregate or other ODK-compatible servers.

There are several reasons for this.

Security vulnerabilities

The ODK developers are constantly upgrading the libraries we use with newer, safer, versions. The older your software, the greater the number of vulnerabilities in it.

Hosting revisions

If you are using Google App Engine as we recommend, your hosting environment is being continuously updated.

Google App Engine is a managed environment, unlike AWS or other "bare-box" hosting services. Google is continuously updating features and removing support for older features in this environment.

The Aggregate development team is committed to supporting Google App Engine, so we update our application as the platform changes. If you do not upgrade gradually as new versions come out, your installation may stop working or cease to have a viable upgrade path.

Performance improvements

As we find performance issues and address them, the Aggregate gets faster and cheaper to run.

Enhanced capabilities

ODK JavaRosa, the underlying form rendering library is updated about annually. Those updates add new functions, features, and occasionally data types. New features are slowly added to ODK Aggregate, too.

To use these newer features, keep your Aggregate installation up to date.

Determining your Aggregate version

If you are able to log onto the server as a Site Administrator, the ODK Aggregate version is displayed at the top of the Preferences sub-tab under the Site Admin tab.

If you are unable to log onto your server, you will need to search for the version in the application logs. To do that:

  1. Open a browser to https://appengine.google.com.
  2. Choose the project id for your ODK Aggregate server by clicking on the project dropdown in the top left corner.
Image showing dropdown option. Image showing project selection window.
  1. Search logs in the search box and select logging.
Image showing searching log.
  1. In the filter text box paste this text : afterPropertiesSet and hit enter.
  2. Expand the list of logs and find the log which shows the version of Aggregate. It will of the following format:
13:24:54.806 org.opendatakit.common.security.Realm afterPropertiesSet: Version: v1.4.15 Production (Realm.java:51)
Image showing search result for version.

General steps for upgrading

  1. Disable all submissions to ODK Aggregate, in the Form Management tab.

  2. Use ODK Briefcase to pull a copy of all data to your computer.

  3. Log onto your server to confirm that it is still functioning.

  4. Determine your current version number.

  5. Download the next ODK Aggregate version and upgrade to that version. Find previous versions here.

    Do not simply upgrade from an old version of Aggregate to the latest version. It is important to upgrade sequentially through versions, instead of trying to upgrade directly to the latest version from an older one.

    Some versions will require manual changes upon upgrade. Complete notes about upgrading can be found in each version's release notes.

  6. Log onto your server to confirm that it is still functioning.

  7. Repeat the steps 4-7 until you have upgraded to the current version.

  8. Enable submissions to ODK Aggregate via the Form Management tab.


You need to know the exact instance name that was used in prior installs for your username and password to continue to work. If you add a space or change capitalization or spelling, the passwords will be invalid (you just need to re-run the installer with the correct string to correct the problem).

Downgrade steps

On April 12, 2016, Google disabled the login mechanism used by the older update scripts that were packaged with these installers.

To use these older installers:

  1. Download and run an ODK Aggregate 1.4.8 (or newer) installer. On the final screen, uncheck the Launch upload tool (3-10 minutes) checkbox and click Finish.
  2. Go into the directory where the installer placed the files, go into the ODK Aggregate directory, and rename the ODKAggregate directory inside it to NewRemoval.
  3. Download and run the pre-1.4.8 ODK Aggregate installer. On the final screen, uncheck the Launch upload tool (3-10 minutes) checkbox and click Finish.
  4. Go into the directory where the pre-1.4.8 installer placed its files, go into the ODK Aggregate directory, and copy the ODKAggregate directory from there to the installer directory created by the newer installer (effectively replacing the configuration produced by the newer installer with the configuration produced by the older one).
  5. In the directory created by the newer installer, if on:
    • Windows: double-click the ODKAggregateAppEngineUpdater.jar and use that to update your App Engine instance.
    • Mac OSX: double-click the uploadAggregateToAppEngine.app file in that directory.
    • Linux: open a bash shell, navigate to this directory, and run the uploadAggregateToAppEngine.sh file.


If you are reverting from a 1.4.8 or later release to a 1.4.7 or earlier release, you must manually delete the background module of your App Engine using the Google Cloud Platform administration web pages.