Skip to contents

Create a new Form.

Source: R/form_create.R
form_create.Rd

[Experimental]

Usage

form_create(
  pid = get_default_pid(),
  xml = NULL,
  file = NULL,
  publish = FALSE,
  ignore_warnings = FALSE,
  xls_form_id_fallback = NULL,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries()
)

Arguments

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

xml

(character) The XForms XML definition as a single string. Exactly one of xml and file must be given. Default: NULL.

file

(character) Path to a local .xml, .xls or .xlsx file holding the Form definition. Exactly one of xml and file must be given. Default: NULL.

publish

(lgl) If TRUE, the Form skips the Draft state and is published immediately. Default: FALSE.

ignore_warnings

(lgl) If TRUE, the Form is created even if the XLSForm conversion results in warnings. Conversion errors always fail the request. Only used for .xls/.xlsx uploads. Default: FALSE.

xls_form_id_fallback

(character) The form ID to use if an uploaded spreadsheet does not specify one. Sent as the X-XlsForm-FormId-Fallback header. Only used for .xls/.xlsx uploads. Default: NULL (no header sent).

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 new Form's metadata as per the ODK Central API docs. Top level list elements are renamed from ODK's camelCase to snake_case.

Details

When creating a Form, the only required data is the actual XForms XML or XLSForm itself.

Forms will by default be created in Draft state, accessible under /projects/.../forms/.../draft. The Form itself will not have a public XML definition, and will not appear for download onto mobile devices. You will need to publish the Form to finalize it for data collection. To disable this behaviour, and force the new Form to be immediately ready, pass publish = TRUE.

The API will check the XML's structure in order to extract the information it needs about it, but ODK Central does not run comprehensive validation on the full contents of the XML. ODK Validate finds problems in the Form before upload. Publish the Draft after the Form passes validation.

See also

https://docs.getodk.org/central-api-form-management/#creating-a-new-form

Other form-management: form_assignment_actors(), form_assignment_grant(), form_assignment_revoke(), form_attachment_download(), form_attachment_list(), form_dataset_diff(), form_delete(), form_detail(), form_draft_attachment_delete(), form_draft_attachment_download(), form_draft_attachment_link(), form_draft_attachment_list(), form_draft_attachment_upload(), form_draft_create(), form_draft_dataset_diff(), form_draft_delete(), form_draft_detail(), form_draft_publish(), form_draft_xlsx(), form_draft_xml(), form_link(), form_list(), form_restore(), form_schema(), form_schema_ext(), form_update(), form_version_attachment_download(), form_version_attachment_list(), form_version_detail(), form_version_list(), form_version_xlsx(), form_version_xml(), form_xlsx(), form_xml(), public_link_create(), public_link_delete(), public_link_detail(), public_link_list(), public_link_update()

Examples

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

xml <- paste0(
  '<h:html xmlns="http://www.w3.org/2002/xforms" ',
  'xmlns:h="http://www.w3.org/1999/xhtml">',
  "<h:head><h:title>Simple</h:title><model><instance>",
  '<data id="simple"><meta><instanceID/></meta><name/></data>',
  "</instance>",
  '<bind nodeset="/data/meta/instanceID" type="string" readonly="true()" ',
  'calculate="concat(\'uuid:\', uuid())"/>',
  '<bind nodeset="/data/name" type="string"/>',
  "</model></h:head>",
  '<h:body><input ref="/data/name"><label>Name</label></input></h:body>',
  "</h:html>"
)

f <- form_create(xml = xml, publish = TRUE)

f$xml_form_id
# > "simple"
} # }