Form List API (original) (raw)

Toggle table of contents sidebar

This standard specifies how clients discover a list of available blank forms on a server.

Discovery Request¶

The discovery request should be sent in compliance with the HTTP 1.1 protocol.

If a server will filter the set of forms based upon the user's identity, then the server should require that the user be authenticated through either the Authentication API or through an alternative authentication mechanism. The server can then make use of the user's authenticated identity through those mechanisms to filter the set of forms to be returned.

The device will make a discovery request to a configured URI with a single query parameter, the deviceID. The deviceID should be the same id as provided by the default population mechanism defined in the Metadata Scheme. The server may filter the set of forms returned using this information.

Warning

The deviceID is advisory information only, and is inherently not authoritative. Anyone can claim to have a given IMEI, for example.

Together, the authentication and deviceID enable a server to tailor the set of forms to both the user and the device (and therefore the device's capabilities).

Query Parameters¶

Optional query parameters MAY also be supplied:

• formID If specified, the server MUST return information for only this formID.
• verbose If specified with the value true, the server MAY include a <descriptionText/> or <descriptionUrl> element providing a longer description of an XForm.
• listAllVersions If specified, provides a listing of all hosted versions of each form (including the <version> element) in the response document (see below).

If not supplied or not present, the server MUST NOT include this optional information in its response.

Successful Response Document¶

If accepted by the server, the server will respond with a Content-Type: text/xml; charset=utf-8 response. An example of such a document is shown below:

This document consists of:

• a top-level <xforms/> element in the http://openrosa.org/xforms/xformsList namespace enclosing,
  • zero or more <xform/> tags followed by
  • zero or more <xforms-group> tags.

Within each of the <xform/> tags, there must be exactly one of each of the following:

• <formID/>
• <name/>
• <version/>
• <hash/>
• <downloadUrl/>

There may be zero or one

• <descriptionText/>
• <descriptionUrl/>
• <manifestUrl/>

Within each <xforms-group> tag, there must be exactly one of each of the following:

• <groupID/>
• <name/>
• <listUrl/>

There may be zero or one

• <descriptionText/>
• <descriptionUrl/>

The <xform/> tag provides information about a single form. The <xforms-group/> tag provides information about a group of forms; a further enumeration of the forms within that group can be obtained through the <listUrl/> of that group (which returns an <xforms/> document). Groups can be used to define sets of forms that a user may wish to download together (such as for clinical studies, for example).

Elements within <xform/>¶

• <formID/> The form identity as defined in the metadata.
• <name/> The user-friendly display name of the form. The server may localize this name (translate it) based upon the Accept-Language: header on the incoming request. Devices SHOULD send this header and servers MAY return different name and description text based upon its value. The default behavior is to return the text within the <title> element of the XForm.
• <version/> The form version as defined in the metadata The device MAY use this to determine if its XForm definition is out of sync with the server (over time, the server may roll the current version forward or backward).
• <hash/> The hash value of the form definition file available for download. The only hash values currently supported are MD5 hashes of the file contents; they are prefixed by md5:. If the hash value identified in the form list differs from the hash value for a previously-downloaded form definition file, then the file should be re-fetched from the server.
• <downloadUrl/> A fully formed URI for downloading the form to the device. It may be a valid http or https URI of any structure; the server may require authentication; the server may require a secure (https) channel, etc.
• <manifestUrl/> A URI from which the device can obtain a manifest defining additional supporting objects and files. Optional
• <descriptionText/> A detailed text explanation of the form. Optional, only returned if verbose=true.
• <descriptionUrl/> A fully qualified URI pointing to a media (audio, video) description of the form. Optional, only returned if verbose=true.

Tip

A media description of the form (audio or video) can be especially useful in low-literacy populations.

Elements within <xforms-group/>¶

• <groupID/> The unique id for this group. It is locale-invariant (in contrast to the <name/> element, below).
• <name/> The user-friendly display name of the xforms group. The server may localize this name (translate it) based upon the Accept-Language: header on the incoming request. Devices SHOULD send this header and servers MAY return different name and description text based upon its value.
• <listUrl/> A fully qualified URI for obtaining the <xforms/> document of this grouping of forms. (That is, the endpoint for the Form List API). It may be a valid http or https URI of any structure; the server may require authentication; the server may require a secure (https) channel, etc.
• <descriptionText/> A detailed text explanation of the form group. Optional, only returned if verbose=true.
• <descriptionUrl/> A fully qualified URI pointing to a media (audio, video) description of the form group. Optional, only returned if verbose=true.

Note

• The server MAY dynamically construct the download and manifest URLs based upon the user identity and device id.
• The manifest MAY include additional (implementation specific) elements and data. These MUST be dealt with gracefully (ignored) by the client if it does not know how to interpret these fields.

The Manifest Document¶

The structure of the manifest document returned by the manifest URI is as follows:

This document consists of:

• a top-level <manifest/> tag in the http://openrosa.org/xforms/xformsManifest namespace enclosing
  • zero or more <mediaFile/> tags.
  • Within each of the <mediaFile/> tags, there must be exactly one of each of the following:
    * <filename/>
    * <hash/>
    * <downloadUrl/>

Elements within <mediaFile/>¶

• <filename/> The unique un-rooted file path for this media file. This un-rooted path must not start with a drive name or slash and must not contain relative path navigations (for example, . or ..).
• <hash/> The hash value of the media file available for download. The only hash values currently supported are MD5 hashes of the file contents; they are prefixed by md5:. If the hash value identified in the manifest differs from the hash value for a previously-downloaded media file, then the file should be re-fetched from the server.
• <downloadUrl/> A fully qualified URI for downloading the media file to the device. It may be a valid http or https URI of any structure; the server may require authentication; the server may require a secure (https) channel, etc.

<mediaFile/> attributes¶

• type Optional attribute to specify a category of file that needs special treatment. The only supported value is entityList (see the Entities addition to the ODK XForms spec).

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No