1. JavaRosa Team Dimagi Avatar JavaRosa Team Dimagi
  2. javarosa
  3. javarosa

Wiki

Clone wiki

javarosa / FormListAPI

View History

Proposal

See the Background section for a description of legacy form discovery and download mechanisms.

It is proposed that all compliant servers provide a common discovery mechanism for returning the set of forms available for download.

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 AuthenticationAPI 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 URL with a single query parameter, the deviceID. The deviceID should be the same id as provided by the default population mechanism defined in the OpenRosaMetaDataSchema. The server may filter the set of forms returned using this information. Note that this is advisory information only, and is inherently not authoritative (anyone can claim to have a given IMEI, for example).

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

Query Parameters

Two additional optional query parameters MAY 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/> and/or <descriptionUrl> tag providing a longer description of an Xform (either in text, or as a media file (e.g., audio clip) for low-literacy applications.
  • listAllVersions : If specified, provides a listing of all hosted versions of each form (including the <version> tag) in the response document (see below).

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

Request Headers

Requests from the device SHOULD set the Accept-Language: HTTP header to indicate the preferred language of the form name, description, etc. (see below). This HTTP header is documented here: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4 and an article on its evolving use for determining locale is here: http://www.w3.org/International/questions/qa-accept-lang-locales

Aside from the query parameters, the structure of the server URL and whether the request is made over http: or https:, is entirely implementor- and server- dependent. Compliant servers MUST NOT require additional query parameters on this request. Compliant devices MUST be able to handle arbitrary http: and https: URLs and must be able to authenticate with the server during this transaction, if required by the server (see Authentication API).

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:

<?xml version='1.0' encoding='UTF-8' ?>
<xforms xmlns="http://openrosa.org/xforms/xformsList">
  <xform>
    <formID>mydomain.org:formId</id>
    <name>Form with zero or more additional files</name>
    <version>1.1</version>
    <hash>md5:c28fc778a9291672badee04ac880a05d</hash>
    <descriptionText>A possibly very long description of the form</descriptionText>
    <downloadUrl>http://myhost.com/app/path/getMe/formIdA</downloadUrl>
    <manifestUrl>http://myothehost.com/app/path/getOtherStuff?formId=formIdA</namifestUrl>
  </xform>
  <xform>
    <formID>http://mydomain.org/uniqueFormXmlns</id>
    <name>Form without additional files</name>
    <version>v50 alpha</version>
    <hash>md5:c28fc778a9291672badee04ac770a05d</hash>
    <descriptionUrl>http://mysecondhost.com/a/description/getMe@formId=uniqueKey</descriptionUrl>
    <downloadUrl>http://mysecondhost.com/a/different/path/getMe@formId=uniqueKey</downloadUrl>
  </xform>
  <xforms-group>
     <groupID>someId</groupID>
     <name>Short name of grouping</name>
     <listUrl>http://whateverhost.com/other/path/forDownload?group=fido</listUrl>
     <descriptionText>Longer description of what is here</descriptionText>
     <descriptionUrl>http://morehost.com/description/link</descriptionUrl>
  </xforms-group>
</xforms>

This document consists of a top-level <xforms/> tag 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 <formID/>, <name/>, <version/>, <hash/> and <downloadUrl/> tag. There may be zero or one <descriptionText/>, <descriptionUrl/> and <manifestUrl/> tags. Within each <xforms-group> tag, there must be exactly one <groupID/>, <name/> and <listUrl/> tag. There may be zero or one <descriptionText/> and <descriptionUrl/> tags.

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 (e.g., such as for clinical studies).

The tags within the <xform/> tag have the following meanings:

  • <formID/> is the form id; either the id attribute of the top-level group within the default model instance or the xmlns namespace attribute (explicitly defined -- not inherited from the surrounding form) of that group. The id attribute value takes precedence if present. Openrosa- compliant forms are expected to have defined at least one of these.
  • <name/> is 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/> is the value of the string-valued version attribute on the top-level group within the default model instance. 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/> contains 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/> is a fully formed URL for downloading the form to the device. It may be a valid http or https URL of any structure; the server may require authentication; the server may require a secure (https) channel, etc.
  • <manifestUrl/> -- an optional element. If present, it defines a URL from which the device can obtain a manifest defining additional supporting objects and files.
  • <descriptionText/> -- an optional element. This is returned only if the verbose=true query parameter is sent to the server on the request. If it is, the server MAY return this optional element. This might be used to present a detailed textual explanation of the form to the user.
  • <descriptionUrl/> -- an optional element. This is returned only if the verbose=true query parameter is sent to the server on the request. If it is, the server MAY return this optional element. This might be used to present an audio (video, etc.) explanation of the form to the user.

The tags within the <xforms-group/> tag have the following meanings:

  • <groupID/> is the unique id for this group. It is locale-invariant (in contrast to the <name/> element, below).
  • <name/> is 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/> is a fully formed URL for obtaining the <xforms/> document(FormListAPI) of this grouping of forms. It may be a valid http or https URL of any structure; the server may require authentication; the server may require a secure (https) channel, etc.
  • <descriptionText/> -- an optional element. This is returned only if the verbose=true query parameter is sent to the server on the request. If it is, the server MAY return this optional element. This might be used to present a detailed textual explanation of the xforms group to the user.
  • <descriptionUrl/> -- an optional element. This is returned only if the verbose=true query parameter is sent to the server on the request. If it is, the server MAY return this optional element. This might be used to present an audio (video, etc.) explanation of the xforms group to the user.

Note:

  • The server, if needed, can dynamically construct the download and manifest URLs based upon the user identity and device id.
  • The manifest CAN include additional (implementation specific) tags and data that 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 returned by the manifest URL is as follows:

<?xml version='1.0' encoding='UTF-8' ?>
<manifest xmlns="http://openrosa.org/xforms/xformsManifest">
 <mediaFile>
  <filename>badger.png</filename>
  <hash>md5:c28fc778a9291672baddd04ac880a05d</hash>
  <downloadUrl>http://funk.appspot.com/binaryData?blobKey=%3A477e3</downloadUrl>
 </mediaFile>
 <mediaFile>
  <filename>path/to/agilefrog.png</filename>
  <hash>md5:9fd39ac868eccdc0c134b3b7a6a25eb7</hash>
  <downloadUrl>http://other.appspot.com/blobSource?foo=222</downloadUrl>
 </mediaFile>
</manifest>

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 <filename/>, <hash/>, and <downloadUrl/> tag.

The tags within the <mediaFile/> tag have the following meanings:

  • <filename/> is 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 (e.g., . or ..).
  • <hash/> contains 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/> is a fully formed URL for downloading the media file to the device. It may be a valid http or https URL of any structure; the server may require authentication; the server may require a secure (https) channel, etc.

The structure of the manifest returned by the manifest URL is expected to be extended. The intent is to have this manifest define external data sets (e.g., databases for selection lists), external dependencies (e.g., on android, desired or required external applications), and media files (icons, images, audio, video). If you are interested in working on the definition of the manifest file structure, send e-mail to the list.

Updated