cto_form_metadata: Download SurveyCTO Form Metadata and Definitions

In ctoclient: A Modern and Flexible Data Pipeline for 'SurveyCTO'

Download SurveyCTO Form Metadata and Definitions

Description

Functions for interacting with SurveyCTO form definitions.

• cto_form_metadata() retrieves raw metadata for a form, including available definition files, version identifiers, and download URLs.

• cto_form_definition() downloads a specific XLSForm definition (Excel file) to a local directory.

Usage

cto_form_metadata(form_id)

cto_form_definition(form_id, version = NULL, dir = getwd(), overwrite = FALSE)

Arguments

form_id	A string giving the unique SurveyCTO form ID.
version	Optional string specifying a particular form version to download. If NULL (default), the currently deployed version is used.
dir	Directory where the XLSForm should be saved. Defaults to getwd().
overwrite	Logical; if TRUE, an existing file in dir will be overwritten. If FALSE (default), the existing file is used.

Details

• Version Handling: When version is supplied, it is validated against the available versions from cto_form_metadata(). An informative error is raised if the requested version does not exist.

• Caching: If the file already exists in dir, it will not be re-downloaded unless overwrite = TRUE.

Value

• cto_form_metadata() returns a list containing the metadata, including keys for deployedGroupFiles and previousDefinitionFiles.

• cto_form_definition() returns a character string with the path to the downloaded Excel file.

See Also

Other Form Management Functions: cto_form_attachment(), cto_form_data(), cto_form_data_attachment(), cto_form_dofile(), cto_form_languages()

Examples

## Not run: 
# --- 1. Get raw metadata ---
meta <- cto_form_metadata("household_survey")

# --- 2. Download the current form definition ---
file_path <- cto_form_definition("household_survey")

# --- 3. Download a specific historical version ---
file_path_v <- cto_form_definition(
  "household_survey",
  version = "20231001"
)

# --- 4. Read XLSForm manually with readxl ---
library(readxl)
survey <- read_excel(file_path, sheet = "survey")
choices <- read_excel(file_path, sheet = "choices")
settings <- read_excel(file_path, sheet = "settings")

## End(Not run)

ctoclient documentation built on March 28, 2026, 5:07 p.m.