Document toolboxDocument toolbox

14.1 DRAFT - NO PUBLISH: Roles and Permissions

Owned by Billy Sewell (Unlicensed)
Jan 26, 2024

On This Page:

Overview

In ServiceManager, users may be assigned to one or more roles, by using the ServiceManager UI. The roles that a user is assigned to defines the permissions that the user has to access data and/or systems.

So, that is:

  • A user may be assigned to one or more roles.
  • A role consists of one or more permissions.
  • A permission defines one or more levels of access to a certain type of data or to a system.

Permissions

ServiceManager's permissions consist of two parts. Firstly, a property, which defines the data on which access permission is being granted, and secondly, an operation, which defines the type of access permission which is being granted.

Properties

The properties that ServiceManager supports are FRUs, Teams, Operatives and Standard Activity Categories.

That is, permissions can be defined to grant access to FRUs, Teams, Operatives or Standard Activity Categories.

Properties are hierarchical - that is:

  • Granting access to an FRU will grant the same level of access to all Teams, Operatives and Standard Activity Categories under the FRU;
  • Granting access to a Team will grant the same level of access to all Operatives and Standard Activity Categories under the Team; and
  • Granting access to an Operative will grant the same level of access to all Standard Activity Categories under the Operative.

Operations

The operations that ServiceManager supports are Create (C), Read (R), Update (U), Delete (D) and eXecute (X).

In addition, the ALL operation can be used as a shorthand for CRUDX.

Examples

RolePermission PropertyPermission OperationDescription
Admin User RoleFRUALLA simple role that provides ALL (Create, Read, Update, Delete and eXecute) access to everything.
Admin View RoleFRURA simple role that provides Read access to everything.

Formal Parameters

While in many cases, the granting of permissions as per the above examples is sufficient, for more complex cases, ServiceManager supports formal parameters for permission properties. These formal parameters allow the FRUs, Teams or Operatives to which a permission applies to be configured on a per-user basis.

Formal parameters consist of a parameter type, and a parameter name.

Parameter Types

A formal parameter's type defines the type of object the formal parameter relates to. That is:

  • If the formal parameter type is FRU_ID, then the formal parameter is defining an FRU;
  • If the formal parameter type is TEAM_ID, then the formal parameter is defining a Team;
  • If the formal parameter type is OPER_ID, then the formal parameter is defining an Operative; and
  • If the formal parameter type is SACAT_ID, then the formal parameter is defining a Standard Activity Category.

Parameter Names

A formal parameter's name is the variable name for the parameter, which is a string of up to 20 characters. Parameter names provide the mechanism for a permission that uses a formal parameter to use one or more different values (e.g. a different FRU, a different Team, etc.) for different users, based on the formal parameter name values that are defined for that user.

  • A permission that does not have a value supplied for all its parameter names will not work - the permission will not be granted. Other permissions in the role may still work if they do not have parameters or they have values for all their parameters.
  • The wildcard value of the asterisk (or star) character (i.e. "*") means all, and can be used to grant permission (via = *) or deny permission (via != *) to all FRUs, Teams, Operatives, Standard Activity Categories, as per the parameter type.

Users may have more than one value defined for a given formal parameter type/name pair, allowing for flexible assignment of permissions.

Parameter Values

For the following formal parameter types, the following parameter name values are required:

  • For FRUs, the value must be an FRU reference (or the wildcard value).
  • For Teams, the value must be a Team name (or the wildcard value).
  • For Operatives, the value must be an Operative reference (or the wildcard value).
  • For Standard Activity Categories, only the wildcard value is supported.

Examples

RolePermission PropertyPermission OperationDescription
FRU Leader  FRU(FRU_ID.F)  ALL 

 

 

A role that provides ALL (create, read, update, delete and execute) access to FRUs, where the user has an appropriate entry in the sp803_auth_actual_parameters database table.

For a user with an entry in the sp803_auth_actual_parameters database table where:

  • The role ID is the same as the role's ID;
  • The parameter type is FRU_ID;
  • The parameter name is F;
  • The assignment type is =; and
  • The value is ABC

then the user will be granted create, read, update, delete and execute permissions to the ABC FRU (and all Teams and Operatives in that FRU).

For a user with an entry in the sp803_auth_actual_parameters database table where:

  • The role ID is the same as the role's ID;
  • The parameter type is FRU_ID;
  • The parameter name is F;
  • The assignment type is =; and
  • The value is DEF

and another entry in the sp803_auth_actual_parameters database table where:

  • The role ID is the same as the role's ID;
  • The parameter type is FRU_ID;
  • The parameter name is F;
  • The assignment type is =; and
  • The value is HIJ

then the user will be granted create, read, update, delete and execute permissions to both the DEF and HIJ FRUs (and all Teams and Operatives in those FRUs).

Team Leader

FRU(FRU_ID.F)

FRU(FRU_ID.F).Team

FRU(FRU_ID.F).Team.Oper

R

CRU

ALL

A role that provides read access to FRUs, create, read and update access to Teams, and ALL access to Operatives, where the user has an appropriate entry in the sp803_auth_actual_parameters database table.

For a user with an entry in the sp803_auth_actual_parameters database table where:

  • The role ID is the same as the role's ID;
  • The parameter type is FRU_ID;
  • The parameter name is F;
  • The assignment type is =; and
  • The value is ABC

then the user will be granted:

  • read permissions to the ABC FRU;
  • create, read and update permissions (but not delete or execute permissions) to all Teams in the ABC FRU; and
  • create, read, update, delete and execute permissions to all Operatives in all Teams in the ABC FRU.
Team AdminTeam(TEAM_ID.T)ALLA role that provides ALL (create, read, update, delete and execute) access to Teams, where the user has an appropriate entry in the sp803_auth_actual_parameters database table.

For a user with an entry in the sp803_auth_actual_parameters database table where:

  • The role ID is the same as the role's ID;
  • The parameter type is TEAM_ID;
  • The parameter name is T;
  • The assignment type is =; and
  • The value is ABC

then the user will be granted create, read, update and delete permissions to the ABC Team (and all Operatives in that Team).

Operative AdminOper(OPER_ID.O)ALLA role that provides ALL (create, read, update, delete and execute) access to Operatives, where the user has an appropriate entry in the sp803_auth_actual_parameters database table.

For a user with an entry in the sp803_auth_actual_parameters database table where:

  • The role ID is the same as the role's ID;
  • The parameter type is OPER_ID;
  • The parameter name is O;
  • The assignment type is =; and
  • The value is ABC

then the user will be granted create, read, update, delete and execute permissions to the ABC Operative.

Notes on Permissions

Use of Formal Parameters

When a permission contains one or more formal parameters, it is recommended that the permission is assigned to only one role - if a different role requires an entry specifying the same permission, then another permission entry should be created, which is unique to that role.

Furthermore, it is recommended that the formal parameter names should be unique for each role.

For instance:

If both the ‘Business Data Administrator (Business)’ and ‘Service Resource Manager (Permanent)’ roles requires the permission:FRU(FRU_ID).Team.Oper 
Then it is recommended that they are set up using unique permission entries; for example:

FRU(FRU_ID.BDAB_F).Team.Oper 

FRU(FRU_ID.SRMP_F).Team.Oper

This allows the user to be assigned to multiple roles without any ambiguity over the formal parameter assignment, which will help ensure that users are not granted unexpected permission. (See also the section on Formal Parameter Matching Rules below.)

Similarly, if within a single role, differing restricted levels of access are required, then different formal parameter are recommended.

Permissions are Hierarchic

Permissions are hierarchic, applied in a top-down fashion.

That is, more permissive levels of access at a higher level override a less permissive level of access at a lower level.

Notes

One of the standard Roles within ServiceManager is the Planner Role which is defined containing only two sp802_permission entries.

  • The higher level (FRU) has a less permissive level of access (read), compared with the lower level (specific FRUs as defined by formal parameter values) which have a more permissive level of access (ALL).
  • As a result, the more permissive level of access (ALL) overrides the less permissive level of access (read) at the specific FRU level.

FRU : R

 

The user can read everything.

 

FRU(FRU_ID.F) : ALLThe user can update everything pertaining to FRU_ID.F

As with the standard Planner Role above, this example permission hierarchy has the same effect.

  • The higher level (FRU) has a less permissive level of access (read), compared with the lower level (specific Operative attributes) which have a more permissive level of access (update).
  • As a result, the more permissive level of access (update) overrides the less permissive level of access (read) for the specific Operative attributes.

FRU : R

The user can read everything.

FRU.Team.Oper.JobTitle : UThe user can update the JobTitle attribute of all Operatives.
FRU.Team.Oper.Phone1 : UThe user can update the Phone1 attribute of all Operatives.
FRU.Team.Oper.Phone2 : UThe user can update the Phone2 attribute of all Operatives.

Removing permissions at a lower level cannot be performed via a simplistic method, as a result of the permissions hierarchy.

  • The higher level (FRU) has a more permissive level of access (update), compared with the lower level (Operatives) which has a less permissive level of access (read).
  • As a result, the second permission has no effect.
  • The more permissive level of access at the FRU level override the less permissive level of access, granting the user update permissions to all FRUs, and update permissions to all of the Teams and Operatives in those FRUs.

FRU : U

The user can read everything.

FRU.Team.Oper : RHas no effect.

Permission are Additive

When a user has more than one permission (either as a result of having multiple roles, or as a result of multiple permissions within a role), then the permissions are additive.

This can sometimes have unexpected results.

User's Permissions

Formal Parameter ValuesResult

FRU(FRU_ID.F) : ALL

FRU-1

FRU-2

The net effect is that the user has the ALL permission for both FRU with ID FRU-1 and for FRU with ID FRU-2.

FRU(!=FRU_ID.F) : ALL

FRU-1

FRU-2

The net effect is that the user has the ALL permission for all FRUs:

  • For the permission set evaluated as FRU(!=FRU-1) : ALL, this gives ALL access to all FRUs except the FRU with ID FRU-1 - this includes FRU with ID FRU-2; and
  • For the permission set evaluated as FRU(!=FRU-2) : ALL, this gives ALL access to all FRUs except the FRU with ID FRU-2 - this includes FRU with ID FRU-1.

This is perhaps not what was intended.

Formal Parameter Matching Rules

Assume that there is a role with ID = 5, and the following database table entries:

sp802_permission

Permission ID

Property

Operation

15

FRU

R

16

FRU(FRU_ID.F).Team.Oper

ALL

sp803_auth_actual_parameters

User Id

Role ID

Parameter Type

Parameter Name

Assignment Type

Value

Permission Parameter

jodd

5

FRU_ID

F

=

ABC

7

jodd

5

XXX

F

=

DEF

7

jodd

5

FRU_ID

X

=

GHI

7

jodd

5

FRU_ID

F

X

JKL

7

jodd

5

FRU_ID

F

=

MNO

8

sp804_permission_parameters

Permission Parameter

Permission ID

7

16

8

29

 

In this case, when processing role with ID = 5 for the user jodd:

  • The 1st entry in the sp803_auth_actual_parameters will be added to the user's authorization policy, because:
    • The role ID in sp803_auth_actual_parameters matches the role being processed; 
    • The permission parameter in sp803_auth_actual_parameters refers to the permission in sp802_permission with ID = 16; 
      • This permission has a formal parameter with parameter type of FRU_ID, which matches the sp803_auth_actual_parameters entry;
      • This permission has a formal parameter with parameter name of F, which matches the  sp803_auth_actual_parameters entry.
  • The 2nd entry in the sp803_auth_actual_parameterswill not be added to the user's authorization policy, because:
    • The role ID in sp803_auth_actual_parameters matches the role being processed; 
    • The permission parameter in sp803_auth_actual_parameters refers to the permission in sp802_permission with ID = 16; 
      • This permission has a formal parameter with parameter type of FRU_ID, which does not match the sp803_auth_actual_parameters entry of XXX.
  • The 3rd entry in the sp803_auth_actual_parameterswill not be added to the user's authorization policy, because:
    • The role ID in sp803_auth_actual_parameters matches the role being processed; 
    • The permission parameter in sp803_auth_actual_parameters refers to the permission in sp802_permission with ID = 16; 
      • This permission has a formal parameter with parameter type of FRU_ID, which matches the sp803_auth_actual_parameters entry;
      • This permission has a formal parameter with parameter name of F, which does not match the sp803_auth_actual_parameters entry of X.
  • The 4th entry in the sp803_auth_actual_parameters will not be added to the user's authorization policy, because:
    • The role ID in sp803_auth_actual_parameters matches the role being processed;
    • The permission parameter in sp803_auth_actual_parametersdoes not have a valid assignment type value.
  • The 5th entry in the sp803_auth_actual_parameters will not be added to the user's authorization policy, because:
    • The role ID in sp803_auth_actual_parameters matches the role being processed; 
    • The permission parameter in sp803_auth_actual_parameters refers to the permission in sp802_permission with ID = 29, which does not exist. 

Standard Activity Category Setup

ServiceManager has the concept of standard activity categories - the ability to aggregate a number of standard activity types within a grouping.  This provides a means within ServiceManager and its authorisation framework to restrict access to groups (categories) of standard activity.  For example a user might be allowed to create/manipulate team management activities (such as team meetings and training courses) but not be allowed to manipulate authorised absence activities (such as holidays, hospital visits and so forth).  This could be achieved by defining categories of standard activity and associating specific types of activity with a given category (in the preceding example there might be two categories defined: "Team Management" and "Absence").

 As each customer may have different types of standard activity the definition of which activities belong in which category is not one that can be automated.  As a consequence an amount of manual configuration is required.

The tables involved here are sp150_std_act_categories and sp151_std_act_cat_types. In order for ServiceManager to work correctly these two tables need to be populated appropriately.

Relationships between ServiceManager Roles and Standard Activities

There is no mandated rule for how standard activity categories, or types, should be named.  However in order for them to be of use within ServiceManager it is necessary for those users requiring specific standard activity category/type interaction to have their role associations defined using the same activity category and type as those defined within and sp105_activity_types.ACTIVITY_TYPE and sp150_std_act_categories.NAME.

sp150_std_act_categories

This is a list of all the activity categories.  Each category has a name and an identifier.  The name is displayed within the ServiceManager user interface when displaying a list of categories.  Also these values are used within the authorisation framework in those properties requiring actual parameters to be associated with a standard activity category.

sp151_std_act_types

Activity types defined in and sp105_activity_types can be assigned to a standard activity category (sp150_std_act_categories) by adding entries to this table associating the sp105_activity_types's activity type with the desired sp150_std_act_categories category identifier.