Download attachments and return the local path.

Usage

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

https://docs.getodk.org/central-api-form-management/#downloading-a-form-attachment

https://docs.getodk.org/central-api-submission-management/#downloading-an-attachment

Other utilities: attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_att_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

if (FALSE) { # \dontrun{
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...")

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
  )
} # }