#' List all attachments of one submission.
#'
#' `r lifecycle::badge("stable")`
#'
#' When a Submission is created, either over the OpenRosa or the REST interface,
#' its XML data is analysed to determine which file attachments it references:
#' these may be photos or video taken as part of the survey, or an audit/timing
#' log, among other things. Each reference is an expected attachment, and these
#' expectations are recorded permanently alongside the Submission. With this
#' subresource, you can list the expected attachments, see whether the server
#' actually has a copy or not, and download, upload, re-upload, or clear binary
#' data for any particular attachment.
#'
#' You can retrieve the list of expected Submission attachments at this route,
#' along with a boolean flag indicating whether the server actually has a copy
#' of the expected file or not. If the server has a file, you can then append
#' its filename to the request URL to download only that file.
#' @template param-iid
#' @template param-pid
#' @template param-fid
#' @template param-url
#' @template param-auth
#' @template param-retries
#' @return A tibble containing some high-level details of the submission
#' attachments.
#' One row per submission attachment, columns are submission attributes:
#'
#' * name: The attachment filename, e.g. 12345.jpg
#' * exists: Whether the attachment for that submission exists on the
#' server.
# nolint start
#' @seealso \url{https://docs.getodk.org/central-api-submission-management/#listing-expected-submission-attachments}
#' @seealso \url{https://docs.getodk.org/central-api-form-management/#listing-form-attachments}
# nolint end
#' @family utilities
#' @export
#' @examples
#' \dontrun{
#' # See vignette("setup") for setup and authentication options
#' # ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...")
#'
#' sl <- submission_list()
#'
#' al <- get_one_submission_attachment_list(sl$instance_id[[1]])
#' al %>% knitr::kable(.)
#'
#' # attachment_list returns a tibble
#' class(al)
#' # > c("tbl_df", "tbl", "data.frame")
#'
#' # Submission attributes are the tibble's columns
#' names(al)
#' # > "name" "exists"
#' }
get_one_submission_attachment_list <- function(iid,
pid = get_default_pid(),
fid = get_default_fid(),
url = get_default_url(),
un = get_default_un(),
pw = get_default_pw(),
retries = get_retries()) {
yell_if_missing(url, un, pw)
httr::RETRY(
"GET",
httr::modify_url(
url,
path = glue::glue(
"v1/projects/{pid}/forms/{URLencode(fid, reserved = TRUE)}",
"/submissions/{iid}/attachments"
)
),
httr::add_headers("Accept" = "application/json"),
httr::authenticate(un, pw),
times = retries
) %>%
yell_if_error(., url, un, pw) %>%
httr::content(.) %>%
{ # nolint
tibble::tibble(
name = purrr::map_chr(., "name"),
exists = purrr::map_lgl(., "exists")
)
}
}
#' List all attachments for a list of submission instances.
#'
#' @param iid A list of submission instance IDs, e.g. from
#' \code{\link{submission_list}$instance_id}.
#' @template param-pid
#' @template param-fid
#' @template param-url
#' @template param-auth
#' @template param-retries
#' @return A tibble containing some high-level details of the submission
#' attachments.
#' One row per submission attachment, columns are submission attributes:
#'
#' * name: The attachment filename, e.g. 12345.jpg
#' * exists: Whether the attachment for that submission exists on the
#' server.
# nolint start
#' @seealso \url{https://docs.getodk.org/central-api-submission-management/#listing-expected-submission-attachments}
#' @seealso \url{https://docs.getodk.org/central-api-form-management/#listing-form-attachments}
# nolint end
#' @family submission-management
#' @export
#' @examples
#' \dontrun{
#' # Step 1: Setup ruODK with OData Service URL (has url, pid, fid)
#' ruODK::ru_setup(svc = "...")
#'
#' # Step 2: List all submissions of form
#' sl <- submission_list()
#'
#' # Step 3a: Get attachment list for first submission
#' al <- get_one_submission_attachment_list(sl$instance_id[[1]])
#'
#' # Ste 3b: Get all attachments for all submissions
#' all <- attachment_list(sl$instance_id)
#' }
attachment_list <- function(iid,
pid = get_default_pid(),
fid = get_default_fid(),
url = get_default_url(),
un = get_default_un(),
pw = get_default_pw(),
retries = get_retries()) {
yell_if_missing(url, un, pw, pid = pid, fid = fid, iid = iid)
tibble::tibble(
iid = iid,
pid = pid,
fid = fid,
url = url,
un = un,
pw = pw,
retries = retries
) %>%
purrr::pmap(ruODK::get_one_submission_attachment_list) %>%
dplyr::bind_rows()
}
# usethis::use_test("attachment_list") # nolint
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.