ODK Documentation ODK Sep 23, 2021 CONTENTS 1 Getting Started With ODK 3 2 ODK Collect 5 3 Setting Up ODK Collect 7 4 Using ODK Collect 27 5 Tips and Best Practices 99 6 ODK Central 153 7 Setting Up ODK Central 157 8 Using ODK Central 187 9 Intro to Forms in ODK 237 10 XLSForm 239 11 Question Types 243 12 Form Logic 361 13 Form Operators and Functions 393 14 Form Datasets 419 15 Form Styling 423 16 Form Language 441 17 Logging enumerator behavior 447 18 Launching External Apps 457 Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. i 19 Form Building Tools 463 20 Tips and Best Practices 477 21 ODK Briefcase 487 22 Setting Up ODK Briefcase 489 23 ODK Aggregate 491 24 Setting Up ODK Aggregate 493 25 Using ODK Aggregate 521 26 Tips and Best Practices 547 27 Google App Engine Support (Legacy) 557 28 Contributing to ODK Docs 563 29 OpenRosa 649 30 ODK JavaRosa 675 31 Launching ODK Collect from External Apps 677 32 Briefcase Aggregate API 681 33 Encrypted Forms 687 34 Security and Privacy 693 35 Glossary 699 ii Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. CONTENTS ODK is a suite of open source tools that help organizations collect and manage data. For a quick start, read Getting Started With ODK. In most cases, users of ODK: • Create survey forms using the XLSForm standard in Excel or Google Sheets. • Upload forms to an ODK Central server. • Download forms into ODK Collect on an Android device. • Use Collect to fill out forms with participants. • Upload survey data from Collect to Central. • Analyze or export data from Central. This requires: • Installing Collect on an Android device • Installing Central on a server While this is the recommended workflow, it is not the only way to do things. ODK is a very flexible set of tools, and organizations will find their own best practices for adopting it. Additional ODK tools are: • ODK Build, a drag-and-drop form designer. We generally recommend XLSForm for its flexibility but users only building very simple forms may prefer Build. • ODK Briefcase, a desktop tool that pulls and exports data from Aggregate and Collect. The specifications and libraries that power the tools are: • OpenRosa, APIs for how ODK clients communicate with ODK servers. • ODK XForms spec, a subset of the W3C XForms specification, for use in the ODK ecosystem. • ODK JavaRosa, a Java library that renders forms complying with ODK XForms. • XLSForm spec, a high-level Excel-based form specification. • pyxform, a Python library that converts XLSForms into ODK XForms. For a complete list of our tools, check out ODK on GitHub. Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. 1 CONTENTS 2 Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. CHAPTER ONE GETTING STARTED WITH ODK This document walks you through the recommended workflow to get started with ODK. You will: • Get a Central server • Get the Collect app • Create a form with XLSForm and upload it to Central • Load a form into Collect from Central • Fill out a form and upload it to Central 1.1 Get a Central server The easiest way to get a Central server is by using ODK Cloud. ODK Cloud provides fast Central servers with regular feature updates, automatic security patches, daily backups, uptime management, enterprise security, and guaranteed support on any issues. If you are technical and prefer to self-host, we recommend you install Central on DigitalO- cean. 1.2 Get the Collect app The easiest way to get the Collect app is to download it from the Google Play Store. You can also install manually from an APK. Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. 3 Chapter 1. Getting Started With ODK 1.3 Create a form with XLSForm and upload it to Central 1. Create a document in your favorite spreadsheet tool (Excel, Google Sheets, etc). 2. Design your form using XLSForm or try a sample XLSForm. 3. Upload the form to Central. 1.4 Load a form into Collect from Central 1. Create an App User in Central. 2. Open Collect on your Android device, tap Configure with QR code and scan the Client Configuration Code created for your App User. 1.5 Fill out a form and upload it to Central 1. Select Fill Blank Form to complete a survey. 2. Select Send Finalized Form to upload your completed survey to Central. Now log back into Central and see your completed survey results. 4 Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. CHAPTER TWO ODK COLLECT ODK Collect is an open source Android app that replaces paper forms used in survey-based data gathering. It supports a wide range of question and answer types, and is designed to work well without network connectivity. ODK Collect renders forms into a sequence of input prompts that apply form logic, entry constraints, and repeating sub-structures. Users work through the prompts and can save the submission at any point. Finalized submissions can be sent to (and new forms downloaded from) a server. Collect supports location, audio, images, video, barcodes, signatures, multiple-choice, free text, and numeric answers. It can even accept answers from other apps on your device. See a complete list of supported question types here. Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. 5 Chapter 2. ODK Collect 2.1 Learn more about ODK Collect • Setting Up ODK Collect • Using ODK Collect • Getting Started With ODK 6 Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. CHAPTER THREE SETTING UP ODK COLLECT 3.1 Installing Collect 3.1.1 Installing from Google Play Store (recommended) ODK Collect is available in the Google Play Store. 3.1.2 Installing manually The Google Play Store always has the latest stable release. If you need a different version of Collect, you can download from the web and install manually. 1. From your device’s Settings, choose Security. • Make sure Unknown Sources is checked. • (On older versions of Android, this setting is in Applications rather than Security) 2. Open a web browser on your phone. 3. Navigate to https://github.com/getodk/collect/releases/latest and download the ODK Collect APK. 4. In the download window, you will see ODK_Collect_vN.N.N.apk. - Select it to down- load the file. • On older devices, the APK will automatically install after you approve the security settings. • On newer devices, you must go to the download list, rename the file to restore the .apk extension (the extension will have been renamed to .man during the download process), then click on it to install it. Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. 7 Chapter 3. Setting Up ODK Collect Note: You can also download the ODK Collect APK to your computer and load it on your device via adb or another tool like AirDroid. Note: On older Android devices (4.0 and earlier), ODK Collect required an external SD Card. This is no longer an issue because Android devices have internal storage. Virtually all current Android devices will run ODK Collect. Tip: You can install ODK Collect on the Android emulator. This is especially helpful if you need to project Collect onto a screen. 3.1.3 Understanding permissions The ODK Collect application requires permissions to access device resources. If your device runs a version of Android below 6, you will be prompted to accept all of the permissions on app install. If your device runs Android 6 or above, permissions will be requested as they are needed. For example, the camera permission will only be requested the first time that you try to take a picture. Once the permission is granted, you won’t be prompted again. If you deny the permission, you will be asked again the next time you try to access the feature that requires the permission unless you check ”Don’t ask me again.” If you deny the permission, you will be shown a dialog explaining why the permission is needed. The only permission that is required for using Collect is the storage permission and it will be requested on first launch on Android 6+. Other permissions may or may not be needed depending on the forms and features used. The permissions that may be requested by Collect are: 8 Our documentation is updated frequently. Get the latest version at https://docs.getodk.org. 3.2. Connecting to a Server Permis- Reason sion Storage required for Collect to be able to access and save form data Camera required by image and video questions to capture new media Con- required to configure a Google account for Google Drive, Google Sheets sub- tacts missions Loca- required for location questions tion Micro- required by audio and video questions to capture new media phone Phone optional on form send to include deviceID in the submission and required for forms that capture device metadata Changing permissions from settings in Android 6+ If you are setting up Collect for someone who is not familiar with Android, you may want to make sure all required permissions are granted in advance. To do this, open the Settings application and tap on the Apps heading. You should now see a list of all your installed applications. Scroll down to find ODK Collect and tap on it to see details about Collect.