What are user roles?

A role is a collection of permissions that you can assign to specific users in specific contexts. The role is available site-wide and can be assigned to a user at site, category, course and activity level. Permissions at a 'lower' context will generally override anything at a 'higher' context. The exception is the permission Prohibit which can not be overridden at lower levels. If two roles are assigned to a person in any context, one with Allow and one with Prevent, then Allow will win.

For example, you may have a role called ‘Trainer’ set up to allow trainers to do certain things (and not others), once this role exists you can assign it to someone in a course to make them a ‘Trainer’ for that course. You could also assign the role to a user in the course category to make them a ‘Trainer’ for all the courses under that category, or assign the role to a user just in a single forum, giving that user those capabilities just in that forum.

A role must have a name, if you need to name the role for multiple languages you can use multilang syntax, for example:

<span class="multilang" lang="en">Trainer</span>
<span class="multilang" lang="es_es">Manager</span>

If you do this make sure the setting to filter strings is switched on for your installation.

The Short name is required for Totara plugins that refer to your roles. e.g. when bulk uploading users. The Description is used to describe the role, so all site administrators have a common understanding of the role. Note that you can base your new role on an existing one (a legacy role).

Assigning system roles

If you assign a system role, then this means the assigned user will have the levels of access and control associated with that role across the entire Totara site. For that reason the default available system roles are only ones which naturally lend themselves to requiring this context.

To assign a system role follow these steps:

  1. From the Administration block go to Site administration > Users  > Permissions > Assign system roles.
  2. Click the name of the role you wish to assign.
  3. Find (or search for) the user in the Potential users column.
  4. Click the users name and then the Add button.

Repeat these steps until you have added all the users you want before navigating away from the page, there is no save button. If you need to remove any users this is similar to the steps above, but you need to click their name in the Existing users column and then click the Remove button. 

It is also worth noting that users will appear greyed out in the Existing users column if they have been assigned a system context role via an audience.

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 and deleting roles, and for moving 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 allow trainees to unenrol themselves from a course when using internal enrolment.

Role import and export

Export role definition to file

To export role definition:

  1. Go to Administration > Site administration > Users > Permissions > Define roles.
  2. Click on a role name.
  3. Click Export button.
  4. XML file containing definition of the role is downloaded to your computer.

The definition file includes following data:

  • Role name and description.
  • Allowed context levels.
  • Allow settings for role assignments, overrides, and role switching.
  • List of permissions at the system level.

Create new role (import) from definition

To create new role (to import a previously exported role definition):

  1. Go to Administration > Site administration > Users > Permissions > Define roles.
  2. Click Add a new role button.
  3. Upload preset.
  4. Click Continue.
  5. Review new role and scroll down and click Create this role.

Reset existing role to definition

To reset role:

  1. Go to Administration > Site administration > Users > Permissions > Define roles.
  2. Click on a role name.
  3. Click Reset button.
  4. Upload preset.
  5. Select required reset options.
  6. Click Continue.
  7. Review changes of role definition and scroll down and click Save changes.


You have three permission levels for each task:

Allow: The role is assigned in the stipulated context.
Prevent: By choosing this you are removing permission for this capability, even if the users with this role were allowed that permission in a higher context.

Prohibit: This is rarely needed, but occasionally you might want to completely deny permissions to a role in a way that can not be overridden at any lower context. A good example of when you might need this is when an admin wants to prohibit one 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.

Allow role assignments: This defines what roles each of the roles listed can allocate to users in the site.

Allow role overrides: This defines what role permissions can be overridden by the roles on the left.

Edit a role

  1. Select Users > Permissions > Define roles on the Site administration menu.
  2. Click the Edit icon opposite the role you want to edit.
  3. On the Edit roles page, change permissions as required.
  4. Click the Save changes button.

In some circumstances it may be easier to create a new role rather than editing an existing one.

Role short name is a low level role identifier in which only ASCII alphanumeric characters are allowed.

Do not change short names of standard roles as standard short names are used in some activity processes.

Add a new role

  1. Select Users > Permissions > Define roles on the Site administration menu.
  2. Click Add a new role on the Manage Roles page.
  3. On the Add a new role page, give the role a name.
  4. Give the role a meaningful short name, the short name is necessary for Totara plugins they refer to the system roles.
  5. Give the role a description (optional).
  6. You can base a new role on the permissions set for an existing role, so that you do not start from scratch. Select from the Legacy role type option to do this.
  7. Set the required permissions.
  8. Click Add a new role to save your new role.

Test the new role

  1. Create a test user and assign the new role to them.
  2. Either log out as the administrator and then log in as the test user, or use a different browser to log in as the test user. Role changes only take effect when the user next logs in.

Allow role assignment

The Allow role assignments tab allows you to define the role a user can assign to another user based on their assigned role.
Using the grid you can allow people who have the roles on the left side to assign some of the column roles to other people.

  1. Select Users > Permissions > Define roles on the Site administration menu.
  2. Click the Allow role assignments tab.
  3. Find the role you wish to set role assignment permissions for.
  4. Click the check box for the roles they are allowed to assign.
  5. Click Save changes.

Allow role overrides

The Allow role overrides tab allows you to define which roles can be overridden by a specific role.

Using the grid you can allow people who have the roles on the left hand side to set overrides for other system roles.

These settings only apply to users who have either the capability role:override or the capability role:safeoverride allowed.

  1. Select Users > Permissions > Define roles on the Site administration menu.
  2. Click the Allow role overrides tab.
  3. Find the role you wish to set role override permissions for.
  4. Click the check box for the roles they are allowed to set role overrides for.
  5. On the Edit roles page, change the Override permissions for others capability to Allow.
  6. Click Save changes.

Allow role switches

The Allow role switches tab allows (or does not allow) a specific role to be able to temporarily change their role to another specific role. For example, this might allow a users assigned to a custom role in a course to see 'Learner' in the Settings > Switch role list.

The selected role must also have the role:switchroles capability to be able to switch.

User policies

User policies allow you to select what actions are taken in specific role circumstances, for example, if someone wishes to sign in as a guest the default role allocated to that person can be specified.

Role for visitors

Users who are not logged in to the site will be treated as if they have the role specified here, granted to them at the site context. The role of Guest is the default and the recommended setting for standard Totara sites. The user will still be required to login to participate in an activity.

Role for guest

This option specifies the role that will automatically be assigned to the guest user. This role is also temporarily assigned to non enrolled users when they enter a course that allows guests without password.

Role for learner, manager assessor

Specify the role that will be automatically assigned to these roles.

Default role for all users

It is recommended that the default role for all users is set to Authenticated user. To set it to a custom role, the custom role must be assignable in the system context and have role archetype set to none.

It is not recommended that the default role for all users is set to learner.

Creators role in new courses

If the user does not already have the permission to manage the new course, the user is automatically enrolled using this role.

Restorers role in courses

If the user does not already have the permission to manage the newly restored course, the user is automatically assigned this role and enrolled if necessary. Select None if you do not want restorers to be able to manage every restored course.

Auto-login guest

If not set, then visitors must click the Login as a guest button before entering a course which allows guest access. 

If auto-login guest is set, the guest login button also needs to be set to show (in Administration > Site administration > Plugins > Authentication > Manage authentication), even though visitors won't necessarily use it.

Hide user fields

The following user fields appear on users' profile pages. Certain user fields are also listed on the course participants page. You can increase learner privacy by hiding selected user fields.

Description, city/town, country, web page, ICQ number, Skype ID, Yahoo ID, AIM ID, MSN ID, first access, last access, My courses, groups and suspended account

  • User fields on users' profile pages are hidden from all users with the capability user:viewhiddendetails not set.
  • User fields on the course participants page are hidden from all users with the capability course:viewhiddenuserfields not set.

Show user identity

Any of the following fields may be shown to users with the capability site:viewuseridentity when searching for users and displaying lists of users.

  • ID number
  • Email address
  • Phone number
  • Mobile phone
  • Department
  • Institution

This setting is useful for sites with large number of users, where the likelihood of users with the same name is high.

Select only one or two fields that are mandatory at your organisation. Do not select more than two fields otherwise tables become very wide.

Full name format

Specify how you want the user's name to be displayed. You can choose to display the name based on the user's language or use: firstname, lastname, firstnamephonetic, lastnamephonetic, middlename and alternatename e.g. "firstname,lastname"

Maximum users per page

You can choose here the maximum number of users to be displayed when searching in courses, groups, cohorts etc. The default is 100 but if your Totara site is very large you can increase the number here.

Enable gravatar

Gravatar (an abbreviation for globally recognized avatar) is a service for providing globally unique avatars.

An administrator can enable the use of gravatars in Administration > Site administration > Users > Permissions > User policies. If a user has not uploaded a user picture, Totara will check whether the user's email address has an associated gravatar and if so, will use the gravatar as the user's picture.

Gravatar default image URL

If gravatars are enabled, an alternative default user picture may be specified. The options are:

If the field is left empty then the theme's default user picture is used.

Temporary managers

It is possible to assign a temporary manager who is able to perform a specified manager's tasks for a specified period. Tasks include approving learning plans, viewing staff records and approving face to face course requests. Settings for temporary managers are:

Enable temporary managers: Enable functionality that allows for assigning a temporary manager to a user. Disabling this will cause all current temporary managers to be unassigned on next cron run.

Temporary manager selection: Determine which users will be available in the temporary manager selection dialog. Selecting Only staff managers will remove any assigned temporary managers who don't have the 'staff manager' role on the next cron run.

Temporary manager expiry days: Set a default temporary manager expiry period (in days).

Check system permissions

The check permissions feature provides a method to view the capabilities for a selected user based on their role assignments. These capabilities determine whether or not the selected user is allowed to perform associated tasks within the system or course.

Checking system permissions

  1. Enter the user's name into the Search field and press Enter.
  2. Select the correct user from the list.
  3. Click Show this user’s permissions.
  4. A list of all permissions for the selected user is displayed.

 Use the filter to search the permissions list. 

Capability overview report

An administrator can generate a capability overview report in Site Administration > Users > Permissions > Capability report.

The 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 in the site. 

For example, it might show the gradereport:user view capability for a learner role is set at the system level as Allow and for Course 1 it is set to Prohibit.

Unsupported role assignment

Unsupported role assignments are role assignments in contexts that are not marked as suitable for that role, such as course creator in activity or course, or teacher in the user context.

An administrator can check for any unsupported role assignments across the site in Settings > Site administration > Users > Permissions > Unsupported role assignments.