This feature requires a CommCare Software Plan

This feature (API Access) is only available to CommCare users with a Standard Plan or higher. For more details, see the CommCare Software Plan page.

Form Submission API

The form submission API can be found here: https://bitbucket.org/javarosa/javarosa/wiki/FormSubmissionAPI.

There are two ways to submit a form to CommCare HQ, which are as multipart/form-data and as the body of a post, currently used by the J2ME and Android implementations, respectively. Here, sample commands are given for submitting a file called "file.xml" to the domain called "demo". (You will need to change these two values in the commands below to suit your own purposes.)

Submission as multipart/form-data

curl -F "xml_submission_file=@file.xml" "https://www.commcarehq.org/a/demo/receiver/"

One way to think of this is that the incoming request looks exactly like a request sent by submitting the following html form:

<form method="post" enctype="multipart/form-data" action="https://www.commcarehq.org/a/demo/receiver/">
    <input type="file" name="xml_submission_file"/>
    <input type="submit" value="Submit Form"/>
</form>

Submission as body of a post

curl -d @file.xml "https://www.commcarehq.org/a/demo/receiver/"

There is no equivalent of this in an html form, because rather than submitting a body which is a mapping from names onto values, the curl command above submits the files contents as the entire body.

Response

The response to a form submission is an XML payload as follows:

<OpenRosaResponse xmlns="http://openrosa.org/http/response">
    <message nature="{{nature}}">{{message}}</message>
</OpenRosaResponse>

 

It has two pieces of data. The response 'nature' and the response 'message'. The message is a human readable message while the 'nature' is intended to classify the response.

In addition to the response XML the HTTP response code is also important.

OpenRosa V 2.0

Response codeNatureMeaning
201
submit_success
Form was received and successfully processed
201
submit_error
Form was received but could not be processed due to some error. See 'message' for more details.
401 Authentication failed. User not allowed to submit forms or authentication credentials incorrect.
500
submit_error

Unable to process form XML. Usually due to malformed XML

500 Unexpected server error


Example Success Response

<OpenRosaResponse xmlns="http://openrosa.org/http/response">
    <message nature="submit_success">   √   </message>
</OpenRosaResponse>

Example Error Response

<OpenRosaResponse xmlns="http://openrosa.org/http/response">
    <message nature="submit_error">InvalidCaseIndex: Case '349580db10da4a67b7089c541742c88b' references non-existent case '9766f50abda94c26a4569df5ce6dda6d'</message>
</OpenRosaResponse>


OpenRosa V 3.0

Response codeNatureMeaning
201
submit_success
Form was received and successfully processed
422
 
processing_failure
Form received but an error occurred during processing. Resubmission likely to result in the same error e.g. InvalidCaseId
422 
post_processing_failure 
Form received and processed but error occurred during post processing. Do not try to re-submit form.
500
submit_error
Unable to process form XML. Usually due to malformed XML
500 Unexpected server error

Additional Notes

For compatibility with CommCare ODK, the Android CommCare client, the urls above can also be replaced with

https://www.commcarehq.org/a/demo/receiver/submission/

That is, you can append the string "submission/" to the end of the url and it works exactly as before.

Examples

Here is a python3 script that builds a form to update the properties of case and submits that form to CommCareHQ

  • No labels