Aggregate Extensions - rev 206

The documentation on this page corresponds to rev 206 (August 2016) of the tools suite. See Older Versions for documentation on earlier releases of this suite.

Release Designation

The ODK 2.0 functionality within ODK Aggregate 1.4.12 (August 2016) is designated Alpha 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.

The ODK 2.0 rev 206 sync protocol is compatible with ODK Aggregate v1.4.12. The sync protocol has been augmented to cache the user's permissions on the device and, for super-users or administrators, to cache the full set of users and all of their permissions (so that the super-user and/or administrator can assign rows to particular individuals).

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


Server Setup

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

  1. Install ODK Aggregate v1.4.12 to a server.
  2. Log onto your ODK Aggregate v1.4.12 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 ODK Aggregate usernames or Gmail or Google Apps account users (do this by typing one or more users' usernames or e-mail addresses into the text area and clicking Add User).
  7. If you have created an ODK Aggregate username, be sure to Change Password on that account to set the initial password for the account.
  8. Grant these users the Synchronize Tables permissions.
  9. 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.
  10. Click 'Save Changes'. These changes will not take effect until you do!

NOTE: This release attempts to resolve the quirk in the 1.4.10 and 1.4.11 release whereby if you configure the anonymousUser to have Synchronized Tables permissions, then if you want to use an ODK Aggregate username to Reset App Server, you must temporarily remove that permission from the anonymousUser in order for the reset to proceed. If you experience problems with Reset App Server and are allowing anonymous access, please let us know; if this is happening, the workaround, above, will resolve the issue.

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, all the ODK 2.0 tools run under the default 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 Services from within ODK Survey, the ODK Survey tool informs ODK Services to run in the context of the application name under which the ODK Survey tool is running. When ODK Services 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 Services. The same applies when launching ODK Services from within ODK Tables.

ODK Aggregate is configured by default to use the 'default' 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.