-
Notifications
You must be signed in to change notification settings - Fork 12
/
ru_setup.Rd
194 lines (166 loc) · 7.02 KB
/
ru_setup.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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ru_setup.R
\name{ru_setup}
\alias{ru_setup}
\title{Configure default \code{\link{ruODK}} settings.}
\usage{
ru_setup(
svc = NULL,
pid = NULL,
fid = NULL,
url = NULL,
un = NULL,
pw = NULL,
pp = NULL,
tz = NULL,
odkc_version = NULL,
retries = NULL,
verbose = NULL,
test_svc = NULL,
test_pid = NULL,
test_fid = NULL,
test_fid_zip = NULL,
test_fid_att = NULL,
test_fid_gap = NULL,
test_fid_wkt = NULL,
test_url = NULL,
test_un = NULL,
test_pw = NULL,
test_pp = NULL,
test_odkc_version = NULL
)
}
\arguments{
\item{svc}{(optional, character) The OData service URL of a form.
This parameter will set \code{pid}, \code{fid}, and \code{url}.
It is sufficient to supply \code{svc}, \code{un}, and \code{pw}.}
\item{pid}{(optional, character) The ID of an existing project on \code{url}.
This will override the project ID from \code{svc}.
A numeric value for \code{pid} will be converted to character.}
\item{fid}{(optional, character) The alphanumeric ID of an existing form
in \code{pid}. This will override the form ID from \code{svc}.}
\item{url}{An ODK Central URL,
e.g. "https://sandbox.central.getodk.org".
This will override the ODK Central base URL from \code{svc}.}
\item{un}{An ODK Central username which is the email of a "web user" in the
specified ODK Central instance \code{url} (optional, character).}
\item{pw}{The password for user \code{un} (optional, character).}
\item{pp}{The passphrase (optional, character) for an encrypted form.}
\item{tz}{Global default time zone.
\code{ruODK}'s time zone is determined in order of precedence:
\itemize{
\item Function parameter:
e.g. \code{\link{odata_submission_get}(tz = "Australia/Perth")}
\item \code{ruODK} setting: \code{\link{ru_setup}(tz = "Australia/Perth")}
\item Environment variable \code{RU_TIMEZONE} (e.g. set in \code{.Renviron})
\item UTC (GMT+00)
}}
\item{odkc_version}{The ODK Central version as major/minor version, e.g. 1.1.}
\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}{Global default for \code{ruODK} verbosity.
\code{ruODK} verbosity is determined in order of precedence:
\itemize{
\item Function parameter:
e.g. \code{\link{odata_submission_get}(verbose = TRUE)}
\item \code{ruODK} setting: \code{\link{ru_setup}(verbose = TRUE)}
\item Environment variable \code{RU_VERBOSE} (e.g. set in \code{.Renviron})
\item \code{FALSE}.
}}
\item{test_svc}{(optional, character) The OData service URL of a test form.
This parameter will set \code{test_pid}, \code{test_fid}, and
\code{test_url}. It is sufficient to supply \code{test_svc},
\code{test_un}, and \code{test_pw} to configure testing.}
\item{test_pid}{(optional, character) The numeric ID of an existing project
on \code{test_url}. This will override the project ID from \code{test_svc}.
A numeric value for \code{test_pid} will be converted to character.}
\item{test_fid}{(optional, character) The alphanumeric ID of an existing form
in \code{test_pid}. This will override the form ID from \code{test_svc}.
This form is used as default form in all tests, examples, vignettes, data,
and Rmd templates.}
\item{test_fid_zip}{(optional, character) The alphanumeric ID of an existing
form in \code{test_pid}. This will override the form ID from
\code{test_svc}.
Provide the form ID of a form with few submissions and without attachments.
This form is used to test the repeated download of all form submissions.}
\item{test_fid_att}{(optional, character) The alphanumeric ID of an existing
form in \code{test_pid}. This will override the form ID from
\code{test_svc}.
Provide the form ID of a form with few submissions and few attachments.
This form is used to test downloading and linking attachments.}
\item{test_fid_gap}{(optional, character) The alphanumeric ID of an existing
form in \code{test_pid}. This will override the form ID from
\code{test_svc}.
Provide the form ID of a form with gaps in the first submission.
This form is used to test parsing incomplete submissions.}
\item{test_fid_wkt}{(optional, character) The alphanumeric ID of an existing
form in \code{test_pid}. This will override the form ID from
\code{test_svc}.
Provide the form ID of a form with geopoints, geotraces, and geoshapes.}
\item{test_url}{(optional, character) A valid ODK Central URL for testing.
This will override the ODK Central base URL from \code{svc}.}
\item{test_un}{(optional, character) A valid ODK Central username (email)
privileged to view the test project(s) at \code{test_url}.}
\item{test_pw}{(optional, character) The valid ODK Central password for
\code{test_un}.}
\item{test_pp}{(optional, character) The valid passphrase to decrypt the
data of encrypted project \code{test_pid} for download,
only used for tests.}
\item{test_odkc_version}{The ODK Central test server's version as major/minor
version, e.g. 1.1.}
}
\description{
Settings are returned invisibly and additionally printed depending on
\code{\link{get_ru_verbose}}.
}
\details{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}
\code{\link{ru_setup}} sets ODK Central connection details.
\code{\link{ruODK}}'s functions default to use the default project ID,
form ID, URL, username, and password unless specified explicitly.
Any parameters not specified will remain unchanged. It is therefore possible
to set up username and password initially with
\code{ru_setup(un="XXX", pw="XXX")}, and switch between forms with
\code{ru_setup(svc="XXX")}, supplying the form's OData service URL.
ODK Central conveniently provides the OData service URL in the form
submission tab, which in turn contains base URL, project ID, and form ID.
\code{\link{ruODK}}'s automated tests require a valid ODK Central URL, and a
privileged username and password of a "web user" on that ODK Central
instance, as well as an existing project and form.
}
\examples{
# `ruODK` users only need default settings to their ODK Central:
ru_setup(url = "https://my-odkc.com", un = "me@email.com", pw = "...")
# `ruODK` contributors and maintainers need specific ODK Central
# instances to run tests and build vignettes, see contributing guide:
ru_setup(
url = "https://odkcentral.dbca.wa.gov.au",
un = "me@email.com",
pw = "...",
pp = "...",
test_url = "https://sandbox.central.getodk.org",
test_un = "me@email.com",
test_pw = "...",
test_pp = "...",
test_pid = 14,
test_fid = "build_Flora-Quadrat-0-2_1558575936",
test_fid_zip = "build_Spotlighting-0-6_1558333698",
test_fid_att = "build_Flora-Quadrat-0-1_1558330379",
test_fid_gap = "build_Turtle-Track-or-Nest-1-0_1569907666",
test_fid_wkt = "build_Locations_1589344221",
retries = 3,
verbose = TRUE
)
}
\seealso{
Other ru_settings:
\code{\link{odata_svc_parse}()},
\code{\link{parse_odkc_version}()},
\code{\link{ru_settings}()},
\code{\link{semver_gt}()},
\code{\link{semver_lt}()},
\code{\link{yell_if_error}()},
\code{\link{yell_if_missing}()}
}
\concept{ru_settings}