IndexedCaseOperations

Using Case XML transactions, you can assign indexes to your case. When a case indexes another, CommCare ensures that when cases are synced, the indexed case is always present as long as the indexing case should be. For instance: even if a case representing a parent is closed, its data will be on a phone if cases which represent the children (and index the parent) are open and assigned to the user.

For ease of description when describing relationships, the word subcase refers to a case which has an <index> to a parent case.

There are a number of implementation patterns for indexed cases which can be helpful for laying out an applicaiton, this guide covers how some common operations are structured most effectively, and how subcases can be used to lay out data in different ways.

Common Tasks

This is a list of XPath and data structures which cover common operations for indexed cases.

Given a subcase ID

Retrieving a parent case's ID

instance('casedb')/casedb/case[@case_id = /data/subcaseid]/index/myparent

Referencing a parent case's data

instance('casedb')/casedb/case
[@case_id = instance('casedb')/casedb/case[@case_id = /data/subcaseid]/index/myparent]
/parentproperty

Given a parent case's ID

Count number of Children

count(instance('casedb')/casedb/case[index/myparent = /data/parentcaseid])

Create a select question to choose a child case

<select1 ref="/data/child_chosen">
    <label>Select a child</label>
    <itemset nodeset="instance('casedb')/casedb/case[index/myparent = /data/parentcaseid]">
        <label ref="case_name"/>
        <value ref="@case_id"/>
    </itemset>
</select1>

Indexed Case Patterns

Here are some ways that indexed cases can be used to represent different information layouts.

Parent and Child Relationships

One of the most common patterns for using case indices is establishing link between parents and children, both of which are being managed by the CommCare user directly. In this relationship, there is one parent, and possibly many children per parent, both of which have their owner_id set to the current user, or to their case sharing group. All of these cases will be present on the user's case lists until the child and parent cases are closed as part of their normal workflow.

Ownership Stub

In some programs, there is a large base of cases which won't all be assigned to individual users in the steady state, but individual cases may need to be assigned temporarily to a user, or multiple users. One example of this is a clinic with a large number of patients which needs to assign a case to a mobile user temporarily to follow up on care.

In this relationship the subcase is a unique case which gets created and has its owner_id set to the user who will receive the case, that case has an index which is set to the case that is to be assigned. When the user syncs, they receive the subcase, and then parent case (and anything which it indexes) as if it was assigned to them.

For example: If a clinic wants to assign a case representing a newborn to a mobile worker A, and they sync, their phone will receive:

 referral_case   -(indexes)>  newborn_case   -(indexes)>  mother_case
 (owned by A)               (not owned by A)           (not owned by A)

As soon as A closes the referral_case, the rest of the case structure is purged from the phone on the next sync.