Custom User Data is useful if you want to be able to reference additional information about users in forms or cases.  By default, when you register a new Mobile Worker you can specify their username, first name, last name, and password. Similarly, you can specify a new Web User’s Email, Role, and Profile. Custom User Data is an advanced tool that enables you to store and reference any number of additional information about your mobile workers or web users. For example, you could create a category of users, additional location data, or other metadata.

Using Custom User Data

Configure Custom User Data

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

• On CommCareHQ navigate to Users -> View All.

• Click on "Edit User Fields" in the sidebar menu:

Open

You will be brought to Edit User Fields page:

Open

On this page, you have the option of adding fields to collect for mobile workers/ web users. 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 or edit a user without filling in this field. The fields will appear with an ‘*' next to the label on the main "Create Mobile Worker", “Edit Mobile Worker’ and “Invite Web User” and “Edit Web User” pages.

• Required for: This dropdown marks the field required for a specific user type. It is only activated when the checkbox is selected to mark the field required. The options include

  • Web users: The field will be required for creating/editing Web users

  • Mobile Workers: The field will be required for creating/editing Mobile workers. This is the default option for all the new fields being created.

  • Both: The field will be required for creating/editing both Mobile workers and Web users. This is the default option for all the existing fields created before October 31, 2024.

• Validation: Here you specify the type of input expected, the options are:

  • none:  you would like to use free text input;

  • choices: if you want to pre-define choices to appear as a dropdown; or

  • Regex: if you would like to use a regular expression for validation of the input. This is useful for validating that custom user data, custom location data, or custom product data follow a specified format. To design and test your regular expressions, you can use this website: http://www.regexr.com/.

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 populated for users, the next time that user's information is updated, any data collected for that field will be deleted as well. See below for more on this.

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:

This configuration would then update the Mobile Worker Registration Page to look like this:

The process remains ultimately the same for web users. The new UI for inviting a web user looks like this:

Now, it is also possible to edit Web User information once they accept the invite. This was previously available only to mobile workers.

Add Custom User Data

There are two ways to add custom user data - through the Create/ Edit user pages on CommCareHQ, or through Bulk Upload.

CommCareHQ Web Users / Mobile Workers Page

After you configure the user data, each time you add a new web user/mobile worker the CommCareHQ user will be prompted to populate the field, in addition to the standard username and password fields. Required fields will have to be populated at the time of creating the web user/mobile worker, while other fields are optional. These can be filled in during registration or when editing an account.

Bulk User Upload

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

Before using the spreadsheet to update user data 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 and any other fields you want to populate.

3. Save and upload it!

Notes:

• 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.

• If you change the Custom User Data for a user, the new values should sync down to the user's phone, any time the user syncs with the server as long as the user has filled in at least one form since the last sync.

Using Custom User Data in an Application

Storing Custom User Data in a Hidden Value

You will have to reference the user data through the commcaresession.  The format is generally instance('commcaresession')/session/user/data/custom_user_data_name

So for example, to put the value of the custom user data village in a hidden value, add the following to the calculation: 

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

Use a Custom User Data in a Display Condition

For example, to only show a particular question if the user is a supervisor (using the custom user data is_supervisor), add the following to a question's display condition.  Replace is_supervisor with the name of your custom user data and yes with the value you want to check for. 

^{count(instance('commcaresession')/session/user/data/is_supervisor) > 0 and instance('commcaresession')/session/user/data/is_supervisor= 'yes'}

Accessing Phone Number and the User Name

Some additional information is also available through custom user data. They are automatically added to the data:

For example, to combine the user's first and last name into a single name in a hidden value, you can do the following:

^{concat(instance('commcaresession')/session/user/data/commcare_first_name, " ", instance('commcaresession')/session/user/data/commcare_last_name)}

Removing Custom User Data and Handling "Uncategorized" Data

As described above, you can remove fields on the "Edit User Fields" page. Removing a field does not necessarily remove the data that is attached to users.

The bottom of the page includes a checkbox to remove unused fields:

If you remove a field and do check this box, all data for the removed field will be removed from users.

If you do not check this box, the field will be removed, but users will still have the related data, which is now called "unrecognized" or "uncategorized." If you created a field called "size," assigned a value to a user, and then deleted the field, when you view the user you will see this section of "unrecognized" data. As described in the warning, if you save this user, the "size" value will be deleted.

This unrecognized data will still appear in mobile worker downloads and can still be edited. It will appear in columns marked "Uncategorized."

Limitations

There are instances where custom user data will not be activated when used in an Application that was copied from another one.