/
attachment_list.R
143 lines (141 loc) · 5.15 KB
/
attachment_list.R
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
#' 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