Configuring Cases in CommCareHQ
This is a guide to configuring case management in your CommCare application. We'll walk through an example application, "Child Monitoring", to see how this is done.
This example application has one menu and three forms:
- Child Menu
- Registration - should create a new case
- Follow up - the mobile user should have to choose a child's name before opening this form, and it should update information about the child
- Edit/Close - should update basic data about the child and be used to close the case/remove the name from the phone.
Menu Case Type Setup
Open your application in CommCareHQ and click on the menu name
Open the "Case Management" tab and enter a "type" that describes your cases. The case type must be one word (no spaces), but the word can be whatever you think best describes the type of case. In Child Monitoring, our case list will be a list of children. So our case type will be "child". Click on the [?] next to "Case Type" for more information on case types. If you have more than one menu or application that share cases, they will need to have exactly the same text in the "Case Type" box.
Hit "save" when you're done.
Form-level Case Management Overview
To configure case management at the form level, you need to select the gear icon that appears next to the form name in the form tree on the left hand side of the screen:
By selecting this gear, you should be brought to the "Case Management" tab at the form level. Select the drop down field in the 'Form Action on Case" section to define what action your form will take on a case:
There are four options to choose from:
- Does not use cases - this is the default option, and is used for forms that do not have case management; for example a simple survey form. You do not have to configure the menu at all if all your forms use this option.
- Registers a new case ("opens a case") - this makes the form one that will create a new case of the case type specified in the menu settings
- Updates or closes a case - with this option the user will have to select a case prior to opening the form
- Registers a case for a different case list - this is a less common option that can be used when you want a menu which only has the purpose of opening a case for a different menu. For example, if you are tracking pregnancies, you may decide to put the registration form in a separate menu from your followup forms. Selecting the registration form will not bring up a case list, but will open a case for the case list in the Followup menu. Because the followup menu contains only followup forms, selecting the menu on the phone brings up the case list and then the form list. This is a nice workflow when possible.
Registers a New Case ("open a case")
You need some way to add new cases to the case list. All applications with case management will have a form which functions to register, or open, a new case. Often this is called a Registration Form and is used to collect preliminary details about the case. For example, our Child menu has a form named "Registration" that collects details about the child (name, date of birth, gender, etc.). Click on the form that you want to create a new case and go to the "Case Management" Tab.
In the drop-down menu choose "Registers a new case"
The first option you have is to open a case based on the answer to a question in the form. For example, you may use Registration as a screening form and only create cases for children who have not had any vaccinations. To add a condition click on the "+ Only if the answer to..." and specify the question you want to reference. You can remove the condition by clicking on the "x":
For this form, we want to open a case whenever the registration form is filled out, so we will not click on the "+". If you have set that up, go ahead and click the 'x' to the left hand side of the condition to remove it.
Now we need to give our case a name. Our cases are children, so we want to name our case based on the child's name. Since a case will always need a name, CommCare will default to use the first question that you add to the form as the case name. This can be configured or changed by selecting the "question" drop down next to the "name" case property.
You also have the option to "Add a Child Case." That is discussed here.
Once you hit "save", you have successfully set the registration form to add a case to the case list for every child!
Saving Data to the Case
As soon as the user finishes filling out a form on the phone, the collected data is removed from the phone – unless you save it to the case (see Case Management). On any form that registers a new case or updates a case, you can specify which case properties you want to save to, or update in, the case.
Let’s say we want to save some data from our registration as case data so that we can use that information in the followup form, and so we can have that data on the phone for reference.
In the box "Save questions to case properties" you’ll see two items you have to identify: “Question” and “Case Property”.
From the “Question” dropdown we can select any question or hidden value from the form. The Case Property is what CommCare will name that piece of data- this is also how the data will appear in case exports. However, this name is not visible anywhere on the phone, so you can name it whatever best describes that information to you, or whatever is most useful for your data analysis. It must not contain any spaces.
Below we have added six additional pieces of information from our form. By default the case property will be whatever the questionID is in the form, though you are free to modify the case property.
Hit “save”. Now, for example, The child's date of birth is saved to the case as "child_dob"- we can show this information to the mobile worker as a "case detail" and we can also use child_dob in other forms.
Updates or Closes a Case
Now let's move on to the follow-up form. Here, we want the user to first select the patient from the case list before they fill out the form. So we'll set the requirement to "Updates or Closes a Case". We now have a way to add new cases to the list, and to select the case from the list before filling out the followup form. You will see the following options:
All that is required to do is to press "save"- now you will have to pick a name prior to opening any form.
Once you opt select 'Save Property', two fields should appear. On the left side of the screen is the option to "load properties" from the case that you want to reference in your form. On the right side is the ability to update case properties with questions from the form:
Again you have the option of opening Child Cases from the form.
Closing a Case
The last step to a basic case management system is finding the right way to remove old, unwanted cases from the case list. You can close the case based on the answer to a question in the followup form, or you can have a separate form just for closing cases. In this application we have a form called "Edit or Remove Child". Just as with opening a case, you can have a form that always closes the case, or you can add a condition. Here we want to remove the child/close the case if the user says "yes" to the question "Do you want to remove this child from your phone?"
Configuring the Case List and Detail Screens
There are two ways to view case information on the phone: the “short” view on the case list screen, and the”long” view on the case detail screen (see Case Management). The data in each of these views is configurable. Here’s how:
Click on the menu name and take a look at the Case List Tab.
At a minimum, you have at least one case property in the case list and details. By default, the name property is already added. You can add to the case list and details any of the case properties that you have saved in any form.
To add a case property just click on it, and to remove a property click on the "x" on the right side.
You can then update the Display Text which is the text the user will see, and can configure the format. More details are available about Case List configuration.
Some key information about the Case List:
- “Property” is CommCare's internal name for this piece of data.
- "Display Text" is what will appear on the phone’s screen as the label for this property.
- “Format” lets you choose how the phone treats the property, so that it correctly displays dates or even calculates current age based on the date of birth.
You can change the order of the properties by clicking on the up/down arrow along the left side and dragging above or below other added items.
Hit “save” when you’re done.
Registers a Case for a different Case List
This is an advanced tool you can use for complex applications with registration menus. For example, if your application has menus for households, children, women, and villages, you may want to have one menu in which you can manage all registrations. For example, your Registration menu could look like this:
- Registration menu
- Register a Village
- Register a Household
- Register a Woman
- Register a Child
For each form in this menu you would set the Case Management to "Register a case for a different case list" and then configure the child case management section to open new cases:
First you much choose which menu or case list you want to open the case into. For example you could open a case into the "Child menu". This means the new case will be the same case type as the destination menu.
As with opening any case, you can specify a condition if desired. Additionally, you can specify certain case properties to be saved to the new case.
You can also open multiple cases from one registration form. So you can have one form that opens a case in the Child menu, and another that opens a "referral case" for sick children. To do this, you would simply add a few Child Case management sections by selecting "+Add a Child Case to open a case for a different Case List."