What is multitenancy?
  • 20 Oct 2023
  • 14 minutes to read

What is multitenancy?


Article Summary

In previous versions of Totara it was possible to support multitenancy using a combination of organisational hierarchies, audiences, dashboards and custom menus to deliver learning and different user experiences to different tenants. While it was possible to organise users into distinct groups, Totara now offers more robust and flexible multitenancy functionality.

Segmenting your site into tenants offers a number of benefits and means that different use cases are now possible. For extended enterprise sites, you can use tenants to deliver learning to users outside of your core organisation. For example, you could create a tenant for users in a partner organisation, allowing them to access learning in a separate environment with dedicated administrators.

A diagram showing how a site with multitenancy enabled could have users, courses, categories, workspaces and activities divided by tenant.

Another key benefit of separating your site into multiple tenants is that you can clearly separate and delegate responsibilities in terms of user and course administration. This means that tenant administrators are only responsible for administration in their tenant and don't need to worry about users, courses and other content in other tenants.

Getting started

To get started with multitenancy you can follow these steps and refer to the respective sections of this page:

  1. If it isn't already enabled then you first need to enable multitenancy on your site.
  2. Next, create one or more tenants and configure the tenant settings.
  3. Customise your tenant themes.
  4. Add existing users or create new users for each tenant.
  5. Create a system-level audience of tenant members and participants if required.

Tenant themes

You can give each tenant a distinct look and feel using Ventura tenant themes. This allows you to brand your tenants based on suborganisations, teams, or whichever categories you use.

You can also give each tenant its own unique login page by navigating to Quick-access menu > Tenants > Settings, and turning on the Enable pre-login tenant themes setting.

If you wish for users to access the site via a tenant login page then you'll need to give them the specific URL, which always takes the format yoursitename/login/index.php?tenanttheme=tenantidnumber, where tenantidnumber is the tenant identifier used for the tenant. Once you have enabled pre-login tenant themes then ?tenanttheme=tenantidentifier can be added to any URL to specify that tenant theming should be applied before a user logs in. The current tenant theme will also be retained after the tenant user logs out.


Adding users

After creating your new tenant you can either associate existing users with the tenant or create new users specifically for the tenant. Below we will look at how to do both of these. 

Individual users can be Tenant Members or Tenant Participants. Before adding users it is important to understand the difference between these roles:

  • Tenant Members: Users can only be a member of one tenant at a time, and their account is managed by the tenant's Tenant User Managers. If isolation mode is turned off then members will be able to see shared spaces in addition to any tenant content, but if isolation mode is enabled then members will not be able to see any parts of the site outside of their tenant. Their access to the site will be suspended if the tenant is suspended.
  • Tenant Participants: Non-members (i.e. system-level users) can be assigned as participants of a tenant. These users are not exclusively associated with a specific tenant, but they require access to the tenant. For example, Trainers or external consultants might participate in a specific tenant's courses, meaning they need to be enrolled on relevant courses, programs and certifications, or added to seminar events.
Note that there are also two tenant roles that can be assigned in the tenant context.

HR import

Site Administrators can use HR import to add or update user information in bulk. When multitenancy is enabled Site Administrators can also add tenant information to the User Source.

FieldDescriptionNotes

Tenant member

This field allows you to specify a tenant ID number for the tenant you want each user to be a member of. Users can only be a member of a single tenant.

If this field is enabled you can specify tenant IDs in the tenantmember field in the Field mappings section.

Users can only be set as members or participants of a tenant, not both.

Tenant participant

This field allows you to add a comma-separated list of tenant ID numbers for the tenants you want each user to participate in. Users can participate in multiple tenants if required.

If this field is enabled you can specify all tenant IDs in the tenantparticipant field in the Field mappings section.

Users can only be set as members or participants of a tenant, not both.

 In a single tenant you can have members and participants in one or many roles.

Tenant audiences  

When a tenant is created an audience is created containing all tenant users (both members and participants). If additional users are later added to the tenant they will be automatically added to this audience. Users are also automatically removed from the audience if they are no longer a tenant member or participant.

The default audience is created at the category level, not the system level. If you wish to create subgroups of tenant members, you can create a dynamic audience at the system level using Tenant Member as a rule.

When setting up a dynamic audience, note that the selected rule sets can result in users across all tenants being added to the audience. To avoid accidentally including users from different tenants in the same audience, ensure that the rules are not too general. Using the Tenant membership audience rule will help.

In order to manage the Rules tab for a dynamic audience, the Tenant Domain Manager (or another role you choose) will need to be given the totara/cohort:managerules capability.

Tenant isolation mode

One additional feature you may want to enable is tenant isolation. When multitenancy is enabled, by default users can see content and users from the site level, which makes it easier to share content across the site. This means that site-wide content is visible regardless of the tenant. However, in some cases you may require your tenants to be totally separated. When isolation mode is enabled the content and users in each tenant are completely separate from other tenants. For example, when isolation is turned on, users in one tenant will only see course catalogue items from their tenant.

You can turn isolation mode on by navigating to Quick-access menu > Development > Experimental > Experimental settings, then check the Enable tenant isolation setting.

Tenant isolation is an experimental setting, meaning it has not been widely tested for all use cases. We recommend you use a test server for testing experimental features before enabling them on your production site.

Please note that when tenant isolation is enabled legacy performance management functionality and learning plans will not be available.

Behaviour when isolation mode is disabled (default)

When Enable tenant isolation is off, the following is true:

  • Tenant members are able to see and interact with:
    • Content within their tenant.
    • Content not within any tenant.
    • Other users who are also members of their tenant.
    • Other users who are also participants of their tenant.
  • A member of Tenant A will not be able to see content in Tenant B or find users in Tenant B.
  • Authenticated users who are not a member of any tenant will be able to see and interact with:
    • Content in the system regardless of whether it is tenant content or not (normal visibility and access control is still respected).
    • Users in the system regardless of whether they are a member of a tenant or not (normal visibility and access control is still respected).
  • Guest users will be able to see and interact with system content and system users only. They cannot access tenants, or tenant content.

Behaviour when isolation mode is enabled

When Enable tenant isolation is on, the following is true:

  • Tenant members are able to see and interact with:
    • Content within their tenant.
    • Other users who are also members of their tenant.
    • Other users who are also participants of their tenant.
  • A member of Tenant A will not be able to see content in Tenant B or find users in Tenant B.
  • Authenticated users who are not a member of any tenant will be able to see and interact with:
    • Content in the system regardless of whether it is tenant content or not (normal visibility and access control is still respected).
    • Users in the system regardless of whether they are a member of a tenant or not (normal visibility and access control is still respected).
  • Guest users will be able to see and interact with system content and system users only. They cannot access tenants, or tenant content.

The main distinction is that with isolation on a tenant member cannot see users or experience content outside of their own tenant.

Reporting

By default, Tenant User Managers and Domain Managers do not have the required permissions to create new user reports. However, global Site Administrators can create and share reports to use for your tenants.

When creating or editing a report you can choose to limit the content of the report based on tenants. To do this follow these steps:

  1. Create a new report or edit an existing one.
  2. Navigate to the Content tab.
  3. To limit the users included in the report to those in the user's tenant, scroll down to the Enforce user visibility restrictions section and enable the Show records based on user visibility rules setting.
  4. To limit the content of the report, scroll down to the Enforce sitewide visibility restrictions section and enable the Show records based on audience, course and workspace visibility restrictions setting.
  5. Configure the other settings as required, then select Save changes.

When this setting is enabled tenant members can only see records for members of their tenant in reports, meaning report data is relevant and report data is not leaked across tenants.


Courses and categories

When you create a new tenant you will also create a new category for that tenant. This is intended to be the location of any courses, programs and certifications created for tenant members. 

You can create, edit and manage categories for a tenant in the same way you would at the system level in Totara.

If you want a course to be available to users in all tenants on your site you can add it to a system-level category. If required you could create a specific category for this purpose.

What happens when a tenant member is assigned to content outside of their tenant?

When a tenant member is assigned to content (such as a course) outside of their tenant, the following behaviours will be true by default:

  • Regardless of any assignment, the user will not be able to access the content belonging to another tenant. All calls to has_capability will return false due to the content and user being in different tenants.
  • If the content does not belong to a tenant (i.e. it is in the system context) and if isolation mode is turned off (default) the user will be able to access it, providing their assignment gives them access.
  • If the content does not belong to a tenant (i.e. it is in the system context) and if isolation mode is turned on then the user will not be able to access it. All calls to has_capability will return false as the content is not in the same tenant as the user.

Moving users and content between tenants

System user moved into a tenant

System users can be moved into a tenant if required. When this happens, the user's context changes its parent from the system context to the tenant context. This effectively puts the user into the tenant. Any content the user has previously created, whether it is personal content (e.g. forum posts, comments) or site content (e.g. courses, activities) is left exactly where it was. The same is true for any assignments or data recorded against the user.

If content was created in a tenant that the user could previously access, but that is not the tenant that they moved into, then they will lose access to that content.

Any assignments the user has remain, however, if they are assigned to content that they cannot access due to now being a member of the tenant, they will lose access to that content.

When a user is moved into a tenant their participation in all other tenants is terminated and they are removed from all other tenant audiences.

Tenant member moved from one tenant to another

A user can also be moved from one tenant to another by a Site Administrator. When they are moved they cease to be a member of the original tenant, and become a member of the new tenant. They still cannot participate in any other tenants.

Any data they have created while a member of the original tenant will remain, as will any assignments between them and content in the original tenant. However, they will lose access to all of this data, and the assignments will not grant them any access.

Tenant course moved from one tenant to another

Courses can also be moved from one tenant to another, or out of a tenant and into the system category. This can be done by editing the course and changing its category.

When a course is moved from a tenant, all of its content and data remains exactly as is. This may mean that users who are assigned and could previously access the course remain assigned but can no longer access the course.

Partially supported features

Although many features are well supported for multitenancy in Totara, some currently have limitations. We are constantly working to improve multitenancy and enable more features. 

The following Totara features currently have limited multitenancy support, meaning they will work but some aspects might not, or may be limited in how you can apply them. 

Audiences

There is multitenancy support for audiences, however, some underlying features are currently not enabled.

As a Tenant Domain Manager, you will not be able to see the Enrolled learning tab when managing an audience in your tenant. This is because the Tenant Domain Manager role does not have appropriate permissions (as some of the underlying features are not fully supported by multitenancy), which could result in the leaking of permissions and access. We are working to implement these features in a future version of Totara. 

When setting up a dynamic audience, note that the selected rule sets can result in users across all tenants being added to the audience. To avoid accidentally including users from different tenants in the same audience, ensure that the rules are not too general. Using the Tenant membership audience rule will help.

Dashboards

Currently, dashboards are supported with multitenancy but with some limitations. As a Tenant Domain Manager or Tenant User Manager, you cannot edit your tenant dashboard.

Unsupported features

At Totara, we are always working to improve our platform and your experience.

Currently, some features across the Totara Talent Experience Platform do not support multitenancy. These features may not interact well with multitenancy instances, or may not allow you to add restrictions as you wish. These features include:

  • HR import: Can be used to add users as members (single tenancy) and participants (one or multiple tenancies). HR Import is still a centralised feature meaning it can't be used by tenant roles.
  • Badges: Tenant roles can only manage course badges. System badge management is currently limited to system-level roles.
  • Messaging: When isolation is off there's no hard restriction on users messaging cross-tenancies. With isolation turned on, tenant members only see users from their own tenancy.
  • Job assignment: Job assignments can only be managed by system-level roles.
  • Learning plans (requires Totara Learn): Learning plans templates can only be managed by system-level roles.
  • Legacy 360 feedback: This feature is outdated and has no multitenancy support 
  • Goals (requires Totara Perform): Tenant members can use goals with isolation turned on, but cannot view company goal details or the associated goal frameworks. Tenant users can create personal goals for themselves or their team. Goal frameworks can only be managed at the system level.
  • Organisations: Organisation frameworks are a system-level feature meaning they can only be managed centrally by system-level roles. There's no way to connect organisations to tenancies.
  • Positions: Position frameworks are a system-level feature meaning they can only be managed centrally by system-level roles. There's no way to connect positions to tenancies.
    When assigning users in a tenant by organisation or position (e.g. to a program or certification), users from other tenants or the site level that meet the assignment criteria will also be assigned, so we strongly recommend that your tenants do not share the same hierarchies.
  • Login as: Tenant members cannot use login as functionality at the moment. However, site-level roles can use login as functionality with all users in the system.
  • Competencies: Competencies can only be managed by system-level roles, and cannot be restricted to specific tenants.
  • Seminar resources (assets, rooms, facilitators): Seminar assets, rooms and facilitators can only be managed by system-level roles, and will be available to users setting up seminar activities in all tenants.
  • Tags: Tags are created and managed at the system level, and cannot be restricted to individual tenants. Tags can only be managed by system-level roles.
  • Authentication methods: Authentication methods can only be enabled, disabled and configured at the site-level, meaning they will be available for all tenants if set up. Authentication methods can only be configured by users with relevant roles at the system level.
  • System and plugin settings: Any system or plugin settings will apply to all tenants. These settings can only be configured by users with relevant roles at the system level.
  • Quick-access menu: A tenant member assigned as Tenant user manager can see the quick-access menu on the site's top navigation bar. However, this menu is hidden from a tenant participant (i.e. not a member) with the same role. To overcome this limitation, all tenant admin actions are available in the administration block on tenant pages.

Next steps

C033 - Course Catalogue(2)The Totara Academy has a whole course dedicated to using Multitenancy in Totara. Here you can learn more on how to set up and use tenants, see best practice, and give it a go yourself.

© Copyright 2024 Totara Learning Solutions. All rights reserved.


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.