GlideForm.getReference() — ServiceNow API

g_form.getReference(fieldName, callback)→ void

intermediateTested on Xanadu

What It Does

The getReference() method performs an asynchronous server call to retrieve the complete record referenced by a reference field. Unlike getValue() which only returns the sys_id, this method fetches the entire referenced record with all field values converted to their display representations.

ServiceNow makes an AJAX call to the server, loads the referenced record using the sys_id from the reference field, and processes all field values through their respective display functions. Choice fields get their choice labels, reference fields get their display values, and date/time fields get formatted according to user preferences. The entire process respects ACLs and field-level security.

The callback receives a GlideRecord-like object that behaves similarly to a server-side GlideRecord but contains only display values. You can access fields using dot notation or getValue() methods. If the reference field is empty or the referenced record doesn't exist, the callback receives null. If the user lacks read access to the referenced record, the callback receives an empty object.

The method processes reference fields differently based on their configuration. For table-specific references, it loads the exact record type. For generic references (like Document ID fields), it determines the correct table and loads from there. Extended tables work correctly—a reference to a Hardware record will load the actual CI type (Server, Network Gear, etc.) with all extended fields populated.

Unlike getDisplayValue() which only returns the reference field's display value, getReference() provides access to all fields on the referenced record. This makes it essential for complex client-side logic that needs to examine multiple fields on the referenced record or chain through multiple reference relationships.

When to Use This

Use getReference() when you need to access fields on the referenced record beyond just its display name. Common scenarios include conditional field visibility based on referenced record attributes, populating dependent fields with data from the referenced record, or building complex validation rules that examine multiple aspects of the referenced data. This is particularly valuable in Service Catalog items where user selections in reference fields drive the visibility and validation of other form elements.

Avoid this method for simple display purposes where getDisplayValue() suffices. Don't use it repeatedly in loops or onChange events for the same field—the AJAX overhead becomes significant. For performance-critical scenarios where you need reference data immediately, consider server-side UI Policies or preloading the data using g_scratchpad from a Business Rule instead of making client-side AJAX calls.

⚠️

This method performs network requests. Use sparingly in onChange events to avoid overwhelming the server with AJAX calls.

Return Value

The method returns void immediately—all meaningful data comes through the callback function. The callback receives a GlideRecord-like object with properties corresponding to the referenced record's fields. All values are display values, meaning choice fields show labels instead of internal values, dates show formatted strings, and reference fields show display names rather than sys_ids.

When the reference field is empty, the referenced record is deleted, or the user lacks read access, the callback receives null. Always check for this condition before accessing properties on the returned object. The object doesn't have all GlideRecord methods—it's a plain JavaScript object with field values, not a full server-side GlideRecord instance.

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

Generates an AJAX request to the server, visible in browser network debugging tools as a call to /api/now/form
Respects ACLs on the referenced table—users without read access get null in the callback
Does not trigger Business Rules, Workflows, or other server-side automation on the referenced record
Results are not cached—each call makes a fresh server request, making it potentially expensive for repeated calls
Works in all client-side contexts (Client Scripts, UI Policies, UI Actions) but not in server-side scripts
Executes asynchronously, so code after the method call runs before the callback executes
Field-level read ACLs on the referenced table are respected—restricted fields appear as empty values in the returned object

Parameters

Name	Type	Required	Description
fieldName	string	Yes	The name of the reference field to retrieve. Must be a valid reference field on the current form. Will fail silently if the field doesn't exist or isn't a reference field.
callback	function	Yes	Function called when the reference is retrieved. Receives a single parameter: a GlideRecord-like object with the referenced record's data. The object contains display values, not raw database values.

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 — loading user details from caller fieldbasic

function onChange(control, oldValue, newValue, isLoading) {
  if (isLoading || newValue === '') {
    return;
  }
  
  // Load full user record when caller changes
  g_form.getReference('caller_id', function(user) {
    if (user) {
      // Populate location and department from user record
      g_form.setValue('location', user.location);
      g_form.setValue('u_department', user.department);
      
      // Show/hide VIP section based on user attribute
      var isVip = user.vip == 'true';
      g_form.setDisplay('u_vip_section', isVip);
    }
  });
}

Demonstrates the most common pattern: loading related data when a reference field changes. The callback safely checks for null and accesses multiple fields on the referenced user record.

Intermediate — chaining reference lookups for validationintermediate

function onChange(control, oldValue, newValue, isLoading) {
  if (isLoading || newValue === '') {
    g_form.clearMessages();
    return;
  }
  
  // Validate that selected CI belongs to caller's location
  g_form.getReference('u_configuration_item', function(ci) {
    if (!ci) return;
    
    g_form.getReference('caller_id', function(user) {
      if (!user) return;
      
      // Compare location sys_ids (both are display values here)
      if (ci.location !== user.location) {
        g_form.addErrorMessage('Selected CI must be at the caller\'s location');
        g_form.clearValue('u_configuration_item');
      }
    });
  });
}

Shows nested callbacks for cross-field validation using reference data. Both callbacks check for null values before proceeding with the validation logic.

Advanced — building dynamic choice lists from reference dataadvanced

function onLoad() {
  // Populate software options based on selected hardware
  g_form.getReference('u_hardware', function(hardware) {
    if (!hardware) {
      g_form.clearOptions('u_software');
      return;
    }
    
    // Clear existing options
    g_form.clearOptions('u_software');
    
    // Build software list based on hardware OS
    var softwareMap = {
      'windows': [['office365', 'Microsoft 365'], ['adobe', 'Adobe Creative']],
      'linux': [['docker', 'Docker CE'], ['ansible', 'Ansible']],
      'macos': [['xcode', 'Xcode'], ['sketch', 'Sketch App']]
    };
    
    var osType = hardware.u_operating_system.toLowerCase();
    var softwareList = softwareMap[osType] || [];
    
    softwareList.forEach(function(option) {
      g_form.addOption('u_software', option[0], option[1]);
    });
  });
}

Advanced pattern showing how to use reference data to dynamically populate choice fields. The callback processes the referenced record's data to determine available options for another field.

Gotchas

The callback executes asynchronously, so any code that depends on the reference data must be inside the callback function or use promise-like patterns.

All field values in the returned object are display values, not database values—choice fields show labels, not internal choice values.

The method fails silently if the field name doesn't exist or isn't a reference field, with the callback never executing.

ACLs are strictly enforced—users without read access to the referenced table get null even if the reference field has a value.

Extended table fields are included in the returned object, but the field names must match exactly including any table prefixes.

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