Package 'ruODK'

Description

Usage

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()
)

Arguments

Details

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

Value

The relative file path for the downloaded attachment(s)

See Also

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_att_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()

Examples

## 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)

Description

Usage

attachment_link(data_tbl, form_schema, att_path = "media")

Arguments

Value

The dataframe with attachment columns modified to contain relative paths to the downloaded attachment files.

See Also

Other utilities: attachment_get(), attachment_url(), drop_null_coords(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_att_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()

Examples

## 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)

Description

List all attachments for a list of submission instances.

Usage

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()
)

Arguments

Value

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.

See Also

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()

Examples

## 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_att_list(sl$instance_id[[1]])

# Ste 3b: Get all attachments for all submissions
all <- attachment_list(sl$instance_id)

## End(Not run)

Description

Usage

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()
)

Arguments

Details

Parameters to filter the audit logs: ⁠action=form.create&start=2000-01-01z&end=2000-12-31T23%3A59.999z⁠

Value

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.

See Also

https://docs.getodk.org/central-api-system-endpoints/#getting-audit-log-entries

Examples

## 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)

Description

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⁠.

Usage

drop_null_coords(x)

Arguments

Details

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).

Value

The nested list minus the last element (if NULL).

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), form_schema_parse(), get_one_attachment(), get_one_submission(), get_one_submission_att_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()

Examples

# 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)

Description

Usage

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 = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

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.

Value

A tibble of encryption keys.

See Also

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()

Examples

## 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)

Description

Usage

entity_audits(
  pid = get_default_pid(),
  did = "",
  eid = "",
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

This returns Server Audit Logs relating to an Entity. The most recent log is returned first.

The authenticated user must have permissions on ODK Central to retrieve audit logs.

Value

A tibble with one row per audit log. See https://docs.getodk.org/central-api-entity-management/#entity-audit-log for the full schema. Top level list elements are renamed from ODK's camelCase to snake_case.

See Also

https://docs.getodk.org/central-api-entity-management/#entity-audit-log

Other entity-management: entity_changes(), entity_create(), entity_delete(), entity_detail(), entity_list(), entity_update(), entity_versions(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

el <- entitylist_list()

# Entity List name (dataset ID, did)
did <- el$name[1]

# All Entities of Entity List
en <- entity_list(did = did)

ed <- entity_detail(did = did, eid = en$uuid[1])

e_label <- ed$current_version$label

# This example updates one field which exists in the example form.
# Your own Entity will have different fields to update.
e_data <- list(
  details = paste0(
    ed$current_version$data$details, ". Updated on ", Sys.time()
  )
)

# Update the Entity (implicitly forced update)
eu <- entity_update(
  did = did,
  eid = en$uuid[1],
  label = e_label,
  data = e_data
)

# Return the server audit logs
ea <- entity_audits(did = did, eid = en$uuid[1])
ea

## End(Not run)

Description

Usage

entity_changes(
  pid = get_default_pid(),
  did = "",
  eid = "",
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

This returns the changes, or edits, between different versions of an Entity. These changes are returned as a list of lists. Between two Entities, there is a list of objects representing how each property changed. This change object contains the old and new values, as well as the property name.

Value

A tibble where rows correspond to each Entity update with three columns:

• old old value

• new new value

• propertyName name of changed entity property

See Also

https://docs.getodk.org/central-api-entity-management/#getting-changes-between-versions

Other entity-management: entity_audits(), entity_create(), entity_delete(), entity_detail(), entity_list(), entity_update(), entity_versions(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

el <- entitylist_list()

# Entity List name (dataset ID, did)
did <- el$name[1]

# All Entities of Entity List
en <- entity_list(did = did)

ed <- entity_detail(did = did, eid = en$uuid[1])

e_label <- ed$current_version$label

# This example updates one field which exists in the example form.
# Your own Entity will have different fields to update.
e_data <- list(
  details = paste0(
    ed$current_version$data$details, ". Updated on ", Sys.time()
  )
)

# Update the Entity (implicitly forced update)
eu <- entity_update(
  did = did,
  eid = en$uuid[1],
  label = e_label,
  data = e_data
)

ec <- entity_changes(did = did, eid = en$uuid[1])
ec

## End(Not run)

Description

Usage

entity_create(
  pid = get_default_pid(),
  did = "",
  label = "",
  uuid = "",
  notes = "",
  data = list(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

Creating a single Entity

For creating a single Entity, include

• An optional uuid. If skipped, Central will create a UUID for the Entity.

• The Entity label must be non-empty.

• A named list data representing the Entity's fields. The value type of all properties is string.

uuid = "..." label = "John Doe" data = list("firstName" = "John", "age" = "22")

This translates to JSON

⁠{ "label": "John Doe", "data": { "firstName": "John", "age": "22" } }⁠

Creating multiple Entities

For creating multiple Entities in bulk, the request body takes an array entities containing a list of Entity objects as described above. The bulk entity version also takes a source property with a required name field and optional size, for example to capture the file name and size of a bulk upload source (in MB).

data=list(
    "entities" = c(
      list("label" = "Entity 1", "data" = list("field1" = "value1")),
      list("label" = "Entity 2", "data" = list("field1" = "value2"))
    ),
    "source" = list("name" = "file.csv", "size" = 100)
  )

This translates to JSON

⁠{ "entities": [...], "source": {"name": "file.csv", "size": 100} }⁠

You can provide notes to store the metadata about the request. The metadata is included in the POST request as header X-Action-Notes and can retrieved using Entity Audit Log.

Value

A nested list identical to the return value of entity_detail. See https://docs.getodk.org/central-api-entity-management/#creating-entities for the full schema. Top level list elements are renamed from ODK's camelCase to snake_case. Nested list elements have the original camelCase.

See Also

https://docs.getodk.org/central-api-entity-management/#creating-entities

Other entity-management: entity_audits(), entity_changes(), entity_delete(), entity_detail(), entity_list(), entity_update(), entity_versions(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

el <- entitylist_list()

# Entity List name (dataset ID, did)
did <- el$name[1]

# All Entities of Entity List
en <- entity_list(did = did)

# Create a single entity
ec <- entity_create(
  did = did,
  label = "Entity label",
  notes = "Metadata about the created entity",
  data = list("field1" = "value1", "field2" = "value1")
)
ec

# Create multiple entities, example: test form "problems"
label <- c(
  glue::glue(
    "Entity {nrow(en) + 1} created by ruODK package test on {Sys.time()}"
  ),
  glue::glue(
    "Entity {nrow(en) + 2} created by ruODK package test on {Sys.time()}"
  )
)
notes <- glue::glue("Two entities created by ruODK package test on {Sys.time()}")
status <- c("needs_followup", "needs_followup")
details <- c("ruODK package test", "ruODK package test")
geometry <- c("-33.2 115.0 0.0 0.0", "-33.2 115.0 0.0 0.0")
data <- data.frame(status, details, geometry, stringsAsFactors = FALSE)
request_data <- list(
  "entities" = data.frame(label, data = I(data), stringsAsFactors = FALSE),
  "source" = list("name" = "file.csv", "size" = 100)
)

# Compare request_data to the schema expected by Central
# https://docs.getodk.org/central-api-entity-management/#creating-entities
# jsonlite::toJSON(request_data, pretty = TRUE, auto_unbox = TRUE)

ec <- entity_create(
  did = did,
  notes = notes,
  data = request_data
)

## End(Not run)

Description

Usage

entity_delete(
  pid = get_default_pid(),
  did = "",
  eid = "",
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

This function soft-deletes one Entity, , which means it is still in Central's database and you can retrieve it via entity_list(deleted=TRUE).

Value

A list with the key "success" (lgl) indicating whether the entity was deleted.

See Also

https://docs.getodk.org/central-api-entity-management/#deleting-an-entity

Other entity-management: entity_audits(), entity_changes(), entity_create(), entity_detail(), entity_list(), entity_update(), entity_versions(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

el <- entitylist_list()

# Entity List name (dataset ID, did)
did <- el$name[1]

# All Entities of Entity List
en <- entity_list(did = did)

# View details of one Entity
ed <- entity_detail(did = did, eid = en$uuid[1])

# Delete the Entity
ed_deleted <- entity_delete(did = did, eid = ed$id)

## End(Not run)

Description

Usage

entity_detail(
  pid = get_default_pid(),
  did = "",
  eid = "",
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

This function returns the metadata and current data of an Entity.

The data and label of an Entity are found in the current_version columns under data and label respectively. The current_version column contains version-specific metadata fields such as version, baseVersion, details about conflicts that version introduced, etc. More details are available from entity_versions(). The Entity also contains top-level system metadata such as uuid, created_at and updated_at timestamps, and creator_id (or full creator if extended metadata is requested).

Conflicts

An Entity's metadata also has a conflict field, which indicates the current conflict status of the Entity. The value of a conflict can either be:

• null. The Entity does not have conflicting versions.

• soft. The Entity has a version that was based on a version other than the version immediately prior to it. (The specified base_version was not the latest version on the server.)

• hard. The Entity has a version that was based on a version other than the version immediately prior to it. Further, that version updated the same property as another update.

If an Entity has a conflict, it can be marked as resolved. After that, the conflict field will be null until a new conflicting version is received.

Value

A nested list identical to the return value of entity_update. See https://docs.getodk.org/central-api-entity-management/#getting-entity-details for the full schema. Top level list elements are renamed from ODK's camelCase to snake_case. Nested list elements have the original camelCase.

See Also

https://docs.getodk.org/central-api-entity-management/#entities-metadata

Other entity-management: entity_audits(), entity_changes(), entity_create(), entity_delete(), entity_list(), entity_update(), entity_versions(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

el <- entitylist_list()

# Entity List name (dataset ID, did)
did <- el$name[1]

# All Entities of Entity List
en <- entity_list(did = did)

ed <- entity_detail(did = did, eid = en$uuid[1])

# The current version of the first Entity
ev <- en$current_version_version[1]

## End(Not run)

Description

Usage

entity_list(
  pid = get_default_pid(),
  did = "",
  deleted = FALSE,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

This function returns a list of the Entities of a kind (belonging to an Entity List or Dataset). Please note that this endpoint only returns metadata of the entities, not the data. If you want to get the data of all entities then please refer to the OData Dataset Service.

You can get only deleted entities with deleted=TRUE.

Value

A tibble with exactly one row for each Entity of the given project as per ODK Central API docs. Column names are renamed from ODK's camelCase to snake_case.

See Also

https://docs.getodk.org/central-api-entity-management/#entities-metadata

Other entity-management: entity_audits(), entity_changes(), entity_create(), entity_delete(), entity_detail(), entity_update(), entity_versions(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

el <- entitylist_list()

# Entity List name (dataset ID)
did <- el$name[1]

# All Entities of Entity List
en <- entity_list(did = el$name[1])

# The UUID of the first Entity
eid <- en$uuid[1]

# The current version of the first Entity
ev <- en$current_version_version[1]

## End(Not run)

Description

Usage

entity_update(
  pid = get_default_pid(),
  did = "",
  eid = "",
  label = "",
  data = list(),
  base_version = NULL,
  force = is.null(base_version),
  resolve = FALSE,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

This endpoint is used to update the label or the properties (passed as JSON in the request body) of an Entity. You only need to include the properties you wish to update. To unset the value of any property, you can set it to empty string (""). The label must be a non-empty string. Setting a property to null will throw an error. Attempting to update a property that doesn't exist in the Dataset will throw an error.

Specifying a base version

You must either provide a base_version or use force=TRUE query parameter. You cannot cause a new Entity conflict via the API, which is why when specifying base_version, it must match the current version of the Entity on the server. This acts as a check to ensure you are not trying to update based on stale data. If you wish to update the Entity regardless of the current state, then you can use the force flag.

Resolving a conflict

You can also use this endpoint to resolve an Entity conflict by passing resolve=true, in which case providing data is optional. When not providing new data, only the conflict status from the Entity will be cleared and no new version will be created. When providing data, the conflict will be cleared and an updated version of the Entity will be added.

Value

A nested list identical to the return value of entity_detail. See https://docs.getodk.org/central-api-entity-management/#updating-an-entity for the full schema. Top level list elements are renamed from ODK's camelCase to snake_case. Nested list elements have the original camelCase.

See Also

https://docs.getodk.org/central-api-entity-management/#updating-an-entity

Other entity-management: entity_audits(), entity_changes(), entity_create(), entity_delete(), entity_detail(), entity_list(), entity_versions(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

el <- entitylist_list()

# Entity List name (dataset ID, did)
did <- el$name[1]

# All Entities of Entity List
en <- entity_list(did = did)

ed <- entity_detail(did = did, eid = en$uuid[1])

e_label <- ed$current_version$label

# This example updates one field which exists in the example form.
# Your own Entity will have different fields to update.
e_data <- list(
  details = paste0(
    ed$current_version$data$details, ". Updated on ", Sys.time()
  )
)

# Update the Entity (implicitly forced update)
eu <- entity_update(
  did = did,
  eid = en$uuid[1],
  label = e_label,
  data = e_data
)
eu

## End(Not run)

Description

Usage

entity_versions(
  pid = get_default_pid(),
  did = "",
  eid = "",
  conflict = FALSE,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

This returns the Entity metadata and data for every version of this Entity in ascending creation order.

The ODK Central endpoint supports retrieving extended metadata which this function always returns.

There is an optional query flag relevantToConflict that returns the subset of past versions of an Entity that are relevant to the Entity's current conflict. This includes the latest version, the base version, the previous server version, and any other versions since the last time the Entity was in a conflict-free state. If the Entity is not in conflict, zero versions are returned.

Value

A tibble with one row per version. List columns contain unstructured data. See https://docs.getodk.org/central-api-entity-management/#listing-versions for the full schema. Top level list elements are renamed from ODK's camelCase to snake_case. Nested list elements have the original camelCase.

See Also

https://docs.getodk.org/central-api-entity-management/#listing-versions

Other entity-management: entity_audits(), entity_changes(), entity_create(), entity_delete(), entity_detail(), entity_list(), entity_update(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## Not run: 
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")

el <- entitylist_list()

# Entity List name (dataset ID, did)
did <- el$name[1]

# All Entities of Entity List
en <- entity_list(did = did)

ed <- entity_detail(did = did, eid = en$uuid[1])

# The current version of the first Entity
ev <- en$current_version_version[1]

## End(Not run)

Description

Usage

entitylist_detail(
  pid = get_default_pid(),
  did = "",
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Value

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.

See Also

https://docs.getodk.org/central-api-dataset-management/#datasets

Other entity-management: entity_audits(), entity_changes(), entity_create(), entity_delete(), entity_detail(), entity_list(), entity_update(), entity_versions(), entitylist_download(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## 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$linked_forms |>
  purrr::list_transpose() |>
  tibble::as_tibble()

ds1$source_forms |>
  purrr::list_transpose() |>
  tibble::as_tibble()

ds1$properties |>
  purrr::list_transpose() |>
  tibble::as_tibble()

## End(Not run)

Description

Usage

entitylist_download(
  pid = get_default_pid(),
  did = "",
  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 = get_default_orders(),
  tz = get_default_tz(),
  verbose = get_ru_verbose()
)

Arguments

Details

CSV file

The downloaded CSV file is named after the entity list name. The download location defaults to the current workdir, but can be modified to a different folder path which will be created if it doesn't exist.

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, and the Dataset (Entity List) or Entity Properties themselves. If any Property for an given Entity is blank (e.g. it was not captured by that Form or was left blank), that field of the CSV is blank.

Filter

The ODK Central ⁠$filter⁠ query string parameter can be used to filter on system-level properties, similar to how filtering in the OData Dataset (Entity List) Service works. Of the OData filter specs 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.

Resuming downloads through ETag

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.

Value

A list of four items:

• entities (tbl_df) The Entity List as tibble

• http_status (int) The HTTP status code of the response. 200 if OK, 304 if a given etag finds no new entities created.

• etag (str) The ETag to use in subsequent calls to entitylist_download()

• downloaded_to (fs_path) The path to the downloaded CSV file

• downloaded_on (POSIXct) The time of download in the local timezone

See Also

https://docs.getodk.org/central-api-dataset-management/#datasets

Other entity-management: entity_audits(), entity_changes(), entity_create(), entity_delete(), entity_detail(), entity_list(), entity_update(), entity_versions(), entitylist_detail(), entitylist_list(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## 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)

Description

Usage

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 = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

The returned list is useful to retrieve the valid name of an Entity List for further use by functions of the Entity Management family.

Value

A tibble with exactly one row for each Entity List of the given Project as per ODK Central API docs. Column names are renamed from ODK Central's camelCase to snake_case.

See Also

https://docs.getodk.org/central-api-dataset-management/#datasets

Other entity-management: entity_audits(), entity_changes(), entity_create(), entity_delete(), entity_detail(), entity_list(), entity_update(), entity_versions(), entitylist_detail(), entitylist_download(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## 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)

Description

Usage

entitylist_update(
  pid = get_default_pid(),
  did = "",
  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 = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Details

You can only update approvalRequired using this endpoint. The approvalRequired flag controls the Entity creation flow; if it is true then the Submission must be approved before an Entity can be created from it and if it is false then an Entity is created as soon as the Submission is received by the ODK Central. By default approvalRequired is false for the Entity Lists created after v2023.3. Entity Lists created prior to that will have approvalRequired set to true.

Value

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.

See Also

https://docs.getodk.org/central-api-dataset-management/#datasets

Other entity-management: entity_audits(), entity_changes(), entity_create(), entity_delete(), entity_detail(), entity_list(), entity_update(), entity_versions(), entitylist_detail(), entitylist_download(), entitylist_list(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()

Examples

## 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)

Description

Usage

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()
)

Arguments

Value

A tibble with one row and all form metadata as columns.

See Also

https://docs.getodk.org/central-api-form-management/#getting-form-details

Other form-management: form_list(), form_schema(), form_schema_ext(), form_xml()

Examples

## 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)

Description

Usage

form_list(
  pid = get_default_pid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  orders = get_default_orders(),
  tz = get_default_tz()
)

Arguments

Value

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.

See Also

https://docs.getodk.org/central-api-form-management/#list-all-forms

Other form-management: form_detail(), form_schema(), form_schema_ext(), form_xml()

Examples

## 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)

Description

Usage

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()
)

Arguments

Details

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.

Value

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.

See Also

https://docs.getodk.org/central-api-form-management/#getting-form-schema-fields

Other form-management: form_detail(), form_list(), form_schema_ext(), form_xml()

Examples

## 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)

Description

Usage

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()
)

Arguments

Details

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.

Value

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.

See Also

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()

Examples

## 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)

Description

Usage

form_schema_parse(fs, path = "Submissions", verbose = get_ru_verbose())

Arguments

Details

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.

See Also

Other utilities: attachment_get(), attachment_link(), attachment_url(), drop_null_coords(), get_one_attachment(), get_one_submission(), get_one_submission_att_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()

Examples

## 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)

Description

Usage

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()
)

Arguments

Value

The form XML as a nested list.

See Also

https://docs.getodk.org/central-api-form-management/#retrieving-form-xml

Other form-management: form_detail(), form_list(), form_schema(), form_schema_ext()

Examples

## 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)

Description

Usage

fq_attachments

Format

A tibble of submission attachments.

Source

The output of attachment_list run on submissions of the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

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

Description

Usage

fq_data

Format

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>⁠.

Details

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.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and odata_submission_get.

See Also

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

Description

Usage

fq_data_strata

Format

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>⁠.

Details

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.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and odata_submission_get.

See Also

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

Description

Usage

fq_data_taxa

Format

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>⁠.

Details

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.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and odata_submission_get.

See Also

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

Description

Usage

fq_form_detail

Format

A tibble of form metadata.

Source

The output of form_detail run on submissions of the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

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

Description

Usage

fq_form_list

Format

A tibble of forms

Source

The output of form_list. run on the project.

See Also

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

Description

Usage

fq_form_schema

Format

The output of ruODK::form_schema(), a tibble with columns "type", "name" and "path" and one row per form field.

Details

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.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") and ruODK::form_schema().

See Also

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

Description

Usage

fq_form_xml

Format

A nested list of a form definition.

Source

The output of form_xml run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

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

Description

Usage

fq_meta

Format

A list of lists

Details

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.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

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

Description

Usage

fq_project_detail

Format

A tibble of project metadata.

Source

The output of project_detail run on the project containing the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

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

Description

Usage

fq_project_list

Format

A tibble of project metadata.

Source

The output of project_list run on all projects on the configured ODK Central server.

See Also

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

Description

Usage

fq_raw

Format

A list of lists

Details

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.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

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

Description

Usage

fq_raw_strata

Format

A list of lists

Details

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.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

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

Description

Usage

fq_raw_taxa

Format

A list of lists

Details

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.

Source

See system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

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

Description

Usage

fq_submission_list

Format

A tibble of submission metadata.

Source

The output of submission_list run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

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

Description

Usage

fq_submissions

Format

A nested list of submission data.

Source

The output of submission_get run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK") using submission instance IDs from submission_list.

See Also

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

Description

Usage

fq_svc

Format

A tibble with one row per submission data endpoint.

Details

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.

Source

OData service document for system.file("extdata", "FloraQuadrat04.xml", package = "ruODK")

See Also

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

Description

Usage

fq_zip_data

Format

A tibble of main records from a test form.

Source

submission_export run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

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

Description

Usage

fq_zip_strata

Format

A tibble of repeated sub-group of records from a test form.

Source

submission_export run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

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

Description

Usage

fq_zip_taxa

Format

A tibble of repeated sub-group of records from a test form.

Source

submission_export run on the test form system.file("extdata", "FloraQuadrat04.xml", package = "ruODK").

See Also

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

Description

Usage

fs_v7

Format

An object of class tbl_df (inherits from tbl, data.frame) with 12 rows and 3 columns.

Source

form_schema_parse(fs_v7_raw)

See Also

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

Description

Usage

fs_v7_raw

Format

An object of class list of length 6.

Source

form_schema(odkc_version = 0.7, parse = FALSE)

See Also

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

Description

Usage

geo_fs

Format

An object of class tbl_df (inherits from tbl, data.frame) with 19 rows and 6 columns.

Source

form_schema run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

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

Description

Usage

geo_gj

Format

An object of class tbl_df (inherits from tbl, data.frame) with 1 rows and 58 columns.

Source

odata_submission_get(wkt=FALSE, parse=TRUE) run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

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

Description

Usage

geo_gj_raw

Format

An object of class list of length 2.

Source

odata_submission_get(wkt=FALSE, parse=FALSE) run on the test form system.file("extdata", "Locations.xml", package = "ruODK").

See Also

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

Description

Usage

geo_gj88

Format