Roles and Permissions Overview
- Ben Talbot
- Mruga Shastri
- Chris Smit
This section provides a high level overview of user management in CommCare - including different user types and structures.
Default Roles
By default, every project in CommcareHQ begins with six default roles with varying degrees of access. This section briefly summarizes these roles. For a detailed description of what each role can and cannot do, please look at the permission descriptions below.
Admin: Admins have complete access to your project space on CommCareHQ. They can add, edit and delete data, along with creating and editing applications.
App Editor: App editors have partially restricted access to CommCareHQ. They cannot access users, groups or locations but can access App Builder and Form Builder. Additionally, they can access reports and exports.
Billing Admin: Billing admins can largely only access subscription information.
Field Implementer: Field implementers can edit data that relates to mobile workers, including locations and groups
Read Only: Users with the Read Only role will be able to access reports and exports, but little else.
Mobile Worker Default: This is the default role for all mobile workers who do not have a role assigned.
Two Types of Users: Mobile Workers & Web Users
In sum, there are two primary types of CommCare users: Mobile Workers and Web Users.
Generally, each user type interacts with CommCare differently and, therefore, has different permissions. The section below provides more information on what types of users you should configure in your project.
Mobile Workers
Mobile Workers (also often referred to as Mobile Users) primarily use CommCare Mobile or Web Applications to collect data in CommCare. Mobile workers have accounts which allow them to access a CommCare application on their mobile phone, tablet, or computer (if using WebApps).
Through a CommCare Mobile Worker account, a mobile worker can access CommCare Mobile, which allows them to access a CommCare application on their phone. Mobile workers then use the application to collect and submit data, follow up with clients, or otherwise use CommCare as part of their work. When a mobile worker wants to open a CommCare application on their mobile device, two options are available for viewing it:
Standard Mode - this allows the mobile worker to login with their username and password; once logged in, the worker can enter and submit data
Demo Mode - also known as a demo user; allows the mobile worker to practice using the application without submitting real data (ideal for training purposes)
Like web users, mobile workers must belong to a project in order to use an application on their phone. However, mobile workers can only belong to one project.
Web Users
Web Users typically play a management role in a project, often overseeing data being collected by Mobile Workers. Web users have accounts which allow them to access the CommCareHQ website, where they can build and change applications, manage users and settings, and view data.
In a given project, you may have a number of people with access to CommCare HQ. Depending on their permissions, these web users may:
Create, modify, download, and deploy CommCare applications
Create, manage, and delete mobile user accounts
View and export data submitted by mobile workers
Send text messages to mobile workers
Manage workspace settings
While web users have a range of tasks that they are able to complete through CommCare HQ, there is one thing they cannot do: submit data. For this, they need a mobile worker account (in addition to their web user account) or an advanced CommCare tool.
Hybrid Configuration for Mobile Worker Accounts
Some projects may have a requirement where mobile workers are required to access some reports on CommCare HQ (or perform some other reporting function on CommCare HQ), in addition to submitting data on CommCare Mobile. In such a scenario, it is possible for mobile worker accounts to be configured in a way where they will be able to access the required functions / reports on CommCare HQ, via the use of Roles and Permissions. More information on how to do this can be viewed on the Roles and Permissions help page.
The exceptions and conditions noted above still stand for such workers: The mobile workers can only belong to one project
Configure User Roles
This feature (Advanced Role-Based Access to CommCareHQ) will only be available to CommCare users with a Standard Plan or higher. The default roles, however, will be available to everyone. For more details, see the CommCare Software Plan page. |
You can create custom project roles and give these roles the desired permissions for accessing parts of your project space. To do this, select the Users tab, then Roles and Permissions. Once on this page, you can choose to add a new role, or to edit any existing role, other than Admin. Either action will trigger the modal seen below:
Most Area Access permissions come with multiple layers of access:
Can Edit: With Edit access enabled for a permission, users can create, edit and delete corresponding data. For example, if a role had Can Edit enabled for mobile workers, users assigned to that role could create, edit and delete mobile workers.
Can View: If Can Edit is disabled, the Can View checkbox becomes editable. Enabling Can View allows users with this permission to see all corresponding data, but not edit it. For example, if a role had only Can View enabled for Web Users, they could see all Web Users but not invite new users nor edit or remove existing users.
No Access: (both Edit and View deselected): If both Can Edit and Can View are disabled for a permission, users will have no access to the corresponding data. This setup removes references to that data from the top and sidebar navigations in CommCareHQ for all associated users. For example, if a role had Can Edit and Can View disabled for Groups, a user with that role would see no links to Groups under the Users tab. If that user navigated directly to groups, say by typing in the URL line, they would receive a 403 error.
Role Descriptions & Permissions
Below is a high-level overview of all of the different types of roles and associated permissions in CommCare.
Area Access Permissions | |
Invite new web users, manage account settings, remove membership. This permission will be hidden if Full Organization Access is disabled. | |
Create new accounts, manage account settings, deactivate or delete mobile workers | |
Groups | Manage groups of mobile workers This permission will be hidden if Full Organization Access is disabled. |
Groups | Allow changing group membership This permission allows you to assign mobile workers to a group. This is typically controlled by the "Edit Mobile Workers" permission, but this option may be useful if you need users who can edit group membership, but not otherwise edit mobile worker data. |
Locations | Manage locations in the Organizations (Locations) 's hierarchy. |
Locations | Allow changing workers at a location This permission allows you to assign mobile workers to a location. This is typically controlled by the "Edit Mobile Workers" permission, but this option may be useful if you need users who can edit location membership, but not otherwise edit mobile worker data. |
Data | View, download and edit form and case data, reassign cases. This also controls access to lookup tables. |
Web Apps | Allow users to enter data using Web Apps. Access may be granted to all apps, a limited set of apps, or no apps. For mobile workers, the “no access” option is ignored. Mobile workers always have full or partial access to Web Apps. When the project has opted to manage Web App permission using mobile worker groups - a feature that is now incorporated into ‘Roles and Permissions’, there will be a warning message “This permission is already configured via Manage Web Apps Permissions. Please remove this configuration before updating access here.” to encourage and assist users in migrating from the deprecated page to the updated configuration. |
Messaging | Configure and send conditional alerts via SMS or email messaging. |
Access APIs | General access to CommCare HQ APIs. Individual APIs require additional specific permissions - for example, the bulk upload users API requires permission to edit mobile workers. Unchecking this permission allows you to completely revoke access to all APIs. *** Important Security Consideration *** This permission grants access to ALL data through the API, even if the web user is Location restricted, thus not having the ability to access all data from CommCareHQ's data tools. |
Applications | Modify or view the structure and configuration of all applications. This permission will be hidden if Full Organization Access is disabled. |
Roles & Permissions | View web user and mobile worker roles & permissions (only Admins can edit roles) This permission is ‘View Only’ for all roles except Admins. View access can be deselected to prevent users from viewing Roles & Permissions entirely. This permission will be hidden if Full organization Access is disabled. |
Manage Shared Exports | Allows users to edit exports whose sharing setting is configured to Edit and Export |
Reports Permissions | |
Create and Edit Reports | Allow role to create, edit and delete reports using the Report Builder. This permission will be hidden if Full Organization Access is disabled. |
Access All Reports | Allow role to access all reports. If this permission is disabled, you have the option to grant access to individual reports. |
Access Specific Reports | If Access All Reports is disabled, a list of specific reports will appear. You can grant or deny the role access to each report individually. |
Download and Email Reports | See under Other Settings Permissions. |
Other Report Settings | Note that there is a separate permission handled elsewhere that provides access to scheduled reports created by other people. That feature is independent of these permission checkboxes, and instead requires for the user be assigned to the Admin role within the domain. Also, see Download and Email Reports below under Other Settings Permissions. |
Other Settings Permissions | |
Manage Subscription Info | Allow role to manage subscription information. Subscription info can be found under your project settings. This permission will be hidden if Full Organization Access is disabled. |
Full Organization Access | Allow role to access data from all locations. If disabled, your users must be assigned locations in order to access CommCareHQ. Disabling this permission renders obsolete Web Users, Groups, Applications, Roles & Permissions, Create and Edit Reports and the Manage Subscription Info permissions and hides them from view. For further information, please see the Full Organization Access sub-section. |
Mobile App Access | Allow mobile users access to offline mobile applications. Mobile App Access enables permissions to access CommCare's Mobile Endpoint API and is essential for enabling offline work from a mobile device. |
Default Landing Page | Upon login, the permission decides where the user begins; on the Dashboard, Web Apps or Reports. If Use Default is selected, mobile workers will be directed to Web Apps and Web Users will go to the dashboard. |
Allow Reporting Issues | Allow this role to report issues. This permission is enabled by default. |
Non-Admin Editable | Allow non-admins to assign this role to other users. Users can assign roles on the Web Users page |
Download and Email Reports | Allow role to download and email report data. If this permission is disabled, the user will not be able to access the My Scheduled Reports tab, export the data to Excel or email it. |
Full Organization Access
The Full Organization Access permission is very powerful and if disabled, can severely limit what a user can see on CommCareHQ. We highly recommend that you test the implications of disabling this permission before rolling it out to your project.
Creating a locations-restricted user by disabling Full Organization Access may be helpful to your workflow if you have a role similar to a ‘District Manager,’ for example. A District Manager may need to access reports and exports, but may only need data restricted to specific locations. This role would not be able to edit apps but could view all data in reports/exports from their assigned location and those locations under it.
Deleting Roles
The Delete Role button is only accessible when no users are assigned to a role. In the below screenshot, users are assigned to the Field Implementer role and therefore, we cannot delete it.