From c8c0d3448d109b55dcf720eefb9fc5bdd5d1bebc Mon Sep 17 00:00:00 2001 From: Florian Mayer Date: Mon, 1 Apr 2024 08:34:20 +0800 Subject: [PATCH] Improve entity_list: add parameter `deleted` --- DESCRIPTION | 11 +++-- R/entity_list.R | 70 +++++++++++++++-------------- R/isodt_to_local.R | 5 +-- man/entity_list.Rd | 15 +++---- man/ruODK-package.Rd | 2 +- tests/testthat/test-entity_detail.R | 4 +- tests/testthat/test-entity_list.R | 4 +- 7 files changed, 58 insertions(+), 53 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 3e811971..1bc721f1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,12 +1,12 @@ Type: Package Package: ruODK Title: An R Client for the ODK Central API -Version: 1.4.9.9004 +Version: 1.4.9.9005 Authors@R: c(person(given = c("Florian", "W."), family = "Mayer", role = c("aut", "cre"), - email = "Florian.Mayer@dbca.wa.gov.au", + email = "Florian.Mayer@dpc.wa.gov.au", comment = c(ORCID = "0000-0003-4269-4242")), person(given = "Maëlle", family = "Salmon", @@ -33,9 +33,12 @@ Authors@R: person(given = "NWSFTCP", role = "fnd")) Description: Access and tidy up data from the 'ODK Central' API. - 'ODK Central' is a clearinghouse for digitally captured data + 'ODK Central' is a clearinghouse for digitally captured data using ODK . - 'ODK Central' and its API are documented at . + It manages user accounts and permissions, stores form definitions, and + allows data collection clients like 'ODK Collect' to connect to it for form + download and submission upload. The 'ODK Central' API is documented at + . License: GPL-3 URL: https://docs.ropensci.org/ruODK, https://github.com/ropensci/ruODK diff --git a/R/entity_list.R b/R/entity_list.R index b3ae774a..948d9395 100644 --- a/R/entity_list.R +++ b/R/entity_list.R @@ -5,18 +5,17 @@ #' This function returns a list of the Entities of a kind (belonging to an #' Entity List or Dataset). #' Please note that this endpoint only returns metadata of the entities, not the -#' data. If you want to get the data of all entities then please refer to OData -#' Dataset Service +#' data. If you want to get the data of all entities then please refer to the +#' OData Dataset Service. #' -#' You can provide ?deleted=true to get only deleted entities. -#' -#' `entity_list()` will fail with incorrect or missing authentication. -#' -#' This function is supported from ODK Central v2022.3 and will warn if the -#' given odkc_version is lower. +#' You can get only deleted entities with `deleted=TRUE`. #' +#' @template tpl-auth-missing +#' @template tpl-compat-2022-3 #' @template param-pid #' @template param-did +#' @param deleted (bool) Whether to get only deleted entities (`TRUE`) or not +#' (`FALSE`). Default: `FALSE`. #' @template param-url #' @template param-auth #' @template param-retries @@ -36,36 +35,37 @@ #' # See vignette("setup") for setup and authentication options #' # ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...") #' -#' el <- entitylist_list() +#' el <- entitylist_list() #' -#' # Entity List name (dataset ID) -#' did <- el$name[1] +#' # Entity List name (dataset ID) +#' did <- el$name[1] #' -#' # All Entities of Entity List -#' en <- entity_list(did = el$name[1]) +#' # All Entities of Entity List +#' en <- entity_list(did = el$name[1]) #' -#' # The UUID of the first Entity -#' eid <- en$uuid[1] +#' # The UUID of the first Entity +#' eid <- en$uuid[1] #' -#' # The current version of the first Entity -#' ev <- en$current_version_version[1] +#' # The current version of the first Entity +#' ev <- en$current_version_version[1] #' } entity_list <- function(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()) { + did = NULL, + deleted = 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()) { yell_if_missing(url, un, pw, pid = pid) if (is.null(did)) { @@ -80,6 +80,10 @@ entity_list <- function(pid = get_default_pid(), "v1/projects/{pid}/datasets/{URLencode(did, reserved = TRUE)}/entities" ) + if (deleted == TRUE) { + pth <- glue::glue("{pth}?deleted=true") + } + httr::RETRY( "GET", httr::modify_url(url, path = pth), @@ -101,4 +105,4 @@ entity_list <- function(pid = get_default_pid(), ) } -# usethis::use_test("entity_list") # nolint \ No newline at end of file +# usethis::use_test("entity_list") # nolint diff --git a/R/isodt_to_local.R b/R/isodt_to_local.R index 8960c1b2..c6084c32 100644 --- a/R/isodt_to_local.R +++ b/R/isodt_to_local.R @@ -22,9 +22,8 @@ isodt_to_local <- function(datetime_string, orders = c("YmdHMS", "YmdHMSz"), tz = get_default_tz(), - quiet=TRUE - ) { + quiet = TRUE) { datetime_string %>% - lubridate::parse_date_time(orders = orders, quiet=quiet) %>% + lubridate::parse_date_time(orders = orders, quiet = quiet) %>% lubridate::with_tz(., tzone = tz) } diff --git a/man/entity_list.Rd b/man/entity_list.Rd index b9c7c482..848e3f68 100644 --- a/man/entity_list.Rd +++ b/man/entity_list.Rd @@ -7,6 +7,7 @@ entity_list( pid = get_default_pid(), did = NULL, + deleted = FALSE, url = get_default_url(), un = get_default_un(), pw = get_default_pw(), @@ -27,6 +28,9 @@ See \code{vignette("Setup", package = "ruODK")}.} \item{did}{(chr) The name of the Entity List, internally called Dataset.} +\item{deleted}{(bool) Whether to get only deleted entities (\code{TRUE}) or not +(\code{FALSE}). Default: \code{FALSE}.} + \item{url}{The ODK Central base URL without trailing slash. Default: \code{\link{get_default_url}}. @@ -86,15 +90,10 @@ Column names are renamed from ODK's \code{camelCase} to \code{snake_case}. This function returns a list of the Entities of a kind (belonging to an Entity List or Dataset). Please note that this endpoint only returns metadata of the entities, not the -data. If you want to get the data of all entities then please refer to OData -Dataset Service - -You can provide ?deleted=true to get only deleted entities. - -\code{entity_list()} will fail with incorrect or missing authentication. +data. If you want to get the data of all entities then please refer to the +OData Dataset Service. -This function is supported from ODK Central v2022.3 and will warn if the -given odkc_version is lower. +You can get only deleted entities with \code{deleted=TRUE}. } \examples{ \dontrun{ diff --git a/man/ruODK-package.Rd b/man/ruODK-package.Rd index 9027a3f5..e14ebdd8 100644 --- a/man/ruODK-package.Rd +++ b/man/ruODK-package.Rd @@ -24,7 +24,7 @@ Useful links: } \author{ -\strong{Maintainer}: Florian W. Mayer \email{Florian.Mayer@dbca.wa.gov.au} (\href{https://orcid.org/0000-0003-4269-4242}{ORCID}) +\strong{Maintainer}: Florian W. Mayer \email{Florian.Mayer@dpc.wa.gov.au} (\href{https://orcid.org/0000-0003-4269-4242}{ORCID}) Other contributors: \itemize{ diff --git a/tests/testthat/test-entity_detail.R b/tests/testthat/test-entity_detail.R index ba8bfb32..b7bddcf0 100644 --- a/tests/testthat/test-entity_detail.R +++ b/tests/testthat/test-entity_detail.R @@ -55,7 +55,7 @@ test_that("entitylist_detail errors if did is missing", { test_that("entitylist_detail warns if odkc_version too low", { skip_if(Sys.getenv("ODKC_TEST_URL") == "", - message = "Test server not configured" + message = "Test server not configured" ) ru_setup( @@ -77,4 +77,4 @@ test_that("entitylist_detail warns if odkc_version too low", { }) -# usethis::use_e("entity_detail") # nolint \ No newline at end of file +# usethis::use_e("entity_detail") # nolint diff --git a/tests/testthat/test-entity_list.R b/tests/testthat/test-entity_list.R index 522eff18..3024d2a5 100644 --- a/tests/testthat/test-entity_list.R +++ b/tests/testthat/test-entity_list.R @@ -1,6 +1,6 @@ test_that("entity_list works", { skip_if(Sys.getenv("ODKC_TEST_URL") == "", - message = "Test server not configured" + message = "Test server not configured" ) ru_setup( @@ -18,7 +18,7 @@ test_that("entity_list works", { testthat::expect_s3_class(en, "tbl_df") - cn <- c( + cn <- c( "uuid", "created_at", "creator_id",