June 2016 - rev 204

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

Release Designations

The ODK 2.0 tools are in various stages of Alpha and Beta release.

  • Alpha software does not have all features, and is more likely to have significant reductions or additions of functionality. Alpha releases are provided to gather user feedback on the usability and capabilities of the application, as well as bug reports (to make the application more robust). Updates may result in loss of data or incompatible changes in form designs.
  • Beta software does not have all features, but is less likely to have significant reductions or alterations in functionality. Beta releases are provided to gather user feedback on the usability and capabilities of the application, as well as bug reports (to make the application more robust). Updates may result in loss of data or incompatible changes in form designs.
  • Alpha and Beta releases can be used at their current set of capabilities, but the ODK core team cannot provide support for deployments using them or guarantee a migration path into future releases. If you use these, you should plan to use them as-is, without expecting upgrades to newer versions of the tools. The ODK 2.0 tools have mechanisms to extract your data as CSV files from these tools, and to re-import data via CSV files. This provides a migration path to newer releases, but will generally require manual actions on your part.
  • Release Candidate software does not have support for deployments, but the ODK core team does guarantee a migration path (possibly with many tedious manual steps) into future releases.
  • Production software has been used in several deployments and there is some level of confidence that the software is stable. As with any software, there is no guarantee of being bug-free.

Non-technical users may find the usage descriptions difficult to follow and there may be a considerable number of manual steps needed to utilize the tools. As we progress from Alpha to Beta to Release Candidate and Production versions of the tools, they should become easier to use.

Overview

The next-generation ODK tools (the ODK 2.0 Tools Suite) are intended to address several limitations of the existing ODK Collect / ODK Aggregate / ODK Briefcase data collection workflow. These are:

  • Fully customizable layout of prompts on the Android device. The 2.0 tools use HTML, Javascript and CSS to specify the layout of nearly all the screens viewed by the data collectors. This enables individuals and organizations with basic web development skills to modify and customize the appearance of their surveys and workflow. At the same time, we retain the easy-to-use spreadsheet-based definition of the survey questions (however, this XLSXConverter mechanism is not cross-compatible with XLSForm).
  • More flexible, user-directed, navigation of a survey. The 2.0 tools do not impose a strict sequential advancement through a form like ODK Collect; form designers can allow users to traverse a form in any order, yet impose validation of collected data prior to traversing into subsequent steps in a workflow.
  • Improved treatment of repeat-groups. In the 2.0 tools, we have eliminated the concept of a repeat-group. In its place, we provide prompts that enable you to open and edit other surveys with links back to the originating survey (if desired). These prompts can describe a sub-form (nested) relationship among the surveys (e.g., household and household-member) or they can represent arbitrary relational linkages across your data (e.g., tea-houses and tea-types).
  • Bi-directional synchronization of data across devices. The ODK 2.0 tools support the collaborative sharing of survey data across devices, and the updating and submission of changes to previously-collected data (i.e., follow-up surveys) via a bi-directional synchronization protocol; this contrasts with the uni-directional device-to-server submission pathway of ODK Collect / ODK Aggregate / ODK Briefcase.
  • Data curation and visualization on the device. ODK Tables gives organizations the ability to investigate and visualize entire datasets directly on the Android devices through graphical and non-graphical displays and through filtered views.
  • Eliminate the need to fork the underlying Java codebase. The ODK 2.0 tools include an Application Packager that will eliminate the need for an organization to fork and maintain their own versions of the ODK Survey or ODK Tables applications in order to create their own branded and controlled app.

The 2.0 Tools Suite consists of:

  1. ODK Application Designer 2.0 rev 204 - a design environment for creating, customizing and previewing your forms and data curation and visualization applications.
  2. ODK Survey v2.0 rev 204 - a data collection application based upon HTML, CSS and Javascript.
  3. ODK Tables v2.0 rev 204 - a data curation and visualization application running on your device.
  4. ODK Scan v2.0 rev 204 - a mark-sense form scanning application running on your device.
  5. ODK Services v2.0 rev 204 - handles database access, file access, and data synchronization services between all the ODK 2.0 applications. It also allows you to synchronize data collected by the ODK 2.0 tools using the 2.0 protocol with an ODK Aggregate instance.
  6. ODK Aggregate Tables Extensions v2.0 rev 204 - enhancements to support bi-directional data synchronization across disconnected devices.
  7. ODK Suitcase v2.0 rev 204 - is a desktop tool for synchronizing data from an ODK 2.0 server so the data can be exported to CSV format.

Trying It Out

First, see the ODK Survey and ODK Tables pages. They cover setting up these tools (and ODK Services) and downloading and exploring demonstration forms and applications built upon these tools. These demonstration applications will give you a good sense of the flexibility and breadth of capabilities of the two tools.

Next, see the Getting Started Guide to understand the process for revising and developing your own forms. That guide will walk you through modifying the Geotagger demo app to add an additional field to it.

Finally, see here to explore the capabilities of ODK Scan.

User-contributed Documentation

If you wish to contribute documentation or tutorials for the new tools, a Google doc has been started to hold user-contributed documentation here.

If you feel a section in that document is stable enough and complete enough to move onto the opendatakit.org site, please contact us to coordinate the move.

Limitations and Expected Changes

These are the known issues with the rev 204 release:

  1. Database tables over 1MB in size can now be handled. However, the sync mechanism and other areas of the code assume the contents of a data table can be held entirely in memory. For very large data sets, this may impact the responsiveness of your device.
  2. Fixed in ODK Aggregate v1.4.10: See Release Notes for upgrade steps. If using ODK Aggregate v1.4.9, media files for table-specific configuration files under the config/assets/csv folder (e.g., geotagger) are not sync'd down from the server and are incorrectly identified as app-level files (rather than table-specific configuration files).
  3. Fixed in ODK Aggregate v1.4.10: See Release Notes for upgrade steps. If using ODK Aggregate v1.4.9, syncing rows that contain more than one media file attachment can cause database corruption (most likely) on App Engine systems. The failure rate is < 1% for these records. In our test data set of ~450 rows with 30-60 attachments on each row, we have seen ~6 rows with data corruption.
  4. Occasionally, if ODK Survey has not yet been started, and needs to run the initialization logic, it can forget what form it was attempting to open and instead display the "default form" with a message about specifying a form_path in the URL. The work-around is to back out of ODK Survey and re-launch it.
  5. If the anonymousUser has Synchronize Tables permissions, you cannot Reset App Server using an appropriately-privileged username or Google account; sync will report a puzzling Authorization Error (with ODK Aggregate v1.4.9, it reported an unhelpful Protocol Error). You must revoke the Synchronize Tables permission from the anonymousUser prior to the reset (and then restore that permission afterward).

Older Versions

Descriptions of older versions of the tools may be found here