Adding Roles - Documentation topics on: adding roles,child roles,parent roles,permission inheritance,role hierarchy,root roles,top level roles,.

Adding Roles

System - Roles & Tabs

When adding a new role from the System tab, the new role can exist as either a "root" role that does not inherit permissions from a parent, or the new role can be added as a "child" role that will subordinately pass its permissions to an existing "parent" role in the system. Even though other roles properties can be edited by a user with access to the System tab, role inheritance may not be changed once established. Roles may not be "moved" with regards to their permission inheritance.

Important Note: There are two types of Roles- 1) roles that are children of other roles and 2) "ROOT" or top-level roles that do not have Parent roles inheriting from them. Before adding a new Role in the system, decide whether the new role should extend it's permissions to a managing parent role or not.

Adding a New Root Role from System → Roles & Tabs

To add a Root Role, first make sure that no role is currently selected in the left hand column of the Roles, Tabs & Tools view. If a role is currently selected, clicking the "add role" button will force the new role to be a child of the selected role. To de-select a role, hold down the control key (on a PC), or command button (on MacOSX), and then click the highlighted role to de-select it. Then click the "+Add Role" button to add a new role as Root, or top level "parent" role.

Clicking "+Add Role" button on the backend Roles page brings up the "Edit Role" window.  The following fields are presented when creating a new role:

  • Role: title of the new role
  • Key: Unique abbreviated reference to the role.  This field is optional but must be set for a role to be accessible to a viewtool or code that will be checking or searching for this role.  Since the Role name is not unique, only this field can checked by custom code written to examine roles through the dotCMS API.
  • Parent: Role to which the new role will extend permissions.  If no parent role is desired, the parent Role can be left blank/set as "Root"
  • *Can Edit -
    • Users: If checked, allows users to be added to the role.
    • Permissions: If checked, allows permissions to be edited for the role.
    • Tabs: If checked, allows user tabs to be edited for the role.
  • Description: Basic description of role/intended usage, etc.


Clicking on any role name in the hierarchical column on the left of the page will display the detail for that particular role in the center-right of the roles page.

*There are three tabs in the role detail area where the role's UsersPermissions, and associated CMS Tabs can be edited as long as their corresponding checkboxes were checked on the role the last time it was edited.

Adding Roles that Inherit Role Permissions

Select an existing role that will become the "parent" role to the new role. A parent role will receive access to all of the permissions granted to its child(ren). After selecting a parent role, click the "+Add Role" button.

Granting role membership is hierarchical. This means that when you add a user to a role, that user will also belong to, and have the permissions of, the children roles of the role you are granting. Note: "Role Tabs" are NOT hierarchical. A user will only have access to the tabs of the roles they belong to directly.

Example Role Hierarchy

The screenshot below of the Roles manager shows an example of role hierarchy in a common scenario:

  • Publisher / Legal role has complete access to all objects permissioned to reviewers or contributors, in addition to objects specifically assigned to the Publisher/Legal role
  • Reviewer role role has complete access to all objects permissioned to contributors, in addition to objects specifically assigned to the reviewer role
  • Contributor role does not inherit permissions from any role, but passes it's permissions to the Reviewer and Publisher/Legal roles.

Hierarchal roles mean (in this example), that if a user is granted the Publisher/Legal role, then they are also granted the Reviewer and Contributor roles as well.  The "Granted From" column displays which role the user membership is coming from.  Due to the Hierarchical inheritance users assigned to the Publisher/Legal, or Reviewer Role, automatically inherit membership to the Contributor Role.