Google Earth Outreach
Change language:

Getting Started with Mobile Data Collection using ODK

More and more organizations are using mobile devices to collect data in the field. Open Data Kit (ODK) is a suite of tools that allows data collection using Android mobile devices and data submission to an online server, even without an Internet connection or mobile carrier service at the time of data collection. Streamline the data collection process with ODK Collect by replacing traditional paper forms with electronic forms that allow text, numeric data, GPS, photo, video, barcodes, and audio uploads to an online server. You can host your data online using Google's powerful hosting platform, AppEngine, manage your data using ODK Aggregate and visualize your data as a map using Google Fusion Tables and Google Earth.

Created by developers at the University of Washington's Computer Science and Engineering department and members of Change, Open Data Kit is an open-source project available to all. Please visit their ODK project page for more information, recent updates, more tutorials, and to contribute to the project.

This image shows data collected remotely using Open Data Kit and displayed in Fusion Tables.

Tutorial Contents:

Prerequisites

  • No programming skills needed!
  • You need a web-enabled mobile device running Android OS 1.5 or newer.
  • You will need a text editor such as Notepad++ (PC and Linux) or TextMate (Mac)
  • You will need a Google Account to create a Google AppEngine instance. (Get one here.)
  • You will need Java 6 installed and running on your computer for ODK Aggregate (download it here free).

 

Let's Get Started!

1. Search for the "ODK Collect" app from the Android App Marketplace. Install the latest version to your mobile device. For more information about ODK Collect and its requirements, visit the ODK Project Page.

2. Download the ODK Sample form to use during this tutorial.

 

Create ODK Forms using ODK Build

There are two ways you can create forms for ODK: using ODK Build and by creating XML forms. If you're creating a form from scratch, keep in mind that a user can only view one question at a time on their mobile device, so the structure of the form should be logical.

  1. Go to ODK Build at http://build.opendatakit.org
  2. Create a new account or log in with an existing account. Note that this account is different from your Google Account, and you can choose to use a different login and passworld. Your forms will be saved to this account for future reference.
  3. Add questions to your form by clicking on the type of question you'd like to add (eg. location, text, etc.) at the bottom of the page.



    Each question has several common properties as well as unique properties. For an explanation of the Common Properties, see below. You do not need to save each question as you go, but remember to save the form when you're satisfied with it.
  4. Enter a Text question, such as "What is your name?", in the Caption Text section.
    Fill in the properties of the text field question on the right-hand side. Optional: you can enter a minimum and/or maximum character length for the text field.
  5. Enter a Numeric field to allow users to record a number in their form, such as "What is your age?" in the Caption Text section.
    In the properties section, specify whether you'd like to record the number as an Integer (whole number) or Decimal (0.0)
  6. Allow the form users to specify a Date. The phone will automatically record the current date, and allow the user to enter the date or modify the date in your form.
  7. If the users of your form have a mobile device that is equipped with a GPS chipset, you can add a Location entry into your form. The question will prompt the user to record the GPS location. The user will be able to view an estimate of the phone's built-in GPS accuracy while the phone's GPS acquires satellite positions.
  8. Allow users of your form to attach media files to their form submissions. You can select from Image, Audio or Video as media format. The form will switch to the device's camera mode, voice memo mode or video camera mode, and the media will be stored with that form entry. For this example, enter "Take a photo" in the Caption Text section and select "Image" as the Kind of media you will use from the drop-down menu.
  9. Use the "Choose One" question type if you'd like the user to select one option from several options. You can specify which options you present by clicking "Add Option." Make sure you add an underlying value to your Options; this is required for each Option. Use lower case text and underscores ( _ ) instead of spaces.
  10. Use the "Choose Multiple" question type for multiple choice questions. As with Choose One, make sure to add an underlying value to each Option and use lower case and underscores for the underlying value fields.


    Common Properties in Form Questions

    Data name (required): This is the variable name that is stored in the xml of your form. You must use lower case and underscores ( _ ) instead of spaces.

    Caption Text (required): Enter your question as you'd like it presented to the user.

    Hint: Specify a question's hint or help text. Note: If you are localizing your form, you must enter English text here as well as localized text. If you do not want to enter English default text, you must create the forms as xml in a text editor. See the tip at the end of this tutorial for more information about localizing forms.

    Default value: this is the default information that will be presented to the user. For example, if you are gathering information on a group of children and you know the majority of the childrens' age is 12, you can enter "12" as a default value.

    Read-only: If you don't want the user to be able to enter information for this question, check this box.

    Required: Users will not be able to save a form as completed unless they have entered information for questions that are checked "required."



  11. Once you're satisfied with your form, save it to your ODK Build account. Go to File > Save Form As. Next time you log in to your account, you can select File > Open to open the form.
  12. To download the form to your computer, select File > Export as XML. You will see xml code. Click the "Download" button to save the file to your computer as an .xml file. This is the format that you will import onto your mobile device in the next step.


    Tip: One of the advantages of ODK is that you can create localized forms. The functionality to create localized forms in ODK Build doesn't exist yet, but you can look at these sample forms (and the Widgets form in particular) as guides to creating your own XML forms that are localized.

    Branching questions where the second follow-up question is dependent upon the answer to the first question, must also be written in XML. Note that displaying data from branching questions is more difficult in Fusion Tables and Google Earth.

    If you'd like to learn more about creating your own forms using xml, view the javarosa xforms training guide.

Change the Form's Unique Namespace (or Form ID)

  1. In order to upload your forms to ODK Aggregate, you need to give it a unique namespace or Form ID.
  2. Open a Text Editor like Notepad, Notepad++, WordPad, TextEdit (Mac) or TextMate (Mac).
  3. Go to File > Open and open the form.
  4. With the form open in your text editor, find the tag <data>. It is a child of the parent tags <model> and <instance>. You will find the <data> tag near the top of the form.
  5. Change the tag from <data> to <data id="myODKform">, where "myODKform" is the unique name you wish to give your form. Be sure to include the quotation marks around the name. Keep the name short and don't include any spaces or special characters in the namespace. Only use alphanumeric characters. If you attempt to upload a form with the same name as another form, your upload will fail.
  6. Save the updated form to a folder on your computer and close your text editor.



Create an AppEngine Instance

Google AppEngine allows easy hosting of your applications, and your applications' data, on an online server. Learn more about AppEngine and read the terms of service.

For this tutorial, you will set up your own server using AppEngine infrastrucure and ODK Aggregate. ODK Aggregate allows you to set up a ready-to-deploy server where you can upload your form submissions, export them as .csv files and send them on to other services like Fusion Tables.

  1. First, you'll need to set up a Google AppEngine account. If this is your first time using AppEngine, Google willl send you a text message to confirm your identity, so have a text-enabled phone ready. Note: A given mobile number can only be used once for creating an AppEngine instance. (Learn more about SMS verification.)
  2. Once you've confirmed your mobile number and logged in, click "Create an Application."

  3. If necessary, verify your account by SMS text message.
  4. Give your application an "Application Identifier." This will become part of the URL for your AppEngine instance, e.g. "myurl.appspot.com."
    (If you would like to restrict the permissions for who can access your data, read the Security section below. You can edit the Security settings in this step.)

    For this tutorial, we will use the default "Open to all Google Account Users." Once you've entered an indentifier, you will receive confirmation that your application has registered successfully.


  5. Download the latest version of ODK Aggregate from the ODK Downloads page.
  6. Unzip it (single-click the file in your Downloads folder on a Mac or Right-click and unzip it on a PC). The file will unzip as a folder called "ODKAggregateDeploy." Open the folder.
  7. If you are using Windows:
    a. Double-click "uploadAggregateToAppEngine.cmd." A terminal window will appear showing the progress for Windows users.
    b. You will be prompted to enter your Google AppEngine Application ID. This is your AppEngine instance name, or Application Identifier, that you created in Step 4 above. Enter it and hit Enter.
    c. Next, you will be prompted for your email and password. Enter your Google Account email and password here (not your ODK login and password).
    d. The script will install ODK Aggregate on your AppEngine instance, and the terminal will close automatically when it is complete.
  8. If you are using a Mac, the process is slightly different:
    a. Open the unzipped folder called "ODK AggregateDeploy."
    b. Open the folder named "war."
    c. Open the folder named "WEB-INF"
    1. Open the file called "appengine-web.xml" in a text editor.
    2. Replace the text between the <application> tags to the name of your AppEngine identifier. For example, we called our AppEngine instance "http://odk-tutorial.appspot.com," so we would replace Line 3 <application>opendatakit</application> with <application>odk-tutorial</application>. Make sure you save this file to overwrite the old one.



    3. Mac users should double-click "uploadAggregateToAppEngine" to run the application. A terminal window will appear showing the progress for Mac users.



      If the application doesn't run automatically, you can also run it manually.
      a. Open a Terminal window
      b. Type "cd Desktop" (without quotes) to get to your Desktop
      c. cd into the file where the ODKAggregateDeploy folder downloaded. For instance, if you downloaded it to your desktop, you would then type "cd ODKAggregateDeploy" to cd into the folder.
      d. To run the application, type sh uploadAggregatetoAppEngine.sh and the application should begin to run.
    4. Enter the login credentials you used to create your AppEngine account.
  9. Congratulations! When the script is finished running, ODK Aggregate is now installed on your AppEngine instance. When it's finished running, confirm that it's set up correctly by visiting your AppEngine url (e.g. myurl.appspot.com).

Restricting Permissions to AppEngine Instances for Increased Security

You can choose to restrict who can access your AppEngine instance. By default, anyone with a Google Account who knows the URL of your application can view your instance. If your data must be kept secure because it is of a confidential nature, be sure to click the "Edit" link next to "Open to all Google Account Users" when you are setting up your application (in Step 5 above). Doing so will reveal more options for hosting your data. You can choose to only allow users from a Google Apps domain (such as foo.com), or you can restrict to allow only users with an OpenID Provider if your application uses authentication. Learn more about authentication for AppEngine.

Uploading your Forms to your AppEngine Instance

Now that you've set up your AppEngine instance with ODK Aggregate, you can upload your forms -- the last step before you start collecting data out in the field with your forms! ODK Aggregate is covered in more depth in the tutorial called "Manage your Data with ODK Aggregate."

  1. Go to your AppEngine instance (or view the sample one we created at http://odk-tutorial.appspot.com, but use your own instance to upload your custom forms to).
  2. Login with your Google Account if prompted.
  3. Click on "Upload Forms."
  4. Choose the form that you wish to upload to your instance and hit "Upload."
  5. If your form has uploaded successfully, you will be taken back to the "List Forms" page.

Discussion & Feedback

Have questions about this tutorial? Want to give us some feedback? Visit the Google Earth Outreach Discussion Group to discuss it with others.

What's Next?

©2011 Google - About Google - Terms and Conditions - Privacy Policy