Create and Manage CommCare Mobile Workers

Mobile Workers are the user accounts that log in to the CommCare mobile app to collect data. You can create and manage these users directly from CommCare HQ. This page provides a high-level overview of how to create and manage Mobile Workers

Setting Up Your Mobile Worker Roles & Permissions

For an overview about Mobile Worker Roles and Permissions, please visit Roles and Permissions Overview

Create a Mobile Worker with Immediate Access

To create a mobile worker and activate the account immediately:

1. Go to Users > Mobile Workers.

Open

2. Click on Create Mobile Worker

3. In the Window that pops up, add a username and password, and click Create. After clicking Create, your new mobile worker is created; it is NOT necessary to add any additional information unless you choose to. 

The username and password you set here will be what the CommCare mobile worker uses to log into the phone application.

Note: All usernames must be in the Roman alphabet, and once created, the username can NOT be changed! (For more information on usernames, see choosing a username section below)

Open

4. If you have Custom User Data or Locations that are required, you also have to add that information.

Create a Mobile Worker Using Account Confirmation

You can also create a mobile worker without setting a password manually, using an email-based confirmation workflow.

1. Go to Users > Mobile Workers and click on Create Mobile Worker.

2. Enter a username and the user’s email address.

   1. Check the box labeled “Require Account Confirmation?”.

   2. If you want to send the email immediately, also check “Send Account Confirmation Email Now?”. Otherwise, you can send it later from the user’s profile page.

3. Click Create Mobile Worker.

Open

The mobile worker will receive an email with a confirmation link. When they open the link, they will be prompted to create their password. Once created, the account becomes active and they can log into the mobile app.

Open

Before the account is confirmed, the mobile worker is considered deactivated. Their account and data can be edited, and they can be assigned cases, but they cannot log in and will not appear in reports or exports by default.

Choosing a Username

We recommend you consider carefully what types of usernames you want to use. Here are some different approaches:

• First name - this is simple for people to remember, but if you have multiple mobile workers with the same name, you will have to devise a strategy, such as serials (laxmi, laxmi2, laxmi3) or use of a second initial.

• Phone number - is a unique number and easy for most people to remember.

• First.last name - is longer and more complex but more likely to be unique for each user.

• Sector/Coverage area name - this has the advantage that if there is lots of turnover, multiple people can use the same username; however, you will not be able to tell which individual person has submitted the data when analyzing later.

Best practices for Mobile Worker Usernames:  

• Design the username so that it is meaningful for the Mobile Worker entering data. 

• If you are tracking the performance of each Mobile Worker individually, we recommend that each Mobile Worker have their own username even if they are sharing a device. CommCare HQ will give you reports on the performance/productivity of your Mobile Workers. If you have multiple Mobile Workers sharing a username, then the performance reports on CommCareHQ will reflect team performance and not necessarily individual performance.

• You may not have duplicate usernames. According to your format, if there is a duplicate username, then you should add some distinction. For example, if there are two Kherunishas in this mobile project, assign one with the username “kherunisha” and the other “kherunisha2.”

• You may use periods ‘.’ in the username.

• You may not use ‘_’ in the username.

• You may not use special characters apart from periods '.' as mentioned above.

• You may use numbers and/or letters in your username.

• All characters should be lowercase in the username.

• All usernames should be in English (Roman Alphabet).

Best practices for Mobile Worker Passwords:      

• Avoid setting the Mobile Worker’s passwords the same as the Admin password. Technical staff associated with your project will have access to the Admin password and may log in in Admin mode for installation and troubleshooting. The default Admin password is 234. (Note that the Admin password is configurable).

• We recommend keeping passwords simple, so Mobile Workers do not forget the password and thus face a barrier in using the application.

Note when using a Mobile Worker on multiple devices:

It is possible for a single Mobile Worker to login on multiple devices, though should be avoided. When the same Mobile Worker is used on multiple devices, those devices will be subject to rate limiting, meaning submissions and restores might fail for a short time period if too many devices are being used simultaneously.

Sending or re-sending a confirmation email

To send (or re-send) the account confirmation email - go to the Mobile Work list view and click "Show Deactivated Mobile Workers". From there click the "Send Confirmation Email" button on the relevant Mobile Worker and follow the instructions.

Open

Edit a CommCare Mobile Worker

User Information

You can change the First/Last names, E-mail, default language, and role. In general, it is only useful to add the First and Last names, as you can see these names in reports, in addition to the username.

It is NOT possible to change the username.

It is possible to add additional information about your mobile workers with Custom User Data, an advanced feature. Additional user information you may want to consider is listed below:

• Mobile Phone IMEI number and Device Model for an inventory of the devices handed out to Mobile Workers

• Mobile Worker demographic information such as education, age, and literacy for training purposes.

For a mobile worker to be able to use CommCare on an Andriod device, their Mobile Worker Role must allow mobile endpoint access. (See Roles and Permissions Overview)

Phone Number

Make sure to add the international country code without any symbols (do NOT add + or 00). After adding a new number, you will be prompted to verify it. This will send you an SMS to which you must reply.

Open

Resetting a Mobile Worker’s Password

There are a few ways to reset a mobile worker’s password on CommCare HQ, depending on whether or not the user has an associated email address:

Option 1: Manually Set a New Password

A project admin can manually reset the password for any mobile worker who has not yet set their own password (e.g., the account was created using the standard method and the mobile worker hasn’t updated it).

To reset the password:

1. Go to Users > Mobile Workers.

2. Select the mobile worker.

3. Open the Password tab.

4. Enter and save a new password.

Note: Once a mobile worker has set their own password (either via account confirmation or email reset), admins can no longer reset it manually. Only the mobile worker will be able to change their password using email-based workflows.

Option 2: Email-Based Password Reset

If the mobile worker has an associated email address:

• A project admin can trigger a password reset email from the user’s profile by navigating to the Security tab and clicking on “Send Password Reset Link”

Open

• Alternatively, the mobile worker can request a reset using the “Forgot your password?” link on the login screen.

Open

In both cases, the user receives an email with a link to reset their password.

Important Notes

Irreversible Password Ownership

Once a mobile worker sets their own password through:

• the initial account confirmation process, or

• the password reset email workflow,

the ability for an admin to reset the password manually is permanently disabled. From that point on, only the mobile worker can change their password using the “Forgot your password?” process or a reset email.

Device Sync Required

CommCare stores login credentials locally on the device. Any password change (whether manual or email-based) will only take effect on the mobile device after it syncs with the server.

To sync:

• From the mobile app home screen, tap "Sync with Server".

• The updated login credentials will be recognized after the next sync.

Understanding Email-Based Password Reset Behavior

When a user requests a password reset either directly using the “Forgot your password?” link or through an admin-triggered email, they may receive multiple password reset emails. This depends on how many accounts are associated with their email address across CommCare HQ.

From the Domain-Specific Login Page:

• If the email is entered:
  The user will receive a password reset email for:

  • Every Mobile Worker with that email in the domain

  • Any Web User with the same email in the domain

• If the username is entered:
  A reset email will only be sent if that user has a valid, associated email address.

Open

From the General Login Page:

• If the email is entered:
  A password reset email will be sent for every Mobile Worker and Web User using that email, across all domains.

• If the username is entered:
  The system will return an error and prompt the user to use the domain-specific login page instead.

Tip: To avoid confusion and unnecessary emails, encourage users to use the domain-specific login page whenever possible.

Use Bulk Upload to create multiple mobile workers at once

This feature requires a CommCare Software Plan

This feature is only available to CommCare users with a Standard Plan or above. For more details, please see the CommCare Pricing Overview.

1. Navigate to the Mobile Workers page on your CommCareHQ project space, as above.

CommCareHQ > Users > Mobile Workers (the page to manage Mobile Workers will show by default)

2. Click on Download Mobile Workers.

Open

3. You can filter and download mobile workers.

Filter by:

a. Role

b. Name or Username

c. Location

d. Active/Deactivated

e. Columns

Open

4. Click Download to download the user.xlsx file. You can see how many mobile workers and how many groups you are downloading.

This file contains all of your current user data: 

a.The first tab contains a row for each mobile worker with the following data:

i.Basic columns: username, password, name, phone number, email, user_id, language, role, is_active

ii. Read-only columns: IMEI, date registered, date of last sync, date of last form submission

iii. Any custom user data fields configured for your project

iv. User location code, if your project uses organizations

b. The second tab contains a row for each group, with its id, name, and whether it is a case sharing group and/or reporting group.

5. Use the downloaded file as a template and populate it with the necessary data. Save the completed file.

6. Click on Bulk Upload.

Open

7. Click the Upload mobile workers button to upload the completed file. 

Open

Bulk Upload Tips and Advanced Info

Sample bulk users excel template

***user_id will be blank if this is a new mobile worker

Tips

• Your first column in excel should say "username", with no spaces. Note that username is required.

• Your second column in excel should say "language". Use the language codes in CommCare, (ex. English = en, French = fra) 

• Name and phone number are optional (but recommended!) fields.

• For any new mobile workers, the password is required.  For existing mobile workers that are in the download, the password will be listed as a *********.  When uploading the file again, the password for these existing mobile workers will not be changed as long as that column contains only *s. If text is set in this column, then the password for the user will be updated to match the text string.  

• Remember to add the international country code to the phone numbers. 

• Add a space between the first and last name of your CommCare user. Do not need to use periods or other punctuation to separate.

Advanced

• Any additional data can be stored by user by adding columns with 'data: xxxx' in the first row of the column.  For instance, village, block, etc can be added, and will be stored. For more information, see https://dimagi.atlassian.net/wiki/x/3DTKfw .

• Mobile workers can be assigned a phone number or multiple phone numbers during bulk upload. To do this, add one or more columns with ‘phone-number xxxx’ in the first row of the column, where ‘xxxx’ is a sequential number (not the phone number). For example, if a user has more than one phone number, this can be sequential numbering, such as “phone-number 1”, then “phone-number 2” and so on. For a user with only one phone number in the “phone-number 1” column, that phone number will automatically be marked as ‘primary’ in CommCare. For a user with several phone numbers, the phone number in the “phone-number 1” column will be marked as ‘primary.’ Inversely, if at least one mobile worker has more than one phone number in CommCare, downloading the user.xlsx file as explained above will generate a file that contains N “phone-number” columns, N being the maximum number of phone numbers that a mobile worker has.

• A web user is able to update or delete an existing phone number via bulk upload. To update an existing phone number, the web user needs to edit the phone number in the appropriate cell, save the excel file and upload it. To delete a phone number, the web user simply needs to delete the number in the appropriate cell (leave the cell blank), save the excel file and upload it.

• If you neither want to delete nor update the phone numbers for any mobile worker, you can simply remove any "phone-number" columns from the upload. This will cause the phone numbers associated with the mobile workers to remain unchanged.

• mobile workers can be pre-assigned to groups during bulk upload.  To do this, any column needs to have the syntax 'group (xxxx)' in the first row of the column. (Note that the 'xxxx' is any identifier, and is not the group name. To keep things simple, this can be sequential numbering, such as "group 1" then "group 2" and so on.)  Any user can be a member of multiple groups of different types by simply adding columns with the correct group syntax.  For groups, make sure you define the group on the 'groups' tab of the spreadsheet and indicate which type of group it is. For more detail see https://dimagi.atlassian.net/wiki/x/1SrKfw .

• For groups, make sure you define the group on the 'groups' tab of the spreadsheet and indicate which type of group it is: There are two types of groups: 1) Reporting groups - these groups users to view by group in the Filters on the Reporting section of HQ.  For example, you can group all mobile workers within one Village or SubCenter. 2) Case sharing groups - these groups allow cases to be shared by different users.  For instance, if two mobile workers were sharing the same catchment area, case information could be shared between these two mobile workers.

  See sample excel file. 

Search for Mobile Workers

You can use the search box to find specific mobile workers. Type in any word to search for that term across all columns or use the syntax below to search in a specific column. 

Names

Insert the first name or the last name of the mobile worker that you are searching for.

Deactivate and Delete Mobile Workers

You can unclutter your reports in two different ways. You may either deactivate (formerly Archive) a user, removing them from the limelight while keeping their data around in the export, or you can delete a user removing all their data permanently. 

Deactivate mobile workers

This will remove mobile workers from the report dashboards while keeping their data in the export. Deactivate a user by clicking the deactivate button on the main Mobile Workers page. Deactivated mobile workers will no longer be able to log into a new phone for the first time. (Note that you can deactivate a large number of mobile workers by following the Bulk deactivation process below).

If a deactivated user submits a form, the following will occur:

• If your app is using secure submissions, deactivated mobile workers' new submissions will be rejected and will stay on the phone

• If your app is not using secure submissions, then it behaves like any other submission, and all case transactions are processed.

• Note: Secure Submissions are enabled for your project by default. For more information, please see https://dimagi.atlassian.net/wiki/x/XTPKfw .

Activate Deactivated mobile workers

If you have deactivated mobile workers, you can click on the Show Deactivated mobile workers link to display them on the screen. Click on reactivate to start displaying this user's data in the reports once again.

Note: Deactivate mobile worker was formerly called Archive mobile worker. When looking for information in the Commcare User's Forum, relevant discussions may sometimes be described as archive.

Bulk Deactivation of Mobile workers

If you need to deactivate a large number of mobile workers, follow those steps. Please note that this feature requires a paid software plan.

1. Go to the User page, click Bulk upload, click on download Mobile workers, get to the downloaded excel spreadsheet.

2. For the workers, you want to deactivate, go to the column "is active" and change the value to false. 

3. Save the Excel file. Re-upload the excel file.

Delete mobile workers

Deleting mobile workers: Are you sure you want to do that?

You may notice that we make it a bit difficult to delete mobile workers. This is because if you delete a mobile worker, you will also be deleting all data that the worker ever submitted or owned. It is not possible to ever get that information back if you delete a mobile worker. We strongly recommend deactivating mobile workers if there is any chance you will ever want to see any of the data submitted by that worker.

Note: once you delete a mobile worker, you can never create a new worker with that username.

This will remove all of the user’s data permanently. Delete a user by clicking on a user's name and navigating to Permanent Actions. Then click the Delete Mobile Worker button and follow the directions.

Things to keep in mind before deleting mobile workers

1. Let's say that while you were testing your app, you created a mobile worker called "test". You might play around with the user and submit a few forms, but none of that data is real, so it shouldn't interfere with the real data, and you will never need to use this data again. In this case, you may want to delete the user and all their data.

2. Let's say instead that you have a mobile worker who has submitted some data but who has taken a leave of absence. You do not want them showing up in your reports day-to-day, but you want to keep their data around. Then you would deactivate them.

You can also watch this video for more information: