Custom User 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 worker you can specify their username, first name, last name and password. Custom User Data allows any number of additional fields. For example, you could create a category of user, additional location data, or other metadata.
Custom User Data is useful if you want to be 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.
View the introduction video for Custom User Data
In this stage you must define what data fields you want to collect for each mobile user.
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:
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:
There are two ways to add custom user data - through the Mobile Workers section of CommCareHQ, or through Bulk Upload
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 fields. Required fields will have to be populated at time of creating the mobile worker, while other fields are optional. These can be filled-in during registration, or when editing a worker account.
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 to update user data you will need to follow the instructions above to set up your user fields.
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")
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'
The user's first and last name, and phone number are 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)
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."