This document is intended as a helper to technical teams who are seeking to create Form Submission packages for submitting data to CommCareHQ, generally to update one or more cases in a project space.

Creating these documents is the biggest stumbling block for implementing partnersThis guide won't go into detail about individual fields or specifications since those are covered elsewhere, but will provide advice about structuring transactions for submission, and what data is expected. 


The best way to get started with a template for integration is to create a CommCare Form in a sample app which completes the actions you want your integration to take, and to review the raw XML in CommCare HQ using the “Raw XML” view / download in the Submit History Report. We strongly, strongly recommend you do that in addition to using these templates.


Note: Forms submitted through the API may only be easy to find with the Raw Forms, Errors & Duplicates report, rather than the Submit History Report

Base Example Template

The following is a sample template for a Form XML Submission illustrating what data needs to be provided by an integration.

Fields which will need to be provided are written as {{field_name}} for further explanation below, everything else should be submitted as is. 

<?xml version="1.0" ?>
<data name="{{form_name}}" version="{{form_version}}" xmlns="{{form_schema_id}}" xmlns:jrm="http://dev.commcarehq.org/jr/xforms">
	<n0:meta xmlns:n0="http://openrosa.org/jr/xforms">				
		<n0:deviceID>{{integration_source_id}}</n0:deviceID>
		<n0:timeStart>{{time_start}}</n0:timeStart>
		<n0:timeEnd>{{time_end}}</n0:timeEnd>
		<n0:username>{{commcare_username}}</n0:username>
		<n0:userID>{{commcare_user_id}}</n0:userID>
		<n0:instanceID>{{unique_form_guid}}</n0:instanceID>
	</n0:meta>
	{{form_contents}}
</data>

Field Explanation Guide


A resulting envelope

<?xml version="1.0" ?>
<data name="Automatic Patient Updater" version="1" xmlns="http://mycompany.com/commcare/patient_updater" xmlns:jrm="http://dev.commcarehq.org/jr/xforms">
	<n0:meta xmlns:n0="http://openrosa.org/jr/xforms">				
		<n0:deviceID>mycompany commcare integration tool</n0:deviceID>
		<n0:timeStart>2019-09-24T13:55:14.281-04</n0:timeStart>
		<n0:timeEnd>2019-09-24T13:55:14.281-04</n0:timeEnd>
		<n0:username>jdoe@mycompany.com</n0:username>
		<n0:userID>1e670b9f-7259-41b0-bb2f-b1e2cf824828</n0:userID>
		<n0:instanceID>9b107fb4-c993-411b-87de-e2037377264a</n0:instanceID>
	</n0:meta>
</data>

Case Data

Inside of your form transaction you are probably ultimately intending to inject one or more CaseXML Transactions to change case data. You can read that spec sheet for additional specifics about what transactions can perform.

Two examples of case changes are provided below to illustrate how to encode those transactions. You can include as many casexml transactions as necessary in your envelopes (in the {{form_contents}} section above, but we recommend batching around 50 case transactions per form submission

Some fields are common with those above, new fields are described below the template


Create a new case

...
	<n0:case case_id="{{case_id}}" date_modified="{{time_end}}" user_id="{{commcare_username}}" xmlns:n0="http://commcarehq.org/case/transaction/v2">
		<n0:create>
			<n0:case_name>{{case_name}}</n0:case_name>
			<n0:owner_id>{{owner_id}}</n0:owner_id>
			<n0:case_type>{{case_type}}</n0:case_type>
		</n0:create>
		<n0:update>
			<n0:{{case_field}}>{{field_value}}</n0:{{case_field}}>
			...
		</n0:update>
	</n0:case>
...


Field Explanation Guide


The remaining data to be set against the case is configured as a key/value dictionary in the update block, which contains the remaining fields whether a case is being created or updated


Update an existing case

If a case should be updated rather than created,  the structure of the transaction is the same, but only containing the update section. Fields from the create section can be placed in the update section to change them once the case is already created.

...
	<n0:case case_id="{{case_id}}" date_modified="{{time_end}}" user_id="{{commcare_username}}" xmlns:n0="http://commcarehq.org/case/transaction/v2">
		<n0:update>
			<n0:{{case_field}}>{{field_value}}</n0:{{case_field}}>
			...
		</n0:update>
	</n0:case>
...


Advanced Usage

These are considerations which aren't important for initial integration rollout or testing, but may prove helpful in long term production use cases

Time Start / End / Etc

There's no specific semantic importance to timeStart and timeEnd values for integrations, and for initial rollout it's generally fine to just create one timestamp when you generate the envelope and reuse it in all fields.

Once things are working, though, setting them intentionally can still be helpful for debugging production issues.

We recommend setting timeStart to the time at which the integration run began or finished retrieving the data that will be submitted, and timeEnd to the time when the envelope was sealed, spooled, and ready to submit. This allows the identification of process ordering or time sequencing issues.