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.
- Please read all the instructions and notes before beginning.
- Make sure you have used ODK Collect and are familiar with how it works.
- Next, try the ODK Aggregate demo server to explore the core functionality.
- 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, see Aggregate Deployment Planning.
Local hosting implies that you are taking ownership of the off-site back-up and restoration of your data and are documenting the steps necessary to return your systems to operation in circumstances that might include a full hardware failure or destruction of your facility. You must also plan for the security of your data and systems. And finally, it requires that you configure your network routers (e.g., WiFi router). We would encourage you to seek assistance from your local computer-technical-support community before proceeding. The set-up of the ODK Aggregate web server and database are very easy in comparison.
Installing on App Engine (Cloud)¶
- 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.
- You will need a Gmail account to use AppEngine. The way the upload script authenticates to AppEngine is now considered a "less secure application" usage by Gmail. You only need to enable reduced security levels during the running of the upload script (at the very end of the installer). After you have uploaded ODK Aggregate to AppEngine, you can restore the secure settings to your Gmail account. You might want to create one specifically for AppEngine if you are not comfortable with weakening your Gmail security for this brief interval of time; or, perhaps, you have already allowed less secure apps access to your Gmail account, and are therefore already running with weakened security. To weaken your security (or verify your settings), go to Google MyAccount and, under the "Signing in" heading, click on "Access for less secure apps" and choose "Turn on".
- You'll need to setup an App Engine account. These accounts are free (under these terms). You may need to be able to receive a text message from Google to verify your account.
- If you are creating an App Engine account for the first time, you will be directed to the
Google Developers Console. Otherwise, you will on a screen displaying all your existing application ids, and have the option of creating a new application. These two cases are described below:
Developers Console (first time) On that console
- click on the 'Create an empty project' option.
- Enter your application's title for the Project Name (e.g., 'South Sudan Water Project'),
- then edit the project ID. The project ID will be your App Engine application Identifier; it determines the url and can never be changed; these are globally unique, so the common ones like 'test' will all have been taken.
- Once you have created the project ID, you can go back to App Engine Console and see a less cluttered view of your available applications.
App Engine Console (existing/legacy) On that console
- click on the "Create Application" button,
- choose an application identifier (e.g., my-app-id; the Google Developers Console project ID). The application identifier determines your url and can never be changed.
- enter your application's title (e.g., 'South Sudan Water Project'; Google Developers Console Project Name), and
- click on "Save."
- 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).
- 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. NOTE: Beginning with Java 7 Update 51, there are security level settings described here that may prevent the upload script from running. A reported work-around is to add the file: path (e.g., file:///) to the Exception Site list.
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 (firstname.lastname@example.org) and obtain and use an application-specific password instead of your normal one. See application-specific password how-to.
- Finally, after successfully uploading ODK Aggregate to AppEngine, update your Gmail account using the same link in step 2, above, to not allow "less secure applications".
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¶
- 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.
- Use the Add New Form button on the Form Management tab to upload a new form definition to ODK Aggregate.
- View data submitted from ODK Collect on the Submissions tab.
- 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. Beginning with ODK Aggregate 1.4.4, the super-user account (the account with full access to the server) is an ODK Aggregate-specific account and not a Google e-mail account. Choose the Sign in with Aggregate password button and enter the super-user username you specified within the installer. The initial password for this account is aggregate When signing in with this method, if you do not enter the password correctly, you may need to close all your browser windows and quit your browser before you can try again.
- If you have not yet changed your super-user password to something other than aggregate, the server will display This server and its data are not secure! Please change the super-user's password! at the top of the web page. Please visit the Permissions sub-tab under the Site Admin tab to change this user's password.
- If the instance name of the server changes (the installer asks for this name), then the passwords for all ODK Aggregate usernames will be cleared (preventing their use) and the super-user username's password will be reset to aggregate and the above message will also be displayed. In this case, you should log in, change the super-user's password, and change the passwords for all of your ODK Aggregate usernames.
- 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.
- Beginning in May 2014, the use of Google e-mail accounts for accessing the site (via Sign in with Google) is only supported on already-existing sites and in April 2015, that support will cease. Migration Timetable. It is unclear whether ODK Aggregate will support any of Google's replacement mechanisms. If you have an already-existing site, you may 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.
- Submitted data, once in ODK Aggregate, can be viewed, exported, mapped and deleted.
- Refer to the inline help in ODK Aggregate (near the login button) for more detailed instructions.
- The developer wiki has release notes and tips on Tomcat 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).