Case Configuration
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.
Overview
In the example below, this application has one menu and three forms:
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.
Change Case Type
Open your application in CommCareHQ and click on the menu name
On "Settings" tab and you can change the case type. The case type must be one word without spaces, or multiple words connected by hyphen or underscore. 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 follow up forms. Selecting the registration form will not bring up a case list, but will open a case for the case list in the Follow up menu. Because the follow up menu contains only follow up 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 device—unless it is saved to the case (see Case Management). In any form that registers a new case or updates an existing one, you can specify which case properties you want to save or update in the case.
Why Save Questions to the Case?
The collected data can be displayed in the case list and case details if needed.
The data can be referenced in other forms.
In some cases, it is useful for data analysis.
Let’s say we want to save some data from our registration form as case data so that we can use it in a follow-up form and keep it available on the phone for reference. To do this, you must save those questions to the case properties.
How to Save a Question to the Case (Case Property)?
Go to "Manage Case", located at the top right of the form where you have the questions, or click on the settings gear button next to the form.
Select the "Case Management" tab.
Under the "Save Questions to Case Properties" section, choose a question/questions or hidden value from the "Question" dropdown. The Case Property is the name CommCare assigns to this data—this is also how it will appear in case exports.
Hit the 'Save' on the top right to save all the new updates you made.
Note: You will see that CommCare automatically populates the Case Property column with the Question ID. You can manually change this if you want to call it something else in the case. Changing the name here will not affect the Question ID. However, if you want to refer to village in a different form you'll have to call it by the Case Property instead of the Question ID. Case Property names follow the same rules as Question IDs (i.e. you can't start with a number, you can't have spaces or special characters, etc.)
Below we have added six additional pieces of information from our form. By default the case property will be whatever the Question ID is in the form, though you are free to modify the case property.
Now, for the above 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 list” or "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 of the page 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 follow up form. All that is required to do is to press "Save"- now you will have to pick a name prior to opening any 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 follow up form, or you can have a separate form just for closing cases. In this application we have a form called "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?". See the below gif to learn how it works.
Speedy Tip
Close and archive cases that are no longer active to reduce sync size and improve your mobile application’s performance. Build workflows into your mobile app that allow users to close cases when they graduate out of the program, or become inactive.
Tip: utilize Automatic Case Update rules to close out cases who have not been updated in a certain amount of time (e.g. 6 months or one year).
Configuring the Case List and Detail Screens
In CommCare, case information can be viewed in two ways on a mobile device:
The Case List Screen (a short view showing key case details).
The Case Detail Screen (a long view displaying more detailed case information).
Both views are configurable. Here’s how:
Click on the menu name and navigate to the Case List tab.
By default, at least one case property is included—this is usually the name property.
You can add any case properties that have been saved in any form.
To add a case property, simply click on it. To remove a property, click the "x" on the right side.
Update the ‘Display’ Text (this is what users will see on their screen) and configure the format as needed.
More details are available about Case List configuration.
Key Information about the Case List
Property – The internal name CommCare assigns to this piece of data.
Display Text – The label that appears on the mobile screen for this property.
Format – Determines how the property is displayed (e.g., correctly formatting dates or calculating the current age based on the date of birth).
You can rearrange the order of properties by clicking the up/down arrows on the left side and dragging items above or below others.
Once you're done, click Save to apply your changes.
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.
In the below gif you can see how for the Child monitoring app, we are registered the child case to Vaccination menu or Referral menu based on the option choses.
First you must 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 case open condition if needed. Additionally, you can specify certain case properties to be saved to the new case, as shown in the gif above and explained in the short video below.
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, “vaccination” case for the children needing vaccination shots, as shown in the video below.
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."