Roles in xMatters can be tricky to understand since they're applied in different ways to control security throughout the product.

This article explains how roles and permissions in xMatters work by breaking down roles into two of the main things they control:

1. Role-on-role permissions
2. Product permissions

It also highlights another way roles can be used in xMatters, to control access to customer-defined add-ons like forms, scenarios, and groups.

Note: Not all users have access to roles in xMatters. This article can help you understand how roles are used in your system; please work with Customer Support to define and implement the roles that meet your business needs.

1. Role-on-role permissions

Role-on-role permissions control what one role is allowed to do to another, and they specify the user data a given user is allowed to see in the interface.

Role-on-role permissions are defined under Roles in the Permissions menu of the Admin tab. Click the name of a role to view what that role can do to other roles, and what other roles can do to it. The example below looks at the Group Supervisor role:

The neatly arranged columns and checkboxes on this page may give the illusion of simplicity, but don't be fooled - a lot of different things are being controlled on this page.

Role Permission Settings

Let's start by defining the six column headings of the role permissions settings:

1. Assign Role (typically not touched): Controls the ability to assign other people to this role.
2. Edit Person (very important): Provides the power to see and edit other users' custom fields, attributes, and devices.
3. Delete Person (obvious): Grants the ability to delete existing users in a role.
4. View Person (also important): Lets a user see other users' custom fields, attributes, and devices - but not edit them.
5. Use Person (most important): Enables the ability to see other people in search results for messaging, groups, or other places - but not drill in to see their custom fields, attributes, or devices.
6. Manage Subscriptions (interesting when you need it): Allows you to assign subscriptions to others.

Note: Some of these settings take precedence over others. For example, if Edit Person is enabled, then View Person or Use Person have no effect. Supervisors always have the ability to view, edit, and delete their supervised users - there's no need to try and replicate the hierarchical structure of your company exactly by assigning employees their actual supervisor in the supervisor field!

Many users in xMatters are assigned more than one role. When users are assigned multiple roles they are not limited by the permissions of their "lowest access" role; they have the permissions from all their roles.

Role Permission Types

The three main sections on the Role Details page define the permission types of the selected role (Group Supervisor, in this case) related to all other roles:

PERMISSIONS WITHIN THIS ROLE: Controls what this role can do to other users with the same role (what Group Supervisors can do to other Group Supervisors).

• For example, with Use Person is selected, Group Supervisors have the ability to see other Group Supervisors in search results for messaging, groups, or other places.

PERMISSIONS ON OTHER ROLES: What this role can do to other roles (what Group Supervisors can to do Company Supervisors, Full Access Users, Standard Users, etc.).

• For example, with View Person selected beside Company Supervisor, Group Supervisors have permission to see (but not edit) the custom fields, attributes, and devices of Company Supervisors, and see them in search results for messages, groups, and other places.

PERMISSIONS OTHER ROLES HAVE: What other roles can do to this role (what Company Supervisors, Full Access Users, etc. can do to Group Supervisors).

• For example, Standard Users only have permissions to "Use" Group Supervisors (that is, see them in searches, etc.) because only Use Person is selected. Full Access Users have full permission over Group Supervisors (they can assign others as Group Supervisors, and edit, delete, and manage their subscriptions).

Example Use Case

An example use case for role-permissioning is to segregate users from different business units:

You can create new roles for "Business Unit 1 - Standard User" and "Business Unit 1 - Supervisor" and not permit them any allowed action on a "Business Unit 2 - Standard User" or "Business Unit 2 - Supervisor"; they won't even be able to see each other in the system.

Try it out! Take a half-hour and create a few users with different roles and supervisory relationships. Log in as each one to see what they have access to — this will help you understand the permissioning model. You can also try combining different roles to see how the user experience changes as their permissions increase. (Or decrease!)

2. Product permissions

The basic principles of product permissions and how they relate to functions and roles are:

• Product permissions are used to control the features (tabs, menus, screens, etc.) that users can access in xMatters.
• Functions are combinations of specific product permissions.
• Roles are combinations of functions.

For example, a single product permission might provide a user with the ability to define their personal details; a separate permission might allow them to view their own group memberships. The combination of these permissions, with some others, might make up a function called "Basic User". Another function, "Advanced User", might include permissions for sharing Communication Center dashboards or viewing performance reports. A role of "Manager" might then combine both sets of basic and advanced user functions.

Product permissions for a role are defined from the upper right-hand menu of the Role Details page, under Common Tasks. Select Assign Functions to this Role.  

Remember, a "function" is just a name for a related group of individual permissions. The "Functions for this Role" page lists the selected functions for the specified role. In this case, Group Supervisors have eight selected functions:

More detailed information on what these functions do, and their underlying permissions, can be found under Functions in the Permissions menu of the Admin tab.

For example, the "Manage Profile" function permits access to and the ability to change all profile information. Click Manage Profile and select Modify Permissions from the Common Tasks menu in the upper right-hand corner to view a list of all the permissions included in the Manage Profile function:

The Modify Permissions page is where permissions for many of the very detailed elements of the xMatters interface can be selected. Elements are grouped using a dotted naming convention: ability.act, view.menu, view.menuitem, and view.screen are the most common items used to enable a feature for a user. Move the pointer over any listed item to read a description of what the permission controls.

In this case, the Manage Profile function contains 17 individual permissions. The Supervise Groups function, also included in the Group Supervisor role, contains 28 individual permissions. In total, the eight functions that make up the Group Supervisor role contain more than 90 permissions! Based on how granular dealing with individual permissions can get, you can see why xMatters uses functions to bundle sets of permissions together to support an actual use case.

It's possible to make many adjustments to the behavior of xMatters by altering roles or functions (it's not possible to alter or create permissions); you can also create roles or functions to support special use cases.

Note: Functions are cumulative. Someone with a "Read-Only User" role and a "Standard User" role will be granted permissions of both roles.

BEST PRACTICES: If you want to alter the permissions or functions of the pre-defined roles in xMatters, it's a good idea to manually create a copy of that role to make changes to. This can make it much easier for support or Content Managers to troubleshoot later if there's a problem.

Other ways you can use roles

Now that you have a better understanding of the relationship between roles and permissions, what are some ways they can be used to customize your deployment?

Customer-defined add-ons in xMatters are also controlled by permissions, so you can selectively provision a form, scenario, group, subscription, or Communication Center dashboard.

For example, you can specify which users or roles have access to forms and scenarios:

• Permissions can be specified for users or roles in the form and scenario design screens.

This feature can be used if there are specific messaging forms you'd like only certain types of users to be able to manage or edit. For example, you might only want members of your company's Emergency Response group to send notifications about what action to take in an emergency situation.

Groups can be configured to be observable only by specific roles from the Groups Overview page.

• Click Edit in the Observers section to select which roles can observe the group. ("Observed By All" is the default selection.)

An example use case for this permissioning is to allow a group of users, such as "Executives", to be visible only by certain other roles in your company. For example, you might only want to provide Supervisors, and not other roles like Standard Users, the permissions to contact Executives.

Managing custom roles

In xMatters it's possible to create new, custom roles to give specific users access to customer add-ons like forms and scenarios, groups, Communication Center dashboards, and other customer-defined objects.

Newly-created custom roles often only define access to customer-defined elements, such as forms and groups, and don't have any role on-role definitions or functions assigned; they must therefore be combined with another standard role, like a Group Supervisor.

 xMatters internal reference: DOC-4403, DOC-7766