Skip to contents

Download Attachments from a SurveyCTO Form

Source: R/cto_form_attachment.R
cto_form_attachment.Rd

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.

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.

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.

See also

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

Examples

if (FALSE) { # \dontrun{
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)
} # }