Essential Guide to Retrieving Reference Field Display Values in ServiceNow

When working with ServiceNow, client-side scripting plays a vital role in enhancing user experience and automating form interactions. A common requirement is to access the value of a field on a form using client scripts. While retrieving the value of standard fields is straightforward, getting the user-friendly display value of a reference field can sometimes be tricky. Many developers new to ServiceNow find that g_form.getValue('field_name') on a reference field returns the system identifier (sys_id) instead of the actual displayed text. This article will explain why this happens and, more importantly, guide you on how to correctly retrieve the display value of a reference field in your ServiceNow client scripts.

Let's delve into the specifics of handling reference fields in ServiceNow client scripts and how to get the information you truly need – the displayed value.

The Issue: g_form.getValue() Returns the Sys_ID

When you use the g_form.getValue('your_reference_field') method on a field that references another table (like the "Company" field on an Incident form, which references the "Core Company" table), you're essentially retrieving the unique identifier (sys_id) of the selected record. This is the underlying value stored in the database. While the sys_id is crucial for system operations, it's often the displayed name or another specific field's value that you need to work with in your client script.

Why g_form.getDisplayValue() Isn't the Answer in Client Scripts

If you're familiar with server-side scripting in ServiceNow, you might think of using getDisplayValue(). However, this method is primarily designed for server-side use (like in Business Rules or Script Includes) and is not directly available within client-side scripts running in the user's browser. Does not work as intended when attempting to use it in a client script.

The Correct Approach: Utilizing g_form.getReference()

The recommended and reliable way to retrieve the display value (or any other field value) from a reference field in a ServiceNow client script is by using the g_form.getReference() method. This method asynchronously fetches the record referenced by the field, allowing you to access its properties within a callback function.

Step-by-Step Instructions:

1. Identify Your Reference Field: Determine the name of the reference field you want to get the display value from (e.g., 'company').

2. Use g_form.getReference(): Call the g_form.getReference() method, passing two arguments:

   • The name of your reference field (as a string).

   • A callback function that will be executed once the referenced record is retrieved.

   The basic syntax looks like this:

   JavaScript

g_form.getReference('your_reference_field_name', function(refRecord) {
	// Your code to work with the referenced record goes here
});

3. Access the Display Value in the Callback Function: Inside the callback function (often named something like getFieldValue or processReference), the refRecord parameter will be a GlideRecord object representing the record referenced by your field. You can then access any field of this record using dot notation. The display value is usually stored in a field like 'name', 'display_name', or a similar field designated as the display field for that table.

4. For example, if the display field for the "Company" table is 'name', you would access it like this:

   JavaScript

g_form.getReference('company', function(companyRecord) {
	var companyName = companyRecord.name;
	alert("Company Name: " + companyName);
	// You can now use the companyName variable as needed
});

Complete Code Example (onChange Client Script)

Let's say you want to display the name of the selected company in an alert when the "Company" field on an Incident form changes. Here's how your onChange client script would look:

JavaScript

function onChange(control, oldValue, newValue, isLoading, isTemplate) {
    if (isLoading || newValue === '') {
        return;
    }

    // Get the GlideRecord of the referenced company
    g_form.getReference('company', getCompanyName);
}

function getCompanyName(companyRecord) {
    // Access the 'name' field (assuming it's the display field)
    var companyName = companyRecord.name;
    // Display the company name in an alert
    alert("Selected Company: " + companyName);
}

Explanation of the Code

• The onChange function is triggered when the value of the "Company" field changes.

• g_form.getReference('company', getCompanyName); initiates the retrieval of the company record. The getCompanyName function will be called once the record is fetched.

• The getCompanyName function receives the companyRecord object.

• var companyName = companyRecord.name; retrieves the value of the 'name' field from the company record.

• alert("Selected Company: " + companyName); displays the retrieved company name.

Example Use Case

Imagine you have a "Requested For" reference field on a custom request form. When a user selects someone in this field, you want to automatically populate a "Department" field based on the selected user's department. You would use g_form.getReference('requested_for', getDepartment); and within the getDepartment callback function, you would access userRecord.department and set the value of the "Department" field using g_form.setValue('department', userRecord.department);.

Attempts to Avoid (and Why)

You might encounter older or less reliable suggestions, such as using g_form.getDisplayBox('company').value. While this might have worked in specific scenarios or older ServiceNow versions, it's not the standard and can be inconsistent across different ServiceNow interfaces (like the standard UI versus the Service Portal). It's best to stick with the g_form.getReference() method for a robust and future-proof solution.

Conclusion

Retrieving the display value of a reference field in ServiceNow client scripts requires using the g_form.getReference() method. This asynchronous approach ensures you get the actual displayed information from the referenced record. By implementing the steps outlined in this article and utilizing the callback function effectively, you can confidently work with reference field display values in your client-side scripting, enhancing the functionality and user experience of your ServiceNow applications. As a next step, identify any client scripts in your ServiceNow instance where you need to access the display value of a reference field and implement the g_form.getReference() method as described. Remember to always test your client scripts thoroughly in a non-production environment before deploying them to your live instance.