The Case List and Case Detail screens on CommCare Mobile allow mobile users to find and view data about a case on their mobile device, even when offline. This page provides an overview of how Case List and Case Detail screens are used, and explains in detail how to configure them.

Table of Contents:

1 About Case Lists & Case Details
- 1.1 Case List
- 1.2 Case Detail
- 1.3 Case List & Case Detail Configuration
2 Case List Configuration
- 2.1 Display Properties
- 2.2 Select a Format
- 2.3 Adding Icons
- 2.4 Using Barcodes to Search the Case List
- 2.5 Parent Child Selection
- 2.6 Case List Filtering
- 2.7 Case List Sorting
- 2.8 Tip: Displaying History of Changes in Case List
3 Case Detail Configuration
4 Case List & Case Detail Tips & Tricks

About Case Lists & Case Details

Case List

You can specify the case property columns that are displayed in the case list. Due to the limited screen space on a mobile phone, you typically want to only include two columns. The phones will also let you search over the case properties in the columns - it is sometimes useful to include an ID that the user can quickly type a search term or scan a barcode to find the case they are looking for. The case list can also be sorted and filtered, based on the state of the case.

With the case list, you can:

Show properties that will help user find the case they want
Add sorts(Case List Sorting) and hidden properties to help user search for the item they want.
It is possible to have several case properties displayed in the case list, but should consider the device type you are using. Phones have smaller screen sizes, and therefore will be able to display fewer properties in the case list, whereas tablets have a more space on the screen to show more properties. In general, 3 to 4 properties is a good number to display in the case list.

Case Detail

The case detail screen appears after selecting a case from the case list. It usually includes more information than the case list and is helpful for checking if the user has selected the correct case and providing additional information. For example, the case list may just contain the mother's name - but the case detail will include the husband's name to help users check if they've selected the right mother. To prevent the need for scrolling the case detail screen, important properties should be listed at the top.

With the case details, you can:

Can show more properties thancase list.
Add properties that will help user make sure they've picked the right case
Add properties that will help user before opening a form for the case
Use the Format option to display case properties correctly for the user. See Case List and Case Detail Configuration.
Use ID Mapping if displaying any case properties that store item values. This will make sure friendly text is shown.

Case List & Case Detail Configuration

The case list and case detail are configured at the menu level. Click on the name of the menu for which you want to configure the list and detail screens.

Each is configured on its own tab:

Case List Configuration

On the Case List tab you can configure several different things:

Properties to Display - select the properties you want to display in the list
Filters - write an expression which restricts the cases that are seen in the list
Sorting - allows for multi-level sorting of the list
Parent Child Selection - forces the user to first select the parent case before a child case

You can see each of these options in the example below:

Display Properties

In the top section you can select the case properties that will be displayed in the list. We recommend you think about the size of your screen when choosing how many properties to include. For example, a java phone can only fit about 2 properties, while a tablet may be able to fit 3 or 4.

Add a property

select between a default property or calculated property. Simply start typing in the name of the property and it will automatically populate allowing you to select one from the dropdown.

Add Display Text

This is the text that the user will see. Note that if your app is in multiple languages, you will need to save your text, and then change your view to the next language in order to type in the display text for other languages.

Select a Format

by default all of your properties will be "plain" which has no special formatting. There are many other options which can be useful:

Plain

The case property will be displayed as plain text.

Date

The case property will be formatted as a date. You may select one of several options for formatting the date (for example, DD/MM/YYYY).

Time Since or Until

This is a way of referencing a date but showing time until that date, or time since that date. Possible units of time ("measured as") include years, months, or days. The time since/until will be truncated and not rounded; for example if 1 month and 3 weeks have passed, that would show up as 1 month on the device, not 2 months.

Phone Number

CommCare will provide functionality to call or send an SMS to the number stored in the case property.

ID Mapping

This will allow you to provide a friendly or localized label for a value stored in the case property. For example, if you have a 'state' case property for a pregnant mother that stores 'pregnant', 'not_pregnant' or 'delivered', you may want to display 'Pregnant', 'Not Pregnant' and 'Delivered' in the case list or detail.

Late Flag

If the specified case property is more than the specified number of dates in the past (i.e. it is late), then it will be flagged i.e. it will show up as a '*' in a narrow column in the case list view (and as a '*' in the case details view). If the case property is less than the specified number of dates in the past or it is in the future (i.e. it is not late), then it will show up as blank in the case list view and it will not show up at all in the case details view. If the specified case property is null/uninitialized, it will be treated as though it is late. If the late flag is the first column in the case list view, then the not late (un-'*'-ed) cases will all be displayed, followed by the late ('*'-ed) cases.

Search Only

The case property will not be displayed in the case list or detail. However, the case list will let you search over the value of that case property (for example, a Patient ID). You can have more than one case property as search only.

Address (Android/WebApps)

If you have GPS coordinates or an address saved as a case property, you can set the type to Address in the Case Details. This will expose a button that will call out to Google Maps and show the location pinned on the map. This only works on CommCare for Android or CloudCare.

Distance from current location (Android/WebApps)

If you have GPS coordinates saved as a case property, this display property will show the distance between you and the case's location property in kilometers. Upon launching the case list, this display property will show the distance from your last known location until CommCare is able to acquire an accurate reading of your current location. Only supported on CommCare for Android or CloudCare.

You can change the order of properties by clicking on the vertical arrow and dragging them into your preferred order:

To remove a property click on the "x" at the end of a row.

Adding Icons

See here: Application Icons | Adding Icons in Case List and Case Detail screen.

Using Barcodes to Search the Case List

If you collected and saved any barcode scanner type questions as case properties, you can search the case list by scanning that barcode and recalling the case. In order to do that, you need to:

At the time of registration (or anytime in subsequent workflow), add a List of Question Types in CommCare | Barcode Scan type question. Save this question as a case property.
In your case details tab, add the barcode scanner question case property. Tip: many people set the property to “search only” since barcodes are typically not readable/ typeable.

When a user enters the case list, they will be able to select the small square barcode icon. Their camera will open, allowing the user to scan the barcode in front of them. The app will display any cases that match the scanned barcode.

Parent Child Selection

If you have https://dimagi.atlassian.net/wiki/x/9i7Kfw set up for your application, you can make it easier to find a particular child case. The phone can be setup to first show a list of parent cases. After selecting a parent, the phone will then display a list of child cases for that parent. After selecting a child, you can open a particular form for that child. This can be extended to multiple levels of selection - for example selecting a village, then a woman's group and the finally a woman within that group.

On the Case List configuration for your child case menu, scroll down to the bottom of the screen. You will see an option to display a parent list first. Check the box and choose which menu will be displayed as the parent (for example, if your child case menu is displaying children, you would select the mother menu in your application).

If you would like multiple levels of selection, on the parent menu you can also setup another parent list.

Case List Filtering

In some applications it is useful to filter the list of cases that can be shown. For example, you can create two separate menus that have the same case type and display different cases in each (ex. Pre-Delivery and Post-Delivery menus for a 'pregnant_mother' case type).

To add a filter click on + Add a Filter and you will be able to type an expression into the text box.

This expression can refer to any case properties and should return true if a record should be shown and false otherwise. The same functions are available as when writing Display or Validation conditions. Refer to case properties using their name (there's no need to include a "/data/" or "#case" in front of the case property). Two examples are below:

(date(admission_date) + 7) <= today() and today() <= (date(admission_date) + 30)
- Admission date is was between 7 and 30 days ago
if(phone_number = '', false(), (date(admission_date) + 7) <= today())
- Only show cases that have a phone number and whose admission date was more than 7 days ago
#user/favorite_number = "1"
- Only show cases to the user if their user property "favorite_number" = 1

For more information on writing these expressions please see https://dimagi.atlassian.net/wiki/x/WCvKfw.

Case List Sorting

The sorting section determines how cases are ordered in your case list, which is useful if you want higher priority cases to appear higher in your case list.

Your case list can have more than one column of case properties. You can sort your case list by any case property, but if you don't specify a property, it will sort by whatever is in the first column of the case list.

For example, you might want to organize your cases first by Village Name, and then by House Number. Or maybe you want to prioritize the list by Estimated Delivery Date and then Presence/absence of danger signs.

You can sort ascending/descending by four types of properties: Plain (text), Date, Integer, and Decimal. If you add a property with special formatting (i.e. ID mapping, date, etc.) it will be converted to Plain format in the sorting.

To configure sorting click on on + Add a sort property

The process is very similar to the Display Properties above:

Sort Property - start typing the name of the property you want to sort against and the dropdown will populate with case properties that match
Direction - ascending or descending
Format - can be plain, date, integer, or decimal

On CommCare for Android you can also use Fuzzy Search if the property is in the sorting list and fuzzy search is turned on. This is configured on the app level, not in the case list/details section.

Other notes:

You do not have to display a given case property in the case list or details in order for it to be used for sorting
There is no limit to the number of case properties you can sort by
If you are using a question that involves numbers you should choose the appropriate type (integer or decimal) to ensure that the case list is sorted in the way you intend
If you do not add anything to the "sort by" section, the list will, by default, sort by the first item in the case list.

You can also add a sort property from a calculated property. Simply define the calculated property in the "Display Properties" section, and select this option in the "Filtering and Sorting" section. The image below provides a brief demonstration of how you would set this up.

Tip: Displaying History of Changes in Case List

In the case list screen it is often useful to display the history of a tracked value like patient weight or blood pressure.

This can be done by following the incrementing a counter trick, but using a string concatenation instead of an increment:

"weight" is a number question in the form.
"weight_history" is a case property that tracks the history of weight values
"new_weight_history" is a hidden value that calculates the new weight history, including the current answer for "weight". This gets saved back to the case property "weight_history"

In the calculate condition for "new_weight_history", you use the concat function to add the answer to the weight question to the weight_history: concat(#case/weight_history, #form/weight, '-'). The final dash is a separator that ensures the weight history can be easily read.

Example

Icon

The output of this would be "55 - 56 - 58 - " and would continue to track the additions.

Case Detail Configuration

The case detail configuration allows you to specify which case properties your users will see after having selected a case from the case list.

To add a case property click on "Add Property" and follow the directions for Display Properties (above).

You can also organize the Case Detail page using tabs.

Text Formatting

It is also possible to use advanced text formatting to the case detail page. Formats that can be used and how to use them can be found at Text Formatting (Markdown).

Copying Rows from the Case List/Detail

If you want to reuse a property from the case list/detail, or from the case list/details of another screen you can use the copy case list/detail function. For example if you put a really long ID Mapping in the case list, but you also want it in the detail screen, you can now click on the ID Mapping row, Ctrl-C, navigate to the detail screen tab, click on the row below which you want to insert it, and Ctrl-V. To insert at the beginning, click on the header. User sees the built in "selected" browser indication when clicking on a row; you can hit tab to select the next row, shift+tab to select the previous. In ID Mappings in particular translations in multiple languages are maintained.

Calculations in the Case List/Detail

It is also possible to use calculations in the case list/details screen by enabling an Add-Ons via the application settings screen. This feature will allow you to use custom xpath expressions to perform calculations on data and case properties that can be displayed to your mobile workers. For more information on how to enable and use this functionality, please see Case List and Case Detail Configuration | Calculations in the Case List and Details

Localization (Translations in the Case Details/List)

If your application contains multiple languages, you can define different Display Text for each language. Select the language drop down in the top-left corner of the application builder and choose the language you want to update. Update the Display Text for each property in the case list.

You can also update the translations for questions with ID mapping - this is particularly important for multiple choice questions where the choice value will only be in one language. For example, to establish Hindi translations for the choice values, change the language of the application builder to Hindi and navigate to the Case List tab for your menu. Select the property with the ID Mapping format you would like to translate, then click Edit and add Key -> Value mappings (choice value -> translation) for each of the possible choice values for that question.

Here is an example of editing the Display Text for a property

And the view of editing the ID Mapping:

If you are using ID mapping for the same question in multiple menus you can use the copy function described above.

Add Tabs on Case Detail Screen

The following section will show you to add tabs to your Case Details page. You can use this feature to organize or categorize case properties that are displayed to the user in the case details page.

Learn more below.

Setup

To add tabs to the case detail page, use the following instructions:

Proceed to your application on CommCareHQ.
Proceed to the menu settings page for the case detail screen that you would like to add tabs to.
Select the Case Details tab.

At the bottom of the Case Details screen, you should now see the button, ‘Add Tab.’

Selecting the ‘Add Tab’ button will insert a new field at the top of the case details property list.

Note: You will need to select this button for each tab you would like to add. If you want to have 2 tabs on the case detail page, you will need to select this button twice.

Enter a name for the tabs in the field.
Drag and drop the ‘Tab’ fields to organize the case details page. The 'Tab' fields have the option to set a Display condition which can be used to display tabs using specific logic such as process stage. Properties should be placed underneath the tab you would like them displayed on.

Save and Deploy a new version.

Now when you deploy the application, the case details page will look as follows:

Case List & Case Detail Tips & Tricks

Referencing the Username in the Case List or Details

It is occasionally useful to display the username who generated a case in the case list.

One example is: a nurse can receive referrals from multiple community health workers (CHWs). It would be useful for this nurse to know which CHW sent a particular referral case. Here is how to display the username:

In the form that acts upon (creates or updates) the case in question, add a hidden value in the form builder. You may call this hidden value whatever is appropriate.
^{In the calculate condition, paste the following: /data/meta/username}
Save this hidden value to your case in the case management section
You may now add this case property to your case list or case details. It will display the username for the user who submitted the form for the case.

Minimize Duplicates: Registration From the Case List

Minimize data errors and duplicate case entries by setting up Register From Case List in your CommCare application.

This feature is intended to make registration forms directly accessible from a case list. Without this feature, if you want to verify that a case was not previously registered you have to look in the case list first, and if you don't find it, leave and navigate to the appropriate registration form.

With this feature turned on a mobile worker will be presented with an option to jump directly to the registration form if they can't find the case in the case list.

https://youtu.be/vdzb3gJzIU8?si=QfQzfo9V8SPlG8oN

You can read more below.

Appearance on CommCare Mobile

When turned on, a link to your selected registration form will always appear in the case list:

Even if you enter a search term, the option to jump directly to registration will show up at the bottom of the case list:

Configuration on CommCare HQ

Firstly, enable the "Register from Case List" Add-Ons from the application settings page, if its not yet enabled.

Access the application settings page by clicking on the gear icon on the top-left pane of your application.
On the settings page, select the Add-ons tab, then select the button with three-lines in the upper right hand corner and make sure the Mobile Experience is checked.
Scroll down to the Mobile Experience block and select the Register from case list checkbox and hit save.

Choose the menu you want to configure.

From the Registration Form Accessible from Case List dropdown, select the relevant registration form.

Note: The form can be in any other menu in the same application, as long as it is the same case type. The form cannot be in the same menu as the menu that you are configuring with Registration from Case List.

Example app setup with register from case list:

"Register new CCFLS case" is the form that is accessible from the case list of "CCFLS register". The menu filter on "Register CCFLS" is set to "false()" so that registration is only possible through the case list. The settings are set up in the case management tab of "CCFLS register".

Change the label, end of registration action and icon/audio if desired.

The label is what will show up on the mobile as the option to jump to the registration form.

Limitations

The minimize duplicates setting cannot be used for menus that have any of the following:
- Parent/Child Case Selection turned on.
- Menu Mode is configured as "Display menu and then forms"
Minimize duplicates only works only on CommCare version 2.20 or higher
Minimize duplicates will override end of form navigation setup for that form. You should leave it set to * Home Screen and should instead control the end of form action in the Advanced settings as shown on the screenshot above.

Minimize Duplicates Method: Validating from a Label

Minimize data errors and duplicate case entries by setting up validations from a label in your CommCare application. This method utilizes labels, validation conditions, and session instance variables to set up a strict way of preventing users from registering duplicate cases. Please modify the instructions below to fit your specific needs.

Click the expand to learn more.

Configuration on CommCareHQ

Imagine the following scenario:

You have a registration form that creates cases of case type = 'People'
You have mobile workers that create cases using this form.
In this form, you collect the first name, last name, and date of birth of the case.
- First name field = /data/first_name
- Last name field = /data/last_name
- Date of birth field = /data/date_of_birth
If the case you are creating shares the same first name, last name, and date of birth with another case, you want to prevent the user from following through with the registration form.

If this scenario seems similar to your needs, please follow the instructions below:

Turn off easy references by going here:

Make sure all your questions (such as the first name, last name, and date of birth questions) are set up in the registration form.
Make sure all your case properties are created.
Navigate to the relevant registration form where you want to prevent duplicates.
After the last question you want to check (in this example, it would be date of birth since you are checking all three fields in separate questions) create a

label field.

a. In the label field, insert a validation condition similar to the following:
i. count(instance('casedb')/casedb/case[@case_type = 'People'][last_name = /data/last_name][first_name = /data/first_name][date_of_birth = /data/date_of_birth]) = 0

b. Change each of the bold parts of the expression to match your application
i. For example, if the case type in your application is "Individual", you would change the text "People" to "Individual"

Add text to warn the user within the "Validation Message" section of the question..
Save and test.

Your label should look something like this:

Calculations in the Case List and Details

In its basic form, the Case list and Case details definition pages only accept case properties of the module case type. However, there is an addon that allows the use of calculations in the case list/details, called Custom Calculations in Case List. In addition to calculations, the Add-Ons also opens the possibilities beyond the module case type, allowing access to any fixture available in the user’s restore file.

Click below to set this up.

Enabling the Add-on

To turn on this feature, proceed to the Application Settings (1) -> Add-Ons section (2) of the application:

Next, select the button with three-lines in the upper right hand corner and choose “Calculations” (3):

In the Calculation section, check the option “Custom Calculations in the Case List” Add-Ons (4) and hit save (5) to commit the changes.

Using the Feature

Once the Add-Ons has been enabled, a new option will appear in the Add Property dropdown list (1) in the Case List or Case Detail definition pages, selecting Calculated Property (2) will create a new field in which it’s possible to define an XPath expressions to perform calculations (3), including the use of case properties.

Writing expressions

Case properties and attributes in Calculated properties are evaluated the same way as Properties in Case List and Details, as long as they are within the scope of the current case being iterated over. For instance, if the selected property is age, Commcare will actually execute “current()/age”. For properties outside the scope, a full XPath query expression is required. See some examples below.

Calculations within the scope

Type	Description	Expression	Example

Type	Description	Expression
Case attributes	Displays the ID of the current case	current()/@case_id
Case indexes	Displays the ID of the parent case of the current case	current()/index/parent
Case properties	Displays the value of the property	current()/age
Mathematical Calculation	Returns the estimated Date of birth according to the Age stored in the case	date(floor(today() - (current()/age * 365.25)))

Calculations beyond the scope

Type	Description	Expression	Example

Type	Description	Expression
Calculation involving the parent case	Displays the name of the Parent case	instance('casedb')/casedb/case[@case_id=current()/index/parent]/case_name
Calculation involving child cases	Returns the number of child cases	count(instance('casedb')/casedb/case[@case_type='member'][index/parent=current()/@case_id])
Calculation involving User properties	Checks whether the User is assigned to the same location as the patient	if(instance('commcaresession')/session/user/data/commcare_location_id=village_id,"YES","NO")
Calculation involving Locations	Retrieves a location's name based on information stored in the case	instance('locations')/locations/location[@id=current()/village_id]/name
Calculation involving Lookup tables	Retrieves a field of a Lookup table item based on information stored in the case	instance('item-list:medicine')/medicine_list/medicine[index=current()/medication_index]/medication

Overwriting Case List and Case Detail Configuration

For applications that have many similar menus, it can be useful to copy one menu's entire case list or case details configuration to another menu.

This feature is behind an application Add-Ons. Click below to learn more.