GlideRecord.getRefRecord() — ServiceNow API

gr.fieldName.getRefRecord()→ GlideRecord

intermediateTested on Xanadu

What It Does

The getRefRecord() method returns a GlideRecord object representing the record referenced by a reference field. When ServiceNow queries a record containing reference fields, it automatically populates those reference field objects with basic information about the referenced records (sys_id, display value, table name). This method provides access to that pre-loaded referenced record without requiring an additional database query.

Internally, ServiceNow maintains a cache of referenced record data when it loads the parent record. The getRefRecord() method accesses this cached data and wraps it in a GlideRecord object. This cached GlideRecord contains all fields that were included in the original query's reference field expansion, plus any fields explicitly added through addQuery() or addJoinQuery() operations.

The method returns null in several scenarios: when the reference field is empty, when it points to a record that no longer exists, or when the current user lacks read access to the referenced record. The returned GlideRecord, when not null, behaves exactly like any other GlideRecord object—you can call getValue(), access field properties, and even call getRefRecord() on its reference fields for nested reference traversal.

A critical edge case occurs when you need field data that wasn't included in the original query. The returned GlideRecord only contains fields that ServiceNow loaded during the initial query. If you access a field that wasn't pre-loaded, ServiceNow will execute a database query to fetch that specific field's value. This behavior differs from calling get() with the reference field's sys_id, which would reload the entire referenced record.

The method is closely related to getDisplayValue() and toString() on reference fields. While those methods return the display value of the referenced record, getRefRecord() provides full access to all available fields on the referenced record. Use getTableName() on the reference field when you only need to identify the referenced record's table.

When to Use This

Use getRefRecord() when you need to access multiple fields from a referenced record or when you need to perform operations on the referenced record object itself. This method is particularly valuable in Business Rules where you're processing records and need efficient access to reference field data without the performance cost of additional database queries. It's also essential when building complex conditional logic that depends on multiple attributes of the referenced record.

Avoid this method when you only need the display value of the reference field—use getDisplayValue() instead. When you need to modify the referenced record, use a fresh GlideRecord with get() rather than the cached record returned by getRefRecord(). The cached record may not contain all fields needed for updates and could lead to unexpected behavior when calling update().

⚠️

Never call update() or delete() on a GlideRecord returned by getRefRecord(). The cached record may be incomplete and could cause data integrity issues.

Return Value

Returns a GlideRecord object representing the referenced record, or null if the reference is empty or invalid. The returned GlideRecord contains field data that was loaded during the original query, including the sys_id, display value, and any fields explicitly included through joins or reference field expansion. This GlideRecord is positioned (no need to call next()) and ready for immediate field access.

Always check for null before using the returned GlideRecord. Reference fields can be empty, point to deleted records, or reference records the current user cannot access due to ACL restrictions. Use if (refRecord && refRecord.isValidRecord()) for the most robust null checking pattern.

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.

Platform Behavior & Side Effects

No Business Rules, ACLs, or other platform mechanisms fire when accessing the cached referenced record
No database queries execute unless you access fields that weren't included in the original query
Performance is excellent—accessing cached reference data is nearly instantaneous
Field access security is enforced based on the current user's ACL permissions to the referenced table
Works identically in before and after Business Rules, Script Includes, and Scheduled Jobs
Reference field data may be stale if the referenced record was modified after the parent record was loaded
Calling setValue() or update() on the returned GlideRecord may not behave as expected due to incomplete field data

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

Code Examples

Basic usage — getting user information from incidentbasic

// Access caller information without additional query
var inc = new GlideRecord('incident');
inc.get('9d385017c611228701d22104cc95c371');

// Get the referenced user record
var caller = inc.caller_id.getRefRecord();
if (caller && caller.isValidRecord()) {
    gs.info('Caller: ' + caller.getValue('name'));
    gs.info('Department: ' + caller.getValue('department'));
    gs.info('Email: ' + caller.getValue('email'));
    
    // Can access reference fields on the referenced record
    var dept = caller.department.getRefRecord();
    if (dept) {
        gs.info('Dept Manager: ' + dept.getValue('dept_head'));
    }
} else {
    gs.info('No caller found or access denied');
}

This example shows the typical pattern: get the referenced record, check for null, then access multiple fields. Notice the nested reference access for the user's department.

Conditional logic based on reference field dataintermediate

// Business rule logic checking assignment group properties
function executeRule(current, previous) {
    var assignmentGroup = current.assignment_group.getRefRecord();
    if (!assignmentGroup || !assignmentGroup.isValidRecord()) {
        return;
    }
    
    // Check if assignment group requires manager approval
    var requiresApproval = assignmentGroup.getValue('u_requires_approval');
    var groupType = assignmentGroup.getValue('type');
    
    if (requiresApproval == 'true' && groupType == 'itil') {
        current.setValue('approval', 'requested');
        
        // Get the manager for auto-approval assignment
        var manager = assignmentGroup.manager.getRefRecord();
        if (manager) {
            current.setValue('u_approver', manager.getValue('sys_id'));
        }
    }
}

This Business Rule uses getRefRecord() to make decisions based on assignment group properties and even accesses the group manager's data for approval routing.

The classic mistake — trying to update cached recordsadvanced

// WRONG - Don't update cached reference records
var req = new GlideRecord('sc_req_item');
req.get(req_item_sys_id);
var user = req.opened_by.getRefRecord();
if (user) {
    user.setValue('u_last_request', new GlideDateTime());
    user.update(); // This may fail or behave unexpectedly
}

// RIGHT - Get a fresh record for updates
var req = new GlideRecord('sc_req_item');
req.get(req_item_sys_id);
if (req.opened_by) {
    var user = new GlideRecord('sys_user');
    if (user.get(req.getValue('opened_by'))) {
        user.setValue('u_last_request', new GlideDateTime());
        user.update(); // Safe update with complete record
    }
}

The cached record from getRefRecord() may not contain all fields needed for safe updates. Always use a fresh GlideRecord when modifying referenced records.

Gotchas

The returned GlideRecord only contains fields that were loaded in the original query—accessing other fields triggers additional database queries.

Returns null for empty reference fields, deleted records, and records the user cannot access due to ACL restrictions.

Calling update() or setValue() on the returned GlideRecord can produce unexpected results because the record may be incomplete.

Reference field data may be stale if the referenced record was modified after the parent record was initially loaded.

The method works on any GlideElement reference field, including custom reference fields and fields that reference multiple tables.

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