cto_form_attachment: Download Attachments from a SurveyCTO Form

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

Download Attachments from a SurveyCTO Form

Description

Downloads files attached to a deployed SurveyCTO form, such as preloaded CSV files, media assets, or other server-side attachments.

Usage

cto_form_attachment(form_id, filename = NULL, dir = getwd(), overwrite = FALSE)

Arguments

form_id	A string specifying the SurveyCTO form ID.
filename	Optional character vector of specific filenames to download (e.g., "prices.csv"). If NULL (default), all available attachments associated with the form are downloaded.
dir	A string giving the directory where files will be saved. Defaults to getwd().
overwrite	Logical; if TRUE, existing files in dir will be overwritten. If FALSE (the default), existing files are skipped.

Details

This function first calls cto_form_metadata() to retrieve metadata for the deployed form, including the list of available attachments.

• File types: Any attached file type can be downloaded (for example, images, audio, or CSV files).

• Progress reporting: When options(scto.verbose = TRUE) (default), progress messages are printed using the CLI framework.

• Caching: Files are not re-downloaded if they already exist in dir unless overwrite = TRUE.

If all requested files are not available, the function aborts with an informative message suggesting how to inspect the form metadata.

Value

A character vector of file paths to all available attachments that exist locally after the function completes (invisibly).

Returns invisible(NULL) if the form has no attachments.

See Also

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

Examples

## Not run: 
files <- cto_form_attachment("household_survey")

# 2. Download specific files to a local directory
cto_form_attachment(
  form_id  = "household_survey",
  filename = c("item_list.csv", "logo.png"),
  dir      = "data/raw"
)

# 3. Force re-download of a file
p <- cto_form_attachment(
  form_id  = "household_survey",
  filename = "prices.csv",
  overwrite = TRUE
)

prices <- read.csv(p)

## End(Not run)

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