ServiceNow Client Scripts: How to Retrieve Reference Field Display Values

In ServiceNow, forms often display friendly names (display values) for reference fields, even though the underlying value is a cryptic sys_id. For example, the Caller field on an Incident form might show "Jane Doe" to the user, while the actual value stored is something like 5137153cc611227c000bbd1bd8cd2005. ServiceNow developers frequently need to retrieve these human-readable names in client-side scripts—for instance, to show messages or perform logic based on the selected reference. This is a common challenge because calling g_form.getValue('caller_id') returns the sys_id, not "Jane Doe." Many developers struggle with this, searching for a ServiceNow client script get display value solution.

In this article, we’ll explain why this happens and explore how to reliably retrieve a reference field’s display value in client scripts. We’ll cover the pitfalls of methods like getDisplayValue() on the client, and then provide verified solutions using g_form.getDisplayBox(), GlideAjax, and other best practices. By the end, you’ll know how to retrieve reference field values in ServiceNow the right way, keeping your scripts both accurate and efficient.

Understanding the Issue

Before diving into solutions, it's important to understand why this issue occurs. Reference fields in ServiceNow store a unique identifier (the sys_id) that points to a record on another table. The platform automatically displays a display value (usually a name or number from that referenced record) on forms so that users see a meaningful value instead of a random ID. However, when you try to access the field's value in a client script using the standard API (g_form.getValue()), you will get the underlying sys_id string. This behavior often confuses developers who expect to retrieve the display name directly.

You might wonder, "Isn't there a getDisplayValue() function I can use on the client?" After all, on the server side (in GlideRecord scripts), getDisplayValue() is commonly used to get a record’s display value. Unfortunately, in client-side scripts, getDisplayValue() does not work the way you’d hope. The client-side GlideForm API (g_form) does have a method called getDisplayValue(), but it doesn’t return a specific field’s display name. Instead, g_form.getDisplayValue() (with no parameters) returns the current form record’s display value (e.g. the Incident number if on an incident form), not the display value of a particular reference field. There is no built-in g_form.getDisplayValue('field_name') for individual fields. So if you tried something like g_form.getDisplayValue('caller_id') in a client script, it either wouldn’t work or wouldn't return what you expect.

This limitation is by design—client scripts have limited access to data to maintain performance. The browser knows the sys_id and the text currently shown on the form, but it doesn’t automatically fetch any other info about that referenced record. In fact, the display text on the form is just part of the rendered HTML, not a readily available script value. Developers end up facing the dilemma: How can I get the user-friendly name from a reference field in a client script? 

The next sections will cover proven methods to solve this.

Verified Solutions

Thankfully, there are a few reliable ways to retrieve a reference field’s display value on the client side.

Below are the verified solutions, each with its use cases and considerations:

Using g_form.getDisplayBox().value to Retrieve the Display Value

One of the simplest solutions in a classic ServiceNow UI form is leveraging the g_form.getDisplayBox() method. This lesser-known GlideForm method returns the HTML input element for a reference field’s display portion (the box showing "Jane Doe", for example). By accessing that element’s .value, you can get the text that’s displayed to the user.

How to use it:

// Assume "caller_id" is a reference field on the form
var callerName = g_form.getDisplayBox('caller_id').value;

In this snippet, callerName will contain the display value of the Caller field (e.g., "Jane Doe") instead of the sys_id. You can then use callerName for comparisons, alerts, or other logic. For example, you might compare two reference fields’ names:

var callerName = g_form.getDisplayBox('caller_id').value;
var assigneeName = g_form.getDisplayBox('assigned_to').value;
if (callerName === assigneeName && callerName !== '') {
    alert("Note: The Caller and Assigned To are the same person (" + callerName + ").");
}

This method is straightforward and does not require any server calls—you're grabbing the value already on the form. It’s perfect when you need to quickly get the display value for on-form use. In fact, before this method was well-known, many developers resorted to more complicated approaches, but g_form.getDisplayBox('fieldName').value provides a clean one-liner solution.

Caveats: Keep in mind that this approach relies on the classic UI form elements. It works in the standard platform UI (often called UI16 or the core UI). If you are working in the Service Portal or a catalog item, g_form.getDisplayBox() may not be available or behave differently, since those use different technologies for forms.

Also, if a reference field is not rendered (for example, if it's hidden via UI policy or not on the form), then there is no display box to retrieve. Another consideration is that g_form.getDisplayBox() is not prominently documented in official docs; it’s considered a bit of a ServiceNow secret that experienced developers have used. That said, it has been around for many years and is safe to use in client scripts for forms.

Using GlideAjax to Retrieve Display Values Dynamically

Another powerful solution is to use GlideAjax to call the server for the display value. GlideAjax is a client-side API that allows you to execute server-side code (in a Script Include) and get a response back – essentially an AJAX call to retrieve data from the server in real time. This method is useful in scenarios where the display value isn't readily available on the form or when you need additional data about the referenced record. It’s also the go-to approach in Service Portal client scripts, where direct DOM access isn’t possible, or anytime you want a robust, scoped solution.

How to use GlideAjax for display values:

1. Create a client-callable Script Include

   In ServiceNow, create a Script Include (set Accessible from = "Client callable"). In this Script Include, write a function to fetch the display value. For example, you might create a function that takes a table name and sys_id and returns the record’s display value:

var DisplayValueUtils = Class.create(); 
DisplayValueUtils.prototype = Object.extendsObject(AbstractAjaxProcessor, { 
	getDisplayValueById: function() { 
		var table = this.getParameter('sysparm_table'); 
		var recordId = this.getParameter('sysparm_sys_id'); 
		if (!table || !recordId) 
			return ''; 
		var gr = new GlideRecord(table); 
		if (gr.get(recordId)) { 
			// Returns the record's display value 
			return gr.getDisplayValue(); 
		} 
	return ''; 
}, 
// Required for every Script Include 
type: 'DisplayValueUtils' 
});

In this example, getDisplayValueById is a function that will retrieve the display value of a given record. We use gr.get(recordId) on the server and then gr.getDisplayValue() to get the record’s display (usually the field marked as Display for that table).

2. Call the GlideAjax in your client script

   From the client script, you use the GlideAjax API to call the above Script Include:

var ga = new GlideAjax('DisplayValueUtils'); 
// name of the function to execute 
ga.addParam('sysparm_name', 'getDisplayValueById'); 
// table name (e.g., incident) 
ga.addParam('sysparm_table', 'incident'); 
// the sys_id of the reference field 
ga.addParam('sysparm_sys_id', g_form.getValue('caller_id')); 
ga.getXMLAnswer(function(response) { 
	// This is the display value returned by the Script Include 
	var callerName = response; 
	if (callerName) { 
		// You can now use callerName as needed 
		console.log("Caller name is: " + callerName); 
	} 
});

In this script, we pass the table and sys_id to the server. The getXMLAnswer() method takes a callback function that processes the server’s answer asynchronously. Inside that callback, response will contain the string returned by our Script Include function (the display value in this case). We can then use that value on the client (e.g., log it, set a field, etc.).

Using ServiceNow GlideAjax for display values has a few advantages:

• It’s dynamic and can retrieve any information from the server, not just the display value. For example, you could extend the Script Include to return multiple fields (maybe you want the caller's department or email in addition to name).

• It works in any client-side context (both classic UI and Service Portal), since it doesn't rely on form internals, just a server call.

• It keeps the heavy lifting on the server side (using GlideRecord), which is where such data lookups are supposed to happen.

  
  

Caveats: GlideAjax calls are asynchronous, which is great for not freezing the user interface, but it means any logic dependent on the result must run inside the callback (or after the data is returned). You cannot immediately use the result in the next line of code outside the callback function. Also, each GlideAjax call does incur a round trip to the server, so there is a slight performance cost, especially if you call it frequently. Make sure to use it judiciously (we’ll cover performance tips in a moment). For a single display value lookup this is usually fine, but if you find yourself needing many reference values at once, you might combine them into one call or consider another approach.

Alternative: g_form.getReference() – It’s worth mentioning that ServiceNow provides a built-in convenience for reference fields in client scripts: g_form.getReference(). This function, when used with a callback, will retrieve the referenced record’s details (similar to a GlideRecord query behind the scenes) and provide an object containing the record’s fields. For example:

g_form.getReference('caller_id', function(callerRecord) {
    if (callerRecord) {
		// 'name' field from sys_user, 
		// which is the display value for users
        var callerName = callerRecord.name; 
        alert("Caller is " + callerName);
    }
});

Here, g_form.getReference('caller_id', callback) fetches the user record for the Caller.

The returned object callerRecord contains properties corresponding to that user's record (like callerRecord.name, callerRecord.email, etc., assuming you have access to those fields). This is often simpler than writing a GlideAjax Script Include if all you need is the reference's display name or a couple of its fields.

Keep in mind getReference is asynchronous when used with a callback (which is the recommended usage to avoid slowing down the form). Under the hood, it’s doing a GlideAjax call to get the data. So whether you use g_form.getReference or a custom GlideAjax, the idea is the same: retrieve data from the server on-demand.

Best Practices and Alternative Approaches

Now that we have two primary methods, let's discuss when to use each and some best practices for working with reference field values on the client side. Optimizing client-side performance is key to ensure your forms remain responsive.

Here are some guidelines:

• Choose the right method for the job

  If you simply need to get the display text of a reference that is already present on the form, using g_form.getDisplayBox() is quick and efficient (zero server calls). It’s ideal for things like onChange or onSubmit checks where the value is readily available.

  On the other hand, if the display value is not on the form or you need additional info from the reference record, use an asynchronous method like g_form.getReference or GlideAjax. For example, use GlideAjax when you have a sys_id and table and need to fetch data that isn't already loaded.

• Avoid unnecessary server calls

  Each call to g_form.getReference() or GlideAjax triggers a request to the server. Overusing them (especially inside loops or repeated scripts) can impact performance. Always ask, “Do I truly need the display value for this logic, or can I use the sys_id (or some other data) instead?” For instance, if you want to check if two reference fields point to the same record, you can just compare their sys_id values (the results of g_form.getValue() on each) instead of fetching their names.

  Only fetch the display value when it’s needed for user feedback or specific logic that requires the text.

• Use asynchronous calls (don’t freeze the UI)

  Never use server calls in a synchronous way on the client. In older practices, some would call g_form.getReference() without a callback (which can pause the form until the server responds) — this is not recommended. Always provide a callback function to getReference so it runs asynchronously.

  Similarly, always use the callback with GlideAjax.getXMLAnswer() or getXML() to handle the response. This ensures the user can continue interacting with the form while data is being retrieved.

• Batch or cache data when possible

  If you foresee needing multiple reference display values, consider optimizing by batching. For example, a single Script Include could return all needed display values in one go (to avoid multiple GlideAjax calls). Alternatively, if the data is static or known beforehand, you might use a Display Business Rule and g_scratchpad to send the info to the client when the form loads.

  The g_scratchpad object allows server-side code (before the form loads) to attach data that becomes available to client scripts without additional queries. This is useful for things like populating a bunch of reference names upfront if you know you'll need them (though it requires a bit of planning and is mostly beneficial in complex scenarios).

• Include display values when setting reference fields

  This is a related tip for client scripting with references. When you use g_form.setValue() on a reference field, ServiceNow will automatically fetch the display value from the server if you only provide the sys_id. This can cause a brief performance hit due to the synchronous call. To avoid that, always provide the third parameter (display value) in setValue if you know it.

  For example:

// Avoid this if possible – triggers a server call to get display name g_form.setValue('manager', someManagerSysId); 

// Better – no extra call since we provide the name g_form.setValue('manager', someManagerSysId, 'Alice Smith');

By supplying 'Alice Smith' (the manager’s name) along with the sys_id, you save the client from needing to fetch it. This tip helps keep forms snappy, especially when setting reference values programmatically.

• Limit direct DOM manipulation

  One reason g_form.getDisplayBox() is handy is because it’s a supported way to get the form element. You should avoid directly using document.getElementById() or other manual DOM queries to fetch field values on a ServiceNow form, as those can break if ServiceNow changes the UI structure. Stick to supported APIs like g_form methods whenever possible.

  g_form.getDisplayBox() is an exception where you are dealing with an element, but it’s an exposed method from ServiceNow that is safer than hardcoding HTML element IDs.

• Test in different contexts

  If your code might run in multiple contexts (for example, on a regular form vs. in the Service Portal or in a record producer), test that the method you choose works there. In Service Portal, for instance, you don’t have access to g_form.getDisplayBox(), and the scripting is AngularJS-based. In that case, you might rely solely on GlideAjax or different APIs. The focus of this article is the standard form client script scenario (UI16), but always double-check if you move your script to a catalog item or workspace.

By following these practices, you ensure that you're retrieving the reference field display values efficiently and only when needed, keeping the user experience smooth.

Conclusion

Retrieving the display value of reference fields in ServiceNow client scripts is a common requirement – one that initially puzzles many developers.

The key takeaways are:

• Understand the default behavior

  By default, g_form.getValue('reference_field') returns the sys_id, not the user-friendly name. The typical server-side approach getDisplayValue() isn't directly available for fields in client scripts, which is why a ServiceNow client script "get display value" question arises so often.

• Use the right tool for the scenario

  If you need the on-screen text of a reference field in a standard form, g_form.getDisplayBox('fieldName').value is a quick solution to grab that display value. If you need to retrieve reference information that isn’t on the form or are working in contexts where getDisplayBox is unavailable, leverage asynchronous calls. Use g_form.getReference() for a simple way to fetch the referenced record (including its display value) via callback, or implement a GlideAjax call for more complex requirements. When you need ultimate flexibility or are dealing with multiple records, ServiceNow GlideAjax for display values and other data is the robust approach.

• Optimize for performance

  Always consider the impact on client-side performance. Minimize calls to the server by fetching only what you need, when you need it. If you only need to compare references, using the underlying sys_ids might be sufficient and more efficient. When you do fetch data, do it asynchronously (never lock up the UI waiting for a server response). For frequently needed data, explore advanced techniques like caching values in g_scratchpad on form load. And remember to provide display values in setValue() calls to avoid unneeded server lookups.

In summary, working with reference fields in client scripts requires a bit of extra know-how, but with the approaches outlined above, you can retrieve reference field display names reliably.

Whether you opt for the convenience of g_form.getDisplayBox(), the built-in getReference method, or a custom GlideAjax solution, you now have the tools to get those readable names and keep your ServiceNow client scripts both user-friendly and efficient.