Package 'ruODK'

Description

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

Details

This function is the workhorse for 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 local_dir:

workdir/media/filename1.jpg

workdir/media/filename2.jpg

workdir/media/filename3.jpg

Value

The relative file path for the downloaded attachment(s)

See Also

https://docs.getodk.org/central-api-form-management/#downloading-a-form-attachment

https://docs.getodk.org/central-api-submission-management/#downloading-an-attachment

Other utilities: attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", 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
  )

## End(Not run)

Description

Usage

attachment_link(data_tbl, form_schema, att_path = "media")

Arguments

Value

The dataframe with attachment columns modified to contain relative paths to the downloaded attachment files.

See Also

Other utilities: attachment_get(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
t <- tempdir()
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

# Predict filenames (with knowledge of form)
fid <- get_default_fid()
fid_csv <- fs::path(t, glue::glue("{fid}.csv"))
fid_csv_tae <- fs::path(t, glue::glue("{fid}-taxon_encounter.csv"))
fs <- form_schema()

# Download the zip file
se <- ruODK::submission_export(
  local_dir = t,
  overwrite = FALSE,
  verbose = TRUE
)

# Unpack the zip file
f <- unzip(se, exdir = t)
fs::dir_ls(t)

# Prepend attachments with media/ to turn into relative file paths
data_quadrat <- fid_csv %>%
  readr::read_csv(na = c("", "NA", "na")) %>%
  janitor::clean_names() %>%
  handle_ru_datetimes(fs) %>%
  attachment_link(fs)

## End(Not run)

Description

List all attachments for a list of submission instances.

Usage

attachment_list(
  iid,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Value

A tibble containing some high-level details of the submission attachments. One row per submission attachment, columns are submission attributes:

    * name: The attachment filename, e.g. 12345.jpg
    * exists: Whether the attachment for that submission exists on the
      server.

See Also

https://docs.getodk.org/central-api-submission-management/#listing-expected-submission-attachments

https://docs.getodk.org/central-api-form-management/#listing-form-attachments

Other submission-management: encryption_key_list(), submission_audit_get(), submission_detail(), submission_export(), submission_get(), submission_list()

Examples

## Not run: 
# Step 1: Setup ruODK with OData Service URL (has url, pid, fid)
ruODK::ru_setup(svc = "...")

# Step 2: List all submissions of form
sl <- submission_list()

# Step 3a: Get attachment list for first submission
al <- get_one_submission_attachment_list(sl$instance_id[[1]])

# Ste 3b: Get all attachments for all submissions
all <- attachment_list(sl$instance_id)

## End(Not run)

Description

Usage

audit_get(
  action = NULL,
  start = NULL,
  end = NULL,
  limit = NULL,
  offset = NULL,
  url = Sys.getenv("ODKC_URL"),
  un = Sys.getenv("ODKC_UN"),
  pw = Sys.getenv("ODKC_PW"),
  retries = get_retries()
)

Arguments

Details

Parameters to filter the audit logs: ⁠action=form.create&start=2000-01-01z&end=2000-12-31T23%3A59.999z⁠

Value

A tibble containing server audit logs. One row per audited action, columns are submission attributes:

• actor_id: integer. The ID of the actor, if any, that initiated the action.

• action: string. The action that was taken.

• actee_id: uuid, string. The ID of the permissioning object against which the action was taken.

• details: list. Additional details about the action that vary according to the type of action.

• logged_at: dttm. Time of action on server.

See Also

https://docs.getodk.org/central-api-system-endpoints/#getting-audit-log-entries

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

logs <- audit_get()

# With search parameters
logs <- audit_get(
  action = "project.update",
  start = "2019-08-01Z",
  end = "2019-08-31Z",
  limit = 100,
  offset = 0
)

# With partial search parameters
logs <- audit_get(
  limit = 100,
  offset = 0
)

logs %>% knitr::kable(.)

# audit_get returns a tibble
class(logs)
# > c("tbl_df", "tbl", "data.frame")

# Audit details
names(logs)
# > "actor_id" "action" "actee_id" "details" "logged_at"

## End(Not run)

Description

This helper patches a bug/feature in ODK Central (versions 0.7-0.9), where geotrace / geoshape GeoJSON contains a last coordinate pair with NULL lat/lon (no alt/acc), and WKT ends in ⁠, undefined NaN⁠.

Usage

drop_null_coords(x)

Arguments

Details

While split_geotrace and split_geoshape modify the WKT inline, it is more maintainable to separate the GeoJSON cleaner into this function.

This helper drops the last element of a GeoJSON coordinate list if it is list(NULL, NULL).

Value

The nested list minus the last element (if NULL).

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

# A snapshot of geo data with trailing empty coordinates.
data("geo_gj88")

len_coords <- length(geo_gj88$path_location_path_gps[[1]]$coordinates)

length(geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]]) %>%
  testthat::expect_equal(2)

geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]][[1]] %>%
  testthat::expect_null()

geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]][[2]] %>%
  testthat::expect_null()

# The last coordinate pair is a list(NULL, NULL).
# Invalid coordinates like these are a choking hazard for geospatial
# packages. We should remove them before we can convert ODK data into native
# spatial formats, such as sf.
str(geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]])

geo_gj_repaired <- geo_gj88 %>%
  dplyr::mutate(
    path_location_path_gps = path_location_path_gps %>%
      purrr::map(drop_null_coords)
  )

len_coords_repaired <- length(
  geo_gj_repaired$path_location_path_gps[[1]]$coordinates
)
testthat::expect_equal(len_coords_repaired + 1, len_coords)

Description

Usage

encryption_key_list(
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"),
  tz = get_default_tz()
)

Arguments

Details

This endpoint provides a listing of all known encryption keys needed to decrypt all Submissions for a given Form. It will return at least the base64RsaPublicKey property (as column public) of all known versions of the form that have submissions against them. If managed keys are being used and a hint was provided, that will be returned as well.

Value

A tibble of encryption keys.

See Also

https://docs.getodk.org/central-api-encryption/

https://docs.getodk.org/central-api-submission-management/#listing-encryption-keys

Other submission-management: attachment_list(), submission_audit_get(), submission_detail(), submission_export(), submission_get(), submission_list()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

x <- encryption_key_list(
  pid = Sys.getenv("ODKC_TEST_PID_ENC"),
  fid = Sys.getenv("ODKC_TEST_FID_ENC"),
  url = get_test_url(),
  un = get_test_un(),
  pw = get_test_pw()
)

names(x)
# > [1] "id" "public" "managed" "hint" "created_at"

## End(Not run)

Description

Usage

entitylist_detail(
  pid = get_default_pid(),
  did = NULL,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"),
  tz = get_default_tz()
)

Arguments

Details

An Entity List is a named collection of Entities that have the same properties. Entity List can be linked to Forms as Attachments. This will make it available to clients as an automatically-updating CSV.

This function is supported from ODK Central v2022.3 and will warn if the given odkc_version is lower.

Value

A list of lists following the exact format and naming of the API response. Since this nested list is so deeply nested and irregularly shaped it is not trivial to rectangle the result into a tibble.

See Also

https://docs.getodk.org/central-api-dataset-management/#datasets

Other entity-management: entitylist_download(), entitylist_list()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

ds <- entitylist_list(pid = get_default_pid())
ds1 <- entitylist_detail(pid = get_default_pid(), did = ds$name[1])

ds1 |> listviewer::jsonedit()
ds1$linkedForms |>
  purrr::list_transpose() |>
  tibble::as_tibble()
ds1$sourceForms |>
  purrr::list_transpose() |>
  tibble::as_tibble()
ds1$properties |>
  purrr::list_transpose() |>
  tibble::as_tibble()

## End(Not run)

Description

Usage

entitylist_download(
  pid = get_default_pid(),
  did = NULL,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  local_dir = here::here(),
  filter = NULL,
  etag = NULL,
  overwrite = TRUE,
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"),
  tz = get_default_tz(),
  verbose = get_ru_verbose()
)

Arguments

Details

The downloaded CSV file is named after the entity list name. The download location defaults to the current workdir, but can be modified to a different folder path which will be created if it doesn't exist.

An Entity List is a named collection of Entities that have the same properties. Entity List can be linked to Forms as Attachments. This will make it available to clients as an automatically-updating CSV.

Entity Lists can be used as Attachments in other Forms, but they can also be downloaded directly as a CSV file. The CSV format closely matches the OData Dataset (Entity List) Service format, with columns for system properties such as ⁠__id⁠ (the Entity UUID), ⁠__createdAt⁠, ⁠__creatorName⁠, etc., the Entity Label label, and the Dataset (Entity List )/Entity Properties themselves. If any Property for an given Entity is blank (e.g. it was not captured by that Form or was left blank), that field of the CSV is blank.

The ODK Central ⁠$filter⁠ querystring parameter can be used to filter on system-level properties, similar to how filtering in the OData Dataset (Entity List) Service works. Of the OData filter specs ODK Central implements a growing set of features . ruODK provides the parameter filter (str) which, if set, will be passed on to the ODK Central endpoint as is.

The ODK Central endpoint supports the ETag header , which can be used to avoid downloading the same content more than once. When an API consumer calls this endpoint, the endpoint returns a value in the ETag header. If you pass that value in the If-None-Match header of a subsequent request, then if the Entity List has not been changed since the previous request, you will receive 304 Not Modified response; otherwise you'll get the new data. ruODK provides the parameter etag which can be set from the output of a previous call to entitylist_download(). ruODK strips the ⁠W/\"⁠ and ⁠\"⁠ from the returned etag and expects the stripped etag as parameter.

Value

A list of four items:

• entities (tbl_df) The Entity List as tibble

• http_status (int) The HTTP status code of the response. 200 if OK, 304 if a given etag finds no new entities created.

• etag (str) The ETag to use in subsequent calls to entitylist_download()

• downloaded_to (fs_path) The path to the downloaded CSV file

• downloaded_on (POSIXct) The time of download in the local timezome

See Also

https://docs.getodk.org/central-api-dataset-management/#datasets

Other entity-management: entitylist_detail(), entitylist_list()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

ds <- entitylist_list(pid = get_default_pid())
ds1 <- entitylist_download(pid = get_default_pid(), did = ds$name[1])
# ds1$entities
# ds1$etag
# ds1$downloaded_to
# ds1$downloaded_on

ds2 <- entitylist_download(
  pid = get_default_pid(),
  did = ds$name[1],
  etag = ds1$etag
)
# ds2$http_status == 304

newest_entity_date <- as.Date(max(ds1$entities$`__createdAt`))
ds3 <- entitylist_download(
  pid = get_default_pid(),
  did = ds$name[1],
  filter = glue::glue("__createdAt le {newest_entity_date}")
)

## End(Not run)

Description

Usage

entitylist_list(
  pid = get_default_pid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"),
  tz = get_default_tz()
)

Arguments

Details

While the API endpoint will return all Entity Lists for one Project, entitylist_list will fail with incorrect or missing authentication.

An Entity List is a named collection of Entities that have the same properties. An Entity List can be linked to Forms as Attachments. This will make it available to clients as an automatically-updating CSV.

ODK Central calls Entity Lists internally Datasets. ruODK chooses the term Entity Lists as it is used in the ODK Central user interface and conveys its relation to Entities better than the term Dataset.

This function is supported from ODK Central v2022.3 and will warn if the given odkc_version is lower.

Value

A tibble with exactly one row for each dataset of the given project as per ODK Central API docs. Column names are renamed from ODK's camelCase to snake_case.

See Also

https://docs.getodk.org/central-api-dataset-management/#datasets

Other entity-management: entitylist_detail(), entitylist_download()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

ds <- entitylist_list(pid = get_default_pid())

ds |> knitr::kable()

## End(Not run)

Description

Usage

entitylist_update(
  pid = get_default_pid(),
  did = NULL,
  approval_required = FALSE,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"),
  tz = get_default_tz()
)

Arguments

Details

You can only update approvalRequired using this endpoint. The approvalRequired flag controls the Entity creation flow; if it is true then the Submission must be approved before an Entity can be created from it and if it is false then an Entity is created as soon as the Submission is received by the ODK Central. By default approvalRequired is false for the Entity Lists created after v2023.3. Entity Lists created prior to that will have approvalRequired set to true.

An Entity List is a named collection of Entities that have the same properties. An Entity List can be linked to Forms as Attachments. This will make it available to clients as an automatically-updating CSV.

This function is supported from ODK Central v2022.3 and will warn if the given odkc_version is lower.

Value

A list of lists following the exact format and naming of the API response for entitylist_detail. Since this nested list is so deeply nested and irregularly shaped it is not trivial to rectangle the result into a tibble.

See Also

https://docs.getodk.org/central-api-dataset-management/#datasets

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

pid <- get_default_pid()

ds <- entitylist_list(pid = pid)

did <- ds$name[1]

ds1 <- entitylist_detail(pid = pid, did = did)
ds1$approvalRequired # FALSE

ds2 <- entitylist_update(pid = pid, did = did, approval_required = TRUE)
ds2$approvalRequired # TRUE

ds3 <- entitylist_update(pid = pid, did = did, approval_required = FALSE)
ds3$approvalRequired # FALSE

## End(Not run)

Description

Usage

form_detail(
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Value

A tibble with one row and all form metadata as columns.

See Also

https://docs.getodk.org/central-api-form-management/#getting-form-details

Other form-management: form_list(), form_schema(), form_schema_ext(), form_xml()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

# With explicit credentials, see tests
fl <- form_list()

# The first form in the test project
f <- form_detail(fid = fl$fid[[1]])

# form_detail returns exactly one row
nrow(f)
# > 1

# form_detail returns all form metadata as columns: name, xmlFormId, etc.
names(f)

# > "name" "fid" "version" "state" "submissions" "created_at"
# > "created_by_id" "created_by" "updated_at" "published_at"
# > "last_submission" "hash"

## End(Not run)

Description

Usage

form_list(
  pid = get_default_pid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"),
  tz = get_default_tz()
)

Arguments

Value

A tibble with one row per form and all given form metadata as cols. Column names are sanitized into snake_case. Nested columns (review start and created by) are flattened and prefixed. The column xml_form_id is replicated as fid according to ruODK naming standards.

See Also

https://docs.getodk.org/central-api-form-management/#list-all-forms

Other form-management: form_detail(), form_schema(), form_schema_ext(), form_xml()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

# With default pid
fl <- form_list()

# With explicit pid
fl <- form_list(pid = 1)

class(fl)
# > c("tbl_df", "tbl", "data.frame")

# Filter out draft forms (published_at=NA)
only_published_forms <- fl %>% dplyr::filter(is.na(published_at))

# Note: older ODK Central versions < 1.1 have published_at = NA for both
# published and draft forms. Drafts have NA for version and hash.
only_published_forms <- fl %>% dplyr::filter(is.na(version) & is.na(hash))

## End(Not run)

Description

Usage

form_schema(
  flatten = FALSE,
  odata = FALSE,
  parse = TRUE,
  draft = FALSE,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  odkc_version = get_default_odkc_version(),
  retries = get_retries(),
  verbose = get_ru_verbose()
)

Arguments

Details

ODK Central has introduced a new API endpoint in version 0.8 which returns a parsed and flattened list of fields. This replaces the nested form schema which is challenging to parse.

While users of newer ODK Central versions (> 0.8) can ignore the legacy support for ODK Central's earlier form schema API, users of ODK Central version < 0.8 can set an environment variable ODKC_VERSION to their ODKC's version in format <major>.<minor> e.g. 0.7. This variable caters for future breaking changes.

Either way, form_schema will always return a tibble with columns name, type, path and ruodk_name.

Value

A tibble or nested list (v0.7) containing the form definition. At the lowest nesting level, each form field consists of a list of two nodes, name (the underlying field name) and type (the XForms field type, as in "string", "select1", "geopoint", "binary" and so on). These fields are nested in lists of tuples name (the XForms screen name), children (the fields as described above), type ("structure" for non- repeating screens, "repeat" for repeating screens). A list with name "meta" may precede the structure, if several metadata fields are captured (e.g. "instanceId", form start datetimes etc.). In all cases for ODK Central 0.8, and with default parameters (parse=TRUE) for ODK Central 0.7, form_schema returns a tibble with the columns:

• name The field name as given in the form schema.

• type The field type, e.g. "string", "select1", etc.

• path The XForms path of the field,

• selectMultiple Whether a field of type "select" is a select multiple (TRUE). Any other types are NA.

• ruodk_name The predicted field name as generated by odata_submission_get, prefixed by the path, additionally cleaned with make_clean_names to match the cleaned column names from odata_submission_rectangle.

See Also

https://docs.getodk.org/central-api-form-management/#getting-form-schema-fields

Other form-management: form_detail(), form_list(), form_schema_ext(), form_xml()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

# With explicit pid and fid
fs_defaults <- form_schema(pid = 1, fid = "build_xformsId")

# With current ODK Central (v0.8)
fs <- form_schema()

# With defaults, ODK Central v0.7
fs_nested <- form_schema(
  flatten = FALSE,
  odata = FALSE,
  parse = FALSE,
  odkc_version = 0.7
)
listviewer::jsonedit(fs_nested)

fs_flattened <- form_schema(
  flatten = TRUE,
  odata = FALSE,
  parse = FALSE,
  odkc_version = 0.7
)
listviewer::jsonedit(fs_flattened)

# form_schema returns a nested list. There's nothing to change about that.
class(fs_nested)
# > "list"

class(fs_flattened)
# > "list"

# This assumes knowledge of that exact form being tested.
# First node: type "structure" (a field group) named "meta".
fs_nested[[1]]$type
# > "structure"

fs_nested[[1]]$name
# > "meta"

# The first node contains children, which means it's an XForms field group.
names(fs_nested[[1]])
# > "name" "children" "type"

# Next node: a "meta" field of type "string" capturing the  "instanceId".
# First child node of "meta": type "string", name "instanceId".
fs_nested[[1]]$children[[1]]$type
# > "string"
fs_nested[[1]]$children[[1]]$name
# > "instanceID"

# In the flattened version, the field's and it's ancestors' names are the
# components of "path".
fs_flattened[[1]]$path
# > "meta". "instanceId"

fs_flattened[[1]]$type
# > "string"

# Last node: a "meta" field capturing the datetime of form completion
fs_flattened[[length(fs_flattened)]]$type
# > "dateTime"
fs_nested[[length(fs_nested)]]$type
# > "dateTime"

# Parsed into a tibble of form field type/name:
# Useful to inform further parsing of submission data (attachments, dates)
fs <- form_schema(parse = TRUE, odkc_version = 0.7)
fs <- form_schema(odkc_version = 0.8)

# Attachments: used by handle_ru_attachments
fs %>% dplyr::filter(type == "binary")

# dateTime: used by handle_ru_datetimes
fs %>% dplyr::filter(type == "dateTime")

# Point location: used by handle_ru_geopoints
fs %>% dplyr::filter(type == "geopoint")

## End(Not run)

Description

Usage

form_schema_ext(
  flatten = FALSE,
  odata = FALSE,
  parse = TRUE,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  odkc_version = get_default_odkc_version(),
  retries = get_retries(),
  verbose = get_ru_verbose()
)

Arguments

Details

ODK Central has introduced a new API endpoint in version 0.8 which returns a parsed and flattened list of fields. This replaces the nested form schema which is challenging to parse. This list is returned by form_schema.

However this still misses important elements, in particular labels and choice_lists.

form_schema_ext returns the same object as form_schema adding labels and choice lists in all languages available. This is done by using the return object from form_xml.

It has the exact function signature as form_schema. In that sense, any call to form_schema can be replaced by form_schema_ext

This function, however, has been prepared with ODK Central version 0.8 or higher. If you use it with an earlier version, a warning will be given.

Value

A tibble containing the form definition. For ODK Central 0.8, and with default parameters (parse=TRUE) for ODK Central 0.7, form_schema returns a tibble with the columns:

• name The field name as given in the form schema.

• type The field type, e.g. "string", "select1", etc.

• path The XForms path of the field,

• ruodk_name The predicted field name as generated by odata_submission_get, prefixed by the path, additionally cleaned with make_clean_names to match the cleaned column names from odata_submission_rectangle.

• label The field label as given in the form schema. If specific languages are available, this column will return the default language or it will be empty if this is not specified.

• label_lang The field label in languange _lang as given in the form schema.

• choices A list of lists containing at least values and, if available, labels of the choices as given in the form schema. If specific languages are available, this column will return the default language or it will be empty if this is not specified. Please notice that whenever choice filters are applied, this will return the unfiltered choice list.

• choices_lang A list of lists containing at least values and, if available, labels of the choices in language _lang as given in the form schema. Please notice that whenever choice filters are applied, this will return the unfiltered choice list.

See Also

https://docs.getodk.org/central-api-form-management/#getting-form-schema-fields

https://docs.getodk.org/central-api-form-management/#retrieving-form-xml

Other form-management: form_detail(), form_list(), form_schema(), form_xml()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

# With current ODK Central (>0.7)
# get extended schema:
fsx <- form_schema_ext()

# print choice list in english:
fsx[fsx$name == "test_yn", "choices_english_(en)"][[1]]

# view the extended schema:
fsx

## End(Not run)

Description

Usage

form_schema_parse(fs, path = "Submissions", verbose = get_ru_verbose())

Arguments

Details

This function is used by form_schema for older versions of ODK Central (pre 0.8). These return the form schema as XML, requiring the quite involved code of form_schema_parse, while newer ODK Central versions return JSON, which is parsed directly in form_schema.

The form_schema returned from ODK Central versions < 0.8 is a nested list of lists containing the form definition. The form definition consists of fields (with a type and name), and form groups, which are rendered as separate ODK Collect screens. Form groups in turn can also contain form fields.

form_schema_parse recursively unpacks the form and extracts the name and type of each field. This information then informs handle_ru_attachments, handle_ru_datetimes, handle_ru_geopoints, handle_ru_geotraces, and handle_ru_geoshapes.

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
# Option 1: in two steps, ODKC Version 0.7
fs <- form_schema(flatten = FALSE, parse = FALSE, odkc_version = 0.7)
fsp <- form_schema_parse(fs)

# Option 2: in one go
fsp <- form_schema(parse = TRUE)

fsp

## End(Not run)

Description

Usage

form_xml(
  parse = TRUE,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Value

The form XML as a nested list.

See Also

https://docs.getodk.org/central-api-form-management/#retrieving-form-xml

Other form-management: form_detail(), form_list(), form_schema(), form_schema_ext()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

# With explicit pid and fid
fxml_defaults <- form_xml(1, "build_xformsId")

# With defaults
fxml <- form_xml()
listviewer::jsonedit(fxml)

# form_xml returns a nested list
class(fxml)
# > "list"

## End(Not run)

Description

Usage

fq_attachments

Format

A tibble of submission attachments.

Source

The output of attachment_list run on submissions of the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

Other included: fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_data

Format

The output of odata_submission_get for a set of example data. A tidy tibble referencing the attachments included in the vignettes and documentation at a relative path ⁠attachments/media/<filename>.<ext>⁠.

Details

The parsed OData response for the submissions of an ODK Central form. This form represents a Flora Quadrat, which is a ca 50 by 50 m quadrat of a uniform plant community.

The XML and .odkbuild versions for this form are available as system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and system.file("extdata", "FloraQuadrat04.odkbuild", package = "ruODK"), respectively.

This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and odata_submission_get.

See Also

Other included: fq_attachments, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_data_strata

Format

The output of odata_submission_get for a set of example data. A tidy tibble referencing the attachments included in the vignettes and documentation at a relative path ⁠attachments/media/<filename>.<ext>⁠.

Details

The parsed OData response for the subgroup of an ODK Central form.

This subgroup represents vegetation strata as per the NVIS classification. A vegetation stratum is a layer of plants with the same height, and dominated by one or few plant taxa. Plant communities can be made of up to five strata, with two to three being most common.

This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and odata_submission_get.

See Also

Other included: fq_attachments, fq_data, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_data_taxa

Format

The output of odata_submission_get for a set of example data. A tidy tibble referencing the attachments included in the vignettes and documentation at a relative path ⁠attachments/media/<filename>.<ext>⁠.

Details

The parsed OData response for a subgroup of an ODK Central form.

This subgroup represents an individual plant taxon which is encountered by the enumerators. Typically, one voucher specimen is taken for each distinct encountered plant taxon. A field name is allocated by the enumerators, which can be the proper canonical name (if known) or any other moniker. The voucher specimens are later determined by taxonomic experts, who then provide the real, terminal taxonomic name for a given voucher specimen.

This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and odata_submission_get.

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_form_detail

Format

A tibble of form metadata.

Source

The output of form_detail run on submissions of the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_form_list

Format

A tibble of forms

Source

The output of form_list. run on the project.

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_form_schema

Format

The output of ruODK::form_schema(), a tibble with columns "type", "name" and "path" and one row per form field.

Details

The parsed form schema of an ODK Central form.

This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.

This data is used to build vignettes offline and without the need for credentials to an ODK Central server. The test suite ensures that the "canned" data is identical to the "live" data.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and ruODK::form_schema().

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_form_xml

Format

A nested list of a form definition.

Source

The output of form_xml run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_meta

Format

A list of lists

Details

The OData response for the metadata of an ODK Central form.

This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_project_detail

Format

A tibble of project metadata.

Source

The output of project_detail run on the project containing the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_project_list

Format

A tibble of project metadata.

Source

The output of project_list run on all projects on the configured ODK Central server.

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_raw

Format

A list of lists

Details

The OData response for the submissions of an ODK Central form. This form represents a Flora Quadrat, which is a ca 50 by 50 m quadrat of a uniform plant community.

The XML and .odkbuild versions for this form are available as system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and system.file("extdata", "FloraQuadrat04.odkbuild", package = "ruODK"), respectively.

This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_raw_strata

Format

A list of lists

Details

The OData response for the subgroup of an ODK Central form.

This subgroup represents vegetation strata as per the NVIS classification. A vegetation stratum is a layer of plants with the same height, and dominated by one or few plant taxa. Plant communities can be made of up to five strata, with two to three being most common.

This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_raw_taxa

Format

A list of lists

Details

The OData response for a subgroup of an ODK Central form.

This subgroup represents an individual plant taxon which is encountered by the enumerators. Typically, one voucher specimen is taken for each distinct encountered plant taxon. A field name is allocated by the enumerators, which can be the proper canonical name (if known) or any other moniker. The voucher specimens are later determined by taxonomic experts, who then provide the real, terminal taxonomic name for a given voucher specimen.

This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_submission_list

Format

A tibble of submission metadata.

Source

The output of submission_list run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_submissions

Format

A nested list of submission data.

Source

The output of submission_get run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") using submission instance IDs from submission_list.

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_svc

Format

A tibble with one row per submission data endpoint.

Details

The OData response for the metadata of an ODK Central form.

This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.

Source

OData service document for system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_zip_data

Format

A tibble of main records from a test form.

Source

submission_export run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_zip_strata

Format

A tibble of repeated sub-group of records from a test form.

Source

submission_export run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fq_zip_taxa

Format

A tibble of repeated sub-group of records from a test form.

Source

submission_export run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fs_v7

Format

An object of class tbl_df (inherits from tbl, data.frame) with 12 rows and 3 columns.

Source

form_schema_parse(fs_v7_raw)

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

fs_v7_raw

Format

An object of class list of length 6.

Source

form_schema(odkc_version = 0.7, parse = FALSE)

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

geo_fs

Format

An object of class tbl_df (inherits from tbl, data.frame) with 19 rows and 6 columns.

Source

form_schema run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

geo_gj

Format

An object of class tbl_df (inherits from tbl, data.frame) with 1 rows and 58 columns.

Source

odata_submission_get(wkt=FALSE, parse=TRUE) run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

geo_gj_raw

Format

An object of class list of length 2.

Source

odata_submission_get(wkt=FALSE, parse=FALSE) run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

geo_gj88

Format

An object of class tbl_df (inherits from tbl, data.frame) with 1 rows and 51 columns.

Details

This issue was fixed in #88. ODK Central versions 0.7 - 0.9 export geotraces and geoshapes with trailing empty coordinates. ruODK has a patch to drop trailing empty coordinates. This dataset is used to test the patch in ruODK.

Source

odata_submission_get(wkt=FALSE, parse=TRUE) run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj_raw, geo_wkt, geo_wkt88, geo_wkt_raw

Description

Usage

geo_wkt

Format

An object of class tbl_df (inherits from tbl, data.frame) with 1 rows and 55 columns.

Source

odata_submission_get(wkt=TRUE, parse=TRUE) run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt88, geo_wkt_raw

Description

Usage

geo_wkt_raw

Format

An object of class list of length 2.

Source

odata_submission_get(wkt=TRUE, parse=FALSE) run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt88

Description

Usage

geo_wkt88

Format

An object of class tbl_df (inherits from tbl, data.frame) with 1 rows and 48 columns.

Details

This issue was fixed in #88. ODK Central versions 0.7 - 0.9 export geotraces and geoshapes with trailing empty coordinates. ruODK has a patch to drop trailing empty coordinates. This dataset is used to test the patch in ruODK.

Source

odata_submission_get(wkt=TRUE, parse=TRUE) run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

Other included: fq_attachments, fq_data, fq_data_strata, fq_data_taxa, fq_form_detail, fq_form_list, fq_form_schema, fq_form_xml, fq_meta, fq_project_detail, fq_project_list, fq_raw, fq_raw_strata, fq_raw_taxa, fq_submission_list, fq_submissions, fq_svc, fq_zip_data, fq_zip_strata, fq_zip_taxa, fs_v7, fs_v7_raw, geo_fs, geo_gj, geo_gj88, geo_gj_raw, geo_wkt, geo_wkt_raw

Description

Usage

get_one_attachment(
  pth,
  fn,
  src,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  verbose = get_ru_verbose()
)

Arguments

Details

This is a helper function used by attachment_get. This function is not vectorised, but mapped by attachment_get to a tibble of input parameters.

Value

The relative local path to the downloaded attachment or NA.

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
# Step 1: Setup ruODK with OData Service URL (has url, pid, fid)
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

# Step 2: Construct attachment_url
att_url <- ruODK:::attachment_url(
  "uuid:d3bcefea-32a8-4dbc-80ca-4ecb0678e2b0",
  "filename.jpg"
)

# Step 3: Get one attachment
local_fn <- get_one_attachment("media/filename.jpg", "filename.jpg", att_url)

# In real life: done in bulk behind the scenes during odata_submission_get()

## End(Not run)

Description

This function is the workhorse for the vectorised function submission_get, which gets all submissions for a list of submission IDs.

Usage

get_one_submission(
  iid,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Details

Note this function returns a nested list containing any repeating subgroups. As the presence and length of repeating subgroups is non-deterministic and entirely depends on the completeness of the submission data, we cannot rectangle them any further here. Rectangling requires knowledge of the form schema and the completeness of submission data.

Value

A nested list of submission data.

See Also

https://docs.getodk.org/central-api-submission-management/#retrieving-submission-xml

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

# With explicit credentials, see tests
sl <- submission_list()

sub <- get_one_submission(sl$instance_id[[1]])
listviewer::jsonedit(sub)

# The details for one submission depend on the form fields
length(sub)
# > 11

# The items are the field names. Repeated groups have the same name.
names(sub)
# > "meta"                     "encounter_start_datetime" "reporter"
# > "device_id"                "location"                 "habitat"
# > "vegetation_structure"     "perimeter"                "taxon_encounter"
# > "taxon_encounter"          "encounter_end_datetime"

## End(Not run)

Description

Usage

get_one_submission_attachment_list(
  iid,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Details

When a Submission is created, either over the OpenRosa or the REST interface, its XML data is analysed to determine which file attachments it references: these may be photos or video taken as part of the survey, or an audit/timing log, among other things. Each reference is an expected attachment, and these expectations are recorded permanently alongside the Submission. With this subresource, you can list the expected attachments, see whether the server actually has a copy or not, and download, upload, re-upload, or clear binary data for any particular attachment.

You can retrieve the list of expected Submission attachments at this route, along with a boolean flag indicating whether the server actually has a copy of the expected file or not. If the server has a file, you can then append its filename to the request URL to download only that file.

Value

A tibble containing some high-level details of the submission attachments. One row per submission attachment, columns are submission attributes:

    * name: The attachment filename, e.g. 12345.jpg
    * exists: Whether the attachment for that submission exists on the
      server.

See Also

https://docs.getodk.org/central-api-submission-management/#listing-expected-submission-attachments

https://docs.getodk.org/central-api-form-management/#listing-form-attachments

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

sl <- submission_list()

al <- get_one_submission_attachment_list(sl$instance_id[[1]])
al %>% knitr::kable(.)

# attachment_list returns a tibble
class(al)
# > c("tbl_df", "tbl", "data.frame")

# Submission attributes are the tibble's columns
names(al)
# > "name" "exists"

## End(Not run)

Description

Usage

get_one_submission_audit(
  iid,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Details

This function is the workhorse for the vectorised function submission_audit_get, which gets all server audit logs for a list of submission IDs.

Note this function returns a nested list containing any repeating subgroups. As the presence and length of repeating subgroups is non-deterministic and entirely depends on the completeness of the submission data, we cannot rectangle them any further here. Rectangling requires knowledge of the form schema and the completeness of submission data.

Value

A nested list of submission data.

See Also

https://docs.getodk.org/central-api-submission-management/#retrieving-audit-logs

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

# With explicit credentials, see tests
sl <- submission_list()

sub <- get_one_submission_audit(sl$instance_id[[1]])
listviewer::jsonedit(sub)

# The details for one submission depend on the form fields
length(sub)
# > 11

# The items are the field names. Repeated groups have the same name.
names(sub)
# > "meta"                     "encounter_start_datetime" "reporter"
# > "device_id"                "location"                 "habitat"
# > "vegetation_structure"     "perimeter"                "taxon_encounter"
# > "taxon_encounter"          "encounter_end_datetime"

## End(Not run)

Description

Usage

handle_ru_attachments(
  data,
  form_schema,
  local_dir = "media",
  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

ruODK::odata_submission_get(parse = FALSE) %>%
ruODK::odata_submission_rectangle()

Details

For a given tibble of submissions, download and link attachments for all columns which are marked in the form schema as type "binary".

Value

The submissions tibble with all attachments downloaded and linked to a local_dir.

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
library(magrittr)
data("fq_raw")
data("fq_form_schema")
t <- tempdir()
fs::dir_ls(t) %>% fs::file_delete()
fq_with_att <- fq_raw %>%
  ruODK::odata_submission_rectangle() %>%
  ruODK::handle_ru_attachments(
    form_schema = fq_form_schema,
    local_dir = t,
    pid = ruODK::get_test_pid(),
    fid = ruODK::get_test_fid(),
    url = ruODK::get_test_url(),
    un = ruODK::get_test_un(),
    pw = ruODK::get_test_pw(),
    verbose <- ruODK::get_ru_verbose()
  )
# There should be files in local_dir
testthat::expect_true(fs::dir_ls(t) %>% length() > 0)

## End(Not run)

Description

Usage

handle_ru_datetimes(
  data,
  form_schema,
  orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"),
  tz = get_default_tz(),
  verbose = get_ru_verbose()
)

Arguments

ruODK::odata_submission_get(parse = FALSE) %>%
ruODK::odata_submission_rectangle()

Details

For a given tibble of submissions, parse all columns which are marked in the form schema as type "date" or "dateTime" using a set of lubridate orders and a given timezone.

Value

The submissions tibble with all date/dateTime columns mutated as lubridate datetimes.

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_geopoints(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
library(magrittr)
data("fq_raw")
data("fq_form_schema")

fq_with_dates <- fq_raw %>%
  ruODK::odata_submission_rectangle() %>%
  ruODK::handle_ru_datetimes(form_schema = fq_form_schema)

dplyr::glimpse(fq_with_dates)

## End(Not run)

Description

Usage

handle_ru_geopoints(data, form_schema, wkt = FALSE, verbose = get_ru_verbose())

Arguments

ruODK::odata_submission_get(parse = FALSE) %>%
ruODK::odata_submission_rectangle()

Details

For a given tibble of submissions, find all columns which are listed in the form schema as type geopoint, and extract their components. Extracted components are longitude (X), latitude (Y), altitude (Z, where given), and accuracy (M, where given).

The original column is retained to allow parsing into other spatially enabled formats.

Value

The submissions tibble with all geopoints retained in their original format, plus columns of their coordinate components as provided by split_geopoint.

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geoshapes(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

library(magrittr)
data("geo_fs")
data("geo_gj_raw")
data("geo_wkt_raw")

# GeoJSON
geo_gj_parsed <- geo_gj_raw %>%
  ruODK::odata_submission_rectangle(form_schema = geo_fs) %>%
  ruODK::handle_ru_geopoints(form_schema = geo_fs, wkt = FALSE)

dplyr::glimpse(geo_gj_parsed)

# WKT
geo_wkt_parsed <- geo_wkt_raw %>%
  ruODK::odata_submission_rectangle(form_schema = geo_fs) %>%
  ruODK::handle_ru_geopoints(form_schema = geo_fs, wkt = TRUE)

dplyr::glimpse(geo_wkt_parsed)

Description

Usage

handle_ru_geoshapes(
  data,
  form_schema,
  wkt = FALSE,
  odkc_version = get_default_odkc_version(),
  verbose = get_ru_verbose()
)

Arguments

ruODK::odata_submission_get(parse = FALSE) %>%
ruODK::odata_submission_rectangle(form_schema = ...)

Details

For a given tibble of submissions, find all columns which are listed in the form schema as type geoshape, and extract their components. Extracted components are longitude (X), latitude (Y), altitude (Z, where given), and accuracy (M, where given) of the first point of the geoshape.

The original column is retained to allow parsing into other spatially enabled formats.

Value

The submissions tibble with all geoshapes retained in their original format, plus columns of their first point's coordinate components as provided by split_geoshape.

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geotraces(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
library(magrittr)
data("geo_fs")
data("geo_wkt_raw")
data("geo_gj_raw")

# GeoJSON
geo_gj_parsed <- geo_gj_raw %>%
  ruODK::odata_submission_rectangle(form_schema = geo_fs) %>%
  ruODK::handle_ru_geoshapes(form_schema = geo_fs, wkt = FALSE)

dplyr::glimpse(geo_gj_parsed)

# WKT
geo_wkt_parsed <- geo_wkt_raw %>%
  ruODK::odata_submission_rectangle(form_schema = geo_fs) %>%
  ruODK::handle_ru_geoshapes(form_schema = geo_fs, wkt = TRUE)

dplyr::glimpse(geo_wkt_parsed)

## End(Not run)

Description

Usage

handle_ru_geotraces(
  data,
  form_schema,
  wkt = FALSE,
  odkc_version = get_default_odkc_version(),
  verbose = get_ru_verbose()
)

Arguments

ruODK::odata_submission_get(parse = FALSE) %>%
ruODK::odata_submission_rectangle(form_schema = ...)

Details

For a given tibble of submissions, find all columns which are listed in the form schema as type geotrace, and extract their components. Extracted components are longitude (X), latitude (Y), altitude (Z, where given), and accuracy (M, where given) of the first point of the geotrace.

The original column is retained to allow parsing into other spatially enabled formats.

Value

The submissions tibble with all geotraces retained in their original format, plus columns of their first point's coordinate components as provided by split_geotrace.

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_attachment_list(), get_one_submission_audit(), handle_ru_attachments(), handle_ru_datetimes(), handle_ru_geopoints(), handle_ru_geoshapes(), isodt_to_local(), odata_submission_rectangle(), predict_ruodk_name(), prepend_uuid(), split_geopoint(), split_geoshape(), split_geotrace(), strip_uuid(), tidyeval, unnest_all()

Examples

## Not run: 
library(magrittr)
data("geo_fs")
data("geo_wkt_raw")
data("geo_gj_raw")

# GeoJSON
geo_gj_parsed <- geo_gj_raw %>%
  ruODK::odata_submission_rectangle(form_schema = geo_fs) %>%
  ruODK::handle_ru_geotraces(form_schema = geo_fs, wkt = FALSE)

dplyr::glimpse(geo_gj_parsed)

# WKT
geo_wkt_parsed <- geo_wkt_raw %>%
  ruODK::odata_submission_rectangle(form_schema = geo_fs) %>%
  ruODK::handle_ru_geotraces(form_schema = geo_fs, wkt = TRUE)

dplyr::glimpse(geo_wkt_parsed)

## End(Not run)

Description

Usage

odata_metadata_get(
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Value

A nested list containing Edmx (dataset schema definition) and .attrs (Version).

See Also

https://docs.getodk.org/central-api-odata-endpoints/#metadata-document

Other odata-api: odata_service_get(), odata_submission_get()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

meta <- odata_metadata_get()
listviewer::jsonedit(meta)

## End(Not run)

Description

Usage

odata_service_get(
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)