ru_setup: Configure default 'ruODK' settings.

In dbca-wa/ruODK: An R Client for the ODK Central API

Configure default ruODK settings.

Description

Settings are returned invisibly and additionally printed depending on get_ru_verbose.

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

svc	(optional, character) The OData service URL of a form. This parameter will set pid, fid, and url. It is sufficient to supply svc, un, and pw.
pid	(optional, character) The ID of an existing project on url. This will override the project ID from svc. A numeric value for pid will be converted to character.
fid	(optional, character) The alphanumeric ID of an existing form in pid. This will override the form ID from svc.
url	An ODK Central URL, e.g. "https://sandbox.central.getodk.org". This will override the ODK Central base URL from svc.
un	An ODK Central username which is the email of a "web user" in the specified ODK Central instance url (optional, character).
pw	The password for user un (optional, character).
pp	The passphrase (optional, character) for an encrypted form.
tz	Global default time zone. ruODK's time zone is determined in order of precedence: Function parameter: e.g. odata_submission_get(tz = "Australia/Perth") ruODK setting: ru_setup(tz = "Australia/Perth") Environment variable RU_TIMEZONE (e.g. set in .Renviron) UTC (GMT+00)
odkc_version	The ODK Central version as major/minor version, e.g. 1.1.
retries	The number of attempts to retrieve a web resource. This parameter is given to RETRY(times = retries). Default: 3.
verbose	Global default for ruODK verbosity. ruODK verbosity is determined in order of precedence: Function parameter: e.g. odata_submission_get(verbose = TRUE) ruODK setting: ru_setup(verbose = TRUE) Environment variable RU_VERBOSE (e.g. set in .Renviron) FALSE.
test_svc	(optional, character) The OData service URL of a test form. This parameter will set test_pid, test_fid, and test_url. It is sufficient to supply test_svc, test_un, and test_pw to configure testing.
test_pid	(optional, character) The numeric ID of an existing project on test_url. This will override the project ID from test_svc. A numeric value for test_pid will be converted to character.
test_fid	(optional, character) The alphanumeric ID of an existing form in test_pid. This will override the form ID from test_svc. This form is used as default form in all tests, examples, vignettes, data, and Rmd templates.
test_fid_zip	(optional, character) The alphanumeric ID of an existing form in test_pid. This will override the form ID from 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.
test_fid_att	(optional, character) The alphanumeric ID of an existing form in test_pid. This will override the form ID from 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.
test_fid_gap	(optional, character) The alphanumeric ID of an existing form in test_pid. This will override the form ID from test_svc. Provide the form ID of a form with gaps in the first submission. This form is used to test parsing incomplete submissions.
test_fid_wkt	(optional, character) The alphanumeric ID of an existing form in test_pid. This will override the form ID from test_svc. Provide the form ID of a form with geopoints, geotraces, and geoshapes.
test_url	(optional, character) A valid ODK Central URL for testing. This will override the ODK Central base URL from svc.
test_un	(optional, character) A valid ODK Central username (email) privileged to view the test project(s) at test_url.
test_pw	(optional, character) The valid ODK Central password for test_un.
test_pp	(optional, character) The valid passphrase to decrypt the data of encrypted project test_pid for download, only used for tests.
test_odkc_version	The ODK Central test server's version as major/minor version, e.g. 1.1.

Details

ru_setup sets ODK Central connection details. 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 ru_setup(un="XXX", pw="XXX"), and switch between forms with 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.

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.

See Also

Other ru_settings: odata_svc_parse(), parse_odkc_version(), ru_settings(), semver_gt(), semver_lt(), yell_if_error(), yell_if_missing()

Examples

# `ruODK` users only need default settings to their ODK Central:
ru_setup(url = "https://my-odkc.com", un = "[e-mail]", 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 = "[e-mail]",
  pw = "...",
  pp = "...",
  test_url = "https://sandbox.central.getodk.org",
  test_un = "[e-mail]",
  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
)

dbca-wa/ruODK documentation built on Nov. 8, 2024, 4:09 a.m.