Skip to contents

OData API

Top-level functions to retrieve and parse data via the OData API. These functions alone are enough to retrieve all submissions with their nested tables and attachments and parse their datatypes. See vignette("odata-api") for a walkthrough.

odata_metadata_get() stable
Retrieve metadata from an OData URL ending in .svc as list of lists.
odata_service_get() stable
Retrieve service metadata from an OData URL ending in .svc as tibble.
odata_submission_get() stable
Retrieve and rectangle form submissions, parse dates, geopoints, download and link attachments.

Projects

Functions to manage projects.

project_create() experimental
Create a new project.
project_detail()
List all details of one project.
project_list()
List all projects.

Entities

An Entity List is a named collection of Entities that have the same properties. In the ODK Central API and in the related ODK XForms specification, collections of Entities are referred to as Datasets. The term “Entity List” is used for this concept in the Central frontend UI, user documentation, and all other text intended for end users who are not developers. Accordingly, ruODK uses the term “entitylist_” for Entity Lists.

entity_audits() maturing
Return server audit logs of one Entity.
entity_changes() maturing
List changes to one Entity.
entity_create() experimental
Creates exactly one Entity in the Dataset.
entity_delete() maturing
Delete one Entity.
entity_detail() maturing
Show metadata and current data of one Entity.
entity_list() maturing
List all Entities of a kind.
entity_update() experimental
Update one Entity.
entity_versions() maturing
List versions of one Entity.
entitylist_detail() maturing
Show Entity List details.
entitylist_download() maturing
Download an Entity List as CSV.
entitylist_list() maturing
List all Entity Lists of one Project.
entitylist_update() maturing
Update Entity List details.

Forms

Functions to manage forms. Once their implementation is completed, these functions can be used to manage the life cycle of forms from drafts to published forms, their retirement, form permissions, as well as form attachments.

form_detail() stable
Show details for one form.
form_list() stable
List all forms.
form_schema() stable
Show the schema of one form.
form_schema_ext() experimental
Show the extended schema of one form.
form_xml() stable
Show the XML representation of one form as list.

Submissions

Functions to manage submissions and their attachments. This family of functions provides an alternative way to the OData family. Specifically, submissions include nested tables in each record. See vignette("restful-api") for a walkthrough.

attachment_list()
List all attachments for a list of submission instances.
encryption_key_list() maturing
List all encryption keys for a form.
submission_audit_get() experimental
Get submission audits for a list of submission instance IDs.
submission_detail() stable
Show metadata for one submission.
submission_export() maturing
Export all form submissions including repeats and attachments to CSV.
submission_get()
Get submissions for a list of submission instance IDs.
submission_list() stable
List all submissions of one form.

Users

Functions to operate on users, roles, and their permissions.

user_list() maturing
List all users.

Server

Functions related to server management.

audit_get() stable
Get server audit log entries.

Utilities

Functions to assist with retrieval and parsing of submissions and their attachments. These functions are used from within top-level functions. The typical workflow does not call these explicitly.

attachment_get() stable
Download attachments and return the local path.
attachment_link() stable
Prefix attachment columns from CSV export with a local attachment file path.
drop_null_coords()
Drop any NULL coordinates from a GeoJSON geometry.
form_schema_parse() stable
Parse a form_schema into a tibble of fields with name, type, and path.
get_one_attachment() stable
Download one media attachment.
get_one_submission()
Download one submission.
get_one_submission_att_list() stable
List all attachments of one submission.
get_one_submission_audit() experimental
Download server audit logs for one submission.
handle_ru_attachments() stable
Download and link submission attachments according to a form schema.
handle_ru_datetimes() stable
Parse datetimes of submission data according to a form schema.
handle_ru_geopoints() stable
Split all geopoints of a submission tibble into their components.
handle_ru_geoshapes() stable
Split all geoshapes of a submission tibble into their components.
handle_ru_geotraces() stable
Split all geotraces of a submission tibble into their components.
odata_submission_rectangle() stable
Rectangle the output of odata_submission_get(parse=FALSE) into a tidy tibble and unnest all levels.
split_geopoint() stable
Annotate a dataframe containing a geopoint column with lon, lat, alt.
split_geoshape() stable
Annotate a dataframe containing a geoshape column with lon, lat, alt of the geotrace's first point.
split_geotrace() stable
Annotate a dataframe containing a geotrace column with lon, lat, alt of the geotrace's first point.

Messaging

Custom handlers for messages, warnings, and errors.

ru_msg_abort() stable
rlang::abort() with a red error message with a cross symbol.
ru_msg_info() stable
Print a blue info message with an info symbol.
ru_msg_noop() stable
Print a green noop message with a filled circle symbol.
ru_msg_success() stable
Print a green success message with a tick symbol.
ru_msg_warn() stable
rlang::warn() with a yellow warning message with a warning symbol.

Settings

Functions to manage ruODK settings.

odata_svc_parse() stable
Retrieve URL, project ID, and form ID from an ODK Central OData service URL.
parse_odkc_version() stable
Parse a given ODK Central version string or number into a semver.
ru_settings() get_default_pid() get_default_fid() get_default_url() get_default_un() get_default_pw() get_default_pp() get_default_tz() get_default_orders() 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() stable
Get or set ruODK settings.
ru_setup()
Configure default ruODK settings.
semver_gt()
Show whether a given semver is greater than a baseline version.
semver_lt()
Show whether a given semver is lesser than a baseline version.

Example data

Datasets included in ruODK, used in unit tests, code examples and vignettes.

fq_attachments stable
A tibble of submission attachments.
fq_data stable
Parsed submission data for an ODK Central form.
fq_data_strata stable
Parsed submission data for a subgroup of an ODK Central form.
fq_data_taxa stable
Parsed submission data for a subgroup of an ODK Central form.
fq_form_detail stable
A tibble of form metadata.
fq_form_list stable
A tibble of forms.
fq_form_schema stable
JSON form schema for an ODK Central form.
fq_form_xml stable
A nested list of a form definition.
fq_meta stable
OData metadata document for an ODK Central form.
fq_project_detail stable
A tibble of project metadata.
fq_project_list stable
A tibble of project metadata.
fq_raw stable
OData submission data for an ODK Central form.
fq_raw_strata stable
OData submission data for a subgroup of an ODK Central form.
fq_raw_taxa stable
OData submission data for a subgroup of an ODK Central form.
fq_submission_list stable
A tibble of submission metadata.
fq_submissions stable
A nested list of submission data.
fq_svc stable
OData service document for an ODK Central form.
fq_zip_data stable
A tibble of the main data table of records from a test form.
fq_zip_strata stable
A tibble of a repeated sub-group of records from a test form.
fq_zip_taxa stable
A tibble of a repeated sub-group of records from a test form.
fs_v7 stable
The parsed XML form_schema of a form from ODK Central v0.6.
fs_v7_raw stable
The unparsed XML form_schema of a form from ODK Central v0.6 as nested list.
geo_fs stable
The form_schema of a form containing geofields in GeoJSON.
geo_gj stable
The parsed submissions of a form containing geofields in GeoJSON.
geo_gj88 stable
The parsed submissions of a form containing geofields in GeoJSON with trailing empty coordinates present.
geo_gj_raw stable
The unparsed submissions of a form containing geofields in GeoJSON.
geo_wkt stable
The parsed submissions of a form containing geofields in WKT.
geo_wkt88 stable
The parsed submissions of a form containing geofields in WKT with trailing empty coordinates present.
geo_wkt_raw stable
The unparsed submissions of a form containing geofields in WKT.