-
Notifications
You must be signed in to change notification settings - Fork 14
CaseAttachmentAPI
Beta in CommCare 2.5 is the notion attaching binary data to cases. The complex part about these attachments is that binary data must be made available in different ways depending on context. This doc explains the standard contract for a client and server to register and share these attachments.
- Case transaction specification for creating attachments
- Referencing attachments in a local commcare environment
- Normal HTTP Sync/Restore API for clients/servers
The standard process for creating a case attachment is that a client device will fill out an XForm which has a piece of external multimedia (like a photograph of a person or object) included. The client submits this form to the server using the standard form transmission API for including additional files.
In addition, the form will include a payload inside of a case specifying that one of these additional files should become an attachment for the case using a block like
...
<case xmlns="http:*commcarehq.org/case/transaction/v2" case_id="83789c75-9587-4df0-bf4a-8c81e6b64c0b" user_id="f8025f339922d82a9abb2a340b0a4ce3" date_modified="2013-03-07T15:00:37.026-05" xmlns:n0="http:*commcarehq.org/case/transaction/v2">
<attachment>
<photo src="1362686433763.jpg" from="local"/>
</attachment>
</case>
...The src for this attachment should correspond to the name of the included Multipart envelope submitted to the server, since the from attribute specifies a local file.
The client will process the attached file and retain a local copy going forward. Additionally, the server should retain a copy of the submitted attachment and associate it with the case by the named ID.
When clients restore data utilizing the Sync API, they will often be incapable of receiving a response which contains all of the attachments in one payload. As such, they should make the attachments available for retrieval asynchronously.
The following is a sample response from the server from another client receiving the updated case from the earlier transaction
...
<case xmlns="http:*commcarehq.org/case/transaction/v2" case_id="83789c75-9587-4df0-bf4a-8c81e6b64c0b" user_id="f8025f339922d82a9abb2a340b0a4ce3" date_modified="2013-03-07T15:00:37.026-05" xmlns:n0="http:*commcarehq.org/case/transaction/v2">
<attachment>
<photo src="http://www.submittedserver.com/case/attachment/83789c75-9587-4df0-bf4a-8c81e6b64c0b/photo.jpg" from="remote" />
</attachment>
</case>
...Upon receiving this transaction the client should detect the remote attachment and make a record to specify that it should be retrieved, then commit the transaction as normal.
The process for fetching those resources is up to the client, but currently the application should not block on the availability of attachments, but rather provide some placeholder if needed to signal to users that an attachment has not yet been downloaded.
The default assumption is that attachments will be retrieved from clients over a network connection asynchronously. The client will request each attachment one-by-one from the server using the user's credentials.
Not all devices are capable of receiving and utilizing attachments of the same resolution (for images or audio) due to hardware or network constraints, so when fulfilling these requests servers are encouraged to accept some parameters from a client specifying transformations or limitations as follows.
For practical consideration, the server need not honor these constraints precisely. For instance, the server could maintain a "small", "medium", and "full" size of submitted images which are scaled uniformly, and return the resource which most closely matches the constraints provided.
| Parameter | Values | Notes |
|---|---|---|
| max_size | The largest size (in bytes) for the attachment | |
| max_image_width | The largest width in pixels for an an image attachment | |
| max_image_height | The largest width in pixels for an an image attachment |