casedb

CaseDB External Instance Definition

The CaseDB External Instance defines an artificial instance interface for XForms in CommCare as a mechanism to access case data.

CaseDB Instance Structure

All CaseDB instances share the same structure, regardless of any URI filtering used to connect the instance. The structure is represented by the abstract XML document

<casedb>
    <case case_id="" case_type="" owner_id="" status="">
                               <!-- case_id: The unique GUID of this case -->
                               <!-- case_type: The id of this case's type -->
                               <!-- owner_id: The GUID of the user or group which owns this case -->
                               <!-- status: 'open' if the case has not been closed. 'closed' if the case has -->
        <case_name/>           <!-- The name of the case-->
        <date_opened/>         <!-- The date this case was opened -->
        <last_modified/>       <!-- The date of the case's last transaction -->
        <*/>                   <!-- An arbitrary data value set in this case -->
        <index>
            <* case_type="" relationship="" />  <!-- An index to another case of the given type -->
                                                <!-- @case_type: Exactly one - the type of the indexed case -->
                                                <!-- @relationship: Exactly one - the relationship of this case to the indexed case. See the casexml spec for details --> 
        </index>
    </case>
    ...
</casedb>

CaseDB URI's

The following URI's can be used to reference a case instance interface. The only options available past the basic prefix are filters which will restrict what cases will be included in the database query, which can be used to optimize

jr://instance/casedb This is the basic casedb connector, and provides an interface to the whole of the casedb database (every case on the phone). It should be used normally to access data, or when it's not clear what the scope of reference will be.

**NOTE: ** types below are as-of-yet unimplemented and prospective

jr://instance/casedb/case_type/CASETYPEARG Filters the set of cases that will be in the instance to only those whose case types match the argument provided (the final token of the URI). Useful for doing searching or selection of all cases of a certain type.

jr://instance/casedb/session/CASEIDARG Filters the set of cases that will be in the instance to either 0 or 1, with the returned case being the singular case with a GUID which matches the value contained in the session value at the index CASEIDARG.

To Illustrate: The instance source and reference pairing

<instance id="casdb" src="jr://instance/casedb/session/pregnancy_id"/>

<bind nodeset="/data/mother_name" calculate="instance('casedb')/casedb/case/@case_name"/>

is equivalent to

<instance id="casedb" src="jr://instance/casedb"/>
<instance id="session" src="jr://instance/session"/>

<bind nodeset="/data/mother_name" calculate="instance('casedb')/casedb/case[@case_id=instance('session')/session/data/pregnancy_id]/@case_name"/>

this provides a convenient shorthand for accessing case information for one of the most common use cases, which is to lookup multiple values from a single case.