Aggregate

ODK Aggregate provides a ready-to-deploy server and data repository to:

  • provide blank forms to ODK Collect (or other OpenRosa clients),
  • accept finalized forms (submissions) from ODK Collect and manage collected data,
  • visualize the collected data using maps and simple graphs,
  • export data (e.g., as CSV files for spreadsheets, or as KML files for Google Earth), and
  • publish data to external systems (e.g., Google Spreadsheets or Google Fusion Tables).

ODK Aggregate can be deployed on Google's App Engine, enabling users to quickly get running without facing the complexities of setting up their own scalable web service. ODK Aggregate can also be deployed locally on a Tomcat server (or any servlet 2.5-compatible web container) backed with a MySQL or PostgreSQL database server.

Installation

  1. Please read all the instructions and notes before beginning.
  2. Make sure you have used ODK Collect and are familiar with how it works.
  3. Next, try the ODK Aggregate demo server to explore the core functionality.
  4. Decide whether to install a cloud instance or a local instance. We strongly recommend you try an App Engine cloud instance first. If you wish to host locally, we strongly recommend you try the ODK Aggregate VM first. See Aggregate Deployment Planning.

Installing on App Engine (Cloud)

  1. Make sure Java 7 or higher is installed on the computer you plan to use. If it is not, download and install it. If you are using MacOSX, it may require special care and attention. See MacOSX Java install and MacOSX Java FAQ.
  2. You'll need to setup an App Engine account. These accounts are free (under these terms). You will need to be able to receive a text message from Google to verify your account.
  3. Once you're logged into your App Engine account, click on the "Create Application" button, choose an application identifier (e.g., my-app-id) and application title, and click on "Save." The identifier determines your url and can never be changed.
  4. Download ODK Aggregate v1.N.N. Select the latest Featured release for your operating system. These downloads are wizard-based installers for the various operating systems. If you are running OSX, you must unzip the downloaded file before running the installer within it. If you are on MacOSX Mountain Lion or onward, you will need to fiddle with GateKeeper settings in order to run the installer. Please consider using a non-Featured release during forms development (to help us identify issues prior to a production release).
  5. The installer will guide you through configuring ODK Aggregate for App Engine and then launch a script to upload this configured ODK Aggregate to App Engine.
    When using a Google account with two step-authentication then the installation using the ODK Aggregate v1.x.0 installers with fail with the message "Unable to update app: Use an application-specific password instead of your regular account". To over come this you need to enter you Google account name (myaccount@gmail.com) and obtain and use an application specific password instead of your normal one. See application-specific password how-to.

Installing VM (Local or Cloud)

The ODK Aggregate VM is a fully-configured install of Aggregate that you can run on any computer. It requires very little setup, works well without Internet connectivity, and gives you complete control over your data collection campaign. Download the ODK Aggregate VM to begin.

Installing on Tomcat (Local or Cloud)

To run on ODK Aggregate on a Tomcat server backed with a MySQL or PostgreSQL database, see Aggregate Tomcat Install.

Installing on AWS (Cloud)

To run on ODK Aggregate on a Linux micro-instance on the Amazon Web Services EC2 infrastructure, see Aggregate AWS Install.

Using the Application

  1. Beginning with ODK Aggregate 1.3.2, upon the initial installation of the server, it is configured to allow unauthenticated (anonymousUser) submissions from ODK Collect and unauthenticated browser access to the submissions and forms management functionality of ODK Aggregate. When the URL to the ODK Aggregate server is first opened, you will be presented with the application page showing the Submissions and Form Management tabs.
  2. For installations prior to ODK Aggregate 1.3.2, upon the initial installation of the server, when the URL to the ODK Aggregate server is first opened, you will be presented with the Log onto Aggregate screen. Choose the Sign in with Google button and enter the Google account you specified within the installer. The first time you do this, Google will ask for your consent to share this e-mail address with ODK Aggregate; you must approve this request. You will be presented with the application page showing the Submissions, Form Management and Site Admin tabs.
  3. Use the Add New Form button on the Form Management tab to upload a new form definition to ODK Aggregate.
  4. View data submitted from ODK Collect on the Submissions tab.
  5. If the Site Admin tab is not visible, click the Log In link in the upper right corner of the screen to be presented with the Log onto Aggregate screen. Choose the Sign in with Google button and enter the Google account you specified within the installer. The first time you do this, Google will ask for your consent to share this e-mail address with ODK Aggregate; you must approve this request. Depending upon how you are accessing the site, you may first need to first click a Log out ... link and perhaps close and reopen your browser in order to get to this login screen.
  6. Use the Permissions sub-tab under the Site Admin tab to restrict who can download forms or submit data from ODK Collect. Do this by creating an ODK username and password and granting it Data Collector privileges. This username and password can then be entered into ODK Collect's settings page. When restricting access you must also remove the Data Collector privilege from the anonymousUser. Remember to click Save Changes to make these changes take effect. Conversely, granting the Data Collector privilege to the anonymousUser enables anyone to submit data to your ODK Aggregate server.
  7. Also use the Permissions sub-tab under the Site Admin tab to specify additional Google accounts and/or usernames and passwords with browser access to the server. For each user you add, select whether they have access to the submitted data (Data Viewer privileges), the ability to upload forms and export or publish data (Form Management), or the ability to manage site access and users (Site Admin) privileges. Remember to click Save Changes to make these changes take effect. Granting any of these privileges to the anonymousUser enables browser access to these functions without first logging in.
  8. Submitted data, once in ODK Aggregate, can be viewed, exported, mapped and deleted.
  9. Refer to the inline help in ODK Aggregate (near the login button) for more detailed instructions.

Useful Notes

  • The developer wiki has release notes and tips on Aggregate troubleshooting (and App Engine troubleshooting).
  • Google App Engine servers may be located anywhere in the world. Depending on the sensitivity of the data and specific storage rules/restrictions, the server infrastructure may not have all necessary security precautions (such as encryption). It is the organization's responsibility to research and comply with applicable laws and regulations before storing data on Google App Engine. The organization is also responsible for taking the appropriate security precautions and educating users that the information will be available to the organization and stored on Google servers as specified in the Google App Engine Terms of Service.
  • Looking for other servers? Try ODK Briefcase (for local offline storage), FormHub (for free data hosting on the cloud), DataHQ (like Aggregate but in Python), RapidSMS (for SMS integration) or OpenMRS (for medical records).