CommCare Submissions API - Input XML Formatting

Developers
1

I'm working on developing an external source for data entry that would make use of the Submission API but am unsure of the XML input formatting. In the following article, an example XML file is passed in, but I have not had success using previously-submitted forms from my App. Are there any resources available for formatting OpenRosa XML submissions?

https://confluence.dimagi.com/display/commcarepublic/Submission+API

My account has a Pro subscription.

2

but I have not had success using previously-submitted forms from my App.

That's definitely the best place to start. However, you'll likely need to make a template out of a previously-submitted form and change some parts of it. One big one is the instanceID attribute. This is expected to be a UUID that is unique to each form. If CommCare receives multiple forms with the same ID, it will treat them as duplicates. I'd read over the whole form submission, particularly the meta block and a case block if one exists and ensure anything that should vary from one submission to another does.

1 Like
3

Hi,

What issues were you experiencing using previously submitted forms, precisely?

OpenRosa XML submissions are largely just XML documents with the exception of the special transaction blocks like and , knowing what errors you were getting when trying to submit would be helpful, it's likely the issue was with the POST structure rather than the content if you were just rebroadcasting an existing form, but you might also try changing the "instanceid" in the meta block, since that's the UUID for a specific submission, and resubmitting a form with the same UUID will be treated as a duplicate.

4

Thanks for this input! My issue was a combination of bad credentials and the instanceID you've mentioned. Once I ran the curl command with -v, I was able to see the authentication error. Here's the command that was suggested by the documentation:

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

And here's the successful command:

curl -F "xml_submission_file=@file.xml" "https://www.commcarehq.org/a/demo/receiver/[app_id]" -u username:password

I also randomly generated an instance ID, and once these two were satisfied, I received the 201 Created response!

The only issue that's remaining is that while I can see the form submission in CommCare HQ and it's denoted as a Case Registration in the desired App, the case itself is not being created.

The n0 and n1 blocks have been updated.

Edit: I was able to make the case visible by passing the generated instanceID as the case_id in the n0 block.

Thanks for your help!

5

Glad to hear you've resolved the authentication issues. Couple things to note:

-u username@domain.commcarehq.org:password
vs
-u username:password

I'm assuming you're using your web user's username for the latter format. That will work, but CommCare expects data to be submitted by mobile workers, and data will show up weirdly in reports (hidden by default, actually) if it's submitted by a web user. I'd recommend creating a mobile worker and using that for the submission. If your mobile worker's name is test_user and your project is called demo (like in the example), it should be:

-u test_user@demo.commcarehq.org:password

I was able to make the case visible by passing the generated instanceID as the case_id in the n0 block.

Form instanceIDs and case_ids are both expected to be unique identifiers. You should never reuse the same ID - the case should have it's own, separate ID.

6

Thanks! This is really useful.

On a similar note, how would one format the <attachment> block? I've been having some trouble replicating image submissions with previously submitted forms, as these do not include the <attachment> details, but rather the form and case properties associated with the attachment.

Using this documentation: casexml20 · dimagi/commcare-core Wiki · GitHub, I've attempted local and inline submissions, and while the submission is successful, and the data is visible in the submission, it is not being mapped to the question_id it's associated with, and does not seem to be accessible via the attachments api. In similar previously-submitted forms, a tab for 'attachments' is visible from the form viewer, but the only place I can see information about the api-submitted attachment is in the 'case metadata', but it doesn't look like the image itself is submitted.

Is it possible to provide a local image or binary (base 64) data and have it accessible via the form attachments api? https://www.commcarehq.org/a/[domain]/api/form/attachment/{form_id}/{attachment_name}

Is there a separate request that must be submitted to push the file itself?

If this is better for a new thread, I can move it there as well!

7

Yeah, you might have better luck in a new thread. I don't know how to submit attachments via the forms API, though that documentation is definitely where I'd start looking to figure it out.

8

So there are two somewhat separate/distinct components for multimedia attachments.

If you are trying to submit multimedia/file attachments with the form, you'll need to POST a multipart/form-data or multipart/mixed HTTP submission, with the images included as part of that post as outlined in the original form submission API.

To associate those attachments with questions in the form, you should include the content-name of the image attachment as the value of the XML element you are associating with the attachment.

The case attachment syntax is separate (it's a mechanism for getting attachments back down to mobile devices), and is not something that is actively supported due to limitations in its utility for our userbase.

-Clayton