Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Tweaks: Clarify importance of UUID, and suggest how to find real XForm submissions

...

The Submission API is specifically for submitting XForms. Below is an example of an XForm submission

If you are not already working with XForms, the easiest way to get started is to use a form that has already been submitted to CommCare. If your project focuses on cases, go to the "Case List" report, choose a case, and select the "Case History" tab. There you will find a list of the form submissions that built the case. Choose a form, and select the "Raw XML" tab. You will find the XForm submission.

If your project is just based on forms, not cases, use the "Submit History" report. Choose a form, and select the "Raw XML" tab.

Once you have an example, modify it to suit your needs.

Let us go through an example of an XForm submission, to see what you might want to keep, change, or drop:

Code Block
<?xml version="1.0" ?>
<data name="Enregistrer un cas COVID-19"
      uiVersion="1"
      version="41"
      xmlns="http://openrosa.org/formdesigner/9baceb4c25a5">
  <consent_list>
    <consent_confirmation>yes</consent_confirmation>
  </consent_list>
  <case<patient_information>
    <covid_id>
      <id_region>KAR</id_region>
      <id_district>BAS</id_district>
      <id_number>306</id_number>
      <unique_id>KAR-BAS-306</unique_id>
      <auto_id>WSW2Y36</auto_id>
    </covid_id>
    <basic_demo>
      <given_name>Moujid</given_name>
      <family_name>GOUPAWEMEY</family_name>
    </basic_demo>
    <name_family_given>GOUPAWEMEY, Moujid</name_family_given>
    <case<patient_status>suspected</casepatient_status>
    <case<patient_location>1.2345678 9.0123456 7.8 901.2</casepatient_location>
    <suspect>
      <suspected_label>OK</suspected_label>
    </suspect>
  </casepatient_information>
 
  <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>
</data>

...

  • "deviceID": Use the device ID to identify set an identifier for the source of the submitted data.
  • "timeStart": When the user opened the form. OptionalIf the form is built programmatically, "now" is a reasonable value.
  • "timeEnd": When the user completed the form. OptionalLike "timeStart", "now" is a reasonable fallback.
  • "username": The name of the user / mobile worker who submitted the form. Optional.
  • "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. OptionalYou 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.

...