Support entity lists (datasets) and entities

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: ruODK
 Title: An R Client for the ODK Central API
-Version: 1.4.2
+Version: 1.5.0.9000
 Authors@R: 
     c(person(given = c("Florian", "W."),
              family = "Mayer",

NAMESPACE

@@ -6,6 +6,9 @@ export(attachment_get)
 export(attachment_link)
 export(attachment_list)
 export(audit_get)
+export(dataset_detail)
+export(dataset_list)
+export(dataset_update)
 export(drop_null_coords)
 export(encryption_key_list)
 export(enexpr)

R/dataset_detail.R

@@ -0,0 +1,84 @@
+#' Show dataset details.
+#'
+#' A Dataset is a named collection of Entities that have the same properties.
+#' A Dataset 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.
+#'
+#' `r lifecycle::badge("maturing")`
+#'
+#' @template param-pid
+#' @param did (chr) The dataset name.
+#' @template param-url
+#' @template param-auth
+#' @template param-retries
+#' @template param-odkcv
+#' @template param-orders
+#' @template param-tz
+#' @return 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.
+# nolint start
+#' @seealso \url{ https://docs.getodk.org/central-api-dataset-management/#datasets}
+# nolint end
+#' @family dataset-management
+#' @export
+#' @examples
+#' \dontrun{
+#' # See vignette("setup") for setup and authentication options
+#' # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")
+#'
+#' ds <- dataset_list(pid = get_default_pid())
+#' ds1 <- dataset_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()
+#' }
+dataset_detail <- 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()) {
+  yell_if_missing(url, un, pw, pid = pid)
+
+  if (is.null(did))
+    ru_msg_abort("dataset_detail requires the dataset names as 'did=\"name\"'.")
+
+  if (odkc_version |> semver_lt("2022.3")) {
+    ru_msg_warn("dataset_detail is supported from v2022.3")
+  }
+
+  ds <- httr::RETRY(
+    "GET",
+    httr::modify_url(url,
+                     path = glue::glue(
+                       "v1/projects/{pid}/datasets/",
+                       "{URLencode(did, reserved = TRUE)}"
+                       )),
+    httr::add_headers(
+      "Accept" = "application/json",
+      "X-Extended-Metadata" = "true"
+    ),
+    httr::authenticate(un, pw),
+    times = retries
+  ) |>
+    yell_if_error(url, un, pw) |>
+    httr::content(encoding="utf-8")
+}
+
+# usethis::use_test("dataset_detail") # nolint

R/dataset_list.R

@@ -0,0 +1,82 @@
+#' List all datasets of one project.
+#'
+#' While the API endpoint will return all datasets for one project,
+#' \code{\link{dataset_list}} will fail with incorrect or missing
+#' authentication.
+#'
+#' A Dataset is a named collection of Entities that have the same properties.
+#' A Dataset 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.
+#'
+#' `r lifecycle::badge("maturing")`
+#'
+#' @template param-pid
+#' @template param-url
+#' @template param-auth
+#' @template param-retries
+#' @template param-odkcv
+#' @template param-orders
+#' @template param-tz
+#' @return 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`.
+# nolint start
+#' @seealso \url{ https://docs.getodk.org/central-api-dataset-management/#datasets}
+# nolint end
+#' @family dataset-management
+#' @export
+#' @examples
+#' \dontrun{
+#' # See vignette("setup") for setup and authentication options
+#' # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")
+#'
+#' ds <- dataset_list(pid = get_default_pid())
+#'
+#' ds |> knitr::kable()
+#' }
+dataset_list <- function(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()) {
+  yell_if_missing(url, un, pw, pid = pid)
+
+  if (odkc_version |> semver_lt("2022.3")) {
+    ru_msg_warn("dataset_list is supported from v2022.3")
+  }
+
+  httr::RETRY(
+    "GET",
+    httr::modify_url(url, path = glue::glue("v1/projects/{pid}/datasets")),
+    httr::add_headers(
+      "Accept" = "application/json",
+      "X-Extended-Metadata" = "true"
+    ),
+    httr::authenticate(un, pw),
+    times = retries
+  ) |>
+    yell_if_error(url, un, pw) |>
+    httr::content(encoding="utf-8") |>
+    purrr::list_transpose() |>
+    tibble::as_tibble() |>
+    janitor::clean_names() |>
+    dplyr::mutate_at(
+      dplyr::vars(c("created_at", "last_entity")),
+      ~ isodt_to_local(., orders = orders, tz = tz)
+    )
+}
+
+# usethis::use_test("dataset_list") # nolint

R/dataset_update.R

@@ -0,0 +1,108 @@
+#' Update dataset 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 Datasets created after
+#' v2023.3. Datasets created prior to that will have approvalRequired set to
+#' true.
+#'
+#' A Dataset is a named collection of Entities that have the same properties.
+#' A Dataset 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.
+#'
+#' `r lifecycle::badge("maturing")`
+#'
+#' @template param-pid
+#' @param did (chr) The dataset name.
+#' @param approval_required (lgl) The value to set approvalRequired to.
+#'   If TRUE, a submission must be approved before an entity is created,
+#'   if FALSE, an entity is created as soon as the submission is received by
+#'   ODK Central.
+#'   Default: FALSE.
+#' @template param-url
+#' @template param-auth
+#' @template param-retries
+#' @template param-odkcv
+#' @template param-orders
+#' @template param-tz
+#' @return A list of lists following the exact format and naming of the API
+#'   response for `dataset_detail`.
+#'   Since this nested list is so deeply nested and irregularly shaped
+#'   it is not trivial to rectangle the result into a tibble.
+# nolint start
+#' @seealso \url{ https://docs.getodk.org/central-api-dataset-management/#datasets}
+# nolint end
+#' @family dataset-management
+#' @export
+#' @examples
+#' \dontrun{
+#' # See vignette("setup") for setup and authentication options
+#' # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")
+#'
+#' pid = get_default_pid()
+#'
+#' ds <- dataset_list(pid = pid)
+#'
+#' did =  ds$name[1]
+#'
+#' ds1 <- dataset_detail(pid = pid, did = did)
+#' ds1$approvalRequired  # FALSE
+#'
+#' ds2 <- dataset_update(pid = pid, did = did, approval_required=TRUE)
+#' ds2$approvalRequired # TRUE
+#'
+#' ds3 <- dataset_update(pid = pid, did = did, approval_required=FALSE)
+#' ds3$approvalRequired # FALSE
+#' }
+dataset_update <- function(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()) {
+  yell_if_missing(url, un, pw, pid = pid)
+
+  if (is.null(did))
+    ru_msg_abort("dataset_update requires the dataset names as 'did=\"name\"'.")
+
+  if (odkc_version |> semver_lt("2022.3")) {
+    ru_msg_warn("dataset_update is supported from v2022.3")
+  }
+
+  ds <- httr::RETRY(
+    "PATCH",
+    httr::modify_url(url,
+                     path = glue::glue(
+                       "v1/projects/{pid}/datasets/",
+                       "{URLencode(did, reserved = TRUE)}"
+                     )),
+    httr::add_headers(
+      "Accept" = "application/json"
+    ),
+    encode = "json",
+    body = list(approvalRequired = approval_required),
+    httr::authenticate(un, pw),
+    times = retries
+  ) |>
+    yell_if_error(url, un, pw) |>
+    httr::content(encoding="utf-8")
+}
+
+# usethis::use_test("dataset_update") # nolint

_pkgdown.yml

@@ -23,6 +23,14 @@ reference:
   desc: "Functions to manage projects."
   contents:
   - has_concept("project-management")
+- title: Datasets
+  desc: "Functions to manage datasets of entities."
+  contents:
+  - has_concept("dataset-management")
+- title: Entities
+  desc: "Functions to manage entities."
+  contents:
+  - has_concept("entity-management")
 - title: Forms
   desc: >
     Functions to manage forms.