- 28 Nov 2023
- 6 minutes to read
What are roles?
- Updated on 28 Nov 2023
- 6 minutes to read
A role is what you assign to users on the site to allow them to perform certain actions. These actions will be determined by the capabilities given to the role, and what level of permission each capability has been granted. You can assign roles to specific users in specific contexts of the site. There are several default roles that you can assign in Totara.
Defining user roles
The Define roles page has four tabs: Manage roles, Allow role assignments, Allow role overrides and Allow role switches.
The Manage roles tab contains a list of roles on your site. The Edit column contains icons for editing, deleting, and moving roles. You can move them up or down in the list (affecting the way that roles are listed around Totara). Below the table is an Add a new role button.
If you wish to modify the capabilities for a particular role, you can do so by editing the role. For example, you may want to prevent users from customising their dashboards.
Before we can look at creating, editing, and assigning roles in more detail we first need to understand how roles work, including what permissions and capabilities mean within Totara.
Role contexts
Roles are available site-wide and can be assigned to a user at various levels:
- System: A role at this level (and its associated permissions) will apply to the entire Totara site
- Tenant: If you are using multitenancy, then a role can be assigned at the tenant level
- User: A role can be assigned at a user level, meaning it will apply to that user in all other contexts
- Category: A role assigned at this level applies to the entire category and therefore permissions associated with the role would be granted for all courses contained in that category (requires Totara Learn)
- Program: A role assigned at this level applies to the entire program and therefore permissions associated with the role would be granted for all courses contained in the program (requires Totara Learn)
- Course: A role given to a user within the confines of a specific course (requires Totara Learn)
- Activity module: A role can be given within an individual activity, and its permissions would only apply within that activity - it would not apply to the rest of the course or any higher contexts (requires Totara Learn)
- Block: A role can be given within an individual block, and its permissions will only apply within that block - it would not apply at any higher contexts such as the rest of the dashboard
These levels act as a hierarchy for permissions, with system being the top and block level at the bottom. Generally permissions at a lower context will override those at a higher context in the case of a user having been assigned multiple roles. For example, if a user is given a role with editing access to an individual block then they will be able to access the block with editing permissions, regardless of their system-level permissions.
Permission levels
Additionally, it is important to understand that there are four levels of permissions (which are set for the capabilities that make up a role):
- Not set: The permission hasn't been set for this capability
- Allow: Permission is granted for the capability
- Prevent: Permission is removed for the capability, even if allowed in a higher context
- Prohibit: Permission is completely denied and cannot be overridden at any lower (more specific) context
Permissions will also act hierarchically, with an Allow permission beating a Prevent permission in the case of multiple roles. However the Prohibit permission cannot be overwritten, regardless of context or anything else.
Although you will not normally need to use Prohibit, a good example of when you might need this is if a Site Administrator wants to prohibit a specific person from starting new discussions in any forum on the whole site. In this case they can create a role with that capability set to Prohibit and then assign it to that user in the site context.
Capabilities
Capabilities are used to define what a particular role can do in the system. For example, the View any evidence on others capability (also presented as totara/evidence:viewanyevidenceonothers) is allowed for the Staff Manager role at the system level. This means that anyone holding that role can view evidence for users they have access to, such as their team members. If this capability was removed from the Manager role then anyone who was assigned that role would no longer be able to view evidence for their team members. Conversely, if you wish to allow another role, perhaps a new role you have created, to be able to view other user's evidence then this can be done by editing that role and giving it the View any evidence on others (totara/evidence:viewanyevidenceonothers) capability.
Capability overview report
A Site Administrator can generate a capability overview report via Quick-access menu > Users > Permissions > Capability report. This report allows the administrator to select a capability and one or more roles. The report shows the role and its permission level for that capability. The report also shows if that capability was overridden for the role anywhere on the site.
For example, it might show the block/totara_user_profile:myaddinstance capability for the Authenticated User role is set at the system level as Allow (although the default is not set), and for the Guest role it has been overridden to Prohibit.
Managing roles
After looking at permissions and capabilities in more detail, we can now move on to look at how you can manage roles within Totara. This includes editing existing roles (perhaps to add or remove capabilities) and creating brand new ones. All new roles will need to be tested before they are assigned to any users. Testing new roles is important, because sometimes capabilities can have different effects depending on which context levels they are assigned at. Therefore, it is also best to test new roles to make sure they have the intended capabilities and there are no unseen side effects.
Roles in multiple languages
All roles must have a name, but you can also give each role a name in multiple languages using multilang syntax. For example:
<span class="multilang" lang="en">Manager</span>
<span class="multilang" lang="es_es">Gerente</span>
If you do this, make sure the Multi-language content filter is enabled on your installation.
Allow role switches
The Allow role switches tab determines which roles can temporarily change their role to another specific role. For example, with Totara Learn this might allow someone with an Editing Trainer role in a course to view the course from the perspective of a Learner. This would be done by going to Course administration > Switch role and clicking Learner.
The selected role must also have the Switch to other role (role:switchroles) capability to be able to switch.
The switch role functionality is designed to enable users to test aspects of Totara and view areas of the site as other user roles might. It is not designed to allow a user to complete content or activities when viewing the site as another role, as completion tracking and user security measures prevent this behaviour.
Unsupported role assignment
Unsupported role assignments are role assignments in contexts that are marked as unsuitable for that role, such as the Workspace Owner role in a course context. If a specific context is removed from a role with users assigned, the role assignment will be marked as unsupported.
A Site Administrator can check for any unsupported role assignments across the site in Quick-access menu > Users > Permissions > Unsupported role assignments. As a Site Administrator, you can use this tool to manually remove any unsupported role assignments. For example, if you have created a role which is available at the system and tenant contexts, you may decide that it isn't appropriate to assign that role at the system level. In this case, you could remove the system context by editing the role. If the role was assigned to any users before being editing, the role will be flagged as an unsupported role assignment, as shown below.
If any unsupported role assignments are detected, these will be displayed with the affected role, the unsupported context, and the number of affected users. In the Edit column you can select either:
- The cog icon () to amend the role and change the available contexts as required
- The cross icon () to delete all unsupported role assignments for that role in the given context level
In the above example, deleting this unsupported role assignment would remove any assigned user's role at the system context. If this user was also assigned to the same role at the tenant context level, this role would not be affected.
Next steps
- Add a new role
- Edit a role
- Check system permissions
- Reset existing role to definition
- Import role definition from file
- Export role definition to file
- Allow role overrides
- Allow role assignment