-
Notifications
You must be signed in to change notification settings - Fork 14
casexml20
Note: this is the new version of the CaseXML specification, which is a replacement for the 1.N spec located at
https://bitbucket.org/javarosa/javarosa/wiki/casexml
CaseXML 2.0 is a replacement for the CaseXML 1.0 data persistence specification. The major differences between CaseXML 1.0 and CaseXML 2.0 are as follows:
- Introduction of namespace for element.
- Moving case_id, user_id, and date_modified to attributes on the element.
- Introduction of <owner_id /> as a new concept for case ownership.
- Introduction of element for working with linked cases.
CommCare applications depend primarily on the use of the Case model to persist data of ongoing interactions. Currently, the operations which can be performed on a case are all manually extracted and manipulated in code. In order to generalize the model and allow for true decoupling of the contents of a case from the code which provides it, this document provides a schema for an XML element which will encapsulate operations that are performed on cases.
The top-level element of all case interactions is the xml element <case>, inside of the '''http://commcarehq.org/case/transaction/v2''' namespace. For the purposes of this document, all xml will be assumed to be in that namespace other than the longform examples at the bottom.
The <case> element contains a subset of possible case action elements which manipulate the abstract representation of a case on the current platform. Depending on which action elements are available, the case will be modified accordingly. An arbitrary set of the subcases can be present, but their ordering is specified.
The <case> element schema is defined as
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="" user_id="" date_modified="" >
<!-- user_id - At Most One: the GUID of the user responsible for this transaction -->
<!-- case_id - Exactly One: The id of the abstract case to be modified (even in the case of creation) -->
<!-- date_modified - Exactly One: The date and time of this operation -->
<create/> <!-- At Most One: Create action -->
<update/> <!-- At Most One: Updates data for the case -->
<index/> <!-- At Most One: Contains a set of referenced GUID's to other cases -->
<attachment/> <!-- (Since 2.5) At Most One: Contains pointers to binary attachments to include with this case -->
<close/> <!-- At Most One: Closes the case -->
</case>
There are four main actions which can be performed against a case. Create, Update, Close, and Index. Each action is represented by an element block contained within a <case>.
<create>
The <create> element instructs the platform to create a new abstract case with the information provided. The <create> is only valid when the case_id specified is not in use for any existing cases. No generic (non-required) data can be registered with the case in the creation subelement, but must be added with the <update> element instead.
The XML Schema for the create element is defined as
<create>
<case_type/> <!-- Exactly One: The ID for the type of case represented -->
<owner_id/> <!-- At Most One: The GUID of the current owner of this case -->
<case_name/> <!-- Exactly One: A semantically meaningless but human readable name associated with the case -->
</create>
<update>
The <update> element instructs the platform to either add or modify generic information about a case. The required data for a case can be modified with a directly named element, and all other datum are specified as generic key/value pairs. All non required data should be manipulated through the use of this element.
The XML Schema for the update element is defined as
<update>
<case_type/> <!-- At Most One: Modifies the Case Type for the case -->
<case_name/> <!-- At Most One: A semantically meaningless but human readable name associated with the case -->
<date_opened/> <!-- At Most One: Modifies the Date the case was opened -->
<owner_id/> <!-- At Most One: Modifies the owner of this case -->
<*/> <-- An Arbitrary Number: Creates or mutates a value identified by the key provided -->
</update>
<close>
The <close> element instructs the platform to close the case which is identified. The behavior of a "closed" case can vary by platform, including removing the case entirely (if resources are limited) or by simply indexing it away in future actions.
Cases which have been closed should be ineligible for actions performed with any <mutate> data that is received after the case is closed, and the behavior of the platform upon receiving that data is unspecified.
The XML schema for this element is defined as
<close>
<!-- No data currently needed. Anything that needs to go here? Closed-by, possibly? -->
</close>
<index>
The <index> element contains key references to other case elements. Each index defined should refer to a case using its GUID and type id. These references are maintained and stored separately from other case data to allow them to be indexed for improved performance.
The relationship of an index to its parent affects the construction of the liveness graph used to identify what cases are in a user's scope. More information about that mechanism is available on the Sync/Restore API Page
The XML schema for this element is defined as
<index>
<* case_type="" relationship="" /> <!-- At least one: A named element who's value is a GUID referring to another element -->
<!-- @case_type: Exactly one: The case type of the indexed element -->
<!-- @relationship[since 2.12]: At most one: Defines how this case and the parent case affect each other's "liveness" when syncing. One of:
"child" (default) - Denotes that this is a fully fledged case that depends on the indexed case. A child case will force the presence of a indexed case.
"extension" - Denotes that this child extends the indexed case to provide additional data. An extension case will be removed from the user's scope if the indexed case is removed.
-->
</index>
<attachment>
The <attachment> element contains pointers to binary data which should be included with this case. The semantics of processing this data are somewhat more complex than with the other elements, since this data is not necessarily included in the same physical payload as the case transaction.
The XML schema for this element is defined as
<attachment>
<* src="" from="" name=""/> <!-- At least one: A named element referring to an attachment. There are four valid states for this element.
1) Named, no attributes, empty - This will remove the attachment.
2) from="local". src must contain a uri which can be retrieved from the local form or environment. This attachment should be processed fully before the case transaction is committed.
3) from="remote". src contains a uri. The URI should be globally accessible to the current user. This attachment can be processed asynchronously and does not need to be available before committing the transaction.
4) from="inline". element must contain inline data (base64 encoded). @name must exist to provide a filetype. -->
<!-- @src - At most one: a reference to the location of this attachment. Either in the local environment or submission, or a remote location. -->
<!-- @from - At most one: one of [local, remote, inline] specifying whether this attachment is already present in the local environment, whether it must be retrieved asynchronously, or whether it is included in the attached element. -->
<!-- @name - At most one: A specific name for this attachment. Mandatory if the attachment is attached as inline data. -->
</attachment>
Inline attachments should be avoided wherever possible. When a case transaction is transmitted as part of a multipart envelope, attachments should be provided as relative data with the same identifier as is used here. When case transactions are provided in large amounts or as part of a response which cannot be placed in an envelope, attachments should be specified as remote, and fetched asynchronously. Care should be taken to ensure that asynchronous attachment fetches are processed in order.
This section presents what the case block might look like for a sample Case Type, which is used to register households for a 3 part distribution of health supplies by the imaginary ONICAF group.
XForm specification:
...
<instance>
<registration>
<meta>
....
</meta>
<scratch>
<case_id/>
</scratch>
...
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="" date_modified="" user_id="">
<create>
<case_type>houshold_rollout_ONICAF</case_type>
<case_name/>
<owner_id/>
</create>
<update>
<household_id/>
<primary_contact_name/>
<visit_number/>
</update>
</case>
</registration>
</instance>
...
XML Payload Sent from JavaRosa
<registration>
<meta>
....
</meta>
<scratch>
<case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
</scratch>
...
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="3F2504E04F8911D39A0C0305E82C3301" date_modified="11/10/09 21:23:43" user_id="9R3504E04F8911D39A0C0305E82C3301">
<create>
<case_type>houshold_rollout_ONICAF</case_type>
<case_name>Smith</case_name>
<owner_id>9R3504E04F8911D39A0C0305E82C3301</owner_id>
</create>
<update>
<household_id>24/F23/3</household_id>
<primary_contact_name>Tom Smith</primary_contact_name>
<visit_number>1</visit_number>
</update>
</case>
</registration>...
<instance>
<follow-up>
<meta>
....
</meta>
...
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="" date_modified="" user_id="">
<update>
<visit_number/>
</update>
</case>
</follow-up>
</instance>
...
XML Payload Sent from JavaRosa
<follow-up>
<meta>
....
</meta>
...
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="3F2504E04F8911D39A0C0305E82C3301" date_modified="11/11/09 03:23:18" user_id="9R3504E04F8911D39A0C0305E82C3301">
<update>
<visit_number>2</visit_number>
</update>
</case>
</follow-up>...
<instance>
<distribution_close>
<meta>
....
</meta>
...
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="" user_id="" date_modified="">
<close/>
</case>
</distribution_close>
</instance>
...
Possible XML Payload Sent from JavaRosa - Possibility 1
<distribution_close>
<meta>
....
</meta>
...
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="3F2504E04F8911D39A0C0305E82C3301" user_id="9R3504E04F8911D39A0C0305E82C3301" date_modified="12/12/09 16:34:23">
<close/>
</case>
</distribution_close>Possible XML Payload Sent from JavaRosa - Possibility 2
<distribution_close>
<meta>
....
</meta>
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="3F2504E04F8911D39A0C0305E82C3301" user_id="9R3504E04F8911D39A0C0305E82C3301" date_modified="12/12/09 16:34:23"/>
...
</distribution_close>Sometimes having an explicit close form is unnecessary. This scheme facilitates not requiring multiple forms by allowing actions to be taken based on the XForms payload state. For example: This set of two forms allows for the close action to occur based on whether the close element is relevant or not.
...
<instance>
<follow-up>
<meta>
....
</meta>
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="" date_modified="" user_id="">
<update>
<visit_number/>
</update>
<close/>
</case>
</follow-up>
</instance>
...
XML Payload Sent from JavaRosa: Not Closing
<follow-up>
<meta>
....
</meta>
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="3F2504E04F8911D39A0C0305E82C3301" date_modified="11/11/09 03:23:18" user_id="9R3504E04F8911D39A0C0305E82C3301">
<update>
<visit_number>2</visit_number>
</update>
</case>
</follow-up>XML Payload Sent From JavaRosa: Closes Case
<follow-up>
<meta>
....
</meta>
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="3F2504E04F8911D39A0C0305E82C3301" date_modified="11/11/09 03:23:18" user_id="9R3504E04F8911D39A0C0305E82C3301">
<update>
<visit_number>3</visit_number>
</update>
<close/>
</case>
</follow-up>One common complex usage of cases is to be able to create new cases which are linked to the original case and track some subtask which should be performed. This example will cover creating a subcase of the household case created above which tracks a referral given to a member of the household.
<registration>
<meta>
....
</meta>
<scratch>
<case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
</scratch>
<household>
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="3F2504E04F8911D39A0C0305E82C3301" date_modified="11/11/09 03:23:18" user_id="9R3504E04F8911D39A0C0305E82C3301">
<create>
<case_type>houshold_rollout_ONICAF</case_type>
<case_name>Smith</case_name>
</create>
<update>
<household_id>24/F23/3</household_id>
<primary_contact_name>Tom Smith</primary_contact_name>
<visit_number>1</visit_number>
</update>
</case>
</household>
<referral>
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="SADF2343223I4IU43A0C0305E82C3301" date_modified="11/11/09 03:23:18" user_id="9R3504E04F8911D39A0C0305E82C3301">
<create>
<case_type>houshold_ONICAF_referral</case_type>
<case_name>illness</case_name>
</create>
<update>
<followup_date>11/17/09</followup_date>
</update>
<index>
<household_case case_type="houshold_rollout_ONICAF">3F2504E04F8911D39A0C0305E82C3301</household_case>
</index>
</case>
</referral>
</registration><referral_visit>
<meta>
....
</meta>
<case xmlns="http://commcarehq.org/case/transaction/v2" case_id="SADF2343223I4IU43A0C0305E82C3301" date_modified="11/17/09 21:23:43" user_id="9R3504E04F8911D39A0C0305E82C3301">
<close/>
</case>
</referral_visit>