Package 'ruODK'

Description

Usage

app_user_create(
  pid = get_default_pid(),
  display_name,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Details

The only information required to create a new App User is its display name (called "Nickname" in the administration panel). When an App User is created, it is assigned no rights. To grant rights, assign the App User a Form Role with form_assignment_grant().

Value

A tibble with one row holding the new App User's metadata as columns, including the token to authenticate requests as this App User. The token is only returned at creation time.

See Also

https://docs.getodk.org/central-api-accounts-and-users/#creating-a-new-app-user

Other user-management: app_user_delete(), app_user_list(), assignment_actors(), assignment_grant(), assignment_list(), assignment_revoke(), form_assignment_list(), project_assignment_list(), role_detail(), role_list(), user_create(), user_delete(), user_detail(), user_list(), user_preference_project_delete(), user_preference_project_set(), user_preference_site_delete(), user_preference_site_set(), user_reset_password(), user_update(), user_update_password()

Examples

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

au <- app_user_create(display_name = "My App User")

au |> knitr::kable()

## End(Not run)

Description

Usage

app_user_delete(
  pid = get_default_pid(),
  id,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Details

Deleting an App User revokes its access.

Value

A list with a single element success (TRUE) as per the ODK Central API docs.

See Also

https://docs.getodk.org/central-api-accounts-and-users/#deleting-an-app-user

Other user-management: app_user_create(), app_user_list(), assignment_actors(), assignment_grant(), assignment_list(), assignment_revoke(), form_assignment_list(), project_assignment_list(), role_detail(), role_list(), user_create(), user_delete(), user_detail(), user_list(), user_preference_project_delete(), user_preference_project_set(), user_preference_site_delete(), user_preference_site_set(), user_reset_password(), user_update(), user_update_password()

Examples

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

au <- app_user_list()

app_user_delete(id = au$id[[1]])
# > $success
# > [1] TRUE

## End(Not run)

Description

Usage

app_user_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

Details

App Users may only be created, fetched, and manipulated within the nested Projects subresource, as App Users themselves are limited to the Project in which they are created.

Value

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

See Also

https://docs.getodk.org/central-api-accounts-and-users/#listing-all-app-users

Other user-management: app_user_create(), app_user_delete(), assignment_actors(), assignment_grant(), assignment_list(), assignment_revoke(), form_assignment_list(), project_assignment_list(), role_detail(), role_list(), user_create(), user_delete(), user_detail(), user_list(), user_preference_project_delete(), user_preference_project_set(), user_preference_site_delete(), user_preference_site_set(), user_reset_password(), user_update(), user_update_password()

Examples

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

au <- app_user_list()

au |> knitr::kable()

## End(Not run)

Description

Usage

assignment_actors(
  role_id,
  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

Given a Role, this endpoint lists all Actors that have been assigned that Role upon the entire system. This endpoint requires ODK Central v0.5 or later.

Value

A tibble with one row for each Actor assigned the Role as per the ODK Central API docs. Column names are renamed from ODK's camelCase to snake_case.

See Also

https://docs.getodk.org/central-api-accounts-and-users/#listing-all-actors-assigned-some-role

Other user-management: app_user_create(), app_user_delete(), app_user_list(), assignment_grant(), assignment_list(), assignment_revoke(), form_assignment_list(), project_assignment_list(), role_detail(), role_list(), user_create(), user_delete(), user_detail(), user_list(), user_preference_project_delete(), user_preference_project_set(), user_preference_site_delete(), user_preference_site_set(), user_reset_password(), user_update(), user_update_password()

Examples

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

aa <- assignment_actors(role_id = "admin")

aa |> knitr::kable()

## End(Not run)

Description

Usage

assignment_grant(
  role_id,
  actor_id,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version()
)

Arguments

Details

Given a Role and an Actor, this endpoint assigns that Role to that Actor upon all system objects. No request body data is required. This endpoint requires ODK Central v0.5 or later.

Value

A list with a single element success (TRUE) as per the ODK Central API docs.

See Also

https://docs.getodk.org/central-api-accounts-and-users/#assigning-an-actor-to-a-server-wide-role

Other user-management: app_user_create(), app_user_delete(), app_user_list(), assignment_actors(), assignment_list(), assignment_revoke(), form_assignment_list(), project_assignment_list(), role_detail(), role_list(), user_create(), user_delete(), user_detail(), user_list(), user_preference_project_delete(), user_preference_project_set(), user_preference_site_delete(), user_preference_site_set(), user_reset_password(), user_update(), user_update_password()

Examples

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

assignment_grant(role_id = "admin", actor_id = 14)
# > $success
# > [1] TRUE

## End(Not run)

Description

Usage

assignment_list(
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Details

This lists every server-wide Assignment in the form of actor_id/role_id pairs. It does not list Project-specific Assignments; those need project_assignment_list().

Value

A tibble with one row per Assignment and the columns actor_id and role_id.

See Also

https://docs.getodk.org/central-api-accounts-and-users/#listing-all-assignments

Other user-management: app_user_create(), app_user_delete(), app_user_list(), assignment_actors(), assignment_grant(), assignment_revoke(), form_assignment_list(), project_assignment_list(), role_detail(), role_list(), user_create(), user_delete(), user_detail(), user_list(), user_preference_project_delete(), user_preference_project_set(), user_preference_site_delete(), user_preference_site_set(), user_reset_password(), user_update(), user_update_password()

Examples

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

al <- assignment_list()

al |> knitr::kable()

## End(Not run)

Description

Usage

assignment_revoke(
  role_id,
  actor_id,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version()
)

Arguments

Details

Given a Role and an Actor, this endpoint unassigns that Role from that Actor upon all system objects. This endpoint requires ODK Central v0.5 or later.

Value

A list with a single element success (TRUE) as per the ODK Central API docs.

See Also

https://docs.getodk.org/central-api-accounts-and-users/#stripping-an-role-assignment-from-an-actor

Other user-management: app_user_create(), app_user_delete(), app_user_list(), assignment_actors(), assignment_grant(), assignment_list(), form_assignment_list(), project_assignment_list(), role_detail(), role_list(), user_create(), user_delete(), user_detail(), user_list(), user_preference_project_delete(), user_preference_project_set(), user_preference_site_delete(), user_preference_site_set(), user_reset_password(), user_update(), user_update_password()

Examples

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

assignment_revoke(role_id = "admin", actor_id = 14)
# > $success
# > [1] TRUE

## End(Not run)

Description

Usage

attachment_delete(
  iid,
  filename,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Details

Because Submission Attachments are completely determined by the XML data of the Submission itself, there is no direct way to entirely remove a Submission Attachment entry from the list, only to clear its uploaded content. Thus, a DELETE to the attachment's endpoint clears the uploaded bytes while the expected file slot remains listed. This endpoint clears attachments on the current version of the Submission.

Value

A list with a single element success (TRUE) as per the ODK Central API docs.

See Also

https://docs.getodk.org/central-api-submission-management/#clearing-a-submission-attachment

Other submission-management: attachment_list(), attachment_upload(), encryption_key_list(), submission_audit_get(), submission_changes(), submission_comment_create(), submission_comment_list(), submission_create(), submission_csv(), submission_delete(), submission_detail(), submission_draft_attachment_delete(), submission_draft_attachment_download(), submission_draft_attachment_list(), submission_draft_attachment_upload(), submission_draft_create(), submission_draft_export(), submission_draft_get(), submission_draft_keys(), submission_draft_list(), submission_edit(), submission_export(), submission_geodata(), submission_geojson(), submission_get(), submission_list(), submission_restore(), submission_review(), submission_submitters(), submission_update(), submission_version_attachment_delete(), submission_version_attachment_download(), submission_version_attachment_list(), submission_version_detail(), submission_version_geojson(), submission_version_xml(), submission_versions()

Examples

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

sl <- submission_list()
iid <- sl$instance_id[[1]]

attachment_delete(iid, "photo.jpg")
# > $success
# > [1] TRUE

## End(Not run)

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(), ru_http_request(), 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(), ru_http_request(), 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: attachment_delete(), attachment_upload(), encryption_key_list(), submission_audit_get(), submission_changes(), submission_comment_create(), submission_comment_list(), submission_create(), submission_csv(), submission_delete(), submission_detail(), submission_draft_attachment_delete(), submission_draft_attachment_download(), submission_draft_attachment_list(), submission_draft_attachment_upload(), submission_draft_create(), submission_draft_export(), submission_draft_get(), submission_draft_keys(), submission_draft_list(), submission_edit(), submission_export(), submission_geodata(), submission_geojson(), submission_get(), submission_list(), submission_restore(), submission_review(), submission_submitters(), submission_update(), submission_version_attachment_delete(), submission_version_attachment_download(), submission_version_attachment_list(), submission_version_detail(), submission_version_geojson(), submission_version_xml(), submission_versions()

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

attachment_upload(
  iid,
  filename,
  file,
  content_type = NULL,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

Details

To upload a binary to an expected file slot, POST the binary to its endpoint. The expected file slots are determined by the Submission XML; list them with attachment_list(). filename must match a slot name from the attachment listing. file is the local file. Its bytes fill the slot.

Value

A list with a single element success (TRUE) as per the ODK Central API docs.

See Also

https://docs.getodk.org/central-api-submission-management/#uploading-an-attachment

Other submission-management: attachment_delete(), attachment_list(), encryption_key_list(), submission_audit_get(), submission_changes(), submission_comment_create(), submission_comment_list(), submission_create(), submission_csv(), submission_delete(), submission_detail(), submission_draft_attachment_delete(), submission_draft_attachment_download(), submission_draft_attachment_list(), submission_draft_attachment_upload(), submission_draft_create(), submission_draft_export(), submission_draft_get(), submission_draft_keys(), submission_draft_list(), submission_edit(), submission_export(), submission_geodata(), submission_geojson(), submission_get(), submission_list(), submission_restore(), submission_review(), submission_submitters(), submission_update(), submission_version_attachment_delete(), submission_version_attachment_download(), submission_version_attachment_list(), submission_version_detail(), submission_version_geojson(), submission_version_xml(), submission_versions()

Examples

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

sl <- submission_list()
iid <- sl$instance_id[[1]]

al <- attachment_list(iid)
al$name
# > "photo.jpg"

attachment_upload(iid, "photo.jpg", "/path/to/photo.jpg")
# > $success
# > [1] TRUE

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

Other server-management: config_public()

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

Usage

config_public(
  url = get_default_url(),
  un = NULL,
  pw = NULL,
  retries = get_retries()
)

Arguments

Details

This endpoint returns all server configuration that is publicly accessible in a single object. This endpoint does not require authentication. The following configurations are publicly accessible: login-appearance, logo and hero-image. For configuration that stores binary data (e.g. logo), this endpoint only returns metadata about the configuration. This endpoint requires ODK Central 2026.1 or later.

Value

A list with the public server configuration as per the ODK Central API docs.

See Also

https://docs.getodk.org/central-api-system-endpoints/#getting-all-public-configuration

Other server-management: audit_get()

Examples

## Not run: 
cfg <- config_public(url = "https://my.odkcentral.org")

names(cfg)

## 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(), ru_http_request(), 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_delete(), attachment_list(), attachment_upload(), submission_audit_get(), submission_changes(), submission_comment_create(), submission_comment_list(), submission_create(), submission_csv(), submission_delete(), submission_detail(), submission_draft_attachment_delete(), submission_draft_attachment_download(), submission_draft_attachment_list(), submission_draft_attachment_upload(), submission_draft_create(), submission_draft_export(), submission_draft_get(), submission_draft_keys(), submission_draft_list(), submission_edit(), submission_export(), submission_geodata(), submission_geojson(), submission_get(), submission_list(), submission_restore(), submission_review(), submission_submitters(), submission_update(), submission_version_attachment_delete(), submission_version_attachment_download(), submission_version_attachment_list(), submission_version_detail(), submission_version_geojson(), submission_version_xml(), submission_versions()

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_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

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_bulk_delete(
  pid = get_default_pid(),
  did = "",
  eids = c(),
  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 accepts an array of Entity UUIDs and performs soft-deletion on all of them.

Value

A list with a single element count holding the number of Entities that the bulk operation deleted or restored.

See Also

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

Other entity-management: entity_audits(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

el <- entitylist_list()
did <- el$name[1]

en <- entity_list(did = did)

entity_bulk_delete(did = did, eids = en$uuid[1:2])
# > $count
# > [1] 2

## End(Not run)

Description

Usage

entity_bulk_restore(
  pid = get_default_pid(),
  did = "",
  eids = c(),
  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 accepts an array of Entity UUIDs and restores all of them that were previously deleted.

Value

A list with a single element count holding the number of Entities that the bulk operation deleted or restored.

See Also

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

Other entity-management: entity_audits(), entity_bulk_delete(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

el <- entitylist_list()
did <- el$name[1]

en <- entity_list(did = did)

entity_bulk_restore(did = did, eids = en$uuid[1:2])
# > $count
# > [1] 2

## 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_bulk_delete(), entity_bulk_restore(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

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_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

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

Details

This endpoint returns a list of all Actors who have created Entities in the Dataset, sorted by display name.

Value

A tibble with one row per creating Actor and all Actor metadata as columns as per the ODK Central API docs. Column names are renamed from ODK Central's camelCase to snake_case.

See Also

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

Other entity-management: entity_audits(), entity_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

el <- entitylist_list()

cr <- entity_creators(did = el$name[1])

cr |> knitr::kable()

## 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_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

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_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

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

Details

This endpoint returns the geometry-interpretable value of the geometry attribute of Entities of a Dataset, in GeoJSON format. No particular ordering is implied.

Value

A list with the GeoJSON FeatureCollection as returned by Central: type and features with geometry and properties per Entity.

See Also

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

Other entity-management: entity_audits(), entity_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

el <- entitylist_list()

g <- entity_geodata(did = el$name[1])

g$type
# > "FeatureCollection"

## End(Not run)

Description

Usage

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

Returns the GeoJSON representation of an Entity's geometry attribute, if available.

Value

A list with the GeoJSON FeatureCollection holding the Entity's geometry.

See Also

https://docs.getodk.org/central-api-entity-management/#entity-geojson-representation

Other entity-management: entity_audits(), entity_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

el <- entitylist_list()
did <- el$name[1]

en <- entity_list(did = did)

g <- entity_geojson(did = did, eid = en$uuid[1])

g$type
# > "FeatureCollection"

## 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_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

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

Entities that have been recently soft-deleted and not yet purged can be restored with this endpoint.

Value

A list with a single element success (TRUE) as per the ODK Central API docs.

See Also

https://docs.getodk.org/central-api-entity-management/#restoring-a-deleted-entity

Other entity-management: entity_audits(), entity_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

el <- entitylist_list()
did <- el$name[1]

en <- entity_list(did = did)

entity_delete(did = did, eid = en$uuid[1])

entity_restore(did = did, eid = en$uuid[1])
# > $success
# > [1] TRUE

## 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_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

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_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entitylist_create(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

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_create(
  pid = get_default_pid(),
  name = "",
  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 create a Dataset with a specific name within a Project. This Dataset can then be populated with Entities via the API or via Forms and Submissions, and then used by other Forms. This endpoint allows a Dataset to be created programmatically without an input form.

The name of a Dataset is case-sensitive in that it will keep the capitalization provided (e.g. "Trees"). But Central will not allow a second Dataset with the same name but different capitalization to be created (e.g. "trees" when "Trees" already exists).

By default, the Dataset will have no properties, but each Entity will have a label and a unique ID (uuid).

This creates an empty Entity List. Add properties with the Dataset properties endpoint. Add Entities with entity_create(). Or publish a Form that defines the Entity List schema.

Value

A list of lists following the exact format and naming of the API response for entitylist_detail.

See Also

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

Other entity-management: entity_audits(), entity_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_delete(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

el <- entitylist_create(name = "Trees")

el$approvalRequired
# > FALSE

## End(Not run)

Description

Usage

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

Details

When a Dataset is deleted, it is soft-deleted and placed in the trash. After 30 days in the trash, the Dataset and all of its Entities are automatically purged. Unlike Forms, deleted Datasets cannot be restored. A Dataset cannot be deleted while any Forms still use it, either as a source of Entities or as a consumer through an attachment. Update or delete those Forms first. This endpoint requires ODK Central 2026.1 or later.

Value

A list with a single element success (TRUE) as per the ODK Central API docs.

See Also

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

Other entity-management: entity_audits(), entity_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_detail(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_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 = "...")

entitylist_delete(did = "trees")
# > $success
# > [1] TRUE

## 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_bulk_delete(), entity_bulk_restore(), entity_changes(), entity_create(), entity_creators(), entity_delete(), entity_detail(), entity_geodata(), entity_geojson(), entity_list(), entity_restore(), entity_update(), entity_versions(), entitylist_create(), entitylist_delete(), entitylist_download(), entitylist_list(), entitylist_property_create(), entitylist_property_delete(), entitylist_trash_download(), entitylist_update(), odata_entitylist_data_get(), odata_entitylist_metadata_get(), odata_entitylist_service_get()