-
Notifications
You must be signed in to change notification settings - Fork 12
/
attachment_get.Rd
159 lines (128 loc) · 4.77 KB
/
attachment_get.Rd
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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/attachment_get.R
\name{attachment_get}
\alias{attachment_get}
\title{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{
\item{sid}{One or many ODK submission UUIDs, an MD5 hash.}
\item{fn}{One or many ODK form attachment filenames,
e.g. "1558330537199.jpg".}
\item{local_dir}{The local folder to save the downloaded files to,
default: "media".}
\item{separate}{(logical) Whether to separate locally downloaded files into
a subfolder named after the submission uuid within \code{local_dir},
default: FALSE.
The defaults mirror the behaviour of \code{\link{submission_export}}, which
keeps all attachment files together in a folder \code{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. \code{DCIM0001.jpg}.}
\item{pid}{The numeric ID of the project, e.g.: 2.
Default: \code{\link{get_default_pid}}.
Set default \code{pid} through \code{ru_setup(pid="...")}.
See \code{vignette("Setup", package = "ruODK")}.}
\item{fid}{The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147".
Default: \code{\link{get_default_fid}}.
Set default \code{fid} through \code{ru_setup(fid="...")}.
See \code{vignette("Setup", package = "ruODK")}.}
\item{url}{The ODK Central base URL without trailing slash.
Default: \code{\link{get_default_url}}.
Set default \code{url} through \code{ru_setup(url="...")}.
See \code{vignette("Setup", package = "ruODK")}.}
\item{un}{The ODK Central username (an email address).
Default: \code{\link{get_default_un}}.
Set default \code{un} through \code{ru_setup(un="...")}.
See \code{vignette("Setup", package = "ruODK")}.}
\item{pw}{The ODK Central password.
Default: \code{\link{get_default_pw}}.
Set default \code{pw} through \code{ru_setup(pw="...")}.
See \code{vignette("Setup", package = "ruODK")}.}
\item{retries}{The number of attempts to retrieve a web resource.
This parameter is given to \code{\link[httr]{RETRY}(times = retries)}.
Default: 3.}
\item{verbose}{Whether to display debug messages or not.
Read \code{vignette("setup", package = "ruODK")} to learn how \code{ruODK}'s
verbosity can be set globally or per function.}
}
\value{
The relative file path for the downloaded attachment(s)
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}
}
\details{
This function is the workhorse for
\code{\link{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 \code{local_dir}:
workdir/media/filename1.jpg
workdir/media/filename2.jpg
workdir/media/filename3.jpg
}
\examples{
\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
)
}
}
\seealso{
\url{https://docs.getodk.org/central-api-form-management/#downloading-a-form-attachment}
\url{https://docs.getodk.org/central-api-submission-management/#downloading-an-attachment}
Other utilities:
\code{\link{attachment_link}()},
\code{\link{attachment_url}()},
\code{\link{drop_null_coords}()},
\code{\link{form_schema_parse}()},
\code{\link{get_one_attachment}()},
\code{\link{get_one_submission}()},
\code{\link{get_one_submission_att_list}()},
\code{\link{get_one_submission_audit}()},
\code{\link{handle_ru_attachments}()},
\code{\link{handle_ru_datetimes}()},
\code{\link{handle_ru_geopoints}()},
\code{\link{handle_ru_geoshapes}()},
\code{\link{handle_ru_geotraces}()},
\code{\link{isodt_to_local}()},
\code{\link{odata_submission_rectangle}()},
\code{\link{predict_ruodk_name}()},
\code{\link{prepend_uuid}()},
\code{\link{split_geopoint}()},
\code{\link{split_geoshape}()},
\code{\link{split_geotrace}()},
\code{\link{strip_uuid}()},
\code{\link{tidyeval}},
\code{\link{unnest_all}()}
}
\concept{utilities}