Overview

The User Case is a special type of case associated with both mobile worker and web user profiles. Each profile 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 profile type

• 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 ownership of user case is attributed to the respective mobile worker or web user. This means that user cases in their original configuration can’t be shared and, therefore, modified through an application by anyone else other than the user to which they 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.

Restrictions to User case manipulation

Given that user cases are closely linked to their mobile workers, it’s understandable that their manipulation is affected by the type of user. 

• Demo mobile user - considering that such users can’t push data to the server, the scope of the any change will be confined to the device only. In another words, while a demo user can manipulate its user case, changes won’t reflect in HQ.

• Web user - it’s possible to use many Commcare features as a web user. However, when accessing forms that manipulate the user case, Commcare will present the following message “Unable to find case referenced by auto-select case ID”, which means that it is trying to load the user case but is unable to find a valid reference from the current user.

Sharing user cases

Taking advantage of the ability that child cases have to Access parent case properties, it is possible to implement a pattern that can allow access to the user case to users other than its owner, the mobile worker. However, this requires careful consideration and the use of some advanced features, please contact Dimagi if this is a must for the application.

Other Notes

Custom User Data

User properties have some similarity to Custom User Data, but Custom User Data cannot be updated from within the application, it can only be updated 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:

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.

Advanced: Raw User Property References

In some contexts in HQ where easy references aren't supported, you may need to write the reference for the "User Case" or Custom User Property from scratch, similar to Location data.

Translations for these references are provided below. The Easy Reference is how the property would be referenced from within a supported form, and the 'raw reference' can be used in other contexts to refer to the same property.