ServiceNow Display Value Explained

What is a Display Value?

A display value is the human-readable name shown to users for a reference field, while the actual value is the unique system ID stored in the database. For example, a Resolved by field might store the user ID ‘a1b2c3d4e5f6g7h8’ internally, but display ‘John Smith’ to users. Display values make ServiceNow interfaces readable; actual values make the database efficient and prevent name collisions when two users have similar names.

How Display Values Work on the Platform

Every table has a display field that determines what appears when a reference is shown. For the User table, the display field is typically the name field. For the Department table, it might be the department code. For the Incident table, it is usually the ticket number. When you add a reference field to a form (for example, Assigned To points to the User table), ServiceNow automatically shows the display value (user name) rather than the user ID. Behind the scenes, the database stores only the sys_id.

In scripting, you can access both: `current.assigned_to` gives you the sys_id; `current.assigned_to.getDisplayValue()` gives you the name. This distinction is critical for troubleshooting. If a script compares `assigned_to == “John Smith”`, it will fail because assigned_to contains an ID, not a name. Reports and queries also distinguish between display values and actual values. A report grouped by Assigned To will group by ID but display the name next to each ID for readability.

Where Display Values Live

Display values are not stored separately in the database. They are configured at the table level through the table’s Display field property (usually set in the table metadata). When ServiceNow renders a form or report, it looks up the display field from the referenced table on-the-fly and shows it to users. This means display values are calculated at runtime, not stored redundantly. The reference field itself stores only the sys_id for efficiency.

Worked Example: Assigned To Field

You have an incident with Assigned To = ‘e5f6g7h8i9j0k1l2’ (the sys_id). ServiceNow looks up the user record ‘e5f6g7h8i9j0k1l2’ in the sys_user table and retrieves the display field (name) = ‘Alice Johnson’. On the incident form, the Assigned To field displays ‘Alice Johnson’ in a readable format. In the database, the incident record stores only the ID. When you export data to CSV, you must decide: export the ID or the display value? CSV exports typically show the display value because names are meaningful to business users; raw IDs are not. When you import data back into ServiceNow, you must provide IDs, not display values, because the system needs the actual unique key.

Common Misunderstandings

Many developers assume the Assigned To field stores the user name. It does not; it stores the user sys_id. The name is the display value calculated at query time. This confusion leads to bugs: a script that tries to match on name instead of ID will silently fail or compare against the wrong record if multiple users have similar names.

Another misconception: that changing a user’s name changes all past incidents. It does not. The incident still references the user sys_id. If the user name changes in the sys_user table, all past incidents automatically show the new name because display values are looked up at query time, not stored with the incident. This is efficient but risky for audit trails: if you need to know the historical name of who was assigned to an incident years ago, you must check audit logs, not the current name.

Some believe display values are permanent or immutable. They are not. If a user is deleted or a department is renamed, the display value changes immediately. For compliance and audit purposes, this is a risk: you lose the historical context of who did what when. To preserve history, store a copy of the display value in a separate text field before deleting users.

Related Concepts

Reference fields link to other tables and store sys_ids. Each reference field has a display field setting and an actual value. System IDs are unique identifiers for every record in ServiceNow. External IDs are alternate unique identifiers from third-party systems. Sys_id is the primary key for most tables and is guaranteed to be unique within a table.

Practical Implications for Scripting

When filtering records: use the sys_id (actual value) for queries, not the display value. Display values are not indexed and queries on them are slow and unreliable. When comparing values in conditions: always compare sys_ids. When displaying in logs, emails, or user-facing messages: use display values for readability. When integrating with external systems: confirm whether they expect sys_ids or display values from ServiceNow, as this affects data mapping.

The question to ask before writing any integration or report

Every reference field in the platform has two faces, and most developer mistakes happen when code uses one face where it needs the other. The label a user reads is a display value. The key the database uses is the sys_id. A script that filters by label works until two users share a name, a directory sync renames someone, or a locale changes how a label is formatted. Before writing an integration, a report or an update script, ask a single question: is this code identifying a record, or presenting one? Identifying a record needs the sys_id or another unique key. Presenting a record can use the label. Mixing the two is a common source of bugs after a data load.

Import lookups where labels cause duplicates

An import set that maps a name column onto a reference field is where display values can cause the most damage. The import asks the target table to find a record whose display field matches the text. If two people share a name, the import may link every row to the first match it finds, or it may create a new record for each unmatched row. Neither outcome is visible on the day of the load. It shows up weeks later as a manager who owns the work of someone else. Prepare the source data with a stable key, such as an employee number or a login, and configure the lookup to use that key. Where no key exists, build a reconciliation step that flags ambiguous matches for a person to resolve before the load.

Keeping the historical name when the current name changes

A reference field shows whatever the referenced record says today. If a department is renamed, every historical record that points to it shows the new name, and a report about last year’s staffing quietly changes. For most operational purposes that is what people want. For audit or compliance, it is a problem. Where history matters, store a text copy of the label at the time of the event in a separate field, and document that the copy is a snapshot rather than a live value. Do this before the first rename or deletion, because after the change there is no way to recover the earlier label from the record itself.

1. Decide which fields need a historical label, and why, with the audit owner.
2. Add a text field for each one and populate it when the event is created, not in a later batch.
3. Test a rename of a referenced record in sub-production and confirm the snapshot keeps the original text.
4. Note in the data dictionary that the snapshot field is not a reference and must not be used as one.

Checks before a bulk update touches reference fields

• Confirm that the script compares sys_ids, and search the code for comparisons against literal names.
• Run the update against a copy and count the rows whose referenced record changed, not only the rows that changed.
• Review any report that groups by a reference field, because grouping uses the key while the displayed group label comes from the referenced record.
• Check whether an external system expects keys or labels, since sending one where the other is expected produces results that look plausible.

When a label is the correct thing to store

Some data should be free text. A ticket that records the name of an outside vendor’s contact person, for example, may not belong to any user record, and forcing it into a reference field creates a record for someone who never used the platform. Use a reference when the person or item is managed in the platform and will be maintained there. Use a text field when the value is a historical description, a one-off external party or a value that must survive the deletion of the source record.

Frequently asked questions about display values

Why does a script comparison work in a test instance and fail in production?

Test data often has unique names, so label comparisons appear to work. Production contains duplicates and renames, and the comparison then matches the wrong record or none at all. Comparing sys_ids in both environments avoids the problem.

Does the display field have to be the name?

No. The display field is a table setting, and it should be whichever field a person reading the form can identify the record by. For a user it is often the name, but for a configuration item a model or a host name may be a better label. Changing the display field changes how every reference to that table is shown, so test the change on the forms and reports people use most.

Can a report group by name instead of by key?

It can display names, but two records with the same name will then appear as one group if the report is built on the label rather than the key. Group by the key and display the label alongside it when the names might collide.

What is the safest way to export data that will be edited and re-imported?

Export the sys_id as a column next to the label, ask business editors to change only the label or the value they own, and re-import with the sys_id as the match key. Reject any row where the sys_id is missing rather than letting the import guess.

Next step

Reference mistakes often show up after a load has already run, so review the lookups before the next import. For the loading side, see Import set and transform map design.