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
- pid
The numeric ID of the project, e.g.: 2.
Default:
get_default_pid
.Set default
pid
throughru_setup(pid="...")
.See
vignette("Setup", package = "ruODK")
.- did
(chr) The name of the Entity List, internally called Dataset.
- url
The ODK Central base URL without trailing slash.
Default:
get_default_url
.Set default
url
throughru_setup(url="...")
.See
vignette("Setup", package = "ruODK")
.- un
The ODK Central username (an email address). Default:
get_default_un
. Set defaultun
throughru_setup(un="...")
. Seevignette("Setup", package = "ruODK")
.- pw
The ODK Central password. Default:
get_default_pw
. Set defaultpw
throughru_setup(pw="...")
. Seevignette("Setup", package = "ruODK")
.- local_dir
The local folder to save the downloaded files to, default:
here::here
. If the folder does not exist it will be created.- filter
(str) A valid filter string. Default: NULL (no filtering, all entities returned).
- etag
(str) The etag value from a previous call to
entitylist_download()
. The value must be stripped of theW/\"
and\"
, which is the format of the etag returned byentitylist_download()
. If provided, only new entities will be returned. If the samelocal_dir
is chosen andoverwrite
is set toTRUE
, the downloaded CSV will also be overwritte, losing the Entities downloaded earlier. Default: NULL (no filtering, all entities returned).- overwrite
Whether to overwrite previously downloaded file, default: FALSE
- retries
The number of attempts to retrieve a web resource.
This parameter is given to
RETRY(times = retries)
.Default: 3.
- 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
/version.txt
. Discard the "v".ruODK
uses this parameter to adjust for breaking changes in ODK Central.Default:
get_default_odkc_version
or "2023.5.1" if unset.Set default
get_default_odkc_version
throughru_setup(odkc_version="2023.5.1")
.See
vignette("Setup", package = "ruODK")
.- orders
(vector of character) Orders of datetime elements for lubridate.
Default:
c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd")
.- tz
A timezone to convert dates and times to.
Read
vignette("setup", package = "ruODK")
to learn howruODK
's timezone can be set globally or per function.- verbose
Whether to display debug messages or not.
Read
vignette("setup", package = "ruODK")
to learn howruODK
's verbosity can be set globally or per function.
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
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.
See also
https://docs.getodk.org/central-api-dataset-management/#datasets
Other entity-management:
entitylist_detail()
,
entitylist_list()
Examples
if (FALSE) { # \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
# 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}")
)
} # }