Wiki
Clone wikijavarosa / ServerResponseFormat
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.
'''Code''' | '''HTTP Meaning''' | '''Intepretation''' | ||||
200 | OK | Everything went great. Thanks for submitting | ||||
202 | Accepted | We got and saved your data, but may not have fully processed it (e.g. couldn't match it to a schema) | ||||
401 | Unauthorized | Phone tried to post something it didn't have permission to post | ||||
403 | Forbidden | You're not allowed to post there. Ever. | ||||
404 | Not Found | Unknown url endpoint, domain, or other | ||||
500 | Internal Server Error | Something went awry on the server and we're not sure what it was |
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:
'''Code''' | '''Meaning''' | |||
2000 | Nothing to report | |||
2020 | Duplicate Submission | |||
2021 | Unknown Form Schema | |||
2022 | Unknown Form ''Version'' | |||
4010 | Unknown/unauthorized User | |||
4011 | User/Domain mismatch* | |||
4040 | Unknown Domain* |
- Probably not OpenRosa Standard, but commcare-specific.
Updated