If you believe you will need to enable Multi-tenancy, please mention it to your Account Manager prior to enabling anything to determine if it is the right fit for your organisation.

1 Overview
2 Multi-tenancy options
- 2.1 Company Hierarchy
- 2.2 Realm Hierarchy
3 How it works
- 3.1 Example
4 Steps to setup Multi-tenancy
- 4.1 Table properties
- 4.2 Realm selector
- 4.3 Multi-tenancy specific scripts

Overview

Servicely provides the ability to enable Multi-tenancy on an instance, which allows you to securely separate data per “tenant”. This is typically required in situations where you provide access to the system to customers external to your organisation. Servicely’s Multi-tenancy setup allows you to do so in providing the ability to allow you to say how records are separated (in terms of what is used as a “tenant”), what roles or users can see what records and any visibility rules on a per table basis. It is not typically used to change configurations per tenant (as each platform feature individually will control that), but much more about record visibility.

Multi-tenancy options

To support multi-tenant requirements, Servicely provides two main Multi-tenancy options.

Company Hierarchy

The company hierarchy tenancy option is suited for organisations that will only have a low number of tenants enabled on their environment with only 2 levels of a tree like structure. It is mostly suited for organisations where the tenancy structure will not grow over time and stays below 30 tenants.

Realm Hierarchy

The realm hierarchy tenancy option is the more scalable and allows for a much larger and complex tenancy model. It provides you the ability to control everything from the type of record used for the tenancy (or a mixture of them), the number of levels, and generally the complexity of your model. This is typically the suggested approach for organisations considering Multi-tenancy, as it provides the level of control and flexibility often required for complex security models. Realms themselves are held as different records within the system and have their own CIDR, to provide a scalable visibility option, as well as to capabilities to grow as your organisation grows.

How it works

Servicely’s Multi-tenancy allows you to configure on a table by table basis: if it has it enabled, what direction the visibility occurs (such as, allows you to see the records up the tree, down the tree, or both direction) and what related records will automatically get synced to the same tenant. It should be noted that the Multi-tenancy functionality works in addition to any permissions or other security you have enabled for your instance. As a result, enabling Multi-tenancy does not mean the typical roles will not be enabled or the table record restrictions will not be followed, it simply means there will be an additional level of visibility on the table you configure it. In addition to this, every user in the system will have a “primary” tenant, however, technically speaking you can give them visibility to different parts of the tree.

To provide further insight as to how Multi-tenancy works in Servicely, the below diagram will be used to provide examples. Please note that we will be describing it with use of the Realm Hierarchy option, using companies as a basis. It should also be noted, with realms you can have completely separate trees if you want (i.e. multiple starts to the tree structure, however, typically there is a singular parent up top). Also, it should be noted that as described earlier, it does not need to be related to companies, it can be based on any type of record (including a mixture of a few types of records), however, this is the most common use case.

Prior to providing an example to explain this this operates, it is important to note if you do go down the Multi-tenancy path, not all records need to have this separation. In other words, you may decide Incidents, Users and Requests utilise Multi-tenancy rules, however, you may decide that Knowledge articles do not. In addition to this, each table that is realm separated can have their own rules in terms of the direction of visibility. As a result, to describe this we will provide an example based on the diagram above. Noting that the bold and italic writing indicates a “Tenant”.

Example

Parent company has introduced Servicely to their organisation and has a structure based on service providers and their own direct customers. To achieve what they wish to achieve, they have decided that their Work tables (such as Incident, Request, etc), CMDB tables, User tables and groups need to have Multi-tenancy enabled. This is because they need to make sure that their agents can see all service provider records and their customers, whilst service providers should only be able to see their customers. As a result, they have decided that:

The Work, CMDB, User related tables have downwards visibility. So they can see all their service providers records, and their customer records, as well as their own.
The Group table has upwards and downwards visibility, so service providers can assign to groups part of the parent company, but cannot assign to other service providers.
Note: Upwards visibility is also possible, however, as this is only used for very specific use cases, for the sake of simplicity, an example has not been provided for this.

Based on these rules, they have decided certain “personas” to take place to achieve this.

Service desk agents of Parent company: These users have a primary tenant of Parent company. So they can see all records in the system. As a result, they can assign, raise tickets for, and enter all information required for their customers, their service providers and their customer’s subsidiary themselves.
End users of Parent company: These users can raise records on behalf of their customers (Customer 2c and 2d), however, due to the fact they are end users, they can only see tickets they have raised, even if they are part of their service providers (Service Providers 1 and 3) and their customers (Customer 1A, 1B, 3A and Customer subsidiary 1Bi)
Service desk agents of Service Provider 3: These users are able to see any CMDB records, Work records and User records for Service Provider 3 and Customer 3A. However, they do not have visibility of the Parent Company records or, any other service providers and customers (such as no access to Service provider 1, Customer 1a, 1b, etc). However, they can see groups that are a part of Parent Company. As a result, they can assign it to the parent company, but cannot assign to specific people there (as they can not see the users). This therefore can be used as an escalation path.
End users of Service Provider 3: These users can raise records on behalf of their customer (Customer 3A) or their own service provider (Service provider 3), however, due to the fact they are end users, they can only see tickets they have raised.

It should be noted, that with the above example of Service provider 3, they can technically be given “extra” visibility to other tenants, but it would have to be explicitly given. As Multi-tenancy provides a wealth of options, it should be noted the above is simply an example of how it can be used, however, we do suggest before going down this path to talk to you Account Manager to understand if Multi-tenancy is right for you.

It should be noted, that although not mentioned explicitly above that within Servicely you are able to give specific users and groups access to other tenants for other parts of the tree, as well as restricting certain parts of the trees (despite someone being at the top of the tree) for only people with a specific role. In addition to this, the visibility of certain realms can be configured more explicitly, however, this would typically be something spoken about to determine if this makes based on your visibility requirements.

Steps to setup Multi-tenancy

Due to the considerations and implications of enabling Multi-tenancy, as of this time we recommend you discuss this with your Account Manager as to the steps to enable this feature. Multi-tenancy, although powerful, means that certain things to do with record visibility should be discussed and taken into consideration early in the process, to avoid rework and migrations in the future. As a result, we are not providing steps in the wiki at the current time.

Table properties

Please note that these properties are largely used for the Realm Hierarchy version of Multi-tenancy, as a result, if a the “Is Realm Separated” flag is true, you can use one (or multiple) of these properties when it makes sense.

Table property name	Usage	Default value	Example

Table property name	Usage	Default value	Example
tenancy.sync_relations	This is used to sync the “child” records' tenant, with the current record’s realm. An example of this is for example an Incident and any related SLA, Timesheet or otherwise. The value is the relationship name, rather than the table and if you are doing this on a hierarchy (such as the Work table hierarchy), you can have different properties on Work, ITSMWork and Incident when it makes sense. Note, you can also sync relations manually with a trigger, but in times you want the records to be synced automatically, you can se this. Without this, the realm field will not be set unless you have a trigger (however, it is strongly suggested you use this instead of a trigger).		WorkTimeCards,RelatedSLA
realm.evaluate (Parent table*)	This is used for any table that is realm separated to automatically set a realm based on a field. Such as, if we are using a company on the Incident record to set the Realm, we put the Company table field’s name to reference it. This is in place to replace any need for a trigger to set the realm, and takes care of it as part of normal processing.		Company.SystemRealm
realm.evaluate (Relation table*)	This can alternatively be used in conjunction with the tenancy.sync_relations property on the relation table. Such as, in the above example where we sync the SLAs based on the realm, we would say what is the relationship field name that matches it. Once again, this replaces the need for a trigger.		Parent
tenancy.filter_direction	This highlights the direction of visibility you have when looking at the table. Such as, if you have down, it will show you any records down the tenancy structure tree of the realm you have selected (assuming you meet the other visibility rules). Options available: down up both	down	down

*This property can be used in two different ways, depending on if it is on the parent table, or the relation table. See usage for more details.

Realm selector

New as of Release 1.10

You can restrict roles required to view and make use of the realm selector. This is useful when for example, you want your self service users to not see the realm selector.

You will need to configure the restriction in the System Realm record(s) of your choosing. Example below showing a System Realm record with its “Realm selection require role” populated:

Notes:

You can apply the role restriction in any position in the tree
Downstream realms will inherit upstream restrictions
Lower levels will override upstream specifications
This only applies FROM the user’s realm and below. If the user cannot see their root level, they will not see any levels below it, e.g. if you restrict the root level realm to the itsm_agent role and no other realm have role restriction, then you will not see the Tenancy selector at all unless you have itsm_agent role.

Multi-tenancy specific scripts

When you enable Multi-tenancy, there are a few scripts that you can use to help the process along. It should be noted that when using the Table API (Server) , by default the “Table” API will not take Multi-tenancy into account. However, if you use TableProtected, this will take Multi-tenancy into account. As a result, you will often use TableProtected for any portal components or otherwise to ensure users do not get more visibility than they should on the portal. Please note that some options that have an yellow background here are only for advanced usage, so do not recommend usage unless it has previously been discussed with us directly.

Script	Usage	Return

Script	Usage	Return
`RealmUtils.updateRealmCIDRsForAllTables()`	This is used in situations where a Realm’s parent has changed and was a pre-existing realm. If it is a new realm or it is a realm that does not have any children, this is not required. It should be noted that this can have a performance impact, so should only be run out of hours if possible and only after all realm updates for a day have run.	N/A
`RealmUtils.renumberDownstreamInclusive(<TableRecord>);`	This is used in situations where a Realm’s parent has changed and was a pre-existing realm. If it is a new realm or it is a realm that does not have any children, this is not required. If this realm has any pre-existing records you will also need to run the above script, RealmUtils.updateRealmCIDRsForAllTables().	N/A
`user.getCurrentTenantID();`	This is part of the user object and gets you the current tenant that a user has selected. As users can have a tenant selected other than the one they have on their user record, this simply gives them the one that is found in the drop down in the top menu.	This returns the ID of the Realm record they have currently selected.
`user.getPrimaryRealmID()`	This is part of the user object and gets you their primary realm against their user record. In other words, they may have a different realm selected, but this gives you the ID of the record that their user lives in.	This returns the ID of the Realm record against their user record.