Table of Contents | ||
---|---|---|
|
Form Submission API
CommCare's Submission API implements the OpenRosa standard Form Submission API for submitting XForms over HTTP/S. You can find details of the Form Submission API standard here.
Submitting forms
There are two ways to submit a form to CommCare HQ:
As multipart/form-data; CommCare uses this method in J2ME.
As the body of a post; CommCare does this on Android.
Below are sample commands for submitting an XForm saved in a file called "xform.xml" to the domain called "demo". (You will need to change these two values in the commands below to suit your own purposes.)
...
In a number of places, CommCare reporting relies on tagging form submissions with the application that they belong to. To tag a form submission with its application, submit it to its application's URL. e.g. "https://www.commcarehq.org/a/demo/receiver/[APPLICATION_ID]/"
The application ID can be found in the URL when editing the application. e.g. In the URL "https://www.commcarehq.org/a/demo/apps/view/952a0b480c7c10dde777b2485375d2237/" the application ID is "952a0b480c7c10dde777b2485375d2237".
...
Code Block |
---|
<n1:meta xmlns:n1="http://openrosa.org/jr/xforms"> <n1:deviceID>commcare_37478fd5-2730-4a14-a847-84e8848a1ff5</n1:deviceID> <n1:timeStart>2020-06-08T18:38:13.855Z</n1:timeStart> <n1:timeEnd>2020-06-08T18:41:33.207Z</n1:timeEnd> <n1:username>exampleuser</n1:username> <n1:userID>de8cc5191f9b4e2a846069f0659fa35e</n1:userID> <n1:instanceID>dca03509-4446-41dc-8352-2bb6f8516c7b</n1:instanceID> <n2:appVersion xmlns:n2="http://commcarehq.org/xforms">CommCare Version 2.48. Build 461457</n2:appVersion> </n1:meta> |
"deviceID": Use the device ID to set an identifier for the source of the submitted data.
"timeStart": When the user opened the form. If the form is built programmatically, "now" is a reasonable value.
"timeEnd": When the user completed the form. Like "timeStart", "now" is a reasonable fallback.
"username": The name of the user / mobile worker who submitted the form.
"userID": The ID of the user / mobile worker who submitted the form.
"instanceID" is a unique ID for this form submission. Create a new UUID for every form submission. This ID needs to be universally unique, so you will need to generate a new Version 4 UUID; do not use an auto-incrementing ID. If "instanceID" is not unique, if the ID is owned by your project space then the new form submission will replace the previous form submission, otherwise if it is not owned by your project space, the form submission will be rejected.
"appVersion": If the form belongs to an app, this can offer useful context for its data. You can submit an empty node if it is not relevant.
Case management
The form above is simply a nested structure of answers to form questions. Case management is a powerful feature of CommCare that it is not using.
...
In addition to the response XML the HTTP response code is also important.
OpenRosa V 2.0
Response code | Nature | Meaning |
---|---|---|
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
Code Block |
---|
<OpenRosaResponse xmlns="http://openrosa.org/http/response"> <message nature="submit_success"> √ </message> </OpenRosaResponse> |
...
Code Block |
---|
<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 code | Nature | Meaning |
---|---|---|
201 | submit_success | Form was received and successfully processed |
422 |
processing_failure | Form received but an error occurred during processing. Re-submission likely to result in the same error e.g. InvalidCaseId Mobile device will 'quarantine' the form and set the quarantine message to the message from the response. |
500 | submit_error | Unable to process form XML. Usually due to malformed XML |
500 | Unexpected server error |
Code Example
The submission_api_example repository on GitHub has an example script to illustrate how to use the Submission API to create CommCare cases. It also has a short explanation of what the code does, so that you can use it as a reference for implementing in your own language, or adapt it for your own use case.
...
Code Block |
---|
https://www.commcarehq.org/a/demo/receiver/[APPLICATION ID]/ |
The application ID can ID can be found in the application edit URL. e.g. https://www.commcarehq.org/a/demo/apps/view/952a0b480c7c10dde777b2485375d2237/ → App ID = 952a0b480c7c10dde777b2485375d2237
...