How to download your data from the ODK server? • so.ii

Disclosure

The code in this vignette demonstrates the intended usage, but it is not executable because the functions require a live server (odk.gedeop.inrae.fr) and actual user credentials. Running this code automatically will result in errors. Code chunks in this vignette are therefore not evaluated (eval = FALSE in the setup chunk) to ensure that the vignette builds properly for documentation without executing the API calls.

Introduction

The so.ii package provides a streamlined workflow to connect to an Open Data Kit (ODK) server, explore available projects and forms, and download submitted data. Under the hood, it relies on the ruODK package but wraps the functionality into simpler functions. The output of our functions are compatible with ruODK functions

This vignette will guide you through the process of:

Setting up your paths and credentials.
Exploring the server to find your target project and form.
Connecting to a specific form.
Retrieving the submitted data and inspecting its structure.

Prerequisites and Setup

Before connecting to the server, you need a plain-text credential file. This file must contain exactly two lines:

Your ODK server username (e.g., email)
Your password

Let’s load the package and set up our workspace paths:

library(so.ii)

# Setup path for downloaded data. Ex:
output_folder <- tempdir()

# Setup path to the directory containing your credential file. Ex:
credential_path <- "./script/credential"

# Assuming there is only one credential file in the folder, we get its full path
my_cred_file <- file.path(credential_path, list.files(credential_path)[1])

Explore your ODK data server

If you don’t know your project or form IDs in advance, you can explore the server. By default, explore_server() will return all the projects you have access to.

# explore odk server
explore_server(
  credential = my_cred_file
)

Once you have identified your project’s ID (for example, pid = “123”), you can pass it to explore_server() to see all the forms available within that specific project.

# explore forms in an odk project
explore_server(
  credential = my_cred_file,
  pid = "123"
)

Connect to a Specific Form

When you already know the project ID (e.g., pid = “123”) and the form ID (e.g., fid = “soii_fieldwork_form”) you can directly establish a dedicated connection to your form. You will need a dedicated connection per form to download the data submitted with said form. We do this with the function connect_to_form():

# Establish dedicated connection to the form "soii_fieldwork_form" in the ODK server
# If any of the arguments are missing, the function will throw a clear error message.
connect_to_form(
  pid = "123",
  fid = "soii_fieldwork_form",
  credential = my_cred_file
)

Retrieve Data

With the connection established, retrieving the data is as simple as calling get_submitted_data(). This function communicates with the OData service to fetch your dataset.

# Get data from the ODK server
dataset = get_submitted_data(
  output_folder = output_folder
)

The function will automatically display a message indicating the number of submissions retrieved. By default, it retrieves all submissions from the connected form.

Retrieve Data and display form structure (Optional)

If you want to better understand the schema of your ODK form (e.g., the variable types and nested structures), you can set display_form_structure = TRUE in the get_submitted_data() function. This will retrieve the data and simultaneously open an interactive HTML viewer (via the listviewer package) showing the JSON structure of your form.

# Display the form structure
dataset = get_submitted_data(
  output_folder = output_folder
  display_form_structure = TRUE
)

This will show you the field names and data types in your ODK form, which can be helpful for data analysis.