1. JavaRosa Team Dimagi Avatar JavaRosa Team Dimagi
  2. javarosa
  3. javarosa

Wiki

Clone wiki

javarosa / casexml

View History

NOTE: this is an old spec document that is in the process of being replaced by https://bitbucket.org/commcare/commcare/wiki/casexml20

Case Workflow XML Schema

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.

Case XML Element

The top-level element of all case interactions is the xml element <case>, inside of the '''http://commcare.org/case/transaction''' namespace.

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.

In addition to operations on the case, operations for referrals based on those cases can be specified In a <referral> section. Note that Multiple referral actions can occur

The <case> element schema is defined as 

 <case>
    <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 of this operation
    <create/>         <-- At Most One: Create action
    <update/>         <-- At Most One: Updates data for the case
    <close/>          <-- At Most One: Closes the case
    <referral/>       <-- At Most One: Referral actions
 </case>

Note: Currently the case block relies on case-id being inside of the block as a sub-element. Case-id should instead be an attribute of the element itself. This is a necessity due to the limitations of the current XForms engine, but isn't expected to be a problem since multiple cases inside of one form is not currently an expected case. Multiple case actions can still be used. In order to do so, multiple case blocks should exist, which can be universally referenced by being sub elements of different, distinct, parent elements. IE: nodeset='/a/b/c/case' and nodeset='a/b/d/case'.

Case Action Elements

There are Three main actions which can be performed against a case. Create, Update, Close. 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_id/>             <-- Exactly One: The ID for the type of case represented
        <user_id/>                  <-- At Most One: The ID for a user who created the case
        <case_name/>                <-- Exactly One: A semantically meaningless but human readable name associated with the case
        <external_id/>              <-- Exactly One: The soft id associated with this record. Generally based on another system's id for this record.
    </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 create element is defined as 

    <update>
        <case_type_id/>             <-- 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
        <*/>                        <-- An Arbitrary Number: Creates or mutates a value identified by the key provided
    </update>

'''NOTE:''' The way in which this specification handles the arbitrary datum used does not conform to the way in which XML generally allows for semantically meaningful data of arbitrary number and name. In the future, this definition will be changed from <*/> to

    <update>
        ... other stuff from above
        <datum key='' value=''/>
    </update>

This is not currently possible due to the limited nature of XPath handling in JavaRosa's XForms engine and in a variety of OR compatible backends.

Also note: possibly add: <case_id/> <-- At Most One: Modifies the ID of the case. in the future

<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>

Referral Action Elements

The <case> element can contain a <referral> sub element set. This set specifies a set of actions which should be taken against an abstract referral object. The set of actions is somewhat similar to those used in a case (open, update close), but for practical purposes the amount of data that can be stored in a referral is much more limited, amounting only to the ID of the case which opened it, an id which is unique within the universe of other referrals opened by that case, and the next date at which the referral is to be followed up.

Currently, the model for referrals is somewhat in question, so although this is the current workflow for handling referrals, this model will likely be rewritten to be more robust eventually.

Due to practical considerations within the xforms engine, multiple referrals can be opened with the same action. This means that '''<referral_types>''' element can contain an arbitrary set of types for a single '''<referral_id'''. Often

The XML schema for this element is defined as

    <referral>
        <referral_id/>              <-- Exactly One: The unique ID. No two referrals should be open with both the same referral_id and referral_type
        <followup_date/>            <-- At Most One: The due date for all followups referenced in this action
        <open>
            <referral_types/>       <-- Exactly One: A space separated list of referral types which should be opened.
        </open>
        <update>
            <referral_type/>        <-- Exactly One: The referral type to be changed
            <date_closed/>          <-- At Most One: The date the referral was closed. If this element exists, the abstract referral matching the referral_id and referral_type should be closed.
        </update>
    </referral>

Usage Example 1 - Registration/Followup/Close

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.

Registration

XForm specification:

...
<instance>
 <registration>
 <meta>
    ....
 </meta>

 <scratch>
   <case_id/>
 </scratch>

...

 <case>
    <case_id/> 
    <date_modified>
    <create>
        <case_type_id>houshold_rollout_ONICAF</case_type_id>
        <case_name/>
    </create>
    <update>
        <household_id/>
        <primary_contact_name/>
        <visit_number/>
    </update>
 </case>
</registration>
</instance>

...

XML Payload Sent from JavaRosa

 <registration>
 <meta>
    ....
 </meta>

 <scratch>
   <case_id/>
 </scratch>

...

 <case>
 <case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
 <date_modified>11/10/09 21:23:43</date_modified>
    <create>
        <case_type_id>houshold_rollout_ONICAF</case_type_id>
        <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>
</registration>

Follow-Up

...
<instance>
 <follow-up>
 <meta>
    ....
 </meta>

...

 <case>
    <case_id/>
    <date_modified/>
    <update>
        <visit_number/>
    </update>
 </case>
</follow-up>
</instance>

...

XML Payload Sent from JavaRosa

 <follow-up>
 <meta>
    ....
 </meta>

...

 <case>
    <case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
    <date_modified>11/11/09 03:23:18</date_modified>
    <update>
        <visit_number>2</visit_number>
    </update>
 </case>
</follow-up>

Close

...
<instance>
 <distribution_close>
 <meta>
    ....
 </meta>

...

 <case>
    <case_id/>
    <date_modified/>
    <close>
    </close>
 </case>
</distribution_close>
</instance>

...

Possible XML Payload Sent from JavaRosa - Possibility 1

 <distribution_close>
 <meta>
    ....
 </meta>

...

 <case>
    <case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
    <date_modified>12/12/09 16:34:23</date_modified>
    <close>
    </close>
 </case>
</distribution_close>

Possible XML Payload Sent from JavaRosa - Possibility 2

 <distribution_close>
 <meta>
    ....
 </meta>

...

 <case>
 </case>
</distribution_close>

Usage Example 2 - Registration/Followup

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.

Registration

XForm specification:

...
<instance>
 <registration>
 <meta>
    ....
 </meta>

 <scratch>
   <case_id/>
 </scratch>

 <case>
    <case_id/> 
    <date_modified>
    <create>
        <case_type_id>houshold_rollout_ONICAF</case_type_id>
        <case_name/>
    </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>
    <case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
    <date_modified>11/10/09 21:23:43</date_modified>
    <create>
        <case_type_id>houshold_rollout_ONICAF</case_type_id>
        <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>
</registration>

Follow-Up

...
<instance>
 <follow-up>
 <meta>
    ....
 </meta>

 <case>
    <case_id/>
    <date_modified/>
    <update>
        <visit_number/>
    </update>
    <close>
    </close>
 </case>
</follow-up>
</instance>

...

XML Payload Sent from JavaRosa: Not Closing

 <follow-up>
 <meta>
    ....
 </meta>

 <case>
    <case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
    <date_modified>11/11/09 03:23:18</date_modified>
    <update>
        <visit_number>2</visit_number>
    </update>
 </case>
</follow-up>

XML Payload Sent From JavaRosa: Closes Case

 <follow-up>
 <meta>
    ....
 </meta>

 <case>
    <case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
    <date_modified>11/11/09 03:23:18</date_modified>
    <update>
        <visit_number>3</visit_number>
    </update>
    <close>
    </close>
 </case>
</follow-up>

Usage Example 3: Referrals

Referrals are a bit more complex to use, but are relatively straightforward in the general case where only one referral type is possible per case type. These examples are for a household distribution where people can be referred if they seem ill.

Registration Payload

 <registration>
 <meta>
    ....
 </meta>

 <scratch>
   <case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
 </scratch>

 <case>
    <case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
    <date_modified>11/10/09 21:23:43</date_modified>
    <create>
        <case_type_id>houshold_rollout_ONICAF</case_type_id>
        <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>
    <referral>
        <referral_id>SADF2343223I4IU43</referral_id>
        <followup_date>11/17/09</followup_date>
        <open>
            <referral_types>illness</referral_types>
        </open>
    </referral>
 </case>
</registration>

Referral Followup Payload

<referral_visit>
 <meta>
    ....
 </meta>
 <case>
    <case_id>3F2504E04F8911D39A0C0305E82C3301</case_id>
    <date_modified>11/17/09 21:23:43</date_modified>
    <referral>
        <referral_id>SADF2343223I4IU43</referral_id>
        <update>
            <referral_type>illness</referral_type>
            <date_closed>11/17/09 21:23:43</date_closed>
        </update>
    </referral>
 </case>
</referral_visit>

Updated