Server Response Format

This page describes the proposed !OpenRosa standard server response to a form submission. Responses in this format should be intelligently handled by the phone to provide feedback on the outcome of the form submission. This document is in draft/proposal stages.

The server response format will be XML formatted.

The following list of tags will be supported/processed by the phone, however any server/application can add custom tags to its own processing:

• SubmissionStatusCode - Same as a standard HTTP Response code, and should be reflected in the http return code. (see below)
• SubmissionStatus - Readable version of the status code.
• OpenRosaStatusCode - A more descriptive version of the status, and potentially used for localization.
• OpenRosaStatus - A readable representation of the status code above.
• SubmissionId - The server's id for the submission.
• UserStatus* - Registered, Unknown
• FormsSubmittedToday - forms today from this user (if known, "today" is based on the user's configured timezone, otherwise based on some server default timezone)
• TotalFormsSubmitted - total forms from this user (cumulative)

• Not sure if this is necessary.

Example response:

<?xml version='1.0' ?>
<OpenRosaResponse>
  <SubmissionStatusCode>200</SubmissionStatusCode>
  <SubmissionStatus>OK</SubmissionStatus>
  <OpenRosaStatusCode>2000</OpenRosaStatusCode>
  <OpenRosaStatus>All is well!<OpenRosaStatus/>
  <SubmissionId>345</SubmissionId>
  <UserStatus>Registered</UserStatus>
  <FormsSubmittedToday>5</FormsSubmittedToday>
  <TotalFormsSubmitted>23</TotalFormsSubmitted>
  <SomeCustomAttribute>asdfj</SomeCustomAttribute>
</OpenRosaResponse>

Server Status Codes

Server status codes will be the same as [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html standard http codes]. The contract should always be that the status code in the XML is the same as the response code used by the server. We will use the same general classification:

• 2XX - Success
• 4XX - Client Error
• 5XX - Server Error

NOTE: I don't think "1XX - informational" or "3XX - redirection" should apply to these posts, but they may down the road. Some common interpretations of codes are below, but more could apply.

Open Rosa Status Codes

These are more specific than the Submission status codes, and apply specifically to X-Forms processing and OpenRosa standards.

This list will likely change over time. The current proposal is to add a digit and continue with the 2XXX, 4XXX syntax, however this is totally up for debate. For instance, it seems we may need more than 10 202X codes.

Some sample codes:

• Probably not OpenRosa Standard, but commcare-specific.