You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »


Custom User Data (formerly called Custom Registration Data) is an advanced tool that enables you to store and reference additional information about your mobile workers.  By default, when you register a new mobile user you can specify their username, first name, last name, e-mail address, language, role, and phone number. Custom User Data allows any number of additional fields. For example, you could note a category of user, additional location data, or other metadata.


Custom User Data is useful if you want to be able to able to reference additional information about users in forms or cases.  For example, you may automatically want to store the user's district or village as part of any cases they register to make future data analysis easier.  

1. Configure Custom User Data

In this stage you must define what data fields you want to collect for each mobile user.

  • On CommCareHQ navigate to Users -> Mobile Workers.
  • Click on the "Edit User Fields" button in the middle of the screen:

You will be brought to Edit User Fields page:

On this page you have the option of adding fields to collect for mobile workers. For each field you will need to define the following:

  • User Property: The unique ID you can use to reference this property in the application builder. The property may not contain spaces. This field is analogous to a "Question ID" in the form builder.
  • Label: The field label that users will see when adding or editing a User in CommCareHQ.
  • Required: Indicates whether this field is required for each user. If it is marked as required then you will not be able to create a mobile worker without filling in this field.

To add a new field click on "Add New Field" and fill in the User Property and Label fields.

To remove a field click on delete - but note that if you delete a field that has already been filled in for users, the next time that user's information is updated that data will be deleted as well.

You can change the order of the fields by dragging the vertical arrows on the left side of the screen.

Here is an example with three user properties:


2. Add Custom User Data

There are two ways to add custom user data - through the Mobile Workers section of CommCareHQ, or through Bulk Upload

A - CommCareHQ Mobile Workers Page

After you configure the user data, each time you add a new mobile worker the CommCareHQ user will be prompted to populate the field, in addition to the standard username and password. Required fields will have to populated at time of creating the mobile worker, while other fields can be populated at creating the mobile worker account. For example, using the configuration from above, in step 1 of creating a mobile worker the Care Team Role field shows up and is required, because the field was marked as required in the Edit User Fields section:

The other, non-required fields, will show up on the next screen after creating the mobile worker:


B - Bulk User Upload

This feature requires a CommCare Software Plan

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

You can use the Upload Mobile Workers in Bulk tool to add and update custom user data in bulk.

Before using the spreadsheet note that you will need to follow the instructions above to set up your user fields.

  1. Download the your current users excel file
  2. Add data to the custom user data columns.
  3. Save and upload it!


  • You cannot add new user data fields by just adding a new column in the Excel file. You must use the edit user fields page to set it up.
  • If a field is required and you upload a spreadsheet that does not have a value for that field for all users, the upload will fail.


How to Reference Custom User Data in an Application

You will have to reference the user data through the commcaresession: instance('commcaresession')/session/user/data/user_data_name

So for example, to reference the training_level data such that you only want user with training level 3 to see something, you would need to refer to the following:

if(count(instance('commcaresession')/session/user/data/training_level) > 0, instance('commcaresession')/session/user/data/training_level, 'Unknown')

another example, for 'village'

if(count(instance('commcaresession')/session/user/data/village) > 0, instance('commcaresession')/session/user/data/village, "Unknown")

The use of the "if" statement prevents CommCare from panicking if it can't find a value for training_level

See the full documentation for the commcaresession object


  • No labels