Survey - 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

ODK Survey rev 126 (February 2015) is designated Beta software.

See Release Designations for the meaning of this designation.

To determine the ODK Survey release, click on the About menu item. The release version will be displayed above the license information.


Note: ODK Survey only works on Android 4.1 and newer devices.

Important Note: ODK Survey cannot read or display the forms created for ODK Collect (e.g., those created via ODK Build, XLSForm or other form design tools). This functionality will never be provided.

Note: This release of ODK Survey is not compatible and cannot read or process the data or form definitions created for prior versions of ODK Survey. You must delete the files on your device and re-generate the formDef.json using the corresponding XLSXConverter, XLSXConverter rev 126 (February 2015), (the XLSX format has not changed).

This document covers the following topics.

  • Downloading and installing ODK Survey
  • Sample Forms
  • Starting ODK Survey
  • Downloading Form Definitions (ODK 1.x mechanism)
  • Opening a Form
  • Uploading Filled-in Submissions (ODK 1.x mechanism)
  • Syncing Forms and Data (ODK 2.0 synchronization)
  • Launching with a different AppName
  • Setting up a Form Development Environment.


Downloading and Installing ODK Survey

To install ODK Survey, you must enable downloading from unknown sources by checking the checkbox beside Unknown sources on the Security screen of your Android device's Settings application.

Then, open your Android device's browser and download rev 126 of the ODK Survey APK from here. Click on the ODK Survey rev 126 APK link on that page and download the actual ODK Survey rev 126 APK.

You should then be able to install that APK onto your device by choosing the Android Notification of the completion of the download. On some devices, you may need to open a file manager and double-tap on the downloaded file in the Downloads directory to trigger the install. On others, you may need to rename the file in the Downloads directory to end with .apk before double-tapping it to trigger the install.


Install Supporting Applications

This release of ODK Survey comes with 2 example configurations. The first uses the ODK 1.x submission mechanism and infrastructure; the second uses the new ODK 2.0 synchronization mechanism. To use the 2.0 synchronization mechanism, you must install:

  • ODK Sync

Download and install this from the same downloads page (see above).

It is useful to have a good file browser available on your device. If you do not already have a favorite application, download and install the following app from Google's Play Store:

  • OI File Manager


Sample Forms

The first example configuration includes this set of example forms:

  • Example Form -- a form with many examples of data entry widgets.
  • Grid Screen Form -- a form used to demonstrate a new screen layout that allows fully-customized prompt placement.
  • Household Survey -- a form used to gather information about a household. To operate correctly, this requires the Household Member Survey sub-form and the Education sub-form.
  • Select Examples -- a form with several examples of select widgets, including widgets that access data on Yahoo servers, and others that access CSV files for their choice lists. It also demonstrates the use of custom CSS styles to change the look of the form.
  • Household Member Survey -- a form used to gather information about household members. This is a sub-form of the Household Survey form. ODK Survey eliminates the repeat group concept and replaces it with sub-forms. From within the Household Survey you navigate into this sub-form by entering information about individuals in a household.
  • Education -- a form used to gather education information about household members. This is another sub-form of the Household Survey form. This sub-form saves information to the same underlying data table (household_members) as the Household Member Survey form, but it asks different questions. This demonstrates the use of multiple forms to revise different sets of values within a data table. From within the Household Survey you navigate into this form when you enter education information about individuals in a household.

The second example configuration contains just this one form:

  • Simple Weather Survey -- a form to record location, temperature and weather conditions.


Starting ODK Survey

Before starting ODK Survey, use your file manager (e.g., OI File Manager) to delete the /sdcard/opendatakit/survey directory, if it exists. This is the default directory that ODK Survey uses.

When you first launch ODK Survey, it unpacks a set of javascript and HTML files that it uses for interpreting form definitions and scans the /sdcard/opendatakit/survey directory for any new form definitions. When complete, it presents you with the list of available forms.

In this case, with a pristine installation, there will be no forms.


Downloading Form Definitions (ODK 1.x style)

The default ODK 2.0 demonstration server, is configured with the first set of example forms using the Legacy XML configuration mechanism described in ODK Legacy XML documentation.

Download these forms to your device via ODK Survey's Downloads screen (accessed via the down-arrow icon). As described in the ODK Legacy XML documentation, this mechanism supports the submission of your form data to the server as if it were from a legacy XML form (e.g., ODK Collect).

The server has one legacy XML form per data table. When you download that form, any ODK Survey forms associated with the underlying data table can be downloaded and installed on the device (this depends upon whether you have uploaded the forms to the server as a media zip -- see the ODK Legacy XML documentation for details).

In this example set of forms, when you download the household member form, it expands and presents the two ODK Survey forms, Household Member Survey and Education that both read and write into that data table.


Opening a Form

After downloading the forms, return to the form chooser screen by choosing the 'open folder' icon on the title bar of the ODK Survey application. After downloading, ODK Survey will perform a re-scan of your directory to discover any newly-downloaded forms before presenting this screen. Once on that screen, select the form to open.

The form will now open. The first time it opens, it will create the database tables and may take a few seconds to load. The application has been tested on Android 4.1 and higher devices; Android 4.0 and earlier devices are not supported.

Forms in ODK Survey are HTML. You can control the look-and-feel of the forms using CSS and add new prompt widgets by writing Javascript. To navigate forms using OpenDataKit's look-and-feel (i.e., the sample forms):

  • Tap on the name of the survey in the top left to access a pop-up menu of options.
  • Swipe or tap the 'back' or 'next' buttons in the top right of the form to navigate through the form.

Every change you make to the data in the form is written immediately to the database as a 'checkpoint' save. You may also manually save the form as 'incomplete' or 'finalize' the form, as you did with ODK Collect. To do so anywhere in the form, open the pop-up menu and take the desired action.

Otherwise, to exit the form without saving or cancelling your changes (and return to the form chooser screen), tap the device's back button (on newer devices, tap the back arrow icon at the bottom of the touch screen).

If you exit a form in this manner, the other ODK 2.0 tools will require you to choose whether to delete these unsaved changes or save them as incomplete before proceeding (this is only partially implemented in this release).


Uploading Filled-in Submissions (ODK 1.x style)

When using the forms you downloaded from, you can submit the data you collect up to the server using ODK Survey's Upload Submissions screen.

As with ODK Collect, you can only upload finalized submissions using this mechanism. To do so,

  1. tap the 'upload media (up arrow)' icon on the title bar of the ODK Survey application (you must finalize and exit the form first).
  2. tap on the table whose submissions you want to upload. If two or more forms write to a common underlying data table, it is the underlying data table that is published to the legacy ODK Collect submission mechanism, not the individual forms.
  3. select the submissions to upload
  4. tap on Send Selected to upload the submissions.

Also beginning with this release, if you revise already-submitted data, you are able to submit those updates to ODK Aggregate through this legacy XML submission mechanism. Each update will appear as a separate submission in the ODK 1.x data pipeline. During your data analysis, you can use the meta/rowId and meta/savepointTimestamp fields to identify the data record being updated and the time of that update, respectively. The meta/savepointTimestamp will generally identify the last change to the data record; however, if the clock on the device is not correctly set, it could falsely report the order of updates. In the future, we may move this legacy submission mechanism into the server to strictly preserve the update order.


Syncing Forms and Data (ODK 2.0 synchronization)

Before beginning, please ensure that the ODK Sync rev 126 APK is installed on the device.

To access the cloud-sync mechanism of the ODK 2.0 Sync protocol, click on the cloud icon on the ODK Survey action bar (between the download and upload icons).

NOTE: Using the ODK Sync mechanism will delete any data tables not present on the server. In our example, the server only contains the one form: Simple Weather Survey; if you try this after downloading the example tables via the legacy XML mechanism described above, all of those forms and data will be removed from your device.

To access the second example and its one form (Simple Weather Survey),

  1. Launch ODK Survey
  2. Click on the cloud icon to launch ODK Sync from within ODK Survey
  3. Specify as the server URL (note the https).
  4. Select any user account associated with the device (if you have not configured one, open your device's Settings app, scroll down to the Accounts heading, and add an account (this is different from the accounts you can set up under Users).
  5. Click on 'Save Settings'
  6. Click on 'Authorize Account'
  7. Authorize access to the account's e-mail address (this is an acceptance screen presented by the Android operating system).
  8. Click on 'Sync Now'

The sync process will now begin. As stated above, this synchronization mechanism forces the configuration of the device to exactly match that of the server. Any local data tables or forms that are not present on the server will be removed from your device.

Once the configuration of the device is an exact match to that of the server, the data within the data tables are synchronized.

If a data table has any checkpoint saves, the data table is not synchronized and a row conflict error is reported. In this case, the user needs to open that table and either delete the checkpoint or edit the survey and save it as either incomplete or finalized.

If two devices edit the same data record, the second device to sync with the server will get a synchronization failure and the user will be required to resolve their conflicting changes with those of the other device (that had already uploaded its changes to the server). Once the conflicts are resolved, the user can initiate another synchronization which will push these revisions up to the server.

The treatment of conflicts and the messaging to the user are works-in-progress and the UI for handling them is likely to change.


Launching with a different 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.

Once the ODK Application Packager is released, you will be able to build your own APK that transparently launches any of the ODK 2.0 tools into an application name of your choice.

You can accomplish this same functionality now through the use of Widget shortcuts. On Android 4.x devices:

  1. Choose to view the installed applications.
  2. Select the Widgets tab at the top of that screen.
  3. Navigate through the available widgets, and select and hold the ODK Survey Form widget. Drag and drop it onto one of your Android launcher (home) screens.
  4. A list of available applications and forms will appear, in the form of application name for applications, and application name > form name for each form within an application. Pick the one you want.

The shortcut will then launch ODK Survey into the chosen application name and form within that application.

You can experiment with this by Force Closing Survey (via your devices Settings / Apps screen), then copying and renaming the /sdcard/opendatakit/survey directory to, e.g., myapp. Then create a widget shortcut to myapp. Now launch ODK Survey via that shortcut, create a submission in one of the forms, and save. Now exit ODK Survey and start it via the installed-applications screen (this will start ODK Survey with the default survey application name). Notice that the submission you created within myapp is not visible within ODK Survey when started under its default name.

This should eliminate much of the need for different groups to fork the ODK codebase.


Setting up a Form Development Environment

You love the look, and want to jump into writing your own forms. The new Application Designer provides an integrated environment for form development. To get started go to the Application Designer documentation.