This feature requires a CommCare Software Plan

This feature (User Case) will only be available to CommCare users with a Standard Plan or higher. For more details, see the CommCare Software Plan page.

General Description

The User Case is a special type of case associated with a mobile worker. Each mobile worker has one "user case" associated with them. You can design an application to update or reference "properties" associated with a user case. This is useful for:

  • Keeping count of something across all cases assigned to a user, like number of referrals or number of cases with a certain response to a question
  • Having a dynamic form or module filter that references something about the user case
  • Creating a unique ID that increments over each case
    • Note regarding Incomplete Forms: For unique IDs to be assigned correctly, the user must complete one registration form before starting the next. In the case of simultaneous incomplete forms, the same value will be loaded in those forms, resulting in duplicate IDs.
    • Also note that if a user uses multiple devices they would need to complete a sync on both devices anytime they switch

Some general characteristics of the user case:

  • There is only one user case per mobile worker
  • The case type is "commcare-user"
  • The data can be exported just like any other case
  • The special syntax to reference user-case properties in a filter is #user/<property name>
  • The user case type can NOT be modified through an application by anyone else other than the user to which it belongs to

Using the User Case

You can save and load properties to and from the user case just like you would with a normal case.  If you have a standard plan you will see an extra tab available on each Form Settings page:

You can load and save user case properties in this special tab. Be careful to keep track of which properties belong in the user case and which ones belong in case management. When you start typing a property the auto-populate function will generate a list of available properties.

Other Notes

Custom User Data

This feature has some similarity to Custom User Data, but Custom User Data cannot be updated from within the application, only via the CommCareHQ users section. You can reference Custom User Data just like you a user-case property, but you will not be able to update it from the application.

Custom user data is copied to the user case whenever the user's account is updated. This allows custom user data to be available just like other user case properties. If you have a user case property with the same name as a custom user data field, the custom user data will overwrite the user case property value.

Always give your user case properties different names from custom user data to avoid custom user data overwriting the user case property value. If you want to store a new or different value for a custom user data field, copy the custom user data value to a property with a different name.

Like Custom User Data, the User Case also stores required fields such as the mobile worker's username and name.  They can be referenced as follows:

Property on HQCase Property of commcare-user case

First Name and Last Name

(these are automatically strung

together as the case property "name"

as follows: concat(first_name," ",last_name)


Exporting User Case Data

Data associated with the user case can be found in the Case Data Export section. It will be listed as case type commcare-user and will have the same name as a mobile worker's username.



  • No labels