cto_form_data_attachment: Download Attachments from SurveyCTO Form Data

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

Download Attachments from SurveyCTO Form Data

Description

Extracts attachment URLs (images, audio, video, signatures) from SurveyCTO form data and downloads the files to a local directory. This function handles encrypted forms if a private key is provided.

Usage

cto_form_data_attachment(
  form_id,
  fields = everything(),
  private_key = NULL,
  dir = file.path(getwd(), "media"),
  overwrite = FALSE
)

Arguments

form_id	A string specifying the SurveyCTO form ID to inspect.
fields	A tidy-select expression (e.g., everything(), starts_with("img_")) specifying which columns should be scanned for attachment URLs. Defaults to everything().
private_key	Optional. A character string specifying the path to a local RSA private key file. Required if the form is encrypted.
dir	A character string specifying the local directory where files should be saved. Defaults to "media". The directory must exist.
overwrite	Logical. If TRUE, existing files with the same name in dir will be overwritten. If FALSE (the default), existing files are skipped.

Details

This function performs the following steps:

1. Fetches the form data using cto_form_data.

2. Scans the selected fields for values matching the standard SurveyCTO API attachment URL pattern.

3. Downloads the identified files sequentially to the specified dir.

Value

Returns a vector of file paths (invisibly). The function is called for its side effect of downloading files to the local disk.

See Also

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

Examples

## Not run: 
# 1. Download all attachments from the form submissions
cto_form_data_attachment(
  form_id = "household_survey_v1",
  dir = "downloads/medias"
)

# 2. Download only specific image fields from an encrypted form
cto_form_data_attachment(
  form_id = "encrypted_health_survey",
  fields = starts_with("image_"),
  private_key = "keys/my_priv_key.pem",
  overwrite = TRUE
)

## End(Not run)

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