Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • form_name - A human readable description of what this form does. Will appear in reports

    • Specific to: Your Integration

    • Suggested Use - A terse describe the function of your submission

    • Example: Automatic Patient Updater

  • form_version - A numeric version for the form schema

    • Specific to: Your Integration

    • Suggested Use - Once your integration is in production, increment this number in your code any time you change the code that generates these blocks

    • Example: 1

  • form_schema_id - A unique ID for the schema of this XML document.  Will be used to group form submissions. XMLNS Schemas look like urls by tradition, but do not need to actually be valid urls.

    • Specific to: Your Integration

    • Suggested Use - Use a different schema ID for each type of integration you build, each document with the same schema ID should have the same document structure

    • Example: http://mycompany.com/commcare/patient_updater

  • integration_source_id - A plaintext description of what engine is generating this form envelope

    • Specific to: Your Integration

    • Suggested Use: Terse description of the integration environment that generated the envelope. If a library was used to generate the envelope, this should name the library.

    • Example: mycompany custom commcare integration

  • time_start - The time the integration run began as an ISO8601 compliant timestamp

    • Specific to: One run of the integration 

    • Suggested Use: Initially just set one timestamp for all time events, or set timestamps to generate as they are requested. Further considerations described at the bottom of this page

    • Example: 2019-09-24T13:55:14.281-04

  • time_end - The time this envelope was finished as an ISO8601 compliant timestamp

    • Specific to: One run of the integration 

    • Suggested Use: Initially just set one timestamp for all time events, or set timestamps to generate as they are requested. Further considerations described at the bottom of this page

    • Example: 2019-09-24T13:55:14.281-04

  • commcare_username - The login username submitting this data.

    • Specific to: The project space where the integration is run

    • Suggested Use: Should be populated with the login username of the user whose credentials will be used to submit this envelope

    • Example: jdoe@mycompany.com

  • commcare_user_id - The machine GUID of the Web User submitting this data 

    • Specific to: The project space where the integration is run

    • Suggested Use: This ID can be identified in a few ways. 

      • Navigating to the CommCareHQ Web Users page, selecting your user, then viewing your GUID in the url bar

      • From the List Web Users API

      • Viewing a form submission submitted by your user in the UI

    • Example: 1e670b9f-7259-41b0-bb2f-b1e2cf824828

  • unique_form_guid - A unique UUIDv4 machine id which represents this form envelope. This ID is used to ensure idempotency about the transaction while allowing resubmission. If you submit an envelope twice with the same id, HQ will treat them as the same submission.

    • Specific to: One run of the integration 

    • Suggested Use: Generate a random UUIDv4 id from a library in your platform for each transaction.

    • Example: 9b107fb4-c993-411b-87de-e2037377264a

  • form_contents - The remainder of the form is an XML document containing arbitrary elements, including structured CaseXML Transactions as explained below

...