knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) options(rmarkdown.html_vignette.check_title = FALSE)
library(ruODK)
ruODK
functions work on a given ODK Central instance using a web user's
credentials (username and password). Some functions also require project and
form IDs.
ruODK
's functions accept these parameters either as explicit keyword
arguments, or fall back to defaults.
Note: Always consider code to be public. Never use plain text credentials in code.
ruODK
suggests as best practice to set the defaults (or parts thereof) using
ruODK::ru_setup()
or through permanently setting environment variables.
ru_setup
ruODK
provides helpers for settings, ru_setup()
to set and ru_settings()
to get settings.
While normal users of ruODK
will only need a default pid, fid, url, username,
and password, contributors to ruODK
can include optional test server settings
which are required to run the test suite and build the vignettes.
ruODK
infers the base URL, project and form ID from the OData Service URL
which is shown in ODK Central on the Form Submissions tab.
Unless specified as function parameter, ruODK
converts dates and times to the
default timezone, in this example set to "Australia/Perth".
Furthermore, some functions offer verbose messages, which can assist to debug
unexpected behaviour. Unless specified in the settings, or in the respective
function calls, ruODK
defaults to hide verbose messages.
# ruODK user using OData service URL, username (an email), and password # Never use plaintext username and password, use Sys.getenv() instead ruODK::ru_setup( svc = Sys.getenv("ODKC_SVC"), un = Sys.getenv("ODKC_UN"), pw = Sys.getenv("ODKC_PW"), tz = "Australia/Perth", verbose = TRUE ) # ruODK contributors: see contributing guidelines for .Renviron variables # Review settings ruODK::ru_settings()
Now we can call ruODK
functions without specifying url
, un
, and pw
, and
let ruODK
fall back to the defaults:
ruODK::project_list() ruODK::submission_list()
Read a great overview of R's startup process, and how environment variables are sourced at the beginning of a new session at whattheyforgot.org.
ruODK
's functions default to the getters
ruODK::get_default_{pid,fid,url,un,pw}()
. These getters in turn look up their
values from environment variables.
The getters and setters are documented in the "Settings" family of the ruODK function reference.
A convenient way to have often used environment variables available is to add
them to ~/.Renviron
using usethis::edit_r_environ(scope = "user")
. This
loads them freshly into a new session, eliminating the need to run ru_setup()
.
Note that the environment variables can be cleared or overwritten through
calling ru_setup()
or Sys.setenv()
with respective arguments.
ru_setup()
will not change any omitted arguments.
usethis::edit_r_environ(scope = "user")
```{eval=FALSE} ODKC_PID=1 ODKC_FID="form_id" ODKC_URL="https://my-instance.getodk.cloud" ODKC_UN="me@email.com" ODKC_PW="..." ODKC_PP="..." ODKC_VERSION="2023.5.1"
ODKC_TEST_SVC="https://ruodk.getodk.cloud/v1/projects/1/forms/Flora-Quadrat-04.svc" ODKC_TEST_URL="https://ruodk.getodk.cloud" ODKC_TEST_PID=1 ODKC_TEST_PID_ENC=2 ODKC_TEST_PP="ThePassphrase" ODKC_TEST_FID="Flora-Quadrat-04" ODKC_TEST_FID_ZIP="Spotlighting-06" ODKC_TEST_FID_ATT="Flora-Quadrat-04-att" ODKC_TEST_FID_GAP="Flora-Quadrat-04-gap" ODKC_TEST_FID_WKT="Locations" ODKC_TEST_FID_I8N0="I8n_no_lang" ODKC_TEST_FID_I8N1="I8n_label_lng" ODKC_TEST_FID_I8N2="I8n_label_choices" ODKC_TEST_FID_ENC="Locations" ODKC_TEST_VERSION="2023.5.1" RU_VERBOSE=TRUE RU_TIMEZONE="Australia/Perth" RU_RETRIES=3 ODKC_TEST_UN="..." ODKC_TEST_PW="..."
As an alternative to setting environment variables through `~/.Renviron`, you can set them through `Sys.setenv()` or through `ruODK::ru_setup()`: ```r Sys.setenv(ODKC_URL = "https://my-instance.getodk.cloud") Sys.setenv(ODKC_UN = "me@mail.com") Sys.setenv(ODKC_PW = "...") Sys.setenv(ODKC_PP = "...") # add settings as needed # Reload R session to take effect ruODK::ru_setup( svc = "ODK service URL contains ODKC URL, project and form IDs", un = "...", pw = "..." ) # Takes effect immediately
We can supply those credentials to each ruODK
function call.
Credentials can be sourced from environment variables (to prevent hard-coding
them) or from other secure sources.
# Use ruODK without ru_setup ruODK::project_list( url = Sys.getenv("ODKC_URL_1"), un = Sys.getenv("ODKC_UN_1"), pw = Sys.getenv("ODKC_PW_1") ) # Use another server ruODK::project_list( url = Sys.getenv("ODKC_URL_2"), un = Sys.getenv("ODKC_UN_2"), pw = Sys.getenv("ODKC_PW_2") ) # Tests use default test settings explicitly ruODK::project_list( url = ruODK::get_test_url(), un = ruODK::get_test_un(), pw = ruODK::get_test_pw() )
An example use case are the ruODK
tests, which explicitly set url
, un
,
pw
, pp
, pid
and fid
from the test variables
ruODK::get_test_{url, un, pw, pp, pid, fid}()
. Note that this uses functions
instead of plain text versions of sensitive credentials. Alternatively,
variables could also be used to set credentials per function call.
ruODK
's functions default to the default values for project ID (pid
), form
ID (fid
), base URL (url
), username (un
), and password (pw
).
A typical workflow is to run several functions of ruODK
against one form (and
the overarching project). By running ru_setup()
with the form's OData service
URL and a web user's username and password, subsequent functions can omit pid
,
fid
, url
, un
, and pw
.
# Server 1, Project 1, Form 1 ruODK::ru_setup( svc = "https://central1.org/v1/projects/1/forms/form1.svc", un = Sys.getenv("ODKC_UN"), pw = Sys.getenv("ODKC_PW") ) ruODK::project_detail() ruODK::form_detail() ruODK::submission_list() # Server 1, Project 1, Form 3 ruODK::ru_setup(svc = "https://central1.org/v1/projects/1/forms/form3.svc") ruODK::project_detail() ruODK::form_detail() ruODK::submission_list() # Server 1, Project 5, Form 4 ruODK::ru_setup(svc = "https://central1.org/v1/projects/5/forms/form4.svc") ruODK::project_detail() ruODK::form_detail() ruODK::submission_list() # Server 2, Project 11, Form 12 ruODK::ru_setup( svc = "https://central2.org/v1/projects/11/forms/form12.svc", un = Sys.getenv("ODKC_UN2"), pw = Sys.getenv("ODKC_PW2") ) ruODK::project_detail() ruODK::form_detail() ruODK::submission_list() # Server 2, Project 11, Form 13 ruODK::ru_setup(svc = "https://central2.org/v1/projects/11/forms/form13.svc") ruODK::project_detail() ruODK::form_detail() ruODK::submission_list()
Users of the latest ODK Central version can safely ignore this section. Users of older ODK Central versions will be exposed to breaking changes coming from upstream ODK Central.
Very occasionally, ODK Central will deprecate API endpoints. ruODK
aims to
keep up with the latest ODK Central API, and will adapt its behaviour to support
both new and old, deprecated behaviour.
As there is no corresponding API endpoint to determine the ODK Central version,
ruODK
has introduced the environment variables ODKC_VERSION
and
ODKC_TEST_VERSION
. If unset, ruODK
defaults to the latest ODK Central
version, which is the version deployed to the ODK Central test server.
ruODK
gracefully handles both the current semantic versioning version format
("year.minor.patch", e.g. "2023.5.1") and the older numeric format (e.g. 0.7,
1.2). If the ODKC_VERSION
needs repair, ruODK
will emit a helpful warning
advising the correct format for the given version.
A recent example is the change of the API endpoint for form_schema
, which
replaced the .schema.json
API in favour of the /fields
API. This required
ruODK
to toggle its behaviour between the relatively involved un-nesting of
the JSON schema (versions before 0.8) with parsing a clean, flat list of field
names, types, and XForms paths (version 0.8 onward).
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.