diff --git a/DESCRIPTION b/DESCRIPTION index 1bc721f1..59588c76 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Type: Package Package: ruODK Title: An R Client for the ODK Central API -Version: 1.4.9.9005 +Version: 1.4.9.9006 Authors@R: c(person(given = c("Florian", "W."), family = "Mayer", diff --git a/R/entity_detail.R b/R/entity_detail.R index def4eb3c..bdd5d37e 100644 --- a/R/entity_detail.R +++ b/R/entity_detail.R @@ -1,4 +1,4 @@ -#' Show details of one Entity. +#' Show metadata and current data of one Entity. #' #' `r lifecycle::badge("maturing")` #' @@ -86,15 +86,7 @@ entity_detail <- function(pid = get_default_pid(), "ymd" ), tz = get_default_tz()) { - yell_if_missing(url, un, pw, pid = pid) - - if (is.null(did)) { - ru_msg_abort("entity_detail requires the Entity List name as 'did=\"name\"'.") - } - - if (is.null(eid)) { - ru_msg_abort("entity_detail requires the Entity UUID as 'eid=\"uuid\"'.") - } + 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") @@ -114,7 +106,6 @@ entity_detail <- function(pid = get_default_pid(), yell_if_error(url, un, pw) |> httr::content(encoding = "utf-8") |> # purrr::list_transpose() |> - # # tibble::enframe() |> # tibble::as_tibble(.name_repair = "universal") |> # tidyr::pivot_wider(names_from = "name", values_from = "value") |> diff --git a/R/entity_list.R b/R/entity_list.R index 948d9395..aa624144 100644 --- a/R/entity_list.R +++ b/R/entity_list.R @@ -14,7 +14,7 @@ #' @template tpl-compat-2022-3 #' @template param-pid #' @template param-did -#' @param deleted (bool) Whether to get only deleted entities (`TRUE`) or not +#' @param deleted (lgl) Whether to get only deleted entities (`TRUE`) or not #' (`FALSE`). Default: `FALSE`. #' @template param-url #' @template param-auth @@ -66,11 +66,7 @@ entity_list <- function(pid = get_default_pid(), "ymd" ), tz = get_default_tz()) { - yell_if_missing(url, un, pw, pid = pid) - - if (is.null(did)) { - ru_msg_abort("entity_list requires the Entity List name as 'did=\"name\"'.") - } + yell_if_missing(url, un, pw, pid = pid, did = did) if (odkc_version |> semver_lt("2022.3")) { ru_msg_warn("entity_list is supported from v2022.3") diff --git a/R/entitylist_detail.R b/R/entitylist_detail.R index dcf39001..f9dc1069 100644 --- a/R/entitylist_detail.R +++ b/R/entitylist_detail.R @@ -2,14 +2,12 @@ #' #' `r lifecycle::badge("maturing")` #' -#' 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. -#' +#' @template tpl-structure-nested +#' @template tpl-names-cleaned-top-level +#' @template tpl-def-entitylist +#' @template tpl-entitylist-dataset +#' @template tpl-auth-missing +#' @template tpl-compat-2022-3 #' @template param-pid #' @template param-did #' @template param-url @@ -32,15 +30,19 @@ #' # ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...") #' #' ds <- entitylist_list(pid = get_default_pid()) +#' #' ds1 <- entitylist_detail(pid = get_default_pid(), did = ds$name[1]) #' #' ds1 |> listviewer::jsonedit() -#' ds1$linkedForms |> +#' +#' ds1$linked_forms |> #' purrr::list_transpose() |> #' tibble::as_tibble() -#' ds1$sourceForms |> +#' +#' ds1$source_forms |> #' purrr::list_transpose() |> #' tibble::as_tibble() +#' #' ds1$properties |> #' purrr::list_transpose() |> #' tibble::as_tibble() @@ -61,11 +63,7 @@ entitylist_detail <- function(pid = get_default_pid(), "ymd" ), tz = get_default_tz()) { - yell_if_missing(url, un, pw, pid = pid) - - if (is.null(did)) { - ru_msg_abort("entitylist_detail requires the Entity List name as 'did=\"name\"'.") - } + yell_if_missing(url, un, pw, pid = pid, did = did) if (odkc_version |> semver_lt("2022.3")) { ru_msg_warn("entitylist_detail is supported from v2022.3") @@ -86,7 +84,8 @@ entitylist_detail <- function(pid = get_default_pid(), times = retries ) |> yell_if_error(url, un, pw) |> - httr::content(encoding = "utf-8") + httr::content(encoding = "utf-8") |> + janitor::clean_names() } # usethis::use_test("entitylist_detail") # nolint diff --git a/R/entitylist_download.R b/R/entitylist_download.R index f1b4da61..150fb009 100644 --- a/R/entitylist_download.R +++ b/R/entitylist_download.R @@ -2,33 +2,33 @@ #' #' `r lifecycle::badge("maturing")` #' +#' ## CSV file #' 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. +#' `__createdAt`, `__creatorName`, etc., the Entity Label, and the +#' Dataset (Entity List) or 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 +#' ## Filter +#' The ODK Central `$filter` query string 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](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948) +#' Of the [OData filter specs +#' ](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948) #' ODK Central implements a [growing set of features #' ](https://docs.getodk.org/central-api-odata-endpoints/#data-document). #' `ruODK` provides the parameter `filter` (str) which, if set, will be passed #' on to the ODK Central endpoint as is. #' +#' ## Resuming downloads through ETag #' The ODK Central endpoint supports the [`ETag` header #' ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag), which can #' be used to avoid downloading the same content more than once. @@ -44,6 +44,10 @@ #' a previous call to `entitylist_download()`. `ruODK` strips the `W/\"` and #' `\"` from the returned etag and expects the stripped etag as parameter. #' +#' @template tpl-def-entitylist +#' @template tpl-entitylist-dataset +#' @template tpl-auth-missing +#' @template tpl-compat-2022-3 #' @template param-pid #' @template param-did #' @template param-url @@ -56,11 +60,11 @@ #' which is the format of the etag returned by `entitylist_download()`. #' If provided, only new entities will be returned. #' If the same `local_dir` is chosen and `overwrite` is set to `TRUE`, -#' the downloaded CSV will also be overwritte, losing the Entities downloaded -#' earlier. -#' Default: NULL (no filtering, all entities returned). +#' the downloaded CSV will also be overwritten, losing the previously +#' downloaded Entities. +#' Default: NULL (no filtering, all Entities returned). #' @param filter (str) A valid filter string. -#' Default: NULL (no filtering, all entities returned). +#' Default: NULL (no filtering, all Entities returned). #' @param overwrite Whether to overwrite previously downloaded file, #' default: FALSE #' @template param-retries @@ -74,7 +78,7 @@ #' 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 +#' - downloaded_on (POSIXct) The time of download in the local timezone # nolint start #' @seealso \url{https://docs.getodk.org/central-api-dataset-management/#datasets} # nolint end @@ -86,6 +90,7 @@ #' # ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...") #' #' ds <- entitylist_list(pid = get_default_pid()) +#' #' ds1 <- entitylist_download(pid = get_default_pid(), did = ds$name[1]) #' # ds1$entities #' # ds1$etag @@ -128,13 +133,7 @@ entitylist_download <- function(pid = get_default_pid(), tz = get_default_tz(), verbose = get_ru_verbose()) { # Gatecheck params - yell_if_missing(url, un, pw, pid = pid) - - if (is.null(did)) { - ru_msg_abort( - "entitylist_download requires the Entity List name as 'did=\"name\"'." - ) - } + yell_if_missing(url, un, pw, pid = pid, did = did) # Gatecheck ODKC version if (odkc_version |> semver_lt("2022.3")) { diff --git a/R/entitylist_list.R b/R/entitylist_list.R index cd9d1dad..a6b05b9c 100644 --- a/R/entitylist_list.R +++ b/R/entitylist_list.R @@ -2,21 +2,13 @@ #' #' `r lifecycle::badge("maturing")` #' -#' While the API endpoint will return all Entity Lists for one Project, -#' \code{\link{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. +#' The returned list is useful to retrieve the valid name of an Entity List for +#' further use by functions of the Entity Management family. #' +#' @template tpl-def-entitylist +#' @template tpl-entitylist-dataset +#' @template tpl-auth-missing +#' @template tpl-compat-2022-3 #' @template param-pid #' @template param-url #' @template param-auth diff --git a/R/entitylist_update.R b/R/entitylist_update.R index 128d48c6..04db8d12 100644 --- a/R/entitylist_update.R +++ b/R/entitylist_update.R @@ -3,31 +3,25 @@ #' `r lifecycle::badge("maturing")` #' #' You can only update `approvalRequired` using this endpoint. -#' The approvalRequired flag controls the Entity creation flow; +#' 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. -#' -#' `r lifecycle::badge("maturing")` +#' v2023.3. Entity Lists created prior to that will have `approvalRequired` set +#' to true. #' +#' @template tpl-def-entitylist +#' @template tpl-entitylist-dataset +#' @template tpl-auth-missing +#' @template tpl-compat-2022-3 #' @template param-pid #' @template param-did -#' @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 +#' @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. +#' Default: `FALSE`. #' @template param-url #' @template param-auth #' @template param-retries @@ -80,11 +74,7 @@ entitylist_update <- function(pid = get_default_pid(), "ymd" ), tz = get_default_tz()) { - yell_if_missing(url, un, pw, pid = pid) - - if (is.null(did)) { - ru_msg_abort("entitylist_update requires the Entity List name as 'did=\"name\"'.") - } + yell_if_missing(url, un, pw, pid = pid, did = did) if (odkc_version |> semver_lt("2022.3")) { ru_msg_warn("entitylist_update is supported from v2022.3") diff --git a/R/isodt_to_local.R b/R/isodt_to_local.R index c6084c32..e85e313a 100644 --- a/R/isodt_to_local.R +++ b/R/isodt_to_local.R @@ -13,7 +13,7 @@ #' `lubridate`. #' Default: \code{c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz")}. #' @template param-tz -#' @param quiet (bool) Used in `lubridate::parse_date_time(quiet=quiet)` to +#' @param quiet (lgl) Used in `lubridate::parse_date_time(quiet=quiet)` to #' suppress warnings from attempting to parse all empty values or columns. #' Run with `quiet=FALSE` to show any `lubridate` warnings. #' @return A `lubridate` PosixCT datetime in the given timezone. diff --git a/R/ru_setup.R b/R/ru_setup.R index e2469b90..cb49c4b2 100644 --- a/R/ru_setup.R +++ b/R/ru_setup.R @@ -710,7 +710,9 @@ get_retries <- function() { #' testthat::expect_error(yell_if_missing("", "", "", "")) #' testthat::expect_error(yell_if_missing("", "", "", "", "")) #' testthat::expect_error(yell_if_missing("", "", "", "", "", "")) -yell_if_missing <- function(url, un, pw, pid = NULL, fid = NULL, iid = NULL) { +#' testthat::expect_error(yell_if_missing("", "", "", "", "", "", "")) +#' testthat::expect_error(yell_if_missing("", "", "", "", "", "", "", "")) +yell_if_missing <- function(url, un, pw, pid = NULL, fid = NULL, iid = NULL, did = NULL, eid = NULL) { if (is.null(url) || identical(url, "")) { ru_msg_abort("Missing ODK Central URL. ru_setup()?") } @@ -729,6 +731,12 @@ yell_if_missing <- function(url, un, pw, pid = NULL, fid = NULL, iid = NULL) { if (!is.null(iid) && identical(iid, "")) { ru_msg_abort("Missing ODK Central submission instance ID.") } + if (!is.null(did) && identical(did, "")) { + ru_msg_abort("Missing ODK Central Entity List (dataset) name.") + } + if (!is.null(eid) && identical(eid, "")) { + ru_msg_abort("Missing ODK Central Entity UUID.") + } } #' Warn about failed web requests and give helpful troubleshooting tips. diff --git a/man-roxygen/tpl-def-entitylist.R b/man-roxygen/tpl-def-entitylist.R new file mode 100644 index 00000000..511813d8 --- /dev/null +++ b/man-roxygen/tpl-def-entitylist.R @@ -0,0 +1,4 @@ +#' 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. +#' diff --git a/man-roxygen/tpl-entitylist-dataset.R b/man-roxygen/tpl-entitylist-dataset.R new file mode 100644 index 00000000..fff8f483 --- /dev/null +++ b/man-roxygen/tpl-entitylist-dataset.R @@ -0,0 +1,5 @@ +#' ## Entity Lists are Datasets +#' 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. +#' diff --git a/man/entity_detail.Rd b/man/entity_detail.Rd index 6d5f5548..f38f3794 100644 --- a/man/entity_detail.Rd +++ b/man/entity_detail.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/entity_detail.R \name{entity_detail} \alias{entity_detail} -\title{Show details of one Entity.} +\title{Show metadata and current data of one Entity.} \usage{ entity_detail( pid = get_default_pid(), diff --git a/man/entity_list.Rd b/man/entity_list.Rd index 848e3f68..4a3f2ba7 100644 --- a/man/entity_list.Rd +++ b/man/entity_list.Rd @@ -28,7 +28,7 @@ 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 +\item{deleted}{(lgl) 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. @@ -100,19 +100,19 @@ You can get only deleted entities with \code{deleted=TRUE}. # 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] } } \seealso{ diff --git a/man/entitylist_detail.Rd b/man/entitylist_detail.Rd index 6d8f9bfe..b25eafbc 100644 --- a/man/entitylist_detail.Rd +++ b/man/entitylist_detail.Rd @@ -82,30 +82,25 @@ it is not trivial to rectangle the result into a tibble. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#maturing}{\figure{lifecycle-maturing.svg}{options: alt='[Maturing]'}}}{\strong{[Maturing]}} } -\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. -} \examples{ \dontrun{ # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...") ds <- entitylist_list(pid = get_default_pid()) + ds1 <- entitylist_detail(pid = get_default_pid(), did = ds$name[1]) ds1 |> listviewer::jsonedit() -ds1$linkedForms |> + +ds1$linked_forms |> purrr::list_transpose() |> tibble::as_tibble() -ds1$sourceForms |> + +ds1$source_forms |> purrr::list_transpose() |> tibble::as_tibble() + ds1$properties |> purrr::list_transpose() |> tibble::as_tibble() diff --git a/man/entitylist_download.Rd b/man/entitylist_download.Rd index 83ad608a..03531705 100644 --- a/man/entitylist_download.Rd +++ b/man/entitylist_download.Rd @@ -55,16 +55,16 @@ default: \code{here::here}. If the folder does not exist it will be created.} \item{filter}{(str) A valid filter string. -Default: NULL (no filtering, all entities returned).} +Default: NULL (no filtering, all Entities returned).} \item{etag}{(str) The etag value from a previous call to \code{entitylist_download()}. The value must be stripped of the \verb{W/\\"} and \verb{\\"}, which is the format of the etag returned by \code{entitylist_download()}. If provided, only new entities will be returned. If the same \code{local_dir} is chosen and \code{overwrite} is set to \code{TRUE}, -the downloaded CSV will also be overwritte, losing the Entities downloaded -earlier. -Default: NULL (no filtering, all entities returned).} +the downloaded CSV will also be overwritten, losing the previously +downloaded Entities. +Default: NULL (no filtering, all Entities returned).} \item{overwrite}{Whether to overwrite previously downloaded file, default: FALSE} @@ -111,38 +111,42 @@ A list of four items: 200 if OK, 304 if a given etag finds no new entities created. \item etag (str) The ETag to use in subsequent calls to \code{entitylist_download()} \item downloaded_to (fs_path) The path to the downloaded CSV file -\item downloaded_on (POSIXct) The time of download in the local timezome +\item downloaded_on (POSIXct) The time of download in the local timezone } } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#maturing}{\figure{lifecycle-maturing.svg}{options: alt='[Maturing]'}}}{\strong{[Maturing]}} } \details{ +\subsection{CSV file}{ + 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 \verb{__id} (the Entity UUID), -\verb{__createdAt}, \verb{__creatorName}, etc., the Entity Label label, and the -Dataset (Entity List )/Entity Properties themselves. +\verb{__createdAt}, \verb{__creatorName}, etc., the Entity Label, and the +Dataset (Entity List) or 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. +} + +\subsection{Filter}{ -The ODK Central \verb{$filter} querystring parameter can be used to filter on +The ODK Central \verb{$filter} query string parameter can be used to filter on system-level properties, similar to how filtering in the OData Dataset (Entity List) Service works. -Of the \href{https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948}{OData filter specs} +Of the \href{https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948}{OData filter specs } ODK Central implements a \href{https://docs.getodk.org/central-api-odata-endpoints/#data-document}{growing set of features }. \code{ruODK} provides the parameter \code{filter} (str) which, if set, will be passed on to the ODK Central endpoint as is. +} + +\subsection{Resuming downloads through ETag}{ The ODK Central endpoint supports the \href{https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag}{\code{ETag} header }, which can be used to avoid downloading the same content more than once. @@ -157,12 +161,14 @@ data. a previous call to \code{entitylist_download()}. \code{ruODK} strips the \verb{W/\\"} and \verb{\\"} from the returned etag and expects the stripped etag as parameter. } +} \examples{ \dontrun{ # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...") ds <- entitylist_list(pid = get_default_pid()) + ds1 <- entitylist_download(pid = get_default_pid(), did = ds$name[1]) # ds1$entities # ds1$etag diff --git a/man/entitylist_list.Rd b/man/entitylist_list.Rd index b00c2a8f..02ec6134 100644 --- a/man/entitylist_list.Rd +++ b/man/entitylist_list.Rd @@ -80,20 +80,8 @@ Column names are renamed from ODK Central's \code{camelCase} to \code{snake_case \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#maturing}{\figure{lifecycle-maturing.svg}{options: alt='[Maturing]'}}}{\strong{[Maturing]}} } \details{ -While the API endpoint will return all Entity Lists for one Project, -\code{\link{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. \code{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. +The returned list is useful to retrieve the valid name of an Entity List for +further use by functions of the Entity Management family. } \examples{ \dontrun{ diff --git a/man/entitylist_update.Rd b/man/entitylist_update.Rd index 9ad5662a..ac4c03a5 100644 --- a/man/entitylist_update.Rd +++ b/man/entitylist_update.Rd @@ -28,11 +28,11 @@ See \code{vignette("Setup", package = "ruODK")}.} \item{did}{(chr) The name of the Entity List, internally called Dataset.} -\item{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 +\item{approval_required}{(lgl) The value to set \code{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.} +Default: \code{FALSE}.} \item{url}{The ODK Central base URL without trailing slash. @@ -92,23 +92,13 @@ it is not trivial to rectangle the result into a tibble. } \details{ You can only update \code{approvalRequired} using this endpoint. -The approvalRequired flag controls the Entity creation flow; +The \code{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 \code{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. - -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#maturing}{\figure{lifecycle-maturing.svg}{options: alt='[Maturing]'}}}{\strong{[Maturing]}} +v2023.3. Entity Lists created prior to that will have \code{approvalRequired} set +to true. } \examples{ \dontrun{ diff --git a/man/isodt_to_local.Rd b/man/isodt_to_local.Rd index a627e3fa..0286e4b7 100644 --- a/man/isodt_to_local.Rd +++ b/man/isodt_to_local.Rd @@ -24,7 +24,7 @@ Default: \code{c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz")}.} Read \code{vignette("setup", package = "ruODK")} to learn how \code{ruODK}'s timezone can be set globally or per function.} -\item{quiet}{(bool) Used in \code{lubridate::parse_date_time(quiet=quiet)} to +\item{quiet}{(lgl) Used in \code{lubridate::parse_date_time(quiet=quiet)} to suppress warnings from attempting to parse all empty values or columns. Run with \code{quiet=FALSE} to show any \code{lubridate} warnings.} } diff --git a/man/yell_if_missing.Rd b/man/yell_if_missing.Rd index 544c383c..935327c8 100644 --- a/man/yell_if_missing.Rd +++ b/man/yell_if_missing.Rd @@ -4,7 +4,16 @@ \alias{yell_if_missing} \title{Abort on missing ODK Central credentials (url, username, password).} \usage{ -yell_if_missing(url, un, pw, pid = NULL, fid = NULL, iid = NULL) +yell_if_missing( + url, + un, + pw, + pid = NULL, + fid = NULL, + iid = NULL, + did = NULL, + eid = NULL +) } \arguments{ \item{url}{A URL (character)} @@ -35,6 +44,8 @@ testthat::expect_error(yell_if_missing("", "", "")) testthat::expect_error(yell_if_missing("", "", "", "")) testthat::expect_error(yell_if_missing("", "", "", "", "")) testthat::expect_error(yell_if_missing("", "", "", "", "", "")) +testthat::expect_error(yell_if_missing("", "", "", "", "", "", "")) +testthat::expect_error(yell_if_missing("", "", "", "", "", "", "", "")) } \seealso{ Other ru_settings: diff --git a/tests/testthat/test-entitylist_detail.R b/tests/testthat/test-entitylist_detail.R index b2f502ef..c981beaa 100644 --- a/tests/testthat/test-entitylist_detail.R +++ b/tests/testthat/test-entitylist_detail.R @@ -15,14 +15,14 @@ test_that("entitylist_detail works", { # entitylist_detail returns a list testthat::expect_is(ds1, "list") - # linkedForms contain form xmlFormId and name - lf <- ds1$linkedForms |> + # linked_forms contain form xmlFormId and name + lf <- ds1$linked_forms |> purrr::list_transpose() |> tibble::as_tibble() testthat::expect_equal(names(lf), c("xmlFormId", "name")) - # sourceForms contain form xmlFormId and name - sf <- ds1$sourceForms |> + # source_forms contain form xmlFormId and name + sf <- ds1$source_forms |> purrr::list_transpose() |> tibble::as_tibble() testthat::expect_equal(names(sf), c("xmlFormId", "name")) diff --git a/tests/testthat/test-ru_setup.R b/tests/testthat/test-ru_setup.R index b385cf21..edad4ef8 100644 --- a/tests/testthat/test-ru_setup.R +++ b/tests/testthat/test-ru_setup.R @@ -284,6 +284,17 @@ test_that("yell_if_missing yells loudly", { testthat::expect_error( yell_if_missing("x", "x", "x", pid = "x", fid = "x", iid = "") ) + testthat::expect_error( + yell_if_missing("x", "x", "x", pid = "x", fid = "x", iid = "x", did = "") + ) + testthat::expect_error( + yell_if_missing( + "x", "x", "x", + pid = "x", fid = "x", iid = "x", did = "x", eid = "" + ) + ) + testthat::expect_error(yell_if_missing("", "", "", "", "", "", "")) + testthat::expect_error(yell_if_missing("", "", "", "", "", "", "", "")) }) test_that("odata_svc_parse works", {