sys_user_role Table — ServiceNow Reference

Table Reference/sys_user_role

The sys_user_role table defines security roles that control access to features and records throughout ServiceNow. Owned by the Platform module, it's the foundation of ServiceNow's role-based access control system. The critical thing to know: roles are hierarchical and cumulative — having multiple roles grants the union of their permissions, not the intersection.

What This Table Is

The sys_user_role table stores security role definitions that form the backbone of ServiceNow's access control system. Each record represents a distinct role like 'incident_manager', 'admin', or 'itil', defining what features users can access and what data they can see. These roles work in conjunction with ACL rules, UI policies, and application menu restrictions to enforce security boundaries.

Owned by the Platform module, this table supports the entire role-based access control (RBAC) process from user provisioning to real-time permission checks. When a user logs in, ServiceNow builds their effective role list by querying this table through the sys_user_has_role many-to-many relationship. Every authorization check — whether it's loading a form, executing a script, or showing a UI action — ultimately traces back to the roles defined here.

This table doesn't extend another table and isn't commonly extended. However, it participates in a complex hierarchy system through the contains_roles field, allowing roles to inherit permissions from other roles. The elevated_privilege field marks high-security roles that require additional authentication for certain operations.

In large enterprises, expect 200-800 role records depending on customization depth. Performance is generally excellent since this table is heavily cached and indexed. Role evaluation happens at session start and is cached in memory, so frequent role changes can cause cache invalidation across the cluster. High-volume role modifications during business hours should be avoided.

When You'll Script Against This Table

You'll query sys_user_role in Business Rules when implementing custom authorization logic, Script Includes when building role utilities, and UI Scripts when showing/hiding interface elements based on role membership. Client-side access is limited by ACLs — you can typically read role names but not modify role assignments. Background scripts and scheduled jobs frequently query this table for bulk user provisioning and compliance reporting.

Access requires the user_admin role for write operations and typically admin for structural changes like modifying role hierarchies. Standard users can query their own role information through gs.hasRole() but cannot directly access the table records.

Common scripting patterns:

Building custom role assignment logic in User Management flows
Creating role-based approval routing in workflow activities
Generating compliance reports showing role assignments and hierarchies
Validating role prerequisites before granting elevated permissions
Implementing dynamic menu filtering based on role membership
Automating role cleanup during employee termination processes
Building role analytics for security auditing and optimization

Table Gotchas

⚠️

The 'name' field is the role identifier used in gs.hasRole() and ACL conditions. Changing it breaks existing security rules. Always check dependencies before modifying role names in production.

⚠️

Role hierarchy through 'contains_roles' is recursive. Creating circular references will cause infinite loops in role resolution. ServiceNow has some protection, but test hierarchy changes carefully.

The active field doesn't immediately revoke access — users keep inactive roles until their session expires or they refresh their role cache
Querying by description is unreliable — it's often empty or generic. Use name for programmatic lookups
The suffix field affects role display names in lists and forms — blank suffix roles sort before suffixed ones regardless of alphabetical order

⚠️

Role grants are additive. If a user has both 'incident_manager' and 'change_manager', they get permissions from both roles. There's no role exclusion mechanism — use conditional scripting instead.

Performance trap: avoid joining sys_user_role to sys_user_has_role to sys_user in large result sets — use gs.getUser().hasRole() for single-user checks

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

The sys_user_has_role table creates the many-to-many relationship between users and roles, storing which roles each user possesses along with granted/inherited flags and inheritance tracking. The sys_user table connects through this relationship — you never directly reference sys_user_role from user records.

The sys_security_acl table frequently references roles in its condition scripts and role requirements, making these tables tightly coupled for access control. The sys_user_group table works alongside roles for comprehensive access control — groups provide data-level security while roles provide feature-level access.

Developers commonly join these tables when building user administration interfaces, generating security audit reports, or implementing complex authorization workflows. The sys_user_grmember table also appears in these queries since group membership often determines automatic role assignment through business rules and workflow.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Key Fields

Column	Type	Label	Notes
name	string	Name	The unique role identifier used in gs.hasRole() calls and ACL conditions. Changing this value breaks existing security rules referencing the old name.
description	string	Description	Human-readable role description, often empty or generic. Don't rely on this for programmatic logic — use the name field instead.
active	boolean	Active	Controls role availability for assignment. Inactive roles remain effective for existing users until session refresh or role cache invalidation.
elevated_privilege	boolean	Elevated privilege	Marks high-security roles that may require additional authentication. Used by security plugins and elevated privilege workflows.
assignable_by	reference	Assignable by	References another role that can grant/revoke this role. Empty means only admins can assign. Creates delegation hierarchies for role management.
contains_roles	string	Contains roles	Comma-separated list of role names that this role inherits. Enables role hierarchy where higher-level roles automatically include lower-level permissions.
can_delegate	boolean	Can delegate	Allows users with this role to delegate it to others if they also have appropriate assignment permissions. Used in approval and workflow scenarios.
suffix	string	Suffix	Appended to role name in UI displays and lists. Affects sorting behavior — blank suffix roles appear before suffixed ones regardless of alphabetical order.
requires_subscription	string	Requires subscription	Plugin or subscription requirement for role availability. Empty for base platform roles, populated for licensed application roles like ITOM or CSM.
grantable	boolean	Grantable	Controls whether this role can be assigned through standard role assignment mechanisms. False prevents normal assignment while allowing programmatic grants.
includes_roles	string	Includes roles	Calculated field showing roles that include this role in their contains_roles list. Read-only field used for hierarchy visualization and dependency tracking.

Common Queries

Get all active roles available for assignment

// Most basic query - shows all roles that can be assigned to users
var gr = new GlideRecord('sys_user_role');
gr.addQuery('active', true);
gr.addQuery('grantable', true);
gr.orderBy('name');
gr.query();

while (gr.next()) {
    gs.info('Role: ' + gr.getValue('name') + ' - ' + gr.getValue('description'));
}

// Returns standard assignable roles like incident_manager, change_manager, etc.

Find roles that contain a specific role in their hierarchy

// Find all roles that inherit permissions from 'itil' role
var searchRole = 'itil';
var gr = new GlideRecord('sys_user_role');
gr.addQuery('active', true);
gr.addQuery('contains_roles', 'CONTAINS', searchRole);
gr.query();

var parentRoles = [];
while (gr.next()) {
    parentRoles.push(gr.getValue('name'));
}

// Shows roles like incident_manager, problem_manager that include itil
gs.info('Roles containing ' + searchRole + ': ' + parentRoles.join(', '));

Get elevated privilege roles for security audit report

// Security audit: find all high-privilege roles and their assignment rules
var gr = new GlideRecord('sys_user_role');
gr.addQuery('elevated_privilege', true);
gr.addQuery('active', true);
gr.orderBy('name');
gr.query();

while (gr.next()) {
    var assignableBy = gr.getDisplayValue('assignable_by') || 'Admin only';
    gs.info('Elevated role: ' + gr.getValue('name') + 
            ', Assignable by: ' + assignableBy +
            ', Can delegate: ' + gr.getValue('can_delegate'));
}

Count roles by subscription requirement for license planning

// Aggregate count of roles by subscription for license planning
var ga = new GlideAggregate('sys_user_role');
ga.addQuery('active', true);
ga.groupBy('requires_subscription');
ga.addAggregate('COUNT');
ga.query();

while (ga.next()) {
    var subscription = ga.getValue('requires_subscription') || 'Base Platform';
    var count = ga.getAggregate('COUNT');
    gs.info('Subscription: ' + subscription + ', Role count: ' + count);
}

Wrong way vs right way to check role hierarchy relationships

// WRONG: String matching on contains_roles field is unreliable
// var gr = new GlideRecord('sys_user_role');
// gr.addQuery('contains_roles', 'LIKE', '%admin%'); // Matches 'user_admin' too!

// RIGHT: Use exact matching with proper delimiters
var targetRole = 'admin';
var gr = new GlideRecord('sys_user_role');
// Match exact role name with word boundaries
gr.addQuery('contains_roles', 'CONTAINS', targetRole);
gr.query();

// Then validate in code to avoid false positives
while (gr.next()) {
    var roles = gr.getValue('contains_roles').split(',');
    if (roles.includes(targetRole)) {
        gs.info('Role ' + gr.getValue('name') + ' properly contains ' + targetRole);
    }
}

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue

sys_user_role