Multi-tenancy

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 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 documentation at the current time once activated however, below are areas on the platform to further configure table properties for a table to be multi tenanted, the "is realm separated?" flag in its table definition record needs to be set to yes on top of that, you can then set one (or multiple) of the properties below when it makes sense 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 process design for every process and dataset that you want to separate by multi tenancy, ensure that whatever you are separating using, that the required tenancy information is always set for every record in the multi tenanted table for example, for a multi tenanted work table and its children, if the separation is done by companies, then every work record needs to have its company field populated this means the process design needs to consider how a work record, e g incident, is created so that every possible creation source for work record will result in a company populated examples for an incident process consideration setting up a trigger to set a fallback company though this is available as part of a multi tenancy quickstart application for company separation make interaction needing company every catalog item that submits an incident, to set company, whether by asking on the catalog form or auto set during submission, e g based on requested for have a mandatory company field on the incident form realm selector 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 https //docs servicely atlassian net/wiki/spaces/sd/pages/2136834049 , 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 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