How To Use getDisplayValue() and GlideRecord

When you’re scripting with reference field’s and sys_id’s, understanding how to use getDisplayValue() is incredibly useful.

Anytime you see a reference field on a form, you need to know that the true value of that field is a sys_id in ServiceNow. This sys_id value, is the value of the record on the related table. The true value is not what you see in the field, for example – a user’s display name on an incident.

ServiceNow’s table structure is a MySQL relational database.

This means that you can have one record on one table, “relate” to another record on another table.

This reference field relationship allows us to do things like dot-walk to different tables in ServiceNow.

When you think of reference fields, sys_ids and records referencing records on other tables, make sure to consider using getDisplayValue() in your GlideRecord queries. This will translate sys_id’s into human readable information.

getDisplayValue() can only be used on reference fields in ServiceNow. I can’t think of a scenario where a non reference field type would ever been associated to using getDisplayValue() in a script.

Understanding Reference Fields

Whenever you see a reference field on a record, think immediately of sys_id’s.

You’ll know a field is a reference field when you see the i icon, with a circle around it, to the right of the field. Furthermore, when you hover over it, you’ll see a modal window popup on the screen, to the data, showing more fields.

Requested by, in this example, is a reference field to sys_user.

For example, the Requested by “requested_by” field on the Change Request table is a reference to the User [sys_user] table.

If you want to verify this, take a look at the actual field value.

You can do this by right-clicking the gray form header, and going to down to “Show XML”, which will pop up the XML of the current record in a new window.

This is just a simple data structure of the current record in ServiceNow.

When you find the “Requested by” field, you’ll see that the value is some long string, which is the sys_id of the record that’s on a different table.

Example sys_id: 5137153cc611227c000bbd1bd8cd2005

You can also see that there’s a display_value, of the users actual name.

This is configurable in ServiceNow at the dictionary level. Every table can have one field/column that is display=true, which will show when it’s being referenced by a reference field. Out of box, the full name on sys_user is setup to display as the field to show when it’s being referred to.

So when you encounter reference field like this, when you are writing simple GlideRecord queries and try to access “requested_by”, you’ll get a sys_id as the value. Which is usually not super helpful, especially if you’re trying to add a comment or send an email, and want the user’s full name instead.

How To Use getDisplayValue() In A Script

Simply put, you use getDisplayValue(), when you have a GlideRecord object that has a reference field. You use the getDisplayValue() method to convert the sys_id of the reference field, to a human readable value, or the “display” value of the record in question.

To really understand this, consider the following 2 examples.

You can completely ignore the GlideRecord addQuery(), I just had to use an example of something. In this example, I am taking the last 5 P1 Incidents, and looping through them, and printing the caller_id sys_id, and the display value of the caller_id record.

Pay attention to the gs.log() statement in the loop, as there’s one simple difference.

To use getDisplayValue(), you use this form:

GlideRecordObject.fieldName.getDisplayValue();

Which will commonly be seen as:

gr.caller_id.getDisplayValue();

Pay attention to line 7 in both scripts, we use getDisplayValue() in one and we don’t in another.

Using getDisplayValue()

var gr = new GlideRecord("incident");
gr.addQuery("priority", 1);
gr.setLimit(5);
gr.query();

while (gr.next()) {
    gs.log(gr.caller_id.getDisplayValue());
    // Will print the caller's full name
    // and not the sys_id of the reference field
}

When you run this example in a background script, you will log the actual value of the related record.

Example of output:

Not Using getDisplayValue()

We access the sys_id on line 7, printing out the sys_id of the caller_id user field

There are a ton of great examples for using the sys_id, especially in scripting. So it’s not “preferred” to use getDisplayValue(). There is a correct time and place for using both methods.

var gr = new GlideRecord("incident");
gr.addQuery("priority", 1);
gr.setLimit(5);
gr.query();

while (gr.next()) {
    gs.log(gr.caller_id);
    // Will print the sys_id of the reference field
}

But when you DON’T use, getDisplayValue() on the reference field, you’ll just print out the sys_id of the related record.

This will print out the following sys_id’s, of the users.

Hopefully all of this makes sense.

This is just one simple example, but the concepts extend to the entire ServiceNow platform.

Also remember that this action is only able to take place server-side in ServiceNow. This action is not possible on the client, because you can’t/shouldn’t access the GlideRecord class client side.

Let us know if you have any questions.