Configure 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.

Best practice: 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 = "https://sandbox.central.getodk.org/v1/projects/14/forms/build_Flora-Quadrat-0-4_1564384341.svc", 
  un = Sys.getenv("ODKC_UN"), 
  pw = Sys.getenv("ODKC_PW"),
  tz = "Australia/Perth",
  verbose = TRUE
)
#> <ruODK settings>
#>   Default ODK Central Project ID: 14 
#>   Default ODK Central Form ID: build_Flora-Quadrat-0-4_1564384341 
#>   Default ODK Central URL: https://sandbox.central.getodk.org 
#>   Default ODK Central Username: [email protected] 
#>   Default ODK Central Password: run ruODK::get_default_pw() to show 
#>   Default Time Zone: Australia/Perth 
#>   Default ODK Central Version: 0.8 
#>   Default HTTP GET retries: 3 
#>   Verbose messages: TRUE 
#>   Test ODK Central Project ID: 14 
#>   Test ODK Central Form ID: build_Flora-Quadrat-0-2_1558575936 
#>   Test ODK Central Form ID (ZIP tests): build_Spotlighting-0-6_1558333698 
#>   Test ODK Central Form ID (Attachment tests): build_Flora-Quadrat-0-1_1558330379 
#>   Test ODK Central Form ID (Parsing tests): build_Turtle-Track-or-Nest-1-0_1569907666 
#>   Test ODK Central Form ID (WKT tests): build_Locations_1589344221 
#>   Test ODK Central URL: https://sandbox.central.getodk.org 
#>   Test ODK Central Username: [email protected] 
#>   Test ODK Central Password: run ruODK::get_test_pw() to show 
#>   Test ODK Central Version: 0.8

# ruODK contributor
ruODK::ru_setup(
  svc = "https://sandbox.central.getodk.org/v1/projects/14/forms/build_Flora-Quadrat-0-4_1564384341.svc", 
  un = Sys.getenv("ODKC_UN"), 
  pw = Sys.getenv("ODKC_PW"),
  tz = "Australia/Perth",
  test_svc = "https://sandbox.central.getodk.org/v1/projects/14/forms/build_Flora-Quadrat-0-4_1564384341.svc", 
  test_fid_zip = "build_Spotlighting-0-6_1558333698",
  test_fid_att = "build_Flora-Quadrat-0-1_1558330379",
  test_un = Sys.getenv("ODKC_TEST_UN"), 
  test_pw = Sys.getenv("ODKC_TEST_PW")
)
#> <ruODK settings>
#>   Default ODK Central Project ID: 14 
#>   Default ODK Central Form ID: build_Flora-Quadrat-0-4_1564384341 
#>   Default ODK Central URL: https://sandbox.central.getodk.org 
#>   Default ODK Central Username: [email protected] 
#>   Default ODK Central Password: run ruODK::get_default_pw() to show 
#>   Default Time Zone: Australia/Perth 
#>   Default ODK Central Version: 0.8 
#>   Default HTTP GET retries: 3 
#>   Verbose messages: TRUE 
#>   Test ODK Central Project ID: 14 
#>   Test ODK Central Form ID: build_Flora-Quadrat-0-4_1564384341 
#>   Test ODK Central Form ID (ZIP tests): build_Spotlighting-0-6_1558333698 
#>   Test ODK Central Form ID (Attachment tests): build_Flora-Quadrat-0-1_1558330379 
#>   Test ODK Central Form ID (Parsing tests): build_Turtle-Track-or-Nest-1-0_1569907666 
#>   Test ODK Central Form ID (WKT tests): build_Locations_1589344221 
#>   Test ODK Central URL: https://sandbox.central.getodk.org 
#>   Test ODK Central Username: [email protected] 
#>   Test ODK Central Password: run ruODK::get_test_pw() to show 
#>   Test ODK Central Version: 0.8

# ruODK contributor using base URL, project ID, and form ID
# Same effect as above, but more typing
ruODK::ru_setup(
  pid = 1,
  fid = "build_Flora-Quadrat-0-4_1564384341",
  url = "https://odkcentral.dbca.wa.gov.au",
  un = Sys.getenv("ODKC_UN"), 
  pw = Sys.getenv("ODKC_PW"),
  tz = "Australia/Perth",
  test_url = "https://sandbox.central.getodk.org",
  test_un = Sys.getenv("ODKC_TEST_UN"), 
  test_pw = Sys.getenv("ODKC_TEST_PW"),
  test_pid = 14,
  test_fid = "build_Flora-Quadrat-0-4_1564384341",
  test_fid_zip = "build_Spotlighting-0-6_1558333698",
  test_fid_att = "build_Flora-Quadrat-0-1_1558330379"
)
#> <ruODK settings>
#>   Default ODK Central Project ID: 1 
#>   Default ODK Central Form ID: build_Flora-Quadrat-0-4_1564384341 
#>   Default ODK Central URL: https://odkcentral.dbca.wa.gov.au 
#>   Default ODK Central Username: [email protected] 
#>   Default ODK Central Password: run ruODK::get_default_pw() to show 
#>   Default Time Zone: Australia/Perth 
#>   Default ODK Central Version: 0.8 
#>   Default HTTP GET retries: 3 
#>   Verbose messages: TRUE 
#>   Test ODK Central Project ID: 14 
#>   Test ODK Central Form ID: build_Flora-Quadrat-0-4_1564384341 
#>   Test ODK Central Form ID (ZIP tests): build_Spotlighting-0-6_1558333698 
#>   Test ODK Central Form ID (Attachment tests): build_Flora-Quadrat-0-1_1558330379 
#>   Test ODK Central Form ID (Parsing tests): build_Turtle-Track-or-Nest-1-0_1569907666 
#>   Test ODK Central Form ID (WKT tests): build_Locations_1589344221 
#>   Test ODK Central URL: https://sandbox.central.getodk.org 
#>   Test ODK Central Username: [email protected] 
#>   Test ODK Central Password: run ruODK::get_test_pw() to show 
#>   Test ODK Central Version: 0.8

# Review settings
ruODK::ru_settings()
#> <ruODK settings>
#>   Default ODK Central Project ID: 1 
#>   Default ODK Central Form ID: build_Flora-Quadrat-0-4_1564384341 
#>   Default ODK Central URL: https://odkcentral.dbca.wa.gov.au 
#>   Default ODK Central Username: [email protected] 
#>   Default ODK Central Password: run ruODK::get_default_pw() to show 
#>   Default Time Zone: Australia/Perth 
#>   Default ODK Central Version: 0.8 
#>   Default HTTP GET retries: 3 
#>   Verbose messages: TRUE 
#>   Test ODK Central Project ID: 14 
#>   Test ODK Central Form ID: build_Flora-Quadrat-0-4_1564384341 
#>   Test ODK Central Form ID (ZIP tests): build_Spotlighting-0-6_1558333698 
#>   Test ODK Central Form ID (Attachment tests): build_Flora-Quadrat-0-1_1558330379 
#>   Test ODK Central Form ID (Parsing tests): build_Turtle-Track-or-Nest-1-0_1569907666 
#>   Test ODK Central Form ID (WKT tests): build_Locations_1589344221 
#>   Test ODK Central URL: https://sandbox.central.getodk.org 
#>   Test ODK Central Username: [email protected] 
#>   Test ODK Central Password: run ruODK::get_test_pw() to show 
#>   Test ODK Central Version: 0.8

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()

Permanent defaults: Environment variables

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.

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")
ODKC_PID=1
ODKC_FID="build_Flora-Quadrat-0-2_1558575936"
ODKC_URL="https://odkcentral.dbca.wa.gov.au"
ODKC_UN="[email protected]"
ODKC_PW="..."
ODKC_VERSION=0.8
ODKC_TEST_URL="https://sandbox.central.getodk.org"
ODKC_TEST_UN="[email protected]"
ODKC_TEST_PW="..."
ODKC_TEST_VERSION=0.8
ODKC_TEST_PID=14
ODKC_TEST_FID="build_Flora-Quadrat-0-2_1558575936"
ODKC_TEST_FID_ZIP="build_Spotlighting-0-6_1558333698"
ODKC_TEST_FID_ATT="build_Flora-Quadrat-0-1_1558330379"
RU_TIMEZONE="Australia/Perth"
RU_VERBOSE=TRUE
RU_RETRIES=3

As an alternative to setting environment variables through ~/.Renviron, you can set them through Sys.setenv():

Sys.setenv(ODKC_URL="https://odkcentral.dbca.wa.gov.au")
Sys.setenv(ODKC_UN="[email protected]")
Sys.setenv(ODKC_PW="...")
Sys.setenv(ODKC_TEST_URL="https://sandbox.central.getodk.org")
Sys.setenv(ODKC_TEST_UN="[email protected]")
Sys.setenv(ODKC_TEST_PW="...")
Sys.setenv(ODKC_TEST_PID=14)
Sys.setenv(ODKC_TEST_FID="build_Flora-Quadrat-0-2_1558575936")
Sys.setenv(ODKC_TEST_FID_ZIP="build_Spotlighting-0-6_1558333698")
Sys.setenv(ODKC_TEST_FID_ATT="build_Flora-Quadrat-0-1_1558330379")
Sys.setenv(RU_TIMEZONE="Australia/Perth")
Sys.setenv(RU_VERBOSE=TRUE)
Sys.setenv(RU_RETRIES=3)

The hard way: Per function call

We can supply those credentials to each ruODK function call.

Note, including sensitive credentials in plain text into code is bad practice. This option is shown only for completeness.

# Use ruODK without ru_setup
ruODK::project_list(
  url="https://my-odkc.com", 
  un = Sys.getenv("ODKC_UN"), 
  pw = Sys.getenv("ODKC_PW")
)

# 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, pid and fid from the test variables ruODK::get_test_{url, un, pw, 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.

Moving across forms

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()

Legacy support for deprecated ODK Central features

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 sandbox (on which ruODK’s package tests run).

The numeric format of major.minor (e.g. 0.7 or 0.8) future-proofs ruODK to be able to handle any other future breaking changes gracefully through the same variable.

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).