From c6f09b5c82a8155595da8513729e1fdf1eaec7d5 Mon Sep 17 00:00:00 2001 From: Florian Mayer Date: Fri, 26 Jul 2024 20:44:40 +0800 Subject: [PATCH] Add entity_version, add get_default_orders --- NAMESPACE | 2 + R/encryption_key_list.R | 9 +- R/entity_create.R | 9 +- R/entity_delete.R | 9 +- R/entity_detail.R | 9 +- R/entity_list.R | 9 +- R/entity_update.R | 9 +- R/entity_versions.R | 117 +++++++++++++++++++++ R/entitylist_detail.R | 9 +- R/entitylist_download.R | 9 +- R/entitylist_list.R | 9 +- R/entitylist_update.R | 9 +- R/form_list.R | 9 +- R/handle_ru_datetimes.R | 9 +- R/odata_submission_get.R | 9 +- R/project_list.R | 9 +- R/ru_setup.R | 14 +++ R/submission_list.R | 9 +- R/user_list.R | 9 +- man/encryption_key_list.Rd | 2 +- man/entity_create.Rd | 3 +- man/entity_delete.Rd | 3 +- man/entity_detail.Rd | 3 +- man/entity_list.Rd | 3 +- man/entity_update.Rd | 3 +- man/entity_versions.Rd | 153 ++++++++++++++++++++++++++++ man/entitylist_detail.Rd | 3 +- man/entitylist_download.Rd | 3 +- man/entitylist_list.Rd | 3 +- man/entitylist_update.Rd | 3 +- man/form_list.Rd | 2 +- man/handle_ru_datetimes.Rd | 2 +- man/odata_submission_get.Rd | 2 +- man/project_list.Rd | 2 +- man/ru_settings.Rd | 3 + man/submission_list.Rd | 2 +- man/user_list.Rd | 2 +- tests/testthat/test-entity_update.R | 35 +++++++ 38 files changed, 365 insertions(+), 144 deletions(-) create mode 100644 R/entity_versions.R create mode 100644 man/entity_versions.Rd diff --git a/NAMESPACE b/NAMESPACE index d9778489..ec9d505a 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -16,6 +16,7 @@ export(entity_delete) export(entity_detail) export(entity_list) export(entity_update) +export(entity_versions) export(entitylist_detail) export(entitylist_download) export(entitylist_list) @@ -30,6 +31,7 @@ export(form_schema_parse) export(form_xml) export(get_default_fid) export(get_default_odkc_version) +export(get_default_orders) export(get_default_pid) export(get_default_pp) export(get_default_pw) diff --git a/R/encryption_key_list.R b/R/encryption_key_list.R index 2c9800f1..eff1d70e 100644 --- a/R/encryption_key_list.R +++ b/R/encryption_key_list.R @@ -45,14 +45,7 @@ encryption_key_list <- function(pid = get_default_pid(), un = get_default_un(), pw = get_default_pw(), retries = get_retries(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw) httr::RETRY( diff --git a/R/entity_create.R b/R/entity_create.R index fa6d4feb..80a2e798 100644 --- a/R/entity_create.R +++ b/R/entity_create.R @@ -151,14 +151,7 @@ entity_create <- function(pid = get_default_pid(), pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid, did = did) diff --git a/R/entity_delete.R b/R/entity_delete.R index 8bec468a..2c039a82 100644 --- a/R/entity_delete.R +++ b/R/entity_delete.R @@ -53,14 +53,7 @@ entity_delete <- function(pid = get_default_pid(), pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid, did = did, eid = eid) diff --git a/R/entity_detail.R b/R/entity_detail.R index 528344bc..58efc4a8 100644 --- a/R/entity_detail.R +++ b/R/entity_detail.R @@ -79,14 +79,7 @@ entity_detail <- function(pid = get_default_pid(), pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid, did = did, eid = eid) diff --git a/R/entity_list.R b/R/entity_list.R index e752dea1..877235ee 100644 --- a/R/entity_list.R +++ b/R/entity_list.R @@ -57,14 +57,7 @@ entity_list <- function(pid = get_default_pid(), pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid, did = did) diff --git a/R/entity_update.R b/R/entity_update.R index 46f73b29..acfadadc 100644 --- a/R/entity_update.R +++ b/R/entity_update.R @@ -107,14 +107,7 @@ entity_update <- function(pid = get_default_pid(), pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid, did = did, eid = eid) diff --git a/R/entity_versions.R b/R/entity_versions.R new file mode 100644 index 00000000..d9af7c9d --- /dev/null +++ b/R/entity_versions.R @@ -0,0 +1,117 @@ +#' List versions of one Entity. +#' +#' `r lifecycle::badge("maturing")` +#' +#' +#' This returns the Entity metadata and data for every version of this Entity +#' in ascending creation order. +#' +#' The ODK Central endpoint supports retrieving extended metadata which this +#' function always returns. +#' +#' There is an optional query flag `relevantToConflict` that returns the subset +#' of past versions of an Entity that are relevant to the Entity's current +#' conflict. This includes the latest version, the base version, the previous +#' server version, and any other versions since the last time the Entity was +#' in a conflict-free state. If the Entity is not in conflict, zero versions +#' are returned. +#' +#' @template tpl-structure-nested +#' @template tpl-names-cleaned-top-level +#' @template tpl-auth-missing +#' @template tpl-compat-2022-3 +#' @template param-pid +#' @template param-did +#' @template param-eid +#' @param conflict (lgl) Whether to return all versions (`FALSE`) or +#' whether to returns the subset of past versions of an Entity that are +#' relevant to the Entity's current conflict (`TRUE`). +#' This includes the latest version, the base version, the previous +#' server version, and any other versions since the last time the Entity was +#' in a conflict-free state. If the Entity is not in conflict, zero versions +#' are returned. +#' Default: `FALSE` (return all versions) +#' @template param-url +#' @template param-auth +#' @template param-retries +#' @template param-odkcv +#' @template param-orders +#' @template param-tz +#' @return A tibble with one row per version. List columns contain unstructured +#' data. +#' See +#' for the full schema. +#' Top level list elements are renamed from ODK's `camelCase` to `snake_case`. +#' Nested list elements have the original `camelCase`. +# nolint start +#' @seealso \url{https://docs.getodk.org/central-api-entity-management/#listing-versions} +# nolint end +#' @family entity-management +#' @export +#' @examples +#' \dontrun{ +#' # See vignette("setup") for setup and authentication options +#' # ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...") +#' +#' el <- entitylist_list() +#' +#' # Entity List name (dataset ID, did) +#' did <- el$name[1] +#' +#' # All Entities of Entity List +#' en <- entity_list(did = did) +#' +#' ed <- entity_detail(did = did, eid = en$uuid[1]) +#' +#' # The current version of the first Entity +#' ev <- en$current_version_version[1] +#' } +entity_versions <- function(pid = get_default_pid(), + did = "", + eid = "", + conflict = FALSE, + url = get_default_url(), + un = get_default_un(), + pw = get_default_pw(), + retries = get_retries(), + odkc_version = get_default_odkc_version(), + orders = get_default_orders(), + tz = get_default_tz()) { + yell_if_missing(url, + un, + pw, + pid = pid, + did = did, + eid = eid + ) + + if (odkc_version |> semver_lt("2022.3")) { + ru_msg_warn("entity_detail is supported from v2022.3") + } + + pth <- glue::glue( + "v1/projects/{pid}/datasets/{URLencode(did, reserved = TRUE)}/", + "entities/{eid}/versions" + ) + + qry <- list(relevantToConflict = ifelse(conflict == TRUE, "True", "False")) + + httr::RETRY( + "GET", + httr::modify_url(url, path = pth), + httr::add_headers( + "Accept" = "application/json", + "X-Extended-Metadata" = "true" + ), + httr::authenticate(un, pw), + query = qry, + times = retries + ) |> + yell_if_error(url, un, pw) |> + httr::content(encoding = "utf-8") |> + purrr::list_transpose() |> + tibble::as_tibble(.name_repair = "universal") |> + janitor::clean_names() +} + +# usethis::use_test("entity_update") # nolint diff --git a/R/entitylist_detail.R b/R/entitylist_detail.R index 1aaa213d..89561e21 100644 --- a/R/entitylist_detail.R +++ b/R/entitylist_detail.R @@ -54,14 +54,7 @@ entitylist_detail <- function(pid = get_default_pid(), pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid, did = did) diff --git a/R/entitylist_download.R b/R/entitylist_download.R index eac13758..3342d77a 100644 --- a/R/entitylist_download.R +++ b/R/entitylist_download.R @@ -122,14 +122,7 @@ entitylist_download <- function(pid = get_default_pid(), overwrite = TRUE, retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz(), verbose = get_ru_verbose()) { # Gatecheck params diff --git a/R/entitylist_list.R b/R/entitylist_list.R index a6b05b9c..7a9855db 100644 --- a/R/entitylist_list.R +++ b/R/entitylist_list.R @@ -39,14 +39,7 @@ entitylist_list <- function(pid = get_default_pid(), pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid) diff --git a/R/entitylist_update.R b/R/entitylist_update.R index 52a8ab3b..69441032 100644 --- a/R/entitylist_update.R +++ b/R/entitylist_update.R @@ -65,14 +65,7 @@ entitylist_update <- function(pid = get_default_pid(), pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid, did = did) diff --git a/R/form_list.R b/R/form_list.R index d5c96833..b0a8ab5f 100644 --- a/R/form_list.R +++ b/R/form_list.R @@ -45,14 +45,7 @@ form_list <- function(pid = get_default_pid(), un = get_default_un(), pw = get_default_pw(), retries = get_retries(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid) httr::RETRY( diff --git a/R/handle_ru_datetimes.R b/R/handle_ru_datetimes.R index 83a6faa7..220b441d 100644 --- a/R/handle_ru_datetimes.R +++ b/R/handle_ru_datetimes.R @@ -33,14 +33,7 @@ #' } handle_ru_datetimes <- function(data, form_schema, - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz(), verbose = get_ru_verbose()) { # Find all date/time columns in form_schema diff --git a/R/odata_submission_get.R b/R/odata_submission_get.R index f1373de9..7efa87e8 100644 --- a/R/odata_submission_get.R +++ b/R/odata_submission_get.R @@ -173,14 +173,7 @@ odata_submission_get <- function(table = "Submissions", filter = NULL, parse = TRUE, download = TRUE, - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), local_dir = "media", pid = get_default_pid(), fid = get_default_fid(), diff --git a/R/project_list.R b/R/project_list.R index f44b1d6b..4f3e32e9 100644 --- a/R/project_list.R +++ b/R/project_list.R @@ -40,14 +40,7 @@ project_list <- function(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" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw) httr::RETRY( diff --git a/R/ru_setup.R b/R/ru_setup.R index d6042579..1d126283 100644 --- a/R/ru_setup.R +++ b/R/ru_setup.R @@ -396,6 +396,20 @@ get_default_tz <- function() { x } +#' `r lifecycle::badge("stable")` +#' @export +#' @rdname ru_settings +get_default_orders <- function() { + c( + "YmdHMS", + "YmdHMSz", + "Ymd HMS", + "Ymd HMSz", + "Ymd", + "ymd" + ) +} + #' `r lifecycle::badge("stable")` #' @export #' @rdname ru_settings diff --git a/R/submission_list.R b/R/submission_list.R index 232534e3..15a65a11 100644 --- a/R/submission_list.R +++ b/R/submission_list.R @@ -57,14 +57,7 @@ submission_list <- function(pid = get_default_pid(), un = get_default_un(), pw = get_default_pw(), retries = get_retries(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz()) { yell_if_missing(url, un, pw, pid = pid, fid = fid) url <- httr::modify_url( diff --git a/R/user_list.R b/R/user_list.R index 172654f2..08cb4dad 100644 --- a/R/user_list.R +++ b/R/user_list.R @@ -69,14 +69,7 @@ user_list <- function(qry = NULL, un = get_default_un(), pw = get_default_pw(), retries = get_retries(), - orders = c( - "YmdHMS", - "YmdHMSz", - "Ymd HMS", - "Ymd HMSz", - "Ymd", - "ymd" - ), + orders = get_default_orders(), tz = get_default_tz(), verbose = get_ru_verbose()) { yell_if_missing(url, un, pw) diff --git a/man/encryption_key_list.Rd b/man/encryption_key_list.Rd index c046cade..fdf916de 100644 --- a/man/encryption_key_list.Rd +++ b/man/encryption_key_list.Rd @@ -11,7 +11,7 @@ encryption_key_list( un = get_default_un(), pw = get_default_pw(), retries = get_retries(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } diff --git a/man/entity_create.Rd b/man/entity_create.Rd index 895cdf45..8f844db7 100644 --- a/man/entity_create.Rd +++ b/man/entity_create.Rd @@ -16,7 +16,7 @@ entity_create( pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } @@ -220,6 +220,7 @@ Other entity-management: \code{\link{entity_detail}()}, \code{\link{entity_list}()}, \code{\link{entity_update}()}, +\code{\link{entity_versions}()}, \code{\link{entitylist_detail}()}, \code{\link{entitylist_download}()}, \code{\link{entitylist_list}()}, diff --git a/man/entity_delete.Rd b/man/entity_delete.Rd index 0a72e089..b0ac6c5c 100644 --- a/man/entity_delete.Rd +++ b/man/entity_delete.Rd @@ -13,7 +13,7 @@ entity_delete( pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } @@ -121,6 +121,7 @@ Other entity-management: \code{\link{entity_detail}()}, \code{\link{entity_list}()}, \code{\link{entity_update}()}, +\code{\link{entity_versions}()}, \code{\link{entitylist_detail}()}, \code{\link{entitylist_download}()}, \code{\link{entitylist_list}()}, diff --git a/man/entity_detail.Rd b/man/entity_detail.Rd index 32f50edb..54572ad8 100644 --- a/man/entity_detail.Rd +++ b/man/entity_detail.Rd @@ -13,7 +13,7 @@ entity_detail( pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } @@ -149,6 +149,7 @@ Other entity-management: \code{\link{entity_delete}()}, \code{\link{entity_list}()}, \code{\link{entity_update}()}, +\code{\link{entity_versions}()}, \code{\link{entitylist_detail}()}, \code{\link{entitylist_download}()}, \code{\link{entitylist_list}()}, diff --git a/man/entity_list.Rd b/man/entity_list.Rd index 4e12f222..0e0a7ce7 100644 --- a/man/entity_list.Rd +++ b/man/entity_list.Rd @@ -13,7 +13,7 @@ entity_list( pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } @@ -125,6 +125,7 @@ Other entity-management: \code{\link{entity_delete}()}, \code{\link{entity_detail}()}, \code{\link{entity_update}()}, +\code{\link{entity_versions}()}, \code{\link{entitylist_detail}()}, \code{\link{entitylist_download}()}, \code{\link{entitylist_list}()}, diff --git a/man/entity_update.Rd b/man/entity_update.Rd index 9898d769..a969cb32 100644 --- a/man/entity_update.Rd +++ b/man/entity_update.Rd @@ -18,7 +18,7 @@ entity_update( pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } @@ -184,6 +184,7 @@ Other entity-management: \code{\link{entity_delete}()}, \code{\link{entity_detail}()}, \code{\link{entity_list}()}, +\code{\link{entity_versions}()}, \code{\link{entitylist_detail}()}, \code{\link{entitylist_download}()}, \code{\link{entitylist_list}()}, diff --git a/man/entity_versions.Rd b/man/entity_versions.Rd new file mode 100644 index 00000000..a0c435a7 --- /dev/null +++ b/man/entity_versions.Rd @@ -0,0 +1,153 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/entity_versions.R +\name{entity_versions} +\alias{entity_versions} +\title{List versions of one Entity.} +\usage{ +entity_versions( + pid = get_default_pid(), + did = "", + eid = "", + conflict = FALSE, + url = get_default_url(), + un = get_default_un(), + pw = get_default_pw(), + retries = get_retries(), + odkc_version = get_default_odkc_version(), + orders = get_default_orders(), + tz = get_default_tz() +) +} +\arguments{ +\item{pid}{The numeric ID of the project, e.g.: 2. + +Default: \code{\link{get_default_pid}}. + +Set default \code{pid} through \code{ru_setup(pid="...")}. + +See \code{vignette("Setup", package = "ruODK")}.} + +\item{did}{(chr) The name of the Entity List, internally called Dataset. +The function will error if this parameter is not given. +Default: "".} + +\item{eid}{(chr) The UUID of an Entity, which can be retrieved by +\code{entity_list()}. +The function will error if this parameter is not given. +Default: "".} + +\item{conflict}{(lgl) Whether to return all versions (\code{FALSE}) or +whether to returns the subset of past versions of an Entity that are +relevant to the Entity's current conflict (\code{TRUE}). +This includes the latest version, the base version, the previous +server version, and any other versions since the last time the Entity was +in a conflict-free state. If the Entity is not in conflict, zero versions +are returned. +Default: \code{FALSE} (return all versions)} + +\item{url}{The ODK Central base URL without trailing slash. + +Default: \code{\link{get_default_url}}. + +Set default \code{url} through \code{ru_setup(url="...")}. + +See \code{vignette("Setup", package = "ruODK")}.} + +\item{un}{The ODK Central username (an email address). +Default: \code{\link{get_default_un}}. +Set default \code{un} through \code{ru_setup(un="...")}. +See \code{vignette("Setup", package = "ruODK")}.} + +\item{pw}{The ODK Central password. +Default: \code{\link{get_default_pw}}. +Set default \code{pw} through \code{ru_setup(pw="...")}. +See \code{vignette("Setup", package = "ruODK")}.} + +\item{retries}{The number of attempts to retrieve a web resource. + +This parameter is given to \code{\link[httr]{RETRY}(times = retries)}. + +Default: 3.} + +\item{odkc_version}{The ODK Central version as a semantic version string +(year.minor.patch), e.g. "2023.5.1". The version is shown on ODK Central's +version page \verb{/version.txt}. Discard the "v". +\code{ruODK} uses this parameter to adjust for breaking changes in ODK Central. + +Default: \code{\link{get_default_odkc_version}} or "2023.5.1" if unset. + +Set default \code{get_default_odkc_version} through +\code{ru_setup(odkc_version="2023.5.1")}. + +See \code{vignette("Setup", package = "ruODK")}.} + +\item{orders}{(vector of character) Orders of datetime elements for +lubridate. + +Default: +\code{c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd")}.} + +\item{tz}{A timezone to convert dates and times to. + +Read \code{vignette("setup", package = "ruODK")} to learn how \code{ruODK}'s +timezone can be set globally or per function.} +} +\value{ +A tibble with one row per version. List columns contain unstructured +data. +See \url{https://docs.getodk.org/central-api-entity-management/#listing-versions} +for the full schema. +Top level list elements are renamed from ODK's \code{camelCase} to \code{snake_case}. +Nested list elements have the original \code{camelCase}. +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#maturing}{\figure{lifecycle-maturing.svg}{options: alt='[Maturing]'}}}{\strong{[Maturing]}} +} +\details{ +This returns the Entity metadata and data for every version of this Entity +in ascending creation order. + +The ODK Central endpoint supports retrieving extended metadata which this +function always returns. + +There is an optional query flag \code{relevantToConflict} that returns the subset +of past versions of an Entity that are relevant to the Entity's current +conflict. This includes the latest version, the base version, the previous +server version, and any other versions since the last time the Entity was +in a conflict-free state. If the Entity is not in conflict, zero versions +are returned. +} +\examples{ +\dontrun{ +# See vignette("setup") for setup and authentication options +# ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...") + +el <- entitylist_list() + +# Entity List name (dataset ID, did) +did <- el$name[1] + +# All Entities of Entity List +en <- entity_list(did = did) + +ed <- entity_detail(did = did, eid = en$uuid[1]) + +# The current version of the first Entity +ev <- en$current_version_version[1] +} +} +\seealso{ +\url{https://docs.getodk.org/central-api-entity-management/#listing-versions} + +Other entity-management: +\code{\link{entity_create}()}, +\code{\link{entity_delete}()}, +\code{\link{entity_detail}()}, +\code{\link{entity_list}()}, +\code{\link{entity_update}()}, +\code{\link{entitylist_detail}()}, +\code{\link{entitylist_download}()}, +\code{\link{entitylist_list}()}, +\code{\link{entitylist_update}()} +} +\concept{entity-management} diff --git a/man/entitylist_detail.Rd b/man/entitylist_detail.Rd index faa1772b..7b2bc4aa 100644 --- a/man/entitylist_detail.Rd +++ b/man/entitylist_detail.Rd @@ -12,7 +12,7 @@ entitylist_detail( pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } @@ -117,6 +117,7 @@ Other entity-management: \code{\link{entity_detail}()}, \code{\link{entity_list}()}, \code{\link{entity_update}()}, +\code{\link{entity_versions}()}, \code{\link{entitylist_download}()}, \code{\link{entitylist_list}()}, \code{\link{entitylist_update}()} diff --git a/man/entitylist_download.Rd b/man/entitylist_download.Rd index 02d90ebb..c28f3826 100644 --- a/man/entitylist_download.Rd +++ b/man/entitylist_download.Rd @@ -16,7 +16,7 @@ entitylist_download( overwrite = TRUE, retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz(), verbose = get_ru_verbose() ) @@ -201,6 +201,7 @@ Other entity-management: \code{\link{entity_detail}()}, \code{\link{entity_list}()}, \code{\link{entity_update}()}, +\code{\link{entity_versions}()}, \code{\link{entitylist_detail}()}, \code{\link{entitylist_list}()}, \code{\link{entitylist_update}()} diff --git a/man/entitylist_list.Rd b/man/entitylist_list.Rd index 26093865..80c05e33 100644 --- a/man/entitylist_list.Rd +++ b/man/entitylist_list.Rd @@ -11,7 +11,7 @@ entitylist_list( pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } @@ -102,6 +102,7 @@ Other entity-management: \code{\link{entity_detail}()}, \code{\link{entity_list}()}, \code{\link{entity_update}()}, +\code{\link{entity_versions}()}, \code{\link{entitylist_detail}()}, \code{\link{entitylist_download}()}, \code{\link{entitylist_update}()} diff --git a/man/entitylist_update.Rd b/man/entitylist_update.Rd index d2b2e189..d498dfaa 100644 --- a/man/entitylist_update.Rd +++ b/man/entitylist_update.Rd @@ -13,7 +13,7 @@ entitylist_update( pw = get_default_pw(), retries = get_retries(), odkc_version = get_default_odkc_version(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } @@ -132,6 +132,7 @@ Other entity-management: \code{\link{entity_detail}()}, \code{\link{entity_list}()}, \code{\link{entity_update}()}, +\code{\link{entity_versions}()}, \code{\link{entitylist_detail}()}, \code{\link{entitylist_download}()}, \code{\link{entitylist_list}()} diff --git a/man/form_list.Rd b/man/form_list.Rd index 2b116630..69ee1e85 100644 --- a/man/form_list.Rd +++ b/man/form_list.Rd @@ -10,7 +10,7 @@ form_list( un = get_default_un(), pw = get_default_pw(), retries = get_retries(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } diff --git a/man/handle_ru_datetimes.Rd b/man/handle_ru_datetimes.Rd index 89d57965..e57bf3d0 100644 --- a/man/handle_ru_datetimes.Rd +++ b/man/handle_ru_datetimes.Rd @@ -7,7 +7,7 @@ handle_ru_datetimes( data, form_schema, - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz(), verbose = get_ru_verbose() ) diff --git a/man/odata_submission_get.Rd b/man/odata_submission_get.Rd index 5b5d22ea..96db5f6d 100644 --- a/man/odata_submission_get.Rd +++ b/man/odata_submission_get.Rd @@ -15,7 +15,7 @@ odata_submission_get( filter = NULL, parse = TRUE, download = TRUE, - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), local_dir = "media", pid = get_default_pid(), fid = get_default_fid(), diff --git a/man/project_list.Rd b/man/project_list.Rd index 4232420c..9d9ee12b 100644 --- a/man/project_list.Rd +++ b/man/project_list.Rd @@ -9,7 +9,7 @@ project_list( un = get_default_un(), pw = get_default_pw(), retries = get_retries(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } diff --git a/man/ru_settings.Rd b/man/ru_settings.Rd index f9f39d17..21b145e5 100644 --- a/man/ru_settings.Rd +++ b/man/ru_settings.Rd @@ -9,6 +9,7 @@ \alias{get_default_pw} \alias{get_default_pp} \alias{get_default_tz} +\alias{get_default_orders} \alias{get_test_url} \alias{get_test_un} \alias{get_test_pw} @@ -41,6 +42,8 @@ get_default_pp() get_default_tz() +get_default_orders() + get_test_url() get_test_un() diff --git a/man/submission_list.Rd b/man/submission_list.Rd index 65c6019a..6b389ab9 100644 --- a/man/submission_list.Rd +++ b/man/submission_list.Rd @@ -11,7 +11,7 @@ submission_list( un = get_default_un(), pw = get_default_pw(), retries = get_retries(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz() ) } diff --git a/man/user_list.Rd b/man/user_list.Rd index 0b33a0fc..5ad4186e 100644 --- a/man/user_list.Rd +++ b/man/user_list.Rd @@ -10,7 +10,7 @@ user_list( un = get_default_un(), pw = get_default_pw(), retries = get_retries(), - orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), + orders = get_default_orders(), tz = get_default_tz(), verbose = get_ru_verbose() ) diff --git a/tests/testthat/test-entity_update.R b/tests/testthat/test-entity_update.R index 0d42e0c2..7e61ebf4 100644 --- a/tests/testthat/test-entity_update.R +++ b/tests/testthat/test-entity_update.R @@ -41,6 +41,41 @@ test_that("entity_update works", { ed$current_version$version, eu$current_version$baseVersion ) + + # Test entity_versions without conflicts flag + ev <- entity_versions(did = did, eid = en$uuid[1]) + + ev_names <- c( + "conflict", + "resolved", + "base_diff", + "server_diff", + "last_good_version", + "current", + "label", + "creator_id", + "user_agent", + "data", + "version", + "base_version", + "data_received", + "conflicting_properties", + "created_at", + "creator", + "source", + "relevant_to_conflict" + ) + + testthat::expect_equal(names(ev), ev_names) + + # With conflicts flag + # Prove that the entity has no conflicts + ed <- entity_detail(did = did, eid = en$uuid[1]) + testthat::expect_equal(ed$current_version$conflictingProperties, NULL) + + # Expect no records for entity without conflicts + ev_conflict <- entity_versions(did = did, eid = en$uuid[1], conflict = TRUE) + testthat::expect_equal(nrow(ev_conflict), 0) }) test_that("entitylist_update warns if odkc_version too low", {