Skip to contents

Update Submission data.

Source: R/submission_update.R
submission_update.Rd

[Experimental]

Usage

submission_update(
  iid,
  pid = get_default_pid(),
  fid = get_default_fid(),
  xml = NULL,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

iid

The instance_id, a UUID, as returned by submission_list.

pid

The numeric ID of the project, e.g.: 2.

Default: get_default_pid.

Set default pid through ru_setup(pid="...").

See vignette("Setup", package = "ruODK").

fid

The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147".

Default: get_default_fid.

Set default fid through ru_setup(fid="...").

See vignette("Setup", package = "ruODK").

xml

(character) The complete new Submission XML as a single string, including the deprecatedID metadata node.

url

The ODK Central base URL without trailing slash.

Default: get_default_url.

Set default url through ru_setup(url="...").

See vignette("Setup", package = "ruODK").

un

The ODK Central username (an email address). Default: get_default_un. Set default un through ru_setup(un="..."). See vignette("Setup", package = "ruODK").

pw

The ODK Central password. Default: get_default_pw. Set default pw through ru_setup(pw="..."). See vignette("Setup", package = "ruODK").

retries

The number of attempts to retrieve a web resource.

This parameter is given to RETRY(times = retries).

Default: 3.

Value

A list with the updated Submission's metadata as per the ODK Central API docs. Top level list elements are renamed from ODK's camelCase to snake_case.

Details

You can use this endpoint to submit updates to an existing Submission. The instanceID submitted with the initial version of the Submission is used permanently to reference that Submission logically, which is to say the initial Submission and all its subsequent versions. Each subsequent version also provides its own instanceID.

To perform an update, provide in the Submission XML an additional deprecatedID metadata node with the instanceID of the particular and current Submission version you are replacing. If the deprecatedID you give is anything other than the identifier of the current version of the Submission at the time the server receives it, Central answers 409. deprecatedID must contain the current instanceID. submission_get() returns the current instanceID. The new version must have a new instanceID.

The XML data you send replaces the existing data entirely. All of the data must be present in the updated XML.

When you create a new Submission version, any uploaded media files attached to the current version that match expected attachment names in the new version are automatically copied over to the new version.

This endpoint requires ODK Central v1.2 or later.

See also

https://docs.getodk.org/central-api-submission-management/#updating-submission-data

Other submission-management: attachment_delete(), 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_export(), submission_geodata(), submission_geojson(), submission_get(), submission_list(), submission_restore(), submission_review(), submission_submitters(), submission_version_attachment_delete(), submission_version_attachment_download(), submission_version_attachment_list(), submission_version_detail(), submission_version_geojson(), submission_versions()

Examples

if (FALSE) { # \dontrun{
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...")

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

xml <- paste0(
  '<data id="simple" version="1">',
  "<meta>",
  "<instanceID>uuid:85cb9aff-005e-4edd-9739-dc9c1a829c45</instanceID>",
  "<deprecatedID>", iid, "</deprecatedID>",
  "</meta>",
  "<name>Jo updated</name>",
  "</data>"
)

s <- submission_update(iid = iid, xml = xml)

s$current_version$instanceId
# > "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c45"
} # }