Stable lifecycle

attachment_get(
  sid,
  fn,
  local_dir = "media",
  separate = FALSE,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  verbose = get_ru_verbose()
)

Arguments

sid

One or many ODK submission UUIDs, an MD5 hash.

fn

One or many ODK form attachment filenames, e.g. "1558330537199.jpg".

local_dir

The local folder to save the downloaded files to, default: "media".

separate

(logical) Whether to separate locally downloaded files into a subfolder named after the submission uuid within `local_dir`, default: FALSE. The defaults mirror the behaviour of submission_export, which keeps all attachment files together in a folder `media`. Enable this option if downloaded files collide on idential names. This can happen if two data collection devices by chance generate the same filename for two respective media files, e.g. `DCIM0001.jpg`.

pid

The numeric ID of the project, e.g.: 2. Default: get_default_pid. Set default pid through ru_setup(pid="..."). See vignette("Setup", package = "ruODK").

fid

The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: get_default_fid. Set default fid through ru_setup(fid="..."). See vignette("Setup", package = "ruODK").

url

The ODK Central base URL without trailing slash. Default: get_default_url. Set default url through ru_setup(url="..."). See vignette("Setup", package = "ruODK").

un

The ODK Central username (an email address). Default: get_default_un. Set default un through ru_setup(un="..."). See vignette("Setup", package = "ruODK").

pw

The ODK Central password. Default: get_default_pw. Set default pw through ru_setup(pw="..."). See vignette("Setup", package = "ruODK").

retries

The number of attempts to retrieve a web resource. This parameter is given to RETRY(times = retries). Default: 3.

verbose

Whether to display debug messages or not. Read `vignette("setup", package = "ruODK")` to learn how `ruODK`'s verbosity can be set globally or per function.

Value

The relative file path for the downloaded attachment(s)

Details

This function is the workhorse for handle_ru_attachments. This function is vectorised and can handle either one or many records. Parameters submission_uuid and attachment_filename accept single or exactly the same number of multiple values. The other parameters are automatically repeated.

The media attachments are downloaded into a folder given by `local_dir`:

workdir/media/filename1.jpg

workdir/media/filename2.jpg

workdir/media/filename3.jpg

See also

Examples

if (FALSE) { # Step 1: Setup ruODK with OData Service URL (has url, pid, fid) ruODK::ru_setup(svc = "...") a_local_dir <- here::here() # Step 2: Get unparsed submissions fresh_raw <- odata_submission_get(parse = FALSE) # Step 3: Get attachment field "my_photo" fresh_parsed <- fresh_raw %>% odata_submission_rectangle() %>% dplyr::mutate( my_photo = attachment_get(id, my_photo, local_dir = a_local_dir, verbose = TRUE ) # Repeat for all other attachment fields ) }