Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Adding new privileges to roles after an upgrade

Updated on July 1, 2021

Pega Platform version 8.5 has introduced new security privileges to align with leading practices and Pega has provided guidance on how to strengthen your security architecture by adding new privileges to roles after an upgrade.

The new privileges will automatically be integrated into your application, if your roles are dependent upon the roles shipped in Pega Platform (the shipped roles are dependent roles for your roles).

For more information, see Dependent roles.

If you do not use dependent roles, you must add the new privileges manually into your application. To assist you with this process, Pega provides the Privilege Information Utility.

Download the Privilege Information Utility from Pega Marketplace and install it according to the directions detailed in Using the Privilege Information Utility, which describes how you import the utility, run an activity, and the export the data to Excel. From there, you can create pivot tables in Excel to best determine where to put a new privilege.

Privileges background

Privileges are assigned using access groups and roles.

When new privileges are added to Pega Platform applications, these privileges must be associated with roles in order to be implemented in that application.

For more information, see Security of access roles.

Manually adding a new privilege to an application

To manually adding a new privilege to an application, you need to do the following steps:

  • Determine where to add the privilege
    • What is the privilege?
    • What users/personas should have access to that privilege?
    • For those users/personas, how will that translate into access groups and roles?
  • Use the Privilege Information Utility

Determine where to add the privilege

When adding a new privilege into an application, start with the following information:

  • What is the privilege?
  • What users/personas should have access to that privilege?
  • For those users/personas, how will that translate into access groups and roles?

What is the privilege?

Determine the context of the privilege: what functionality it provides. It may protect some types of data from being accessed by ineligible users, or provide users with the ability to run certain features, like tracing.

In addition, determine where this privilege would be used. As stated above, it might affect data, or managerial functions in the application (like the ability to run a report), or system administration functions, such as the ability to view logs.

The new privilege might also be dependent upon an already-existing privilege.

For example, the ability to edit a report might depend on the user’s ability to view the report. If the privilege works with another privilege, then it is important to verify that the roles being granted that privilege also have been granted the underlying privilege.

What users/personas should have access to that privilege?

It is also important to determine what kind of user should be granted the privilege: work user, manager, system administrator, or others. Decide who would need the access – or who should be denied the access – that the privilege represents.

Note: The addition of a privilege for some users to gain access means that other types of users will be denied access.

For those users/personas, how will that translate into access groups and roles?

As shown above, access for users flows from the Operator ID through the access groups to the roles. Privileges are associated with those roles through the Rule-Access-Role-Obj records.

Once you have determined which users/personas should have access to this privilege, you must determine which role the privilege should be associated with, in order for the correct personas to receive that access.

Similar to the situational layer cake for rules, when you view your application as a series of layers, you should create new rules in the correct layer, so that functionality is available for all the layers above, and you don’t have to duplicate the rule around the system, which could cause future problems.

Likewise, if there is one role which is associated with all the access groups who need access to the privilege functionality, then it is easier to associate the privilege with that one role, rather than loading it into every role for every access group.

Example: Your access groups have the following roles:

Access GroupRoles






















In this example, a privilege having to do with the ability to see trace logs, or the ability to stop and start agents, would be a System Administrator privilege.

The following access groups in the example above have the PegaRULES:SysAdm4 role:

  • PegaHC:Administrators
  • PegaHC:Administrators4010
  • PegaHC:HealthCheck

If the users in those access groups are the one who should have this ability to see trace logs, then associating the SeeTraceLogs privilege with the PegaRULES:SysAdm4 role would be the easiest way to make sure all those users have the appropriate access.

Now let’s suppose that the HealthCheck access group should not have access to see trace logs, but the two Administrator access groups should. Associating the SeeTraceLogs privilege with the SysAdm4 role would not work, because the HealthCheck users would also get that privilege. In that case, the PegaRULES:SecurityAdministrator role might be a better choice, as only the two administrators have that role.

Determining the best role to associate a privilege with requires that you be able to see all the access groups with their roles. The new Privilege List Utility provides this ability.

Use the Privileges Information Utility

The Privileges Information Utility helps you determine how best to integrate these new privileges into your existing security architecture, by displaying your access group and role structure in one report.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us