Title: | An R Client for the ODK Central API |
---|---|
Description: | Access and tidy up data from the 'ODK Central' API. 'ODK Central' is a clearinghouse for digitally captured data <https://docs.getodk.org/central-intro/>. 'ODK Central' and its API are documented at <https://docs.getodk.org/>. |
Authors: | Florian W. Mayer [aut, cre] |
Maintainer: | Florian W. Mayer <[email protected]> |
License: | GPL-3 |
Version: | 1.4.9.9002 |
Built: | 2024-08-21 02:46:23 UTC |
Source: | https://github.com/ropensci/ruODK |
attachment_get( sid, fn, local_dir = "media", separate = FALSE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries(), verbose = get_ru_verbose() )
attachment_get( sid, fn, local_dir = "media", separate = FALSE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries(), verbose = get_ru_verbose() )
sid |
One or many ODK submission UUIDs, an MD5 hash. |
fn |
One or many ODK form attachment filenames, e.g. "1558330537199.jpg". |
local_dir |
The local folder to save the downloaded files to, default: "media". |
separate |
(logical) Whether to separate locally downloaded files into
a subfolder named after the submission uuid within |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
verbose |
Whether to display debug messages or not. Read |
This function is the workhorse for
handle_ru_attachments
.
This function is vectorised and can handle either one or many records.
Parameters submission_uuid and attachment_filename accept single or exactly
the same number of multiple values.
The other parameters are automatically repeated.
The media attachments are downloaded into a folder given by local_dir
:
workdir/media/filename1.jpg
workdir/media/filename2.jpg
workdir/media/filename3.jpg
The relative file path for the downloaded attachment(s)
https://docs.getodk.org/central-api-form-management/#downloading-a-form-attachment
https://docs.getodk.org/central-api-submission-management/#downloading-an-attachment
Other utilities:
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") a_local_dir <- here::here() # Step 2: Get unparsed submissions fresh_raw <- odata_submission_get(parse = FALSE) # Step 3: Get attachment field "my_photo" fresh_parsed <- fresh_raw %>% odata_submission_rectangle() %>% dplyr::mutate( my_photo = attachment_get(id, my_photo, local_dir = a_local_dir, verbose = TRUE ) # Repeat for all other attachment fields ) ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") a_local_dir <- here::here() # Step 2: Get unparsed submissions fresh_raw <- odata_submission_get(parse = FALSE) # Step 3: Get attachment field "my_photo" fresh_parsed <- fresh_raw %>% odata_submission_rectangle() %>% dplyr::mutate( my_photo = attachment_get(id, my_photo, local_dir = a_local_dir, verbose = TRUE ) # Repeat for all other attachment fields ) ## End(Not run)
attachment_link(data_tbl, form_schema, att_path = "media")
attachment_link(data_tbl, form_schema, att_path = "media")
data_tbl |
The downloaded submissions from
|
form_schema |
The |
att_path |
A local path, default: "media" (as per .csv.zip export).
Selected columns of the dataframe (containing attchment filenames) are
prefixed with |
The dataframe with attachment columns modified to contain relative paths to the downloaded attachment files.
Other utilities:
attachment_get()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: t <- tempdir() # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # Predict filenames (with knowledge of form) fid <- get_default_fid() fid_csv <- fs::path(t, glue::glue("{fid}.csv")) fid_csv_tae <- fs::path(t, glue::glue("{fid}-taxon_encounter.csv")) fs <- form_schema() # Download the zip file se <- ruODK::submission_export( local_dir = t, overwrite = FALSE, verbose = TRUE ) # Unpack the zip file f <- unzip(se, exdir = t) fs::dir_ls(t) # Prepend attachments with media/ to turn into relative file paths data_quadrat <- fid_csv %>% readr::read_csv(na = c("", "NA", "na")) %>% janitor::clean_names() %>% handle_ru_datetimes(fs) %>% attachment_link(fs) ## End(Not run)
## Not run: t <- tempdir() # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # Predict filenames (with knowledge of form) fid <- get_default_fid() fid_csv <- fs::path(t, glue::glue("{fid}.csv")) fid_csv_tae <- fs::path(t, glue::glue("{fid}-taxon_encounter.csv")) fs <- form_schema() # Download the zip file se <- ruODK::submission_export( local_dir = t, overwrite = FALSE, verbose = TRUE ) # Unpack the zip file f <- unzip(se, exdir = t) fs::dir_ls(t) # Prepend attachments with media/ to turn into relative file paths data_quadrat <- fid_csv %>% readr::read_csv(na = c("", "NA", "na")) %>% janitor::clean_names() %>% handle_ru_datetimes(fs) %>% attachment_link(fs) ## End(Not run)
List all attachments for a list of submission instances.
attachment_list( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
attachment_list( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
iid |
A list of submission instance IDs, e.g. from
|
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
A tibble containing some high-level details of the submission attachments. One row per submission attachment, columns are submission attributes:
* name: The attachment filename, e.g. 12345.jpg * exists: Whether the attachment for that submission exists on the server.
https://docs.getodk.org/central-api-submission-management/#listing-expected-submission-attachments
https://docs.getodk.org/central-api-form-management/#listing-form-attachments
Other submission-management:
encryption_key_list()
,
submission_audit_get()
,
submission_detail()
,
submission_export()
,
submission_get()
,
submission_list()
## Not run: # Step 1: Setup ruODK with OData Service URL (has url, pid, fid) ruODK::ru_setup(svc = "...") # Step 2: List all submissions of form sl <- submission_list() # Step 3a: Get attachment list for first submission al <- get_one_submission_attachment_list(sl$instance_id[[1]]) # Ste 3b: Get all attachments for all submissions all <- attachment_list(sl$instance_id) ## End(Not run)
## Not run: # Step 1: Setup ruODK with OData Service URL (has url, pid, fid) ruODK::ru_setup(svc = "...") # Step 2: List all submissions of form sl <- submission_list() # Step 3a: Get attachment list for first submission al <- get_one_submission_attachment_list(sl$instance_id[[1]]) # Ste 3b: Get all attachments for all submissions all <- attachment_list(sl$instance_id) ## End(Not run)
audit_get( action = NULL, start = NULL, end = NULL, limit = NULL, offset = NULL, url = Sys.getenv("ODKC_URL"), un = Sys.getenv("ODKC_UN"), pw = Sys.getenv("ODKC_PW"), retries = get_retries() )
audit_get( action = NULL, start = NULL, end = NULL, limit = NULL, offset = NULL, url = Sys.getenv("ODKC_URL"), un = Sys.getenv("ODKC_UN"), pw = Sys.getenv("ODKC_PW"), retries = get_retries() )
action |
string. The action to filter the logs, e.g. "user.create". See https://docs.getodk.org/central-api-system-endpoints/#getting-audit-log-entries for the full list of available actions. |
start |
string. The ISO8601 timestamp of the earliest log entry to
return.
E.g. |
end |
string. The ISO8601 timestamp of the last log entry to return. |
limit |
integer. The max number of log entries to return. |
offset |
integer. The number of log entries to skip. |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
Parameters to filter the audit logs:
action=form.create&start=2000-01-01z&end=2000-12-31T23%3A59.999z
A tibble containing server audit logs. One row per audited action, columns are submission attributes:
actor_id: integer. The ID of the actor, if any, that initiated the action.
action: string. The action that was taken.
actee_id: uuid, string. The ID of the permissioning object against which the action was taken.
details: list. Additional details about the action that vary according to the type of action.
logged_at: dttm. Time of action on server.
https://docs.getodk.org/central-api-system-endpoints/#getting-audit-log-entries
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") logs <- audit_get() # With search parameters logs <- audit_get( action = "project.update", start = "2019-08-01Z", end = "2019-08-31Z", limit = 100, offset = 0 ) # With partial search parameters logs <- audit_get( limit = 100, offset = 0 ) logs %>% knitr::kable(.) # audit_get returns a tibble class(logs) # > c("tbl_df", "tbl", "data.frame") # Audit details names(logs) # > "actor_id" "action" "actee_id" "details" "logged_at" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") logs <- audit_get() # With search parameters logs <- audit_get( action = "project.update", start = "2019-08-01Z", end = "2019-08-31Z", limit = 100, offset = 0 ) # With partial search parameters logs <- audit_get( limit = 100, offset = 0 ) logs %>% knitr::kable(.) # audit_get returns a tibble class(logs) # > c("tbl_df", "tbl", "data.frame") # Audit details names(logs) # > "actor_id" "action" "actee_id" "details" "logged_at" ## End(Not run)
This helper patches a bug/feature in ODK Central (versions 0.7-0.9), where
geotrace / geoshape GeoJSON contains a last coordinate pair with NULL
lat/lon (no alt/acc), and WKT ends in , undefined NaN
.
drop_null_coords(x)
drop_null_coords(x)
x |
A GeoJSON geometry parsed as nested list.
E.g. |
While split_geotrace
and split_geoshape
modify
the WKT inline, it is more maintainable to separate the GeoJSON cleaner
into this function.
This helper drops the last element of a GeoJSON coordinate list if it is
list(NULL, NULL)
.
The nested list minus the last element (if NULL).
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
# A snapshot of geo data with trailing empty coordinates. data("geo_gj88") len_coords <- length(geo_gj88$path_location_path_gps[[1]]$coordinates) length(geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]]) %>% testthat::expect_equal(2) geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]][[1]] %>% testthat::expect_null() geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]][[2]] %>% testthat::expect_null() # The last coordinate pair is a list(NULL, NULL). # Invalid coordinates like these are a choking hazard for geospatial # packages. We should remove them before we can convert ODK data into native # spatial formats, such as sf. str(geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]]) geo_gj_repaired <- geo_gj88 %>% dplyr::mutate( path_location_path_gps = path_location_path_gps %>% purrr::map(drop_null_coords) ) len_coords_repaired <- length( geo_gj_repaired$path_location_path_gps[[1]]$coordinates ) testthat::expect_equal(len_coords_repaired + 1, len_coords)
# A snapshot of geo data with trailing empty coordinates. data("geo_gj88") len_coords <- length(geo_gj88$path_location_path_gps[[1]]$coordinates) length(geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]]) %>% testthat::expect_equal(2) geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]][[1]] %>% testthat::expect_null() geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]][[2]] %>% testthat::expect_null() # The last coordinate pair is a list(NULL, NULL). # Invalid coordinates like these are a choking hazard for geospatial # packages. We should remove them before we can convert ODK data into native # spatial formats, such as sf. str(geo_gj88$path_location_path_gps[[1]]$coordinates[[len_coords]]) geo_gj_repaired <- geo_gj88 %>% dplyr::mutate( path_location_path_gps = path_location_path_gps %>% purrr::map(drop_null_coords) ) len_coords_repaired <- length( geo_gj_repaired$path_location_path_gps[[1]]$coordinates ) testthat::expect_equal(len_coords_repaired + 1, len_coords)
encryption_key_list( pid = get_default_pid(), fid = get_default_fid(), 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"), tz = get_default_tz() )
encryption_key_list( pid = get_default_pid(), fid = get_default_fid(), 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"), tz = get_default_tz() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
This endpoint provides a listing of all known encryption keys needed to
decrypt all Submissions for a given Form. It will return at least the
base64RsaPublicKey
property (as column public
) of all known versions
of the form that have submissions against them.
If managed keys are being used and a hint was provided, that will be returned
as well.
A tibble of encryption keys.
https://docs.getodk.org/central-api-encryption/
https://docs.getodk.org/central-api-submission-management/#listing-encryption-keys
Other submission-management:
attachment_list()
,
submission_audit_get()
,
submission_detail()
,
submission_export()
,
submission_get()
,
submission_list()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") x <- encryption_key_list( pid = Sys.getenv("ODKC_TEST_PID_ENC"), fid = Sys.getenv("ODKC_TEST_FID_ENC"), url = get_test_url(), un = get_test_un(), pw = get_test_pw() ) names(x) # > [1] "id" "public" "managed" "hint" "created_at" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") x <- encryption_key_list( pid = Sys.getenv("ODKC_TEST_PID_ENC"), fid = Sys.getenv("ODKC_TEST_FID_ENC"), url = get_test_url(), un = get_test_un(), pw = get_test_pw() ) names(x) # > [1] "id" "public" "managed" "hint" "created_at" ## End(Not run)
entitylist_detail( 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() )
entitylist_detail( 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() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
did |
(chr) The name of the Entity List, internally called Dataset. |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to 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 Default: Set default See |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
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.
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.
https://docs.getodk.org/central-api-dataset-management/#datasets
Other entity-management:
entitylist_download()
,
entitylist_list()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") ds <- entitylist_list(pid = get_default_pid()) ds1 <- entitylist_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() ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") ds <- entitylist_list(pid = get_default_pid()) ds1 <- entitylist_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() ## End(Not run)
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() )
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() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
did |
(chr) The name of the Entity List, internally called Dataset. |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
local_dir |
The local folder to save the downloaded files to,
default: |
filter |
(str) A valid filter string. Default: NULL (no filtering, all entities returned). |
etag |
(str) The etag value from a previous call to
|
overwrite |
Whether to overwrite previously downloaded file, default: FALSE |
retries |
The number of attempts to retrieve a web resource. This parameter is given to 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 Default: Set default See |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
verbose |
Whether to display debug messages or not. Read |
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.
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
https://docs.getodk.org/central-api-dataset-management/#datasets
Other entity-management:
entitylist_detail()
,
entitylist_list()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", 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}") ) ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", 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}") ) ## End(Not run)
entitylist_list( 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() )
entitylist_list( 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() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to 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 Default: Set default See |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
While the API endpoint will return all Entity Lists for one Project,
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.
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
.
https://docs.getodk.org/central-api-dataset-management/#datasets
Other entity-management:
entitylist_detail()
,
entitylist_download()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") ds <- entitylist_list(pid = get_default_pid()) ds |> knitr::kable() ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") ds <- entitylist_list(pid = get_default_pid()) ds |> knitr::kable() ## End(Not run)
entitylist_update( 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() )
entitylist_update( 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() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
did |
(chr) The name of the Entity List, internally called Dataset. |
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. |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to 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 Default: Set default See |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
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 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.
A list of lists following the exact format and naming of the API
response for entitylist_detail
.
Since this nested list is so deeply nested and irregularly shaped
it is not trivial to rectangle the result into a tibble.
https://docs.getodk.org/central-api-dataset-management/#datasets
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") pid <- get_default_pid() ds <- entitylist_list(pid = pid) did <- ds$name[1] ds1 <- entitylist_detail(pid = pid, did = did) ds1$approvalRequired # FALSE ds2 <- entitylist_update(pid = pid, did = did, approval_required = TRUE) ds2$approvalRequired # TRUE ds3 <- entitylist_update(pid = pid, did = did, approval_required = FALSE) ds3$approvalRequired # FALSE ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") pid <- get_default_pid() ds <- entitylist_list(pid = pid) did <- ds$name[1] ds1 <- entitylist_detail(pid = pid, did = did) ds1$approvalRequired # FALSE ds2 <- entitylist_update(pid = pid, did = did, approval_required = TRUE) ds2$approvalRequired # TRUE ds3 <- entitylist_update(pid = pid, did = did, approval_required = FALSE) ds3$approvalRequired # FALSE ## End(Not run)
form_detail( pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
form_detail( pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
A tibble with one row and all form metadata as columns.
https://docs.getodk.org/central-api-form-management/#getting-form-details
Other form-management:
form_list()
,
form_schema()
,
form_schema_ext()
,
form_xml()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit credentials, see tests fl <- form_list() # The first form in the test project f <- form_detail(fid = fl$fid[[1]]) # form_detail returns exactly one row nrow(f) # > 1 # form_detail returns all form metadata as columns: name, xmlFormId, etc. names(f) # > "name" "fid" "version" "state" "submissions" "created_at" # > "created_by_id" "created_by" "updated_at" "published_at" # > "last_submission" "hash" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit credentials, see tests fl <- form_list() # The first form in the test project f <- form_detail(fid = fl$fid[[1]]) # form_detail returns exactly one row nrow(f) # > 1 # form_detail returns all form metadata as columns: name, xmlFormId, etc. names(f) # > "name" "fid" "version" "state" "submissions" "created_at" # > "created_by_id" "created_by" "updated_at" "published_at" # > "last_submission" "hash" ## End(Not run)
form_list( pid = get_default_pid(), 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"), tz = get_default_tz() )
form_list( pid = get_default_pid(), 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"), tz = get_default_tz() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
A tibble with one row per form and all given form metadata as cols.
Column names are sanitized into snake_case
.
Nested columns (review start and created by) are flattened and prefixed.
The column xml_form_id
is replicated as fid
according to ruODK
naming
standards.
https://docs.getodk.org/central-api-form-management/#list-all-forms
Other form-management:
form_detail()
,
form_schema()
,
form_schema_ext()
,
form_xml()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With default pid fl <- form_list() # With explicit pid fl <- form_list(pid = 1) class(fl) # > c("tbl_df", "tbl", "data.frame") # Filter out draft forms (published_at=NA) only_published_forms <- fl %>% dplyr::filter(is.na(published_at)) # Note: older ODK Central versions < 1.1 have published_at = NA for both # published and draft forms. Drafts have NA for version and hash. only_published_forms <- fl %>% dplyr::filter(is.na(version) & is.na(hash)) ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With default pid fl <- form_list() # With explicit pid fl <- form_list(pid = 1) class(fl) # > c("tbl_df", "tbl", "data.frame") # Filter out draft forms (published_at=NA) only_published_forms <- fl %>% dplyr::filter(is.na(published_at)) # Note: older ODK Central versions < 1.1 have published_at = NA for both # published and draft forms. Drafts have NA for version and hash. only_published_forms <- fl %>% dplyr::filter(is.na(version) & is.na(hash)) ## End(Not run)
form_schema( flatten = FALSE, odata = FALSE, parse = TRUE, draft = FALSE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), odkc_version = get_default_odkc_version(), retries = get_retries(), verbose = get_ru_verbose() )
form_schema( flatten = FALSE, odata = FALSE, parse = TRUE, draft = FALSE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), odkc_version = get_default_odkc_version(), retries = get_retries(), verbose = get_ru_verbose() )
flatten |
Whether to flatten the resulting list of lists (TRUE) or not (FALSE, default). Only applies to ODK Central version < 0.8. |
odata |
Whether to sanitise the field names to match the way they will be outputted for OData. While the original field names as given in the XForms definition may be used as-is for CSV output, OData has some restrictions related to the domain-qualified identifier syntax it uses. Only applies to ODK Central version < 0.8. Default: FALSE. |
parse |
Whether to parse the form schema into a tibble of form field
type and name. This uses |
draft |
Whether the form is published (FALSE) or a draft (TRUE). Default: TRUE. |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
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 Default: Set default See |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
verbose |
Whether to display debug messages or not. Read |
ODK Central has introduced a new API endpoint in version 0.8 which returns a parsed and flattened list of fields. This replaces the nested form schema which is challenging to parse.
While users of newer ODK Central versions (> 0.8) can ignore the legacy
support for ODK Central's earlier form schema API, users of ODK Central
version < 0.8 can set an environment variable ODKC_VERSION
to their
ODKC's version in format <major>.<minor>
e.g. 0.7
.
This variable caters for future breaking changes.
Either way, form_schema
will always return a tibble with
columns name
, type
, path
and ruodk_name
.
A tibble or nested list (v0.7) containing the form definition.
At the lowest nesting level, each form field consists of a list of two
nodes, name
(the underlying field name) and type
(the XForms field
type, as in "string", "select1", "geopoint", "binary" and so on).
These fields are nested in lists of tuples name
(the XForms screen name),
children
(the fields as described above), type
("structure" for non-
repeating screens, "repeat" for repeating screens).
A list with name
"meta" may precede the structure, if several metadata
fields are captured (e.g. "instanceId", form start datetimes etc.).
In all cases for ODK Central 0.8, and with default parameters
(parse=TRUE
) for ODK Central 0.7, form_schema
returns
a tibble with the columns:
name
The field name as given in the form schema.
type
The field type, e.g. "string", "select1", etc.
path
The XForms path of the field,
selectMultiple
Whether a field of type "select" is
a select multiple (TRUE
). Any other types are NA
.
ruodk_name
The predicted field name as generated by
odata_submission_get
, prefixed by the path, additionally
cleaned with make_clean_names
to match the
cleaned column names from odata_submission_rectangle
.
https://docs.getodk.org/central-api-form-management/#getting-form-schema-fields
Other form-management:
form_detail()
,
form_list()
,
form_schema_ext()
,
form_xml()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit pid and fid fs_defaults <- form_schema(pid = 1, fid = "build_xformsId") # With current ODK Central (v0.8) fs <- form_schema() # With defaults, ODK Central v0.7 fs_nested <- form_schema( flatten = FALSE, odata = FALSE, parse = FALSE, odkc_version = 0.7 ) listviewer::jsonedit(fs_nested) fs_flattened <- form_schema( flatten = TRUE, odata = FALSE, parse = FALSE, odkc_version = 0.7 ) listviewer::jsonedit(fs_flattened) # form_schema returns a nested list. There's nothing to change about that. class(fs_nested) # > "list" class(fs_flattened) # > "list" # This assumes knowledge of that exact form being tested. # First node: type "structure" (a field group) named "meta". fs_nested[[1]]$type # > "structure" fs_nested[[1]]$name # > "meta" # The first node contains children, which means it's an XForms field group. names(fs_nested[[1]]) # > "name" "children" "type" # Next node: a "meta" field of type "string" capturing the "instanceId". # First child node of "meta": type "string", name "instanceId". fs_nested[[1]]$children[[1]]$type # > "string" fs_nested[[1]]$children[[1]]$name # > "instanceID" # In the flattened version, the field's and it's ancestors' names are the # components of "path". fs_flattened[[1]]$path # > "meta". "instanceId" fs_flattened[[1]]$type # > "string" # Last node: a "meta" field capturing the datetime of form completion fs_flattened[[length(fs_flattened)]]$type # > "dateTime" fs_nested[[length(fs_nested)]]$type # > "dateTime" # Parsed into a tibble of form field type/name: # Useful to inform further parsing of submission data (attachments, dates) fs <- form_schema(parse = TRUE, odkc_version = 0.7) fs <- form_schema(odkc_version = 0.8) # Attachments: used by handle_ru_attachments fs %>% dplyr::filter(type == "binary") # dateTime: used by handle_ru_datetimes fs %>% dplyr::filter(type == "dateTime") # Point location: used by handle_ru_geopoints fs %>% dplyr::filter(type == "geopoint") ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit pid and fid fs_defaults <- form_schema(pid = 1, fid = "build_xformsId") # With current ODK Central (v0.8) fs <- form_schema() # With defaults, ODK Central v0.7 fs_nested <- form_schema( flatten = FALSE, odata = FALSE, parse = FALSE, odkc_version = 0.7 ) listviewer::jsonedit(fs_nested) fs_flattened <- form_schema( flatten = TRUE, odata = FALSE, parse = FALSE, odkc_version = 0.7 ) listviewer::jsonedit(fs_flattened) # form_schema returns a nested list. There's nothing to change about that. class(fs_nested) # > "list" class(fs_flattened) # > "list" # This assumes knowledge of that exact form being tested. # First node: type "structure" (a field group) named "meta". fs_nested[[1]]$type # > "structure" fs_nested[[1]]$name # > "meta" # The first node contains children, which means it's an XForms field group. names(fs_nested[[1]]) # > "name" "children" "type" # Next node: a "meta" field of type "string" capturing the "instanceId". # First child node of "meta": type "string", name "instanceId". fs_nested[[1]]$children[[1]]$type # > "string" fs_nested[[1]]$children[[1]]$name # > "instanceID" # In the flattened version, the field's and it's ancestors' names are the # components of "path". fs_flattened[[1]]$path # > "meta". "instanceId" fs_flattened[[1]]$type # > "string" # Last node: a "meta" field capturing the datetime of form completion fs_flattened[[length(fs_flattened)]]$type # > "dateTime" fs_nested[[length(fs_nested)]]$type # > "dateTime" # Parsed into a tibble of form field type/name: # Useful to inform further parsing of submission data (attachments, dates) fs <- form_schema(parse = TRUE, odkc_version = 0.7) fs <- form_schema(odkc_version = 0.8) # Attachments: used by handle_ru_attachments fs %>% dplyr::filter(type == "binary") # dateTime: used by handle_ru_datetimes fs %>% dplyr::filter(type == "dateTime") # Point location: used by handle_ru_geopoints fs %>% dplyr::filter(type == "geopoint") ## End(Not run)
form_schema_ext( flatten = FALSE, odata = FALSE, parse = TRUE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), odkc_version = get_default_odkc_version(), retries = get_retries(), verbose = get_ru_verbose() )
form_schema_ext( flatten = FALSE, odata = FALSE, parse = TRUE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), odkc_version = get_default_odkc_version(), retries = get_retries(), verbose = get_ru_verbose() )
flatten |
Whether to flatten the resulting list of lists ( |
odata |
Whether to sanitise the field names to match the way they will
be outputted for OData. While the original field names as given in the
XForms definition may be used as-is for CSV output, OData has some
restrictions related to the domain-qualified identifier syntax it uses.
Only applies to ODK Central version < 0.8.
Default: |
parse |
Whether to parse the form schema into a tibble of form field
type and name. This uses |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
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 Default: Set default See |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
verbose |
Whether to display debug messages or not. Read |
ODK Central has introduced a new API endpoint in version 0.8 which
returns a parsed and flattened list of fields. This replaces the nested
form schema which is challenging to parse. This list is returned
by form_schema
.
However this still misses important elements, in particular labels
and
choice_lists
.
form_schema_ext
returns the same object as
form_schema
adding labels
and choice lists
in all languages available.
This is done by using the return object from form_xml
.
It has the exact function signature as form_schema
.
In that sense, any call to form_schema
can be replaced
by form_schema_ext
This function, however, has been prepared with ODK Central version 0.8 or higher. If you use it with an earlier version, a warning will be given.
A tibble containing the form definition.
For ODK Central 0.8, and with default parameters
(parse=TRUE
) for ODK Central 0.7, form_schema
returns
a tibble with the columns:
name
The field name as given in the form schema.
type
The field type, e.g. "string", "select1", etc.
path
The XForms path of the field,
ruodk_name
The predicted field name as generated by
odata_submission_get
, prefixed by the path, additionally
cleaned with make_clean_names
to match the
cleaned column names from odata_submission_rectangle
.
label
The field label as given in the form schema.
If specific languages are available,
this column will return the default
language or it will be empty
if this is not specified.
label_lang
The field label in languange _lang as
given in the form schema.
choices
A list of lists containing at least values
and,
if available, labels
of the choices as given in the form schema.
If specific languages are available, this column will return the
default
language or it will be empty if this is not specified.
Please notice that whenever choice filters are applied, this will return
the unfiltered choice list.
choices_lang
A list of lists containing at least
values
and, if available, labels
of the choices in language
_lang as given in the form schema.
Please notice that whenever choice filters are applied, this will return
the unfiltered choice list.
https://docs.getodk.org/central-api-form-management/#getting-form-schema-fields
https://docs.getodk.org/central-api-form-management/#retrieving-form-xml
Other form-management:
form_detail()
,
form_list()
,
form_schema()
,
form_xml()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With current ODK Central (>0.7) # get extended schema: fsx <- form_schema_ext() # print choice list in english: fsx[fsx$name == "test_yn", "choices_english_(en)"][[1]] # view the extended schema: fsx ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With current ODK Central (>0.7) # get extended schema: fsx <- form_schema_ext() # print choice list in english: fsx[fsx$name == "test_yn", "choices_english_(en)"][[1]] # view the extended schema: fsx ## End(Not run)
form_schema_parse(fs, path = "Submissions", verbose = get_ru_verbose())
form_schema_parse(fs, path = "Submissions", verbose = get_ru_verbose())
fs |
The output of form_schema as nested list |
path |
The base path for form fields. Default: "Submissions".
|
verbose |
Whether to display debug messages or not. Read |
This function is used by form_schema
for older versions of
ODK Central (pre 0.8). These return the form schema as XML, requiring the
quite involved code of form_schema_parse
, while newer ODK
Central versions return JSON, which is parsed directly in
form_schema
.
The form_schema
returned from ODK Central versions < 0.8 is a nested list
of lists containing the form definition.
The form definition consists of fields (with a type and name), and form
groups, which are rendered as separate ODK Collect screens.
Form groups in turn can also contain form fields.
form_schema_parse
recursively unpacks the form and extracts the
name and type of each field. This information then informs
handle_ru_attachments
, handle_ru_datetimes
,
handle_ru_geopoints
, handle_ru_geotraces
, and
handle_ru_geoshapes
.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: # Option 1: in two steps, ODKC Version 0.7 fs <- form_schema(flatten = FALSE, parse = FALSE, odkc_version = 0.7) fsp <- form_schema_parse(fs) # Option 2: in one go fsp <- form_schema(parse = TRUE) fsp ## End(Not run)
## Not run: # Option 1: in two steps, ODKC Version 0.7 fs <- form_schema(flatten = FALSE, parse = FALSE, odkc_version = 0.7) fsp <- form_schema_parse(fs) # Option 2: in one go fsp <- form_schema(parse = TRUE) fsp ## End(Not run)
form_xml( parse = TRUE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
form_xml( parse = TRUE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
parse |
Whether to parse the XML into a nested list, default: TRUE |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
The form XML as a nested list.
https://docs.getodk.org/central-api-form-management/#retrieving-form-xml
Other form-management:
form_detail()
,
form_list()
,
form_schema()
,
form_schema_ext()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit pid and fid fxml_defaults <- form_xml(1, "build_xformsId") # With defaults fxml <- form_xml() listviewer::jsonedit(fxml) # form_xml returns a nested list class(fxml) # > "list" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit pid and fid fxml_defaults <- form_xml(1, "build_xformsId") # With defaults fxml <- form_xml() listviewer::jsonedit(fxml) # form_xml returns a nested list class(fxml) # > "list" ## End(Not run)
fq_attachments
fq_attachments
A tibble of submission attachments.
The output of attachment_list
run on submissions of the test form
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
.
Other included:
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_data
fq_data
The output of odata_submission_get
for a set of example
data. A tidy tibble referencing the attachments included in the vignettes
and documentation at a relative path attachments/media/<filename>.<ext>
.
The parsed OData response for the submissions of an ODK Central form. This form represents a Flora Quadrat, which is a ca 50 by 50 m quadrat of a uniform plant community.
The XML and .odkbuild versions for this form are available as
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
and system.file("extdata", "FloraQuadrat04.odkbuild", package = "ruODK")
,
respectively.
This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.
See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
and odata_submission_get
.
Other included:
fq_attachments
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_data_strata
fq_data_strata
The output of odata_submission_get
for a set of example
data. A tidy tibble referencing the attachments included in the vignettes
and documentation at a relative path attachments/media/<filename>.<ext>
.
The parsed OData response for the subgroup of an ODK Central form.
This subgroup represents vegetation strata as per the NVIS classification. A vegetation stratum is a layer of plants with the same height, and dominated by one or few plant taxa. Plant communities can be made of up to five strata, with two to three being most common.
This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.
See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
and odata_submission_get
.
Other included:
fq_attachments
,
fq_data
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_data_taxa
fq_data_taxa
The output of odata_submission_get
for a set of example
data. A tidy tibble referencing the attachments included in the vignettes
and documentation at a relative path attachments/media/<filename>.<ext>
.
The parsed OData response for a subgroup of an ODK Central form.
This subgroup represents an individual plant taxon which is encountered by the enumerators. Typically, one voucher specimen is taken for each distinct encountered plant taxon. A field name is allocated by the enumerators, which can be the proper canonical name (if known) or any other moniker. The voucher specimens are later determined by taxonomic experts, who then provide the real, terminal taxonomic name for a given voucher specimen.
This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.
See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
and odata_submission_get
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_form_detail
fq_form_detail
A tibble of form metadata.
The output of form_detail
run on submissions of the test form
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_form_list
fq_form_list
A tibble of forms
The output of form_list
.
run on the project.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_form_schema
fq_form_schema
The output of ruODK::form_schema()
, a tibble with columns "type",
"name" and "path" and one row per form field.
The parsed form schema of an ODK Central form.
This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.
This data is used to build vignettes offline and without the need for credentials to an ODK Central server. The test suite ensures that the "canned" data is identical to the "live" data.
See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
and ruODK::form_schema()
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_form_xml
fq_form_xml
A nested list of a form definition.
The output of form_xml
run on the test form
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_meta
fq_meta
A list of lists
The OData response for the metadata of an ODK Central form.
This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.
See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_project_detail
fq_project_detail
A tibble of project metadata.
The output of project_detail
run on the project containing the test form
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_project_list
fq_project_list
A tibble of project metadata.
The output of project_list
run on all projects on the configured ODK Central server.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_raw
fq_raw
A list of lists
The OData response for the submissions of an ODK Central form. This form represents a Flora Quadrat, which is a ca 50 by 50 m quadrat of a uniform plant community.
The XML and .odkbuild versions for this form are available as
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
and system.file("extdata", "FloraQuadrat04.odkbuild", package = "ruODK")
,
respectively.
This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.
See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_raw_strata
fq_raw_strata
A list of lists
The OData response for the subgroup of an ODK Central form.
This subgroup represents vegetation strata as per the NVIS classification. A vegetation stratum is a layer of plants with the same height, and dominated by one or few plant taxa. Plant communities can be made of up to five strata, with two to three being most common.
This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.
See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_raw_taxa
fq_raw_taxa
A list of lists
The OData response for a subgroup of an ODK Central form.
This subgroup represents an individual plant taxon which is encountered by the enumerators. Typically, one voucher specimen is taken for each distinct encountered plant taxon. A field name is allocated by the enumerators, which can be the proper canonical name (if known) or any other moniker. The voucher specimens are later determined by taxonomic experts, who then provide the real, terminal taxonomic name for a given voucher specimen.
This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.
See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_submission_list
fq_submission_list
A tibble of submission metadata.
The output of submission_list
run on the test form
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_submissions
fq_submissions
A nested list of submission data.
The output of submission_get
run on the test form
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
using submission instance IDs from submission_list
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_svc
fq_svc
A tibble with one row per submission data endpoint.
The OData response for the metadata of an ODK Central form.
This data is kept up to date with the data used in vignettes and package tests. The data is comprised of test records with nonsensical data. The forms used to capture this data are development versions of real-world forms.
OData service document for
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_zip_data
fq_zip_data
A tibble of main records from a test form.
submission_export
run on the test form
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_zip_strata
fq_zip_strata
A tibble of repeated sub-group of records from a test form.
submission_export
run on the test form
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fq_zip_taxa
fq_zip_taxa
A tibble of repeated sub-group of records from a test form.
submission_export
run on the test form
system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fs_v7
fs_v7
An object of class tbl_df
(inherits from tbl
, data.frame
) with 12 rows and 3 columns.
form_schema_parse(fs_v7_raw)
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
fs_v7_raw
fs_v7_raw
An object of class list
of length 6.
form_schema(odkc_version = 0.7, parse = FALSE)
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
geo_fs
geo_fs
An object of class tbl_df
(inherits from tbl
, data.frame
) with 19 rows and 6 columns.
form_schema
run on the test form
system.file("extdata", "Locations.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
geo_gj
geo_gj
An object of class tbl_df
(inherits from tbl
, data.frame
) with 1 rows and 58 columns.
odata_submission_get(wkt=FALSE, parse=TRUE)
run on the test form
system.file("extdata", "Locations.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
geo_gj_raw
geo_gj_raw
An object of class list
of length 2.
odata_submission_get(wkt=FALSE, parse=FALSE)
run on the test form
system.file("extdata", "Locations.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
geo_gj88
geo_gj88
An object of class tbl_df
(inherits from tbl
, data.frame
) with 1 rows and 51 columns.
This issue was fixed in #88. ODK Central versions 0.7 - 0.9 export geotraces and geoshapes with trailing empty coordinates. ruODK has a patch to drop trailing empty coordinates. This dataset is used to test the patch in ruODK.
odata_submission_get(wkt=FALSE, parse=TRUE)
run on the test form
system.file("extdata", "Locations.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
,
geo_wkt_raw
geo_wkt
geo_wkt
An object of class tbl_df
(inherits from tbl
, data.frame
) with 1 rows and 55 columns.
odata_submission_get(wkt=TRUE, parse=TRUE)
run on the test form
system.file("extdata", "Locations.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt88
,
geo_wkt_raw
geo_wkt_raw
geo_wkt_raw
An object of class list
of length 2.
odata_submission_get(wkt=TRUE, parse=FALSE)
run on the test form
system.file("extdata", "Locations.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt88
geo_wkt88
geo_wkt88
An object of class tbl_df
(inherits from tbl
, data.frame
) with 1 rows and 48 columns.
This issue was fixed in #88. ODK Central versions 0.7 - 0.9 export geotraces and geoshapes with trailing empty coordinates. ruODK has a patch to drop trailing empty coordinates. This dataset is used to test the patch in ruODK.
odata_submission_get(wkt=TRUE, parse=TRUE)
run on the test form
system.file("extdata", "Locations.xml", package = "ruODK")
.
Other included:
fq_attachments
,
fq_data
,
fq_data_strata
,
fq_data_taxa
,
fq_form_detail
,
fq_form_list
,
fq_form_schema
,
fq_form_xml
,
fq_meta
,
fq_project_detail
,
fq_project_list
,
fq_raw
,
fq_raw_strata
,
fq_raw_taxa
,
fq_submission_list
,
fq_submissions
,
fq_svc
,
fq_zip_data
,
fq_zip_strata
,
fq_zip_taxa
,
fs_v7
,
fs_v7_raw
,
geo_fs
,
geo_gj
,
geo_gj88
,
geo_gj_raw
,
geo_wkt
,
geo_wkt_raw
get_one_attachment( pth, fn, src, url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries(), verbose = get_ru_verbose() )
get_one_attachment( pth, fn, src, url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries(), verbose = get_ru_verbose() )
pth |
A local file path to save the attachment to. |
fn |
The attachment filename, as per ODK form submission. If NA, no file will be downloaded, but NA will be returned. If the file does not exist in ODK Central, a warning will be emitted. |
src |
The attachment's download URL, generated by
|
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
verbose |
Whether to display debug messages or not. Read |
This is a helper function used by attachment_get
.
This function is not vectorised, but mapped by attachment_get
to a tibble of input parameters.
The relative local path to the downloaded attachment or NA.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: # Step 1: Setup ruODK with OData Service URL (has url, pid, fid) # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # Step 2: Construct attachment_url att_url <- ruODK:::attachment_url( "uuid:d3bcefea-32a8-4dbc-80ca-4ecb0678e2b0", "filename.jpg" ) # Step 3: Get one attachment local_fn <- get_one_attachment("media/filename.jpg", "filename.jpg", att_url) # In real life: done in bulk behind the scenes during odata_submission_get() ## End(Not run)
## Not run: # Step 1: Setup ruODK with OData Service URL (has url, pid, fid) # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # Step 2: Construct attachment_url att_url <- ruODK:::attachment_url( "uuid:d3bcefea-32a8-4dbc-80ca-4ecb0678e2b0", "filename.jpg" ) # Step 3: Get one attachment local_fn <- get_one_attachment("media/filename.jpg", "filename.jpg", att_url) # In real life: done in bulk behind the scenes during odata_submission_get() ## End(Not run)
This function is the workhorse for the vectorised function submission_get, which gets all submissions for a list of submission IDs.
get_one_submission( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
get_one_submission( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
iid |
The |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
Note this function returns a nested list containing any repeating subgroups. As the presence and length of repeating subgroups is non-deterministic and entirely depends on the completeness of the submission data, we cannot rectangle them any further here. Rectangling requires knowledge of the form schema and the completeness of submission data.
A nested list of submission data.
https://docs.getodk.org/central-api-submission-management/#retrieving-submission-xml
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit credentials, see tests sl <- submission_list() sub <- get_one_submission(sl$instance_id[[1]]) listviewer::jsonedit(sub) # The details for one submission depend on the form fields length(sub) # > 11 # The items are the field names. Repeated groups have the same name. names(sub) # > "meta" "encounter_start_datetime" "reporter" # > "device_id" "location" "habitat" # > "vegetation_structure" "perimeter" "taxon_encounter" # > "taxon_encounter" "encounter_end_datetime" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit credentials, see tests sl <- submission_list() sub <- get_one_submission(sl$instance_id[[1]]) listviewer::jsonedit(sub) # The details for one submission depend on the form fields length(sub) # > 11 # The items are the field names. Repeated groups have the same name. names(sub) # > "meta" "encounter_start_datetime" "reporter" # > "device_id" "location" "habitat" # > "vegetation_structure" "perimeter" "taxon_encounter" # > "taxon_encounter" "encounter_end_datetime" ## End(Not run)
get_one_submission_attachment_list( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
get_one_submission_attachment_list( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
iid |
The |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
When a Submission is created, either over the OpenRosa or the REST interface, its XML data is analysed to determine which file attachments it references: these may be photos or video taken as part of the survey, or an audit/timing log, among other things. Each reference is an expected attachment, and these expectations are recorded permanently alongside the Submission. With this subresource, you can list the expected attachments, see whether the server actually has a copy or not, and download, upload, re-upload, or clear binary data for any particular attachment.
You can retrieve the list of expected Submission attachments at this route, along with a boolean flag indicating whether the server actually has a copy of the expected file or not. If the server has a file, you can then append its filename to the request URL to download only that file.
A tibble containing some high-level details of the submission attachments. One row per submission attachment, columns are submission attributes:
* name: The attachment filename, e.g. 12345.jpg * exists: Whether the attachment for that submission exists on the server.
https://docs.getodk.org/central-api-submission-management/#listing-expected-submission-attachments
https://docs.getodk.org/central-api-form-management/#listing-form-attachments
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") sl <- submission_list() al <- get_one_submission_attachment_list(sl$instance_id[[1]]) al %>% knitr::kable(.) # attachment_list returns a tibble class(al) # > c("tbl_df", "tbl", "data.frame") # Submission attributes are the tibble's columns names(al) # > "name" "exists" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") sl <- submission_list() al <- get_one_submission_attachment_list(sl$instance_id[[1]]) al %>% knitr::kable(.) # attachment_list returns a tibble class(al) # > c("tbl_df", "tbl", "data.frame") # Submission attributes are the tibble's columns names(al) # > "name" "exists" ## End(Not run)
get_one_submission_audit( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
get_one_submission_audit( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
iid |
The |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
This function is the workhorse for the vectorised function submission_audit_get, which gets all server audit logs for a list of submission IDs.
Note this function returns a nested list containing any repeating subgroups. As the presence and length of repeating subgroups is non-deterministic and entirely depends on the completeness of the submission data, we cannot rectangle them any further here. Rectangling requires knowledge of the form schema and the completeness of submission data.
A nested list of submission data.
https://docs.getodk.org/central-api-submission-management/#retrieving-audit-logs
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit credentials, see tests sl <- submission_list() sub <- get_one_submission_audit(sl$instance_id[[1]]) listviewer::jsonedit(sub) # The details for one submission depend on the form fields length(sub) # > 11 # The items are the field names. Repeated groups have the same name. names(sub) # > "meta" "encounter_start_datetime" "reporter" # > "device_id" "location" "habitat" # > "vegetation_structure" "perimeter" "taxon_encounter" # > "taxon_encounter" "encounter_end_datetime" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # With explicit credentials, see tests sl <- submission_list() sub <- get_one_submission_audit(sl$instance_id[[1]]) listviewer::jsonedit(sub) # The details for one submission depend on the form fields length(sub) # > 11 # The items are the field names. Repeated groups have the same name. names(sub) # > "meta" "encounter_start_datetime" "reporter" # > "device_id" "location" "habitat" # > "vegetation_structure" "perimeter" "taxon_encounter" # > "taxon_encounter" "encounter_end_datetime" ## End(Not run)
handle_ru_attachments( data, form_schema, local_dir = "media", pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries(), verbose = get_ru_verbose() )
handle_ru_attachments( data, form_schema, local_dir = "media", pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries(), verbose = get_ru_verbose() )
data |
Submissions rectangled into a tibble. E.g. the output of ruODK::odata_submission_get(parse = FALSE) %>% ruODK::odata_submission_rectangle() |
form_schema |
The |
local_dir |
The local folder to save the downloaded files to, default: "media". |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
verbose |
Whether to display debug messages or not. Read |
For a given tibble of submissions, download and link attachments for all columns which are marked in the form schema as type "binary".
The submissions tibble with all attachments downloaded and linked to
a local_dir
.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: library(magrittr) data("fq_raw") data("fq_form_schema") t <- tempdir() fs::dir_ls(t) %>% fs::file_delete() fq_with_att <- fq_raw %>% ruODK::odata_submission_rectangle() %>% ruODK::handle_ru_attachments( form_schema = fq_form_schema, local_dir = t, pid = ruODK::get_test_pid(), fid = ruODK::get_test_fid(), url = ruODK::get_test_url(), un = ruODK::get_test_un(), pw = ruODK::get_test_pw(), verbose <- ruODK::get_ru_verbose() ) # There should be files in local_dir testthat::expect_true(fs::dir_ls(t) %>% length() > 0) ## End(Not run)
## Not run: library(magrittr) data("fq_raw") data("fq_form_schema") t <- tempdir() fs::dir_ls(t) %>% fs::file_delete() fq_with_att <- fq_raw %>% ruODK::odata_submission_rectangle() %>% ruODK::handle_ru_attachments( form_schema = fq_form_schema, local_dir = t, pid = ruODK::get_test_pid(), fid = ruODK::get_test_fid(), url = ruODK::get_test_url(), un = ruODK::get_test_un(), pw = ruODK::get_test_pw(), verbose <- ruODK::get_ru_verbose() ) # There should be files in local_dir testthat::expect_true(fs::dir_ls(t) %>% length() > 0) ## End(Not run)
handle_ru_datetimes( data, form_schema, orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), tz = get_default_tz(), verbose = get_ru_verbose() )
handle_ru_datetimes( data, form_schema, orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), tz = get_default_tz(), verbose = get_ru_verbose() )
data |
Submissions rectangled into a tibble. E.g. the output of ruODK::odata_submission_get(parse = FALSE) %>% ruODK::odata_submission_rectangle() |
form_schema |
The |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
verbose |
Whether to display debug messages or not. Read |
For a given tibble of submissions, parse all columns which are marked in the form schema as type "date" or "dateTime" using a set of lubridate orders and a given timezone.
The submissions tibble with all date/dateTime columns mutated as lubridate datetimes.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: library(magrittr) data("fq_raw") data("fq_form_schema") fq_with_dates <- fq_raw %>% ruODK::odata_submission_rectangle() %>% ruODK::handle_ru_datetimes(form_schema = fq_form_schema) dplyr::glimpse(fq_with_dates) ## End(Not run)
## Not run: library(magrittr) data("fq_raw") data("fq_form_schema") fq_with_dates <- fq_raw %>% ruODK::odata_submission_rectangle() %>% ruODK::handle_ru_datetimes(form_schema = fq_form_schema) dplyr::glimpse(fq_with_dates) ## End(Not run)
handle_ru_geopoints(data, form_schema, wkt = FALSE, verbose = get_ru_verbose())
handle_ru_geopoints(data, form_schema, wkt = FALSE, verbose = get_ru_verbose())
data |
Submissions rectangled into a tibble. E.g. the output of ruODK::odata_submission_get(parse = FALSE) %>% ruODK::odata_submission_rectangle() |
form_schema |
The |
wkt |
Whether geofields are GeoJSON (if FALSE) or WKT strings (if TRUE), default: FALSE. |
verbose |
Whether to display debug messages or not. Read |
For a given tibble of submissions, find all columns which are listed
in the form schema as type geopoint
, and extract their components.
Extracted components are longitude (X), latitude (Y), altitude (Z, where
given), and accuracy (M, where given).
The original column is retained to allow parsing into other spatially enabled formats.
The submissions tibble with all geopoints retained in their original
format, plus columns of their coordinate components as provided by
split_geopoint
.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
library(magrittr) data("geo_fs") data("geo_gj_raw") data("geo_wkt_raw") # GeoJSON geo_gj_parsed <- geo_gj_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geopoints(form_schema = geo_fs, wkt = FALSE) dplyr::glimpse(geo_gj_parsed) # WKT geo_wkt_parsed <- geo_wkt_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geopoints(form_schema = geo_fs, wkt = TRUE) dplyr::glimpse(geo_wkt_parsed)
library(magrittr) data("geo_fs") data("geo_gj_raw") data("geo_wkt_raw") # GeoJSON geo_gj_parsed <- geo_gj_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geopoints(form_schema = geo_fs, wkt = FALSE) dplyr::glimpse(geo_gj_parsed) # WKT geo_wkt_parsed <- geo_wkt_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geopoints(form_schema = geo_fs, wkt = TRUE) dplyr::glimpse(geo_wkt_parsed)
handle_ru_geoshapes( data, form_schema, wkt = FALSE, odkc_version = get_default_odkc_version(), verbose = get_ru_verbose() )
handle_ru_geoshapes( data, form_schema, wkt = FALSE, odkc_version = get_default_odkc_version(), verbose = get_ru_verbose() )
data |
Submissions rectangled into a tibble. E.g. the output of ruODK::odata_submission_get(parse = FALSE) %>% ruODK::odata_submission_rectangle(form_schema = ...) |
form_schema |
The |
wkt |
Whether geofields are GeoJSON (if FALSE) or WKT strings (if TRUE), default: FALSE. |
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 Default: Set default See |
verbose |
Whether to display debug messages or not. Read |
For a given tibble of submissions, find all columns which are listed
in the form schema as type geoshape
, and extract their components.
Extracted components are longitude (X), latitude (Y), altitude (Z, where
given), and accuracy (M, where given) of the first point of the geoshape.
The original column is retained to allow parsing into other spatially enabled formats.
The submissions tibble with all geoshapes retained in their original
format, plus columns of their first point's coordinate components as
provided by split_geoshape
.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: library(magrittr) data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # GeoJSON geo_gj_parsed <- geo_gj_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geoshapes(form_schema = geo_fs, wkt = FALSE) dplyr::glimpse(geo_gj_parsed) # WKT geo_wkt_parsed <- geo_wkt_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geoshapes(form_schema = geo_fs, wkt = TRUE) dplyr::glimpse(geo_wkt_parsed) ## End(Not run)
## Not run: library(magrittr) data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # GeoJSON geo_gj_parsed <- geo_gj_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geoshapes(form_schema = geo_fs, wkt = FALSE) dplyr::glimpse(geo_gj_parsed) # WKT geo_wkt_parsed <- geo_wkt_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geoshapes(form_schema = geo_fs, wkt = TRUE) dplyr::glimpse(geo_wkt_parsed) ## End(Not run)
handle_ru_geotraces( data, form_schema, wkt = FALSE, odkc_version = get_default_odkc_version(), verbose = get_ru_verbose() )
handle_ru_geotraces( data, form_schema, wkt = FALSE, odkc_version = get_default_odkc_version(), verbose = get_ru_verbose() )
data |
Submissions rectangled into a tibble. E.g. the output of ruODK::odata_submission_get(parse = FALSE) %>% ruODK::odata_submission_rectangle(form_schema = ...) |
form_schema |
The |
wkt |
Whether geofields are GeoJSON (if FALSE) or WKT strings (if TRUE), default: FALSE. |
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 Default: Set default See |
verbose |
Whether to display debug messages or not. Read |
For a given tibble of submissions, find all columns which are listed
in the form schema as type geotrace
, and extract their components.
Extracted components are longitude (X), latitude (Y), altitude (Z, where
given), and accuracy (M, where given) of the first point of the geotrace.
The original column is retained to allow parsing into other spatially enabled formats.
The submissions tibble with all geotraces retained in their original
format, plus columns of their first point's coordinate components as
provided by split_geotrace
.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: library(magrittr) data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # GeoJSON geo_gj_parsed <- geo_gj_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geotraces(form_schema = geo_fs, wkt = FALSE) dplyr::glimpse(geo_gj_parsed) # WKT geo_wkt_parsed <- geo_wkt_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geotraces(form_schema = geo_fs, wkt = TRUE) dplyr::glimpse(geo_wkt_parsed) ## End(Not run)
## Not run: library(magrittr) data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # GeoJSON geo_gj_parsed <- geo_gj_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geotraces(form_schema = geo_fs, wkt = FALSE) dplyr::glimpse(geo_gj_parsed) # WKT geo_wkt_parsed <- geo_wkt_raw %>% ruODK::odata_submission_rectangle(form_schema = geo_fs) %>% ruODK::handle_ru_geotraces(form_schema = geo_fs, wkt = TRUE) dplyr::glimpse(geo_wkt_parsed) ## End(Not run)
odata_metadata_get( pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
odata_metadata_get( pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
A nested list containing Edmx (dataset schema definition) and .attrs (Version).
https://docs.getodk.org/central-api-odata-endpoints/#metadata-document
Other odata-api:
odata_service_get()
,
odata_submission_get()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") meta <- odata_metadata_get() listviewer::jsonedit(meta) ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") meta <- odata_metadata_get() listviewer::jsonedit(meta) ## End(Not run)
odata_service_get( pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
odata_service_get( pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
A tibble with one row per submission data endpoint. Columns: name, kind, url.
https://docs.getodk.org/central-api-odata-endpoints/#service-document
Other odata-api:
odata_metadata_get()
,
odata_submission_get()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") svc <- odata_service_get() svc ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") svc <- odata_service_get() svc ## End(Not run)
odata_submission_get( table = "Submissions", skip = NULL, top = NULL, count = FALSE, wkt = FALSE, expand = FALSE, filter = NULL, parse = TRUE, download = TRUE, orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), local_dir = "media", pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), odkc_version = get_default_odkc_version(), tz = get_default_tz(), retries = get_retries(), verbose = get_ru_verbose() )
odata_submission_get( table = "Submissions", skip = NULL, top = NULL, count = FALSE, wkt = FALSE, expand = FALSE, filter = NULL, parse = TRUE, download = TRUE, orders = c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd"), local_dir = "media", pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), odkc_version = get_default_odkc_version(), tz = get_default_tz(), retries = get_retries(), verbose = get_ru_verbose() )
table |
The submission EntityType, or in plain words, the table name.
Default: |
skip |
The number of rows to be omitted from the results.
Example: 10, default: |
top |
The number of rows to return.
Example: 100, default: |
count |
If TRUE, an |
wkt |
If TRUE, geospatial data will be returned as WKT (Well Known Text)
strings. Default: |
expand |
If TRUE, all subtables will be expanded and included with
column names containing the number of the repeat, the group name, and the
field name. This parameter is supported from ODK Central v1.2 onwards and
will be ignored on earlier versions of ODK Central. The version is inferred
from the parameter |
filter |
If provided, will filter responses to those matching the query.
For an |
parse |
Whether to parse submission data based on form schema.
Dates and datetimes will be parsed into local time.
Attachments will be downloaded, and the field updated to the local file
path.
Point locations will be split into components; GeoJSON ( |
download |
Whether to download attachments to |
orders |
(vector of character) Orders of datetime elements for
lubridate.
Default:
|
local_dir |
The local folder to save the downloaded files to,
default: |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
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 Default: Set default See |
tz |
A timezone to convert dates and times to. Read |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
verbose |
Whether to display debug messages or not. Read |
odata_submission_get
downloads submissions from
(default) the main form group (submission table) including any non-repeating
form groups, or from any other table as specified by parameter table
.
With parameter parse=TRUE
(default), submission data is parsed into a
tibble. Any fields of type dateTime
or date
are parsed into
dates, with an optional parameter tz
to specify the local timezone.
A parameter local_dir
(default: media
) specifies a local
directory for downloaded attachment files.
Already existing, previously downloaded attachments will be retained.
With parameter wkt=TRUE
, spatial fields will be returned as WKT, rather
than GeoJSON. In addition, fields of type geopoint
will be split into
latitude, longitude, and altitude, prefixed with the original field name.
E.g. a field start_location
of type geopoint
will be split into
start_location_latitude
, start_location_longitude
, and
start_location_altitude
. The field name prefix will allow multiple fields
of type geopoint
to be split into their components without naming
conflicts.
Geotraces (lines) and gepshapes (polygons) will be retained in their original
format, plus columns of their first point's coordinate components as
provided by split_geotrace
and split_geoshape
,
respectively.
Entirely unpopulated form fields, as well as notes and form groups, will be excluded from the resulting tibble. Submitting at least one complete form instance will prevent the accidental exclusion of an otherwise mostly empty form field.
The only remaining manual step is to optionally join any sub-tables to the master table.
The parameter verbose
enables diagnostic messages along the download
and parsing process.
With parameter parse=FALSE
, submission data is presented as nested
list, which is the R equivalent of the JSON structure returned from the API.
From there, odata_submission_rectangle
can rectangle the data
into a tibble, and subsequent lines of handle_ru_datetimes
,
handle_ru_attachments
, handle_ru_geopoints
,
handle_ru_geotraces
, and handle_ru_geoshapes
parse dates, download and link file attachments, and extract coordinates from
geofields.
ruODK
offers this manual and explicit pathway as an option to
investigate and narrow down unexpected or unwanted behaviour.
A list of lists.
value
contains the submissions as list of lists.
@odata.context
is the URL of the metadata.
@odata.count
is the total number of rows in the table.
https://docs.getodk.org/central-api-odata-endpoints/#odata-form-service
https://docs.getodk.org/central-api-odata-endpoints/#data-document
Other odata-api:
odata_metadata_get()
,
odata_service_get()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") form_tables <- ruODK::odata_service_get() data <- odata_submission_get() # default: main data table data <- odata_submission_get(table = form_tables$url[1]) # same, explicitly data_sub1 <- odata_submission_get(table = form_tables$url[2]) # sub-table 1 data_sub2 <- odata_submission_get(table = form_tables$url[3]) # sub-table 2 # Skip one row, return the next 1 rows (top), include total row count data <- odata_submission_get( table = form_tables$url[1], skip = 1, top = 1, count = TRUE ) # Filter submissions data <- odata_submission_get( table = form_tables$url[1], filter = "year(__system/submissionDate) lt year(now())" ) data <- odata_submission_get( table = form_tables$url[1], filter = "year(__system/submissionDate) lt 2020" ) # To include all of the month of January, you need to filter by either # filter = "__system/submissionDate le 2020-01-31T23:59:59.999Z" # or # filter = "__system/submissionDate lt 2020-02-01". # Instead of timezone UTC ("Z"), you can also filter by any other timezone. ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") form_tables <- ruODK::odata_service_get() data <- odata_submission_get() # default: main data table data <- odata_submission_get(table = form_tables$url[1]) # same, explicitly data_sub1 <- odata_submission_get(table = form_tables$url[2]) # sub-table 1 data_sub2 <- odata_submission_get(table = form_tables$url[3]) # sub-table 2 # Skip one row, return the next 1 rows (top), include total row count data <- odata_submission_get( table = form_tables$url[1], skip = 1, top = 1, count = TRUE ) # Filter submissions data <- odata_submission_get( table = form_tables$url[1], filter = "year(__system/submissionDate) lt year(now())" ) data <- odata_submission_get( table = form_tables$url[1], filter = "year(__system/submissionDate) lt 2020" ) # To include all of the month of January, you need to filter by either # filter = "__system/submissionDate le 2020-01-31T23:59:59.999Z" # or # filter = "__system/submissionDate lt 2020-02-01". # Instead of timezone UTC ("Z"), you can also filter by any other timezone. ## End(Not run)
odata_submission_get(parse=FALSE)
into a tidy tibble and unnest all levels.odata_submission_rectangle( data, names_repair = "universal", names_sep = "_", form_schema = NULL, verbose = get_ru_verbose() )
odata_submission_rectangle( data, names_repair = "universal", names_sep = "_", form_schema = NULL, verbose = get_ru_verbose() )
data |
A nested list of lists as given by
|
names_repair |
The argument |
names_sep |
The argument |
form_schema |
An optional form_schema,
like the output of |
verbose |
Whether to display debug messages or not. Read |
This function cleans names with janitor::clean_names()
and drops the
prefix value_
.
The submissions as un-nested tibble
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: # Using canned data data_parsed <- odata_submission_rectangle(fq_raw, verbose = TRUE) # Field "device_id" is known part of fq_raw testthat::expect_equal( data_parsed$device_id[[1]], fq_raw$value[[1]]$device_id ) # fq_raw has two submissions testthat::expect_equal(length(fq_raw$value), nrow(data_parsed)) ## End(Not run)
## Not run: # Using canned data data_parsed <- odata_submission_rectangle(fq_raw, verbose = TRUE) # Field "device_id" is known part of fq_raw testthat::expect_equal( data_parsed$device_id[[1]], fq_raw$value[[1]]$device_id ) # fq_raw has two submissions testthat::expect_equal(length(fq_raw$value), nrow(data_parsed)) ## End(Not run)
odata_svc_parse(svc)
odata_svc_parse(svc)
svc |
(character) The OData service URL of a form as provided by the ODK Central form submissions tab. Example: "https://URL/v1/projects/PID/forms/FID.svc" |
A named list with three components (all of type character):
url
The ODK Central base URL.
pid
The project ID.
fid
The form ID.
Other ru_settings:
parse_odkc_version()
,
ru_settings()
,
ru_setup()
,
semver_gt()
,
semver_lt()
,
yell_if_error()
,
yell_if_missing()
semver
.parse_odkc_version(v, env_var = "ODKC_VERSION")
parse_odkc_version(v, env_var = "ODKC_VERSION")
v |
A string (e.g. "ODKC_VERSION=") or number (e.g. 0.8, 1.5) of a complete or partial semver, or a semver of class "svlist". |
env_var |
A string indicating which environment variable was targeted. This is used in the warning to advise which environment variable to update. If set to an empty string, the warning message is suppressed. Default: "ODKC_VERSION". |
Past versions of ruODK advised to set ODKC_VERSION to a floating point number
indicating major and minor versions, e.g. ODKC_VERSION=0.7
or
ODKC_VERSION=1.5
.
ODK Central has since switched to semantic versioning, e.g.
ODKC_VERSION=ODKC_VERSION=
.
To preserve backwards compatibility, ruODK handles both formats gracefully, but emits a helpful warning to update the version string if the older format is detected, or the version string is missing the minor or patch version.
semver::svlist The version as semver of major, minor, and patch.
Other ru_settings:
odata_svc_parse()
,
ru_settings()
,
ru_setup()
,
semver_gt()
,
semver_lt()
,
yell_if_error()
,
yell_if_missing()
parse_odkc_version("1.2.3") # Warn: too short parse_odkc_version("1") parse_odkc_version("1.2") # Warn: too long parse_odkc_version("1.2.3.4") # Warn: otherwise invalid parse_odkc_version("1.2.") parse_odkc_version(".2.3")
parse_odkc_version("1.2.3") # Warn: too short parse_odkc_version("1") parse_odkc_version("1.2") # Warn: too long parse_odkc_version("1.2.3.4") # Warn: otherwise invalid parse_odkc_version("1.2.") parse_odkc_version(".2.3")
project_create( name, url = get_default_url(), un = get_default_un(), pw = get_default_pw() )
project_create( name, url = get_default_url(), un = get_default_un(), pw = get_default_pw() )
name |
The desired name of the project. Can contain whitespace. |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
A tibble with one row per project and all project metadata as columns as per ODK Central API docs.
https://docs.getodk.org/central-api-project-management/#creating-a-project
Other project-management:
project_detail()
,
project_list()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") p <- project_create("Test Project") knitr::kable(p) # project_create returns a tibble class(p) # > "tbl_df" "tbl" "data.frame" # columns are project metadata names(p) # > "id" "name" "archived" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") p <- project_create("Test Project") knitr::kable(p) # project_create returns a tibble class(p) # > "tbl_df" "tbl" "data.frame" # columns are project metadata names(p) # > "id" "name" "archived" ## End(Not run)
While the API endpoint will return all details for one project,
project_detail
will fail with incorrect or missing
authentication.
project_detail( pid = get_default_pid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
project_detail( pid = get_default_pid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
A tibble with exactly one row for the project and all project
metadata as columns as per ODK Central API docs.
Column names are renamed from ODK's camelCase
to snake_case
.
Values differ to values returned by ODK Central API:
archived: FALSE (if NULL) else TRUE
dates: NA if NULL
https://docs.getodk.org/central-api-project-management/#getting-project-details
Other project-management:
project_create()
,
project_list()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") pd <- project_detail() pd %>% dplyr::select(-"verbs") %>% knitr::kable(.) ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") pd <- project_detail() pd %>% dplyr::select(-"verbs") %>% knitr::kable(.) ## End(Not run)
While the API endpoint will return all projects,
project_list
will fail with incorrect or missing
authentication.
project_list( 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"), tz = get_default_tz() )
project_list( 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"), tz = get_default_tz() )
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
A tibble with one row per project and all project metadata as columns as per ODK Central API docs.
https://docs.getodk.org/central-api-project-management/#listing-projects
Other project-management:
project_create()
,
project_detail()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") pl <- project_list() knitr::kable(pl) # project_list returns a tibble class(pl) # > "tbl_df" "tbl" "data.frame" # columns are project metadata names(pl) # > "id" "name" "forms" "app_users" "created_at" "updated_at" # > "last_submission" "archived" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") pl <- project_list() knitr::kable(pl) # project_list returns a tibble class(pl) # > "tbl_df" "tbl" "data.frame" # columns are project metadata names(pl) # > "id" "name" "forms" "app_users" "created_at" "updated_at" # > "last_submission" "archived" ## End(Not run)
ru_msg_abort(message)
ru_msg_abort(message)
message |
(chr) A message to print |
Other messaging:
ru_msg_info()
,
ru_msg_noop()
,
ru_msg_success()
,
ru_msg_warn()
## Not run: ru_msg_abort("This is an error, abort.") ## End(Not run)
## Not run: ru_msg_abort("This is an error, abort.") ## End(Not run)
ru_msg_info(message, verbose = get_ru_verbose())
ru_msg_info(message, verbose = get_ru_verbose())
message |
(chr) A message to print |
verbose |
Whether to display debug messages or not. Read |
Other messaging:
ru_msg_abort()
,
ru_msg_noop()
,
ru_msg_success()
,
ru_msg_warn()
ru_msg_info("This is an info message.")
ru_msg_info("This is an info message.")
ru_msg_noop(message, verbose = get_ru_verbose())
ru_msg_noop(message, verbose = get_ru_verbose())
message |
(chr) A message to print |
verbose |
Whether to display debug messages or not. Read |
Other messaging:
ru_msg_abort()
,
ru_msg_info()
,
ru_msg_success()
,
ru_msg_warn()
ru_msg_noop("This is a noop message.")
ru_msg_noop("This is a noop message.")
ru_msg_success(message, verbose = get_ru_verbose())
ru_msg_success(message, verbose = get_ru_verbose())
message |
(chr) A message to print |
verbose |
Whether to display debug messages or not. Read |
Other messaging:
ru_msg_abort()
,
ru_msg_info()
,
ru_msg_noop()
,
ru_msg_warn()
ru_msg_success("This is a success message.")
ru_msg_success("This is a success message.")
ru_msg_warn(message, verbose = get_ru_verbose())
ru_msg_warn(message, verbose = get_ru_verbose())
message |
(chr) A message to print |
verbose |
Whether to display debug messages or not. Read |
Other messaging:
ru_msg_abort()
,
ru_msg_info()
,
ru_msg_noop()
,
ru_msg_success()
## Not run: ru_msg_warn("This is a warning.") ## End(Not run)
## Not run: ru_msg_warn("This is a warning.") ## End(Not run)
ruODK
settings.ru_settings() get_default_pid() get_default_fid() get_default_url() get_default_un() get_default_pw() get_default_pp() get_default_tz() get_test_url() get_test_un() get_test_pw() get_test_pid() get_test_fid() get_test_fid_zip() get_test_fid_att() get_test_fid_gap() get_test_fid_wkt() get_test_pp() get_ru_verbose() get_default_odkc_version() get_test_odkc_version() get_retries()
ru_settings() get_default_pid() get_default_fid() get_default_url() get_default_un() get_default_pw() get_default_pp() get_default_tz() get_test_url() get_test_un() get_test_pw() get_test_pid() get_test_fid() get_test_fid_zip() get_test_fid_att() get_test_fid_gap() get_test_fid_wkt() get_test_pp() get_ru_verbose() get_default_odkc_version() get_test_odkc_version() get_retries()
ru_settings
prints your default ODK Central project ID,
form ID, url, username, and password, corresponding optional test
server as well as verbosity and HTTP request settings.
ru_setup
sets your production and test settings, while
get_(default/test)_*
get each of those respective settings.
ru_setup
,
get_default_pid
,
get_default_fid
,
get_default_url
,
get_default_un
,
get_default_pw
,
get_default_pp
,
get_default_tz
,
get_default_odkc_version
,
get_retries
,
get_test_pid
,
get_test_fid
,
get_test_fid_zip
,
get_test_fid_att
,
get_test_fid_gap
,
get_test_fid_wkt
,
get_test_url
,
get_test_un
,
get_test_pw
,
get_test_pp
,
get_test_odkc_version
,
get_ru_verbose
.
Other ru_settings:
odata_svc_parse()
,
parse_odkc_version()
,
ru_setup()
,
semver_gt()
,
semver_lt()
,
yell_if_error()
,
yell_if_missing()
ru_settings()
ru_settings()
ruODK
settings.Settings are returned invisibly and additionally printed depending on
get_ru_verbose
.
ru_setup( svc = NULL, pid = NULL, fid = NULL, url = NULL, un = NULL, pw = NULL, pp = NULL, tz = NULL, odkc_version = NULL, retries = NULL, verbose = NULL, test_svc = NULL, test_pid = NULL, test_fid = NULL, test_fid_zip = NULL, test_fid_att = NULL, test_fid_gap = NULL, test_fid_wkt = NULL, test_url = NULL, test_un = NULL, test_pw = NULL, test_pp = NULL, test_odkc_version = NULL )
ru_setup( svc = NULL, pid = NULL, fid = NULL, url = NULL, un = NULL, pw = NULL, pp = NULL, tz = NULL, odkc_version = NULL, retries = NULL, verbose = NULL, test_svc = NULL, test_pid = NULL, test_fid = NULL, test_fid_zip = NULL, test_fid_att = NULL, test_fid_gap = NULL, test_fid_wkt = NULL, test_url = NULL, test_un = NULL, test_pw = NULL, test_pp = NULL, test_odkc_version = NULL )
svc |
(optional, character) The OData service URL of a form.
This parameter will set |
pid |
(optional, character) The ID of an existing project on |
fid |
(optional, character) The alphanumeric ID of an existing form
in |
url |
An ODK Central URL,
e.g. "https://sandbox.central.getodk.org".
This will override the ODK Central base URL from |
un |
An ODK Central username which is the email of a "web user" in the
specified ODK Central instance |
pw |
The password for user |
pp |
The passphrase (optional, character) for an encrypted form. |
tz |
Global default time zone.
|
odkc_version |
The ODK Central version as major/minor version, e.g. 1.1. |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
verbose |
Global default for
|
test_svc |
(optional, character) The OData service URL of a test form.
This parameter will set |
test_pid |
(optional, character) The numeric ID of an existing project
on |
test_fid |
(optional, character) The alphanumeric ID of an existing form
in |
test_fid_zip |
(optional, character) The alphanumeric ID of an existing
form in |
test_fid_att |
(optional, character) The alphanumeric ID of an existing
form in |
test_fid_gap |
(optional, character) The alphanumeric ID of an existing
form in |
test_fid_wkt |
(optional, character) The alphanumeric ID of an existing
form in |
test_url |
(optional, character) A valid ODK Central URL for testing.
This will override the ODK Central base URL from |
test_un |
(optional, character) A valid ODK Central username (email)
privileged to view the test project(s) at |
test_pw |
(optional, character) The valid ODK Central password for
|
test_pp |
(optional, character) The valid passphrase to decrypt the
data of encrypted project |
test_odkc_version |
The ODK Central test server's version as major/minor version, e.g. 1.1. |
ru_setup
sets ODK Central connection details.
ruODK
's functions default to use the default project ID,
form ID, URL, username, and password unless specified explicitly.
Any parameters not specified will remain unchanged. It is therefore possible
to set up username and password initially with
ru_setup(un="XXX", pw="XXX")
, and switch between forms with
ru_setup(svc="XXX")
, supplying the form's OData service URL.
ODK Central conveniently provides the OData service URL in the form
submission tab, which in turn contains base URL, project ID, and form ID.
ruODK
's automated tests require a valid ODK Central URL, and a
privileged username and password of a "web user" on that ODK Central
instance, as well as an existing project and form.
Other ru_settings:
odata_svc_parse()
,
parse_odkc_version()
,
ru_settings()
,
semver_gt()
,
semver_lt()
,
yell_if_error()
,
yell_if_missing()
# `ruODK` users only need default settings to their ODK Central: ru_setup(url = "https://my-odkc.com", un = "[email protected]", pw = "...") # `ruODK` contributors and maintainers need specific ODK Central # instances to run tests and build vignettes, see contributing guide: ru_setup( url = "https://odkcentral.dbca.wa.gov.au", un = "[email protected]", pw = "...", pp = "...", test_url = "https://sandbox.central.getodk.org", test_un = "[email protected]", test_pw = "...", test_pp = "...", test_pid = 14, test_fid = "build_Flora-Quadrat-0-2_1558575936", test_fid_zip = "build_Spotlighting-0-6_1558333698", test_fid_att = "build_Flora-Quadrat-0-1_1558330379", test_fid_gap = "build_Turtle-Track-or-Nest-1-0_1569907666", test_fid_wkt = "build_Locations_1589344221", retries = 3, verbose = TRUE )
# `ruODK` users only need default settings to their ODK Central: ru_setup(url = "https://my-odkc.com", un = "[email protected]", pw = "...") # `ruODK` contributors and maintainers need specific ODK Central # instances to run tests and build vignettes, see contributing guide: ru_setup( url = "https://odkcentral.dbca.wa.gov.au", un = "[email protected]", pw = "...", pp = "...", test_url = "https://sandbox.central.getodk.org", test_un = "[email protected]", test_pw = "...", test_pp = "...", test_pid = 14, test_fid = "build_Flora-Quadrat-0-2_1558575936", test_fid_zip = "build_Spotlighting-0-6_1558333698", test_fid_att = "build_Flora-Quadrat-0-1_1558330379", test_fid_gap = "build_Turtle-Track-or-Nest-1-0_1569907666", test_fid_wkt = "build_Locations_1589344221", retries = 3, verbose = TRUE )
Show whether a given semver is greater than a baseline version.
semver_gt(sv = get_default_odkc_version(), to = "1.5.0")
semver_gt(sv = get_default_odkc_version(), to = "1.5.0")
sv |
The semver to compare as character
("2023.5.1", "1.5.0", "1.5"), or numeric (1.5).
The value is always parsed with |
to |
The semver to compare to as string. Although semver can parse
complete version strings, |
A boolean indicating whether the given semver sv
is greater than
the baseline semver to
.
Other ru_settings:
odata_svc_parse()
,
parse_odkc_version()
,
ru_settings()
,
ru_setup()
,
semver_lt()
,
yell_if_error()
,
yell_if_missing()
get_default_odkc_version() |> semver_gt("0.8.0") "2024.1.1" |> semver_gt("2024.1.0") "2024.1.1" |> semver_gt("2024.1.1") "2024.1.1" |> semver_gt("2024.1.2")
get_default_odkc_version() |> semver_gt("0.8.0") "2024.1.1" |> semver_gt("2024.1.0") "2024.1.1" |> semver_gt("2024.1.1") "2024.1.1" |> semver_gt("2024.1.2")
Show whether a given semver is lesser than a baseline version.
semver_lt(sv = get_default_odkc_version(), to = "1.5.0")
semver_lt(sv = get_default_odkc_version(), to = "1.5.0")
sv |
The semver to compare as character
("2023.5.1", "1.5.0", "1.5"), or numeric (1.5).
The value is always parsed with |
to |
The semver to compare to as string. Although semver can parse
complete version strings, |
A boolean indicating whether the given semver sv
is greater than
the baseline semver to
.
Other ru_settings:
odata_svc_parse()
,
parse_odkc_version()
,
ru_settings()
,
ru_setup()
,
semver_gt()
,
yell_if_error()
,
yell_if_missing()
get_default_odkc_version() |> semver_lt("0.8.0") "2024.1.1" |> semver_lt("2024.1.0") "2024.1.1" |> semver_lt("2024.1.1") "2024.1.1" |> semver_lt("2024.1.2")
get_default_odkc_version() |> semver_lt("0.8.0") "2024.1.1" |> semver_lt("2024.1.0") "2024.1.1" |> semver_lt("2024.1.1") "2024.1.1" |> semver_lt("2024.1.2")
split_geopoint(data, colname, wkt = FALSE)
split_geopoint(data, colname, wkt = FALSE)
data |
(dataframe) A dataframe with a geopoint column. |
colname |
(chr) The name of the geopoint column. This column will be retained. |
wkt |
Whether geofields are GeoJSON (if FALSE) or WKT strings (if TRUE), default: FALSE. |
This function is used by handle_ru_geopoints
on all geopoint
fields as per form_schema
.
The given dataframe with the WKT POINT column colname, plus
three new columns, colname_longitude
, colname_latitude
,
colname_altitude
.
The three new columns are prefixed with the original colname
to
avoid naming conflicts with any other geopoint columns.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geoshape()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: df_wkt <- tibble::tibble( stuff = c("asd", "sdf", "sdf"), loc = c( "POINT (115.99 -32.12 20.01)", "POINT (116.12 -33.34 15.23)", "POINT (114.01 -31.56 23.56)" ) ) df_wkt_split <- df |> split_geopoint("loc", wkt = TRUE) testthat::expect_equal( names(df_wkt_split), c("stuff", "loc", "loc_longitude", "loc_latitude", "loc_altitude") ) # With package data data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # Find variable names of geopoints geo_fields <- geo_fs |> dplyr::filter(type == "geopoint") |> magrittr::extract2("ruodk_name") geo_fields[1] # First geotrace in data: point_location_point_gps # Rectangle but don't parse submission data (GeoJSON and WKT) geo_gj_rt <- geo_gj_raw |> odata_submission_rectangle(form_schema = geo_fs) geo_wkt_rt <- geo_wkt_raw |> odata_submission_rectangle(form_schema = geo_fs) # Data with first geopoint split gj_first_gt <- split_geopoint(geo_gj_rt, geo_fields[1], wkt = FALSE) gj_first_gt$point_location_point_gps_longitude wkt_first_gt <- split_geopoint(geo_wkt_rt, geo_fields[1], wkt = TRUE) wkt_first_gt$point_location_point_gps_longitude ## End(Not run)
## Not run: df_wkt <- tibble::tibble( stuff = c("asd", "sdf", "sdf"), loc = c( "POINT (115.99 -32.12 20.01)", "POINT (116.12 -33.34 15.23)", "POINT (114.01 -31.56 23.56)" ) ) df_wkt_split <- df |> split_geopoint("loc", wkt = TRUE) testthat::expect_equal( names(df_wkt_split), c("stuff", "loc", "loc_longitude", "loc_latitude", "loc_altitude") ) # With package data data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # Find variable names of geopoints geo_fields <- geo_fs |> dplyr::filter(type == "geopoint") |> magrittr::extract2("ruodk_name") geo_fields[1] # First geotrace in data: point_location_point_gps # Rectangle but don't parse submission data (GeoJSON and WKT) geo_gj_rt <- geo_gj_raw |> odata_submission_rectangle(form_schema = geo_fs) geo_wkt_rt <- geo_wkt_raw |> odata_submission_rectangle(form_schema = geo_fs) # Data with first geopoint split gj_first_gt <- split_geopoint(geo_gj_rt, geo_fields[1], wkt = FALSE) gj_first_gt$point_location_point_gps_longitude wkt_first_gt <- split_geopoint(geo_wkt_rt, geo_fields[1], wkt = TRUE) wkt_first_gt$point_location_point_gps_longitude ## End(Not run)
split_geoshape( data, colname, wkt = FALSE, odkc_version = get_default_odkc_version() )
split_geoshape( data, colname, wkt = FALSE, odkc_version = get_default_odkc_version() )
data |
(dataframe) A dataframe with a geoshape column. |
colname |
(chr) The name of the geoshape column. This column will be retained. |
wkt |
Whether geofields are GeoJSON (if FALSE) or WKT strings (if TRUE), default: FALSE. |
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 Default: Set default See |
This function is used by handle_ru_geopoints
on all geopoint
fields as per form_schema
.
The given dataframe with the geoshape column colname, plus
three new columns, colname_longitude
, colname_latitude
,
colname_altitude
.
The three new columns are prefixed with the original colname
to
avoid naming conflicts with any other geoshape columns.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geotrace()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: library(magrittr) data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # Find variable names of geoshapes geo_fields <- geo_fs %>% dplyr::filter(type == "geoshape") %>% magrittr::extract2("ruodk_name") geo_fields[1] # First geoshape in data: shape_location_shape_gps # Rectangle but don't parse submission data (GeoJSON and WKT) geo_gj_rt <- geo_gj_raw %>% odata_submission_rectangle(form_schema = geo_fs) geo_wkt_rt <- geo_wkt_raw %>% odata_submission_rectangle(form_schema = geo_fs) # Data with first geoshape split gj_first_gt <- split_geoshape(geo_gj_rt, geo_fields[1], wkt = FALSE) cn_gj <- names(gj_first_gt) testthat::expect_true("shape_location_shape_gps_longitude" %in% cn_gj) testthat::expect_true("shape_location_shape_gps_latitude" %in% cn_gj) testthat::expect_true("shape_location_shape_gps_altitude" %in% cn_gj) testthat::expect_true( is.numeric(gj_first_gt$shape_location_shape_gps_longitude) ) testthat::expect_true( is.numeric(gj_first_gt$shape_location_shape_gps_latitude) ) testthat::expect_true( is.numeric(gj_first_gt$shape_location_shape_gps_altitude) ) wkt_first_gt <- split_geoshape(geo_wkt_rt, geo_fields[1], wkt = TRUE) cn_wkt <- names(wkt_first_gt) testthat::expect_true("shape_location_shape_gps_longitude" %in% cn_wkt) testthat::expect_true("shape_location_shape_gps_latitude" %in% cn_wkt) testthat::expect_true("shape_location_shape_gps_altitude" %in% cn_wkt) testthat::expect_true( is.numeric(wkt_first_gt$shape_location_shape_gps_longitude) ) testthat::expect_true( is.numeric(wkt_first_gt$shape_location_shape_gps_latitude) ) testthat::expect_true( is.numeric(wkt_first_gt$shape_location_shape_gps_altitude) ) ## End(Not run)
## Not run: library(magrittr) data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # Find variable names of geoshapes geo_fields <- geo_fs %>% dplyr::filter(type == "geoshape") %>% magrittr::extract2("ruodk_name") geo_fields[1] # First geoshape in data: shape_location_shape_gps # Rectangle but don't parse submission data (GeoJSON and WKT) geo_gj_rt <- geo_gj_raw %>% odata_submission_rectangle(form_schema = geo_fs) geo_wkt_rt <- geo_wkt_raw %>% odata_submission_rectangle(form_schema = geo_fs) # Data with first geoshape split gj_first_gt <- split_geoshape(geo_gj_rt, geo_fields[1], wkt = FALSE) cn_gj <- names(gj_first_gt) testthat::expect_true("shape_location_shape_gps_longitude" %in% cn_gj) testthat::expect_true("shape_location_shape_gps_latitude" %in% cn_gj) testthat::expect_true("shape_location_shape_gps_altitude" %in% cn_gj) testthat::expect_true( is.numeric(gj_first_gt$shape_location_shape_gps_longitude) ) testthat::expect_true( is.numeric(gj_first_gt$shape_location_shape_gps_latitude) ) testthat::expect_true( is.numeric(gj_first_gt$shape_location_shape_gps_altitude) ) wkt_first_gt <- split_geoshape(geo_wkt_rt, geo_fields[1], wkt = TRUE) cn_wkt <- names(wkt_first_gt) testthat::expect_true("shape_location_shape_gps_longitude" %in% cn_wkt) testthat::expect_true("shape_location_shape_gps_latitude" %in% cn_wkt) testthat::expect_true("shape_location_shape_gps_altitude" %in% cn_wkt) testthat::expect_true( is.numeric(wkt_first_gt$shape_location_shape_gps_longitude) ) testthat::expect_true( is.numeric(wkt_first_gt$shape_location_shape_gps_latitude) ) testthat::expect_true( is.numeric(wkt_first_gt$shape_location_shape_gps_altitude) ) ## End(Not run)
split_geotrace( data, colname, wkt = FALSE, odkc_version = get_default_odkc_version() )
split_geotrace( data, colname, wkt = FALSE, odkc_version = get_default_odkc_version() )
data |
(dataframe) A dataframe with a geotrace column. |
colname |
(chr) The name of the geotrace column. This column will be retained. |
wkt |
Whether geofields are GeoJSON (if FALSE) or WKT strings (if TRUE), default: FALSE. |
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 Default: Set default See |
This function is used by handle_ru_geopoints
on all geopoint
fields as per form_schema
.
The format of the geotrace (GeoJSON, WKT, ODK Linestring) is determined via
parameters wkt
and odkc_version
, rather than inferred from the class of
the column. ODK Linestrings are character vectors without a leading
"LINESTRING (", WKT are character vectors with a leading "LINESTRING (",
and GeoJSON are list columns.
The given dataframe with the geotrace column colname, plus
three new columns, colname_longitude
, colname_latitude
,
colname_altitude
.
The three new columns are prefixed with the original colname
to
avoid naming conflicts with any other geotrace columns.
Other utilities:
attachment_get()
,
attachment_link()
,
attachment_url()
,
drop_null_coords()
,
form_schema_parse()
,
get_one_attachment()
,
get_one_submission()
,
get_one_submission_attachment_list()
,
get_one_submission_audit()
,
handle_ru_attachments()
,
handle_ru_datetimes()
,
handle_ru_geopoints()
,
handle_ru_geoshapes()
,
handle_ru_geotraces()
,
isodt_to_local()
,
odata_submission_rectangle()
,
predict_ruodk_name()
,
prepend_uuid()
,
split_geopoint()
,
split_geoshape()
,
strip_uuid()
,
tidyeval
,
unnest_all()
## Not run: library(magrittr) data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # Find variable names of geotraces geo_fields <- geo_fs %>% dplyr::filter(type == "geotrace") %>% magrittr::extract2("ruodk_name") geo_fields[1] # First geotrace in data: path_location_path_gps # Rectangle but don't parse submission data (GeoJSON and WKT) geo_gj_rt <- geo_gj_raw %>% odata_submission_rectangle(form_schema = geo_fs) geo_wkt_rt <- geo_wkt_raw %>% odata_submission_rectangle(form_schema = geo_fs) # Data with first geotrace split gj_first_gt <- split_geotrace(geo_gj_rt, geo_fields[1], wkt = FALSE) testthat::expect_true( "path_location_path_gps_longitude" %in% names(gj_first_gt) ) testthat::expect_true( "path_location_path_gps_latitude" %in% names(gj_first_gt) ) testthat::expect_true( "path_location_path_gps_altitude" %in% names(gj_first_gt) ) testthat::expect_true( is.numeric(gj_first_gt$path_location_path_gps_longitude) ) testthat::expect_true( is.numeric(gj_first_gt$path_location_path_gps_latitude) ) testthat::expect_true( is.numeric(gj_first_gt$path_location_path_gps_altitude) ) wkt_first_gt <- split_geotrace(geo_wkt_rt, geo_fields[1], wkt = TRUE) testthat::expect_true( "path_location_path_gps_longitude" %in% names(wkt_first_gt) ) testthat::expect_true( "path_location_path_gps_latitude" %in% names(wkt_first_gt) ) testthat::expect_true( "path_location_path_gps_altitude" %in% names(wkt_first_gt) ) testthat::expect_true( is.numeric(wkt_first_gt$path_location_path_gps_longitude) ) testthat::expect_true( is.numeric(wkt_first_gt$path_location_path_gps_latitude) ) testthat::expect_true( is.numeric(wkt_first_gt$path_location_path_gps_altitude) ) ## End(Not run)
## Not run: library(magrittr) data("geo_fs") data("geo_wkt_raw") data("geo_gj_raw") # Find variable names of geotraces geo_fields <- geo_fs %>% dplyr::filter(type == "geotrace") %>% magrittr::extract2("ruodk_name") geo_fields[1] # First geotrace in data: path_location_path_gps # Rectangle but don't parse submission data (GeoJSON and WKT) geo_gj_rt <- geo_gj_raw %>% odata_submission_rectangle(form_schema = geo_fs) geo_wkt_rt <- geo_wkt_raw %>% odata_submission_rectangle(form_schema = geo_fs) # Data with first geotrace split gj_first_gt <- split_geotrace(geo_gj_rt, geo_fields[1], wkt = FALSE) testthat::expect_true( "path_location_path_gps_longitude" %in% names(gj_first_gt) ) testthat::expect_true( "path_location_path_gps_latitude" %in% names(gj_first_gt) ) testthat::expect_true( "path_location_path_gps_altitude" %in% names(gj_first_gt) ) testthat::expect_true( is.numeric(gj_first_gt$path_location_path_gps_longitude) ) testthat::expect_true( is.numeric(gj_first_gt$path_location_path_gps_latitude) ) testthat::expect_true( is.numeric(gj_first_gt$path_location_path_gps_altitude) ) wkt_first_gt <- split_geotrace(geo_wkt_rt, geo_fields[1], wkt = TRUE) testthat::expect_true( "path_location_path_gps_longitude" %in% names(wkt_first_gt) ) testthat::expect_true( "path_location_path_gps_latitude" %in% names(wkt_first_gt) ) testthat::expect_true( "path_location_path_gps_altitude" %in% names(wkt_first_gt) ) testthat::expect_true( is.numeric(wkt_first_gt$path_location_path_gps_longitude) ) testthat::expect_true( is.numeric(wkt_first_gt$path_location_path_gps_latitude) ) testthat::expect_true( is.numeric(wkt_first_gt$path_location_path_gps_altitude) ) ## End(Not run)
submission_audit_get( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
submission_audit_get( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
iid |
A list of submission instance IDs, e.g. from
|
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
Uses get_one_submission_audit
on a list of submission
instance IDs
(iid
) as returned from submission_list$instance_id
.
By giving the list of iid
to download explicitly, that list can be
modified using information not accessible to ruODK
,
e.g. iid
can be restricted to "only not already downloaded submissions".
To get the combined submission audit logs for one form
as one single, concatenated audit.csv
file, use submission_export
.
A nested list of submission audit logs.
https://docs.getodk.org/central-api-submission-management/#retrieving-submission-xml
Other submission-management:
attachment_list()
,
encryption_key_list()
,
submission_detail()
,
submission_export()
,
submission_get()
,
submission_list()
## Not run: # Step 1: Setup ruODK with OData Service URL (has url, pid, fid) ruODK::ru_setup(svc = "...") # Step 2: List all submissions of form sl <- submission_list() # Step 3: Get submission audit logs sa <- submission_audit_get(sl$instance_id) ## End(Not run)
## Not run: # Step 1: Setup ruODK with OData Service URL (has url, pid, fid) ruODK::ru_setup(svc = "...") # Step 2: List all submissions of form sl <- submission_list() # Step 3: Get submission audit logs sa <- submission_audit_get(sl$instance_id) ## End(Not run)
submission_detail( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
submission_detail( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
iid |
The |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
A nested list of submission metadata.
https://docs.getodk.org/central-api-submission-management/#getting-submission-metadata
Other submission-management:
attachment_list()
,
encryption_key_list()
,
submission_audit_get()
,
submission_export()
,
submission_get()
,
submission_list()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") sl <- submission_list() sub <- submission_detail(sl$instance_id[[1]]) # The details for one submission return exactly one row nrow(sub) # > 1 # The columns are metadata about the submission and the submitter names(sub) # > "instance_id" "submitter_id" "submitter_type" "submitter_display_name" # > "submitter_created_at" "device_id" "created_at" ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") sl <- submission_list() sub <- submission_detail(sl$instance_id[[1]]) # The details for one submission return exactly one row nrow(sub) # > 1 # The columns are metadata about the submission and the submitter names(sub) # > "instance_id" "submitter_id" "submitter_type" "submitter_display_name" # > "submitter_created_at" "device_id" "created_at" ## End(Not run)
submission_export( local_dir = here::here(), overwrite = TRUE, media = TRUE, repeats = TRUE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), pp = get_default_pp(), retries = get_retries(), odkc_version = get_default_odkc_version(), verbose = get_ru_verbose() )
submission_export( local_dir = here::here(), overwrite = TRUE, media = TRUE, repeats = TRUE, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), pp = get_default_pp(), retries = get_retries(), odkc_version = get_default_odkc_version(), verbose = get_ru_verbose() )
local_dir |
The local folder to save the downloaded files to,
default: |
overwrite |
Whether to overwrite previously downloaded zip files, default: FALSE |
media |
Whether to include media attachments, default: TRUE. This feature only has effect on ODK Central v1.1 and higher. Setting this feature to FALSE with an odkc_version < 1.1 and will display a verbose noop message, but still return all media attachments. |
repeats |
Whether to include repeat data (if TRUE), or whether
to return the root table only (FALSE). Default: TRUE.
Requesting |
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
pp |
The passphrase for an encrypted form. Default: NULL. Passphrases can be stored e.g. as environment variables. See |
retries |
The number of attempts to retrieve a web resource. This parameter is given to 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 Default: Set default See |
verbose |
Whether to display debug messages or not. Read |
This function exports all the Submission data associated with a Form as one zip file containing one or more CSV files, as well as all multimedia attachments associated with the included Submissions.
For an incremental download of a subset of submissions, use
submission_list
or odata_submission_get
with
filter queries.
The inclusion of subtables (from repeating form groups) can be toggled
through repeats
, whereas the inclusion of media attachments can be toggled
through media
.
The file will be downloaded to the project root unless specified otherwise
(via local_dir
). Subsequently, the zip file can be extracted.
Attachment filenames (e.g. "12345.jpg") should be prepended with media
(resulting in e.g. media/12345.jpg
) in order to represent the relative
path to the actual attachment file (as extracted from the zip file).
ODK Central supports two modes of encryption - learn about them
here.
ruODK
supports project managed encryption, however the support is limited
to exactly one encryption key. The supplied passphrase will be used against
the first returned encryption key. Remaining encryption keys are ignored by
ruODK
.
If an incorrect passphrase is given, the request is terminated immediately. It has been reported that multiple requests with incorrect passphrases can crash ODK Central.
The absolute path to the exported ZIP file named after the form ID.
The exported ZIP file will have the extension .zip
unless only the
root table was requested (with repeats=FALSE
), in which case the
exported file will have the extension .csv
.
In contrast to ODK Central, which exports to submissions.csv(.zip)
,
the exported ZIP file is named after
the form to avoid accidentally overwriting the ZIP export from
another form.
https://docs.getodk.org/central-api-submission-management/#exporting-form-submissions-to-csv
Other submission-management:
attachment_list()
,
encryption_key_list()
,
submission_audit_get()
,
submission_detail()
,
submission_get()
,
submission_list()
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") se <- submission_export() # Unzip and inspect the loot t <- tempdir() f <- unzip(se, exdir = t) fs::dir_ls(t) fid <- get_test_fid() sub <- fs::path(t, glue::glue("{fid}.csv")) %>% readr::read_csv() sub %>% knitr::kable(.) ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") se <- submission_export() # Unzip and inspect the loot t <- tempdir() f <- unzip(se, exdir = t) fs::dir_ls(t) fid <- get_test_fid() sub <- fs::path(t, glue::glue("{fid}.csv")) %>% readr::read_csv() sub %>% knitr::kable(.) ## End(Not run)
Uses get_one_submission
on a list of submission instance IDs
(iid
) as returned from submission_list$instance_id
.
By giving the list of iid
to download explicitly, that list can be
modified using information not accessible to ruODK
,
e.g. iid
can be restricted to "only not already downloaded submissions".
submission_get( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
submission_get( iid, pid = get_default_pid(), fid = get_default_fid(), url = get_default_url(), un = get_default_un(), pw = get_default_pw(), retries = get_retries() )
iid |
A list of submission instance IDs, e.g. from
|
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
Forms with submission audit enabled will also receive the submission audit
as audit.csv
. This will overwrite all previous audit.csv
files.
To get the combined submission audit logs as one single, concatenated
audit.csv
file, use submission_export
.
Note that the submission audit is different from the server audit.
The submission audit logs the actions of the enumerator in ODK Collect,
whereas the form audit logs the actions of the project manager in
ODK Central.
A nested list of submission data.
https://docs.getodk.org/central-api-submission-management/#retrieving-submission-xml
Other submission-management:
attachment_list()
,
encryption_key_list()
,
submission_audit_get()
,
submission_detail()
,
submission_export()
,
submission_list()
## Not run: # Step 1: Setup ruODK with OData Service URL (has url, pid, fid) ruODK::ru_setup(svc = "...") # Step 2: List all submissions of form sl <- submission_list() # Step 3: Get submissions subs <- submission_get(sl$instance_id) ## End(Not run)
## Not run: # Step 1: Setup ruODK with OData Service URL (has url, pid, fid) ruODK::ru_setup(svc = "...") # Step 2: List all submissions of form sl <- submission_list() # Step 3: Get submissions subs <- submission_get(sl$instance_id) ## End(Not run)
submission_list( pid = get_default_pid(), fid = get_default_fid(), 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"), tz = get_default_tz() )
submission_list( pid = get_default_pid(), fid = get_default_fid(), 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"), tz = get_default_tz() )
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
fid |
The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147". Default: Set default See |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
A tibble containing some high-level details of the form submissions. One row per submission, columns are submission attributes:
* instance_id: uuid, string. The unique ID for each submission. * submitter_id: user ID, integer. * created_at: time of submission upload, dttm * updated_at: time of submission update on server, dttm or NA
https://docs.getodk.org/central-api-submission-management/#listing-all-submissions-on-a-form
Other submission-management:
attachment_list()
,
encryption_key_list()
,
submission_audit_get()
,
submission_detail()
,
submission_export()
,
submission_get()
## Not run: # Set default credentials, see vignette("setup") ruODK::ru_setup( svc = ..., un = "[email protected]", pw = "..." ) sl <- submission_list() sl %>% knitr::kable(.) fl <- form_list() # submission_list returns a tibble class(sl) # > c("tbl_df", "tbl", "data.frame") # Submission attributes are the tibble's columns names(sl) # > "instance_id" "submitter_id" "device_id" "created_at" "updated_at" # Number of submissions (rows) is same as advertised in form_list form_list_nsub <- fl %>% filter(fid == get_test_fid()) %>% magrittr::extract2("submissions") %>% as.numeric() nrow(sl) == form_list_nsub # > TRUE ## End(Not run)
## Not run: # Set default credentials, see vignette("setup") ruODK::ru_setup( svc = ..., un = "[email protected]", pw = "..." ) sl <- submission_list() sl %>% knitr::kable(.) fl <- form_list() # submission_list returns a tibble class(sl) # > c("tbl_df", "tbl", "data.frame") # Submission attributes are the tibble's columns names(sl) # > "instance_id" "submitter_id" "device_id" "created_at" "updated_at" # Number of submissions (rows) is same as advertised in form_list form_list_nsub <- fl %>% filter(fid == get_test_fid()) %>% magrittr::extract2("submissions") %>% as.numeric() nrow(sl) == form_list_nsub # > TRUE ## End(Not run)
user_list( qry = NULL, 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"), tz = get_default_tz(), verbose = get_ru_verbose() )
user_list( qry = NULL, 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"), tz = get_default_tz(), verbose = get_ru_verbose() )
qry |
A query string to filter users by. The query string is not case
sensitive and can contain special characters, such as The query string must be at least 5 alphabetic characters long to
return good enough matches.
E.g. Default: |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
verbose |
Whether to display debug messages or not. Read |
Currently, there are no paging or filtering options, so listing Users will get you every User in the system, every time. Optionally, a q query string parameter may be provided to filter the returned users by any given string. The search is performed via a trigram similarity index over both the Email and Display Name fields, and results are ordered by match score, best matches first. If a q parameter is given, and it exactly matches an email address that exists in the system, that user's details will always be returned, even for actors who cannot user.list. The request must still authenticate as a valid Actor. This allows non-Administrators to choose a user for an action (e.g. grant rights) without allowing full search.
Actors who cannot user.list
will always receive [] with a 200 OK response.
ruODK does not (yet) warn if this is the case, and you (the requesting Actor)
have no permission to user.list
.
A tibble with user details as per the ODK Central API docs.
https://docs.getodk.org/central-api-accounts-and-users/#listing-all-users
https://www.postgresql.org/docs/9.6/pgtrgm.html
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # All users ul <- user_list() # Search users # Given a user with display name "Janette Doe" and email "@org.com.au" user_list(qry = "jan") # no results, query string too short user_list(qry = "jane") # no results, query string too short user_list(qry = "janet") # returns Janette user_list(qry = "@org") # no results, query string too short user_list(qry = "@org.c") # no results, query string too short user_list(qry = "@org.co") # returns all users matching "@org.co" # Actor not allowed to user.list user_list() # If this is empty, you might not have permissions to list users ## End(Not run)
## Not run: # See vignette("setup") for setup and authentication options # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...") # All users ul <- user_list() # Search users # Given a user with display name "Janette Doe" and email "@org.com.au" user_list(qry = "jan") # no results, query string too short user_list(qry = "jane") # no results, query string too short user_list(qry = "janet") # returns Janette user_list(qry = "@org") # no results, query string too short user_list(qry = "@org.c") # no results, query string too short user_list(qry = "@org.co") # returns all users matching "@org.co" # Actor not allowed to user.list user_list() # If this is empty, you might not have permissions to list users ## End(Not run)