Aggregate Extensions - rev 126

The documentation on this page corresponds to rev 126 (February 2015) of the tools suite. See Older Versions for documentation on earlier releases of this suite.

This is an older version of our software.

The websites referenced in this documentation will generally have been updated to work with the newer software, and therefore may not function with this older release.

Where practical, we have provided zip files of the ApplicationDesigner environment used in creating those sites. See Survey and Tables Aux Files

Release Designation

The ODK 2.0 functionality within ODK Aggregate 1.4.5 (January 2015) is designated Beta software.

See Release Designations for the meaning of this designation.

To determine the ODK Aggregate release, log in with Site Admin privileges and go to the Site Admin / Preferences sub-tab.


The ODK Aggregate Tables Extensions enable the ODK 2.0 tools to share data via bi-directional synchronization with a central ODK Aggregate server.

This documents how to set up ODK Aggregate to accept sync and how to perform a sync and a data-table-download using ODK Sync v2.0 rev 126.


Server Setup

First you’ll have to install ODK Aggregate v1.4.5 to a server (see the Aggregate page for these instructions).

  1. install ODK Aggregate v1.4.5 to a server.
  2. Log onto your ODK Aggregate v1.4.5 instance.
  3. Go to the Site Admin / Preferences page.
  4. Check the checkbox for "ODK Tables Synchronization Functionality"
  5. Go to the Site Admin / Permissions page.
  6. Add Gmail or Google Apps account users (do this by typing the user's e-mail addresses and clicking Add User). Only anonymous users or Google Gmail or Apps Domain users can use the ODK Tables synchronization protocol.
  7. Grant these users the Synchronize Tables permissions.
  8. Select at least one user to be the administrator and grant them Administer Tables permissions. This user will have the ability to 'Reset App Server' from the Android device and add or remove tables and configuration files on the server. This is the equivalent of the Form Manager permissions in ODK 1.x deployments.
  9. Click 'Save Changes'. These changes will not take effect until you do!


Changing the AppName

The ODK 2.0 tools are designed to support multiple, independent, ODK 2.0 applications running on the Android device. Each of our tools has the ability to run in the context of either a default application name, or a specified application name.

By default, ODK Survey runs under the 'survey' application name and ODK Tables and ODK Sync run under the 'tables' application name. Application names correspond to the name of the directory under /sdcard/opendatakit where the data files for that application are stored.

When you run ODK Sync from within ODK Survey, the ODK Survey tool informs ODK Sync to run in the context of the 'survey' application name. When ODK Sync then interacts with ODK Aggregate, it reports that application name to the server. The server must be configured with exactly the same application name or it will reject the requests from ODK Sync.

In contrast, when you launch ODK Sync from within ODK Tables, or when you launch it directly, it runs in the context of the 'tables' application name.

ODK Aggregate is configured by default to use the 'tables' application name. To change the name, go to the Site Admin / Preferences screen and click the 'Change ODK 2.0 App Name' button, and enter a new application name. For example, the server is configured with 'survey' as its application name.

Using Device Synchronization

For more information on syncing, click here.