Survey - rev 208

The documentation on this page corresponds to rev 208 (October 2016) of the tools suite. See Previous Distribution or Older Versions for documentation on earlier releases of this suite.

Release Designation

ODK Survey rev 208 (October 2016) is designated Alpha 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.

Overview

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 may not be compatible with previous form definitions created for prior versions of ODK Survey depending on the revisions you are upgrading between. To be safe delete the files on your device and re-generate the formDef.json using the corresponding XLSXConverter, XLSXConverter rev 208 (October 2016), (the XLSX format has not changed).

This document covers the following topics.

  • Downloading and installing ODK Survey
  • Sample Forms
  • Starting ODK Survey
  • Deploying Form Definitions
  • Opening a Form
  • Syncing Forms and Data
  • 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 208 of the ODK Survey APK from here. Click on the ODK Survey rev 208 APK link on that page and download the actual ODK Survey rev 208 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

ODK Survey requires:

  • ODK Services

Download and install this from the same downloads page (see above). You must install the compatible version of this tool (e.g., rev 206)

Install the following app from Google's Play Store (this is required):

  • OI File Manager

Install the Sample Application

There is one sample application for this release.

  • 6 sample forms

Unlike ODK Collect, the ODK 2.0 tools are application-focused. An application is identified by the name of the directory under the /sdcard/opendatakit/ folder. The sample application is named default, as are the sample applications described on the Survey and Services pages. This means that you can only deploy one application at a time onto a device. Later, we will explain how to rename one of these so that two or more applications can co-exist and not interfere with each other on this same device (this will require setting up an ODK Aggregate for that renamed application; each ODK Aggregate can host only one application at a time and must be configured with the application name that it will host).

6 Sample Forms

A reference set of sample forms to start with are:

  • 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 (you should not open those sub-forms directly -- they are launched from within Household Survey).
  • 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 (you should not open it directly -- it is launched from within Household Survey). 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 (you should not open it directly -- it is launched from within Household Survey). 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.

To access the sample application and its 6 sample forms,

  1. Launch ODK Survey
  2. Click on the sync icon (2 curved arrows) to launch ODK Services directly into the sync activity
  3. From the menu, choose the Settings
  4. Choose Server Settings
  5. Choose Server URL and specify https://opendatakit-2.appspot.com as the server URL (note the https).
  6. Because this server allows anonymous access, the Server Sign-on Credential can be set to anything (by default, this will be set to None (anonymous access), which is fine). Other options are Username and Google Account.
  7. Exit out of the Server Settings page, and then the Settings page, by using the back button.
  8. By default, the sync interaction will synchronize all row-level data and file attachments with the server (Fully Sync Attachments). Other options are to only upload attachments from the device to the server (Upload Attachments Only), only download attachments from the server to the device (Download Attachments Only), or to not sync any attachments (Do Not Sync Attachments). For the demo, please ensure that Fully Sync Attachments is selected.
  9. Click on Sync Now

The sync process will now begin. If you have selected to use a Google Account, you may be challenged to authorize access to your Google account information. Otherwise, the sync will begin and a progress dialog will appear. As stated above, this synchronization mechanism forces the configuration of the device to exactly match that of the server. Any local configuration files for data tables or forms that are not present on the server will be removed from your device (i.e., everything under the /sdcard/opendatakit/default/config directory will be revised to exactly match the content on the server).

NOTE: As a safeguard to prevent data loss, data tables that are only defined on the device will not be deleted. However, because their associated configuration files will have been removed, they are generally inaccessible until you restore their configuration files and their forms onto the device.

Once the configuration of the device is an exact match to that of the server, the data within the data tables are synchronized. And, finally, the file attachments associated with those data are synchronized. If you have a slow connection, it may take two or three tries before the sync is successful; the system stops at the first timeout and does not attempt any retries.

When complete, click 'OK' on the Sync Outcome dialog and back out of the ODK Services application, returning to ODK Survey.

Opening a Form

If the sync was successful, you should now be presented with the list of those 6 sample forms.

Select the desired form. Note that the Household Members and Education forms are not intended to be called directly, but are launched from within the Household form.

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). You will be asked whether to ignore any changes since your last explicit save, whether to save your changes as an incomplete change, or whether to cancel the back (exit) action and return to the form.

Syncing Forms and Data

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 open a form for that table, select the row that was last saved as a checkpoint change, 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 'default' application name (as does ODK Tables and the other ODK 2.0 tools). Application names correspond to the name of the directory under /sdcard/opendatakit where the configuration and 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.

First, you must create an alternative application. To do so, open OI File Manager, navigate to the /sdcard/opendatakit directory, and copy the default directory, renaming it myapp. You have now created the myapp application! It is isolated from and operates independently of the default application.

To launch and use that application, 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 myapp application that you created via OI File Manager.

To launch and use that application, on Android 5.x devices:

  1. Long press an open area of the device homescreen
  2. Select the Widgets tab at the bottom of resulting 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 myapp application that you created via OI File Manager.

Now, play around with launching ODK Survey using this application shortcut and Finalizing a new filled-in form. Exit ODK Survey, and launch it from the applications list (so that it launches as the default application). Verify that you do not see that newly-filled-in form. You can also create a new filled-in form in this default application and confirm that it is not visible in the myapp application.

This highlights the isolation of applications in the ODK 2.0 tools. This is even more powerful with applications that use ODK Tables because you can create entirely isolated applications, such as a forestry app and a health clinic app, and have the forms and data entirely independent of each other.

If you attempt to sync the myapp app, it will still be configured to use the https://opendatakit-2.appspot.com site. However, this site is configured for the default app and will report an error should you try to sync to it (give it a try!).

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.