Using setDisplayValue for Salesforce References and Lookup Fields

By /






Mastering ServiceNow Reference Fields: The Power of setDisplayValue



Mastering ServiceNow Reference Fields: The Power of setDisplayValue

Alright, fellow ServiceNow enthusiasts and code wranglers, let’s talk about something that often trips up even seasoned developers: handling reference fields in scripts. You’ve probably found yourself in a situation where you need to populate a reference field, but all you have is a user’s name, a group’s name, or a CI’s display name, not that elusive sys_id. That’s where the magical setDisplayValue method swoops in, offering a much-needed shortcut. But like all powerful tools, it comes with its own set of nuances, best practices, and even a few pitfalls.

In this deep dive, we’re going to unravel the mystery of setDisplayValue, compare it head-to-head with its more common sibling, setValue, and explore when each is your best friend. We’ll look at real-world scenarios, peek under the hood, and even equip you with the knowledge to ace those tricky interview questions.

The Core of Reference Fields: sys_id vs. Display Value

Before we jump into the mechanics of setting values, let’s make sure we’re all on the same page about how ServiceNow handles reference fields. This understanding is foundational.

Understanding Reference Fields: The Two Faces of a Single Truth

Imagine a field on your Incident form called “Caller” or “Assignment Group.” When you look at it in the UI, you see a human-readable name like “Abel Tuter” or “Service Desk.” This is what we call the display value. It’s user-friendly, intuitive, and generally what we interact with on forms.

However, beneath that friendly façade lies the true identity of that record: its sys_id. This is a 32-character globally unique identifier (GUID) that ServiceNow assigns to every record created in the system. Think of it like a Social Security Number for a person, or a unique serial number for a product. While many people might be named “John Doe,” only one will have a specific SSN. Similarly, while multiple groups might be called “Internal Support (Deprecated),” only one will have a specific sys_id.

In the database, a reference field *always* stores the sys_id of the referenced record. The display value you see in the UI is generated on the fly by looking up the record associated with that sys_id and pulling its display field (often ‘name’, ‘user_name’, or ‘short_description’).

Why sys_id is King for Direct Assignment

Because the sys_id is the definitive, unique identifier for any record, it’s the most robust and performant way to directly link records in scripts. When you’re using GlideRecord to create or update records, providing the sys_id for a reference field is the standard, most direct approach.

Let’s look at some classic examples from the provided reference material:


// Creating a user-role association
var userRole = new GlideRecord('sys_user_has_role');
userRole.setValue('user', '62826bf03710200044e0bfc8bcbe5df1'); // sys_id of the user
userRole.setValue('role', '2831a114c611228501d4ea6c309d626d'); // sys_id of the role
userRole.insert();

// Creating an Incident record
var gr = new GlideRecord('incident');
gr.initialize();
gr.caller_id = '86826bf03710200044e0bfc8bcbe5d94'; // Direct assignment using sys_id
gr.assignment_group = 'a715cd759f2002002920bde8132e7018'; // Direct assignment using sys_id
gr.short_description = 'Test record using script';
gr.insert();

Notice how `setValue()` and direct dot-walking assignments (e.g., `gr.caller_id = …`) explicitly use the `sys_id`. This is efficient because ServiceNow doesn’t need to perform an extra database lookup; it simply stores the provided unique identifier.

Enter setDisplayValue: A Developer’s Ally

Now that we’ve firmly established the `sys_id` as the underlying truth, let’s talk about those times when you simply don’t have it at hand. Perhaps you’re parsing data from an external system that only provides user names, or you’re writing a script that needs to be more flexible without hardcoding `sys_id`s. This is where `setDisplayValue` comes to the rescue.

What setDisplayValue Does: The “Smart” Setter

The core magic of `setDisplayValue` is deceptively simple: it allows you to set the value of a reference field using its human-readable display value, and ServiceNow will automatically resolve that to the correct sys_id behind the scenes.

Consider the contrast directly from our reference material:

“current.setValue('field_name",value); if we are writing this for reference type of field then we should give sys_id in place of value.”
“current.setDisplayValue('field_name",value); here if reference field give value as value only not sys_id.”

This means if you want to set the “Caller” field to “Abel Tuter,” you’d normally have to first find Abel’s `sys_id` and then use `setValue`. With `setDisplayValue`, you just pass “Abel Tuter,” and ServiceNow takes care of the lookup.

When to Reach for setDisplayValue

So, when is this method your go-to? Here are a few practical scenarios:

  • Integration Scripts: When receiving data from external systems (e.g., a third-party HR system, an API endpoint) that only provides names, email addresses, or other display values for referenced entities. Rather than performing a `GlideRecord` query yourself to find the `sys_id`, `setDisplayValue` handles it for you.
  • Data Imports: If you’re importing data via scripts (not necessarily using the import sets UI), and your source data uses human-readable identifiers.
  • Developer Convenience: Sometimes, for smaller scripts or proof-of-concept work, obtaining a `sys_id` might be an extra step you want to avoid, especially if the `sys_id` might change in different environments (though ideally, `sys_id`s for core data like users/groups would be consistent across instances, this isn’t always true for custom data).
  • User-Friendly Inputs: In more complex scripted solutions where user input might be a display name, `setDisplayValue` simplifies the process.

Syntax and Basic Usage

The syntax for `setDisplayValue` is straightforward:


// On the 'current' object (e.g., in a Business Rule)
current.setDisplayValue('reference_field_name', 'Display Value of Record');

// On a GlideRecord object (e.g., in a background script, Script Include)
var grIncident = new GlideRecord('incident');
// ... set other fields ...
grIncident.setDisplayValue('caller_id', 'Abel Tuter');
grIncident.setDisplayValue('assignment_group', 'Service Desk');
grIncident.insert();

Let’s revisit our incident creation example, but this time using `setDisplayValue` for the reference fields:


// Creating an Incident record using display values
var gr = new GlideRecord('incident');
gr.initialize();
gr.setDisplayValue('caller_id', 'Abel Tuter'); // Using the display name
gr.category = 'inquiry';
gr.subcategory = 'antivirus';
// gr.cmdb_ci = 'affd3c8437201000deeabfc8bcbe5dc3'; // If you still have sys_id, use it!
gr.setDisplayValue('cmdb_ci', 'MacBook Pro'); // Using the CI's display name
gr.short_description = 'Test record using setDisplayValue';
gr.description = 'This record was created using setDisplayValue for references.';
gr.setDisplayValue('assignment_group', 'Service Desk'); // Using the group name
gr.insert();

As you can see, this makes the script much more readable and potentially easier to maintain if you’re dealing with values that are typically known by their names rather than their cryptic `sys_id`s.

The `current` Object: Where setDisplayValue Shines

The `current` object is a pivotal concept in server-side scripting in ServiceNow, particularly within Business Rules, Script Actions, and other event-driven scripts. It represents the record that is currently being inserted, updated, or deleted. Our reference material reminds us:

“What is current object? Answer)it is used to set and get the values on the form at the server side.”

When you’re working with the `current` object, `setDisplayValue` often finds its perfect use case.

Revisiting `current` for Context

The `current` object gives you direct access to the fields of the record triggering the script. It’s your window into the current state of a form submission or a record operation. When a user submits a form, the values they entered (including display values for reference fields) are available. If your Business Rule needs to adjust a reference field based on some logic, and you only have the display name (perhaps from another field or a system property), `setDisplayValue` on `current` is incredibly convenient.

Practical Scenarios with `current`

Let’s imagine a few scenarios where `setDisplayValue` on the `current` object becomes invaluable:

Scenario 1: Defaulting an Assignment Group based on Category (Business Rule)

You have a requirement: if an incident’s category is “Hardware,” the “Assignment Group” should automatically be set to “Hardware Team,” unless the user has already specified one.


// Business Rule: Before Insert/Update
// Table: Incident [incident]
// Condition: current.category.changes() || current.assignment_group.nil()

if (current.category == 'Hardware' && current.assignment_group.nil()) {
    current.setDisplayValue('assignment_group', 'Hardware Team');
    gs.info('Incident ' + current.number + ': Assignment group set to Hardware Team by BR.');
} else if (current.category == 'Software' && current.assignment_group.nil()) {
    current.setDisplayValue('assignment_group', 'Software Support');
    gs.info('Incident ' + current.number + ': Assignment group set to Software Support by BR.');
}

Using `setDisplayValue` here means you don’t need to hardcode the `sys_id` of the “Hardware Team” or “Software Support” groups, making the script more readable and less prone to errors if those group `sys_id`s differ across instances.

Scenario 2: Setting an “Approval Manager” from an External Source

Perhaps an integration sends you a request, and part of the payload includes the email address of the manager who needs to approve it. You want to set a “u_approval_manager” reference field on your custom table.


// Assuming 'emailFromIntegration' is the email address provided by the external system
var emailFromIntegration = 'john.doe@example.com'; 

// Within a Scripted REST API or Import Transform Script
// Let's assume 'gr' is your target record, could also be 'current' in some contexts
var gr = new GlideRecord('u_custom_request');
gr.initialize();
gr.setValue('u_request_number', 'REQ12345'); 
gr.setDisplayValue('u_approval_manager', emailFromIntegration); // ServiceNow will find user by email
gr.insert();

ServiceNow is smart enough to often resolve reference fields using common display fields like `name` or `email` if the field dictionary is configured appropriately for display. This again saves you a manual `GlideRecord` query to find the `sys_id` of the user from their email address.

Under the Hood: How `setDisplayValue` Works (and Its Nuances)

It’s easy to think of `setDisplayValue` as pure magic, but understanding how it actually functions internally can save you from unexpected behavior and help you debug more effectively.

The Lookup Process

When you call `setDisplayValue(‘field_name’, ‘Display Value’)`, ServiceNow essentially performs a `GlideRecord` query for you on the *referenced table*. It searches for a record in that table whose display field (the field configured as the “Display” field in the dictionary, often `name` for `sys_user`, `sys_user_group`, or `short_description` for `cmdb_ci`) matches the ‘Display Value’ you provided.

If a match is found, it extracts the `sys_id` of that matching record and then internally calls `setValue(‘field_name’, resolved_sys_id)`. If multiple matches are found, it often picks the first one it encounters (which might not be the one you intended) or, in some contexts, might fail to set the value at all, depending on the exact implementation and version.

Performance Considerations: The Cost of Convenience

This internal lookup isn’t free. `setDisplayValue` requires an additional database query compared to `setValue`, which directly assigns the `sys_id`. This means:

  • `setValue` is generally faster and more performant. It’s a direct assignment.
  • `setDisplayValue` introduces a slight overhead. For a single record update, this overhead is negligible. However, if you’re processing thousands of records in a loop (e.g., a large data import or a complex scheduled job), repeatedly using `setDisplayValue` can accumulate and impact performance.

When is this overhead acceptable? When developer convenience, code readability, or the source data format (only display values available) outweighs the minor performance hit. For most Business Rules and single-record operations, it’s perfectly fine. For bulk operations, consider pre-fetching `sys_id`s if possible.

What Happens on Failure?

This is a crucial point for troubleshooting. If `setDisplayValue` cannot find a matching record for the provided display value:

  • The field typically remains empty or retains its previous value. It usually doesn’t throw a JavaScript error that would halt your script entirely.
  • No explicit error message (usually). You might not get a clear “record not found” message in the logs by default, making debugging a little trickier. You’ll simply observe that the field didn’t get set as expected.
  • Warnings in system logs (sometimes). Depending on the ServiceNow version and specific context, you *might* see a warning message in the system logs indicating that a display value could not be resolved. Always check your logs!

`setDisplayValue` vs. Reference Qualifiers: A Tangential but Crucial Relationship

This is where things can get a little tricky and is a prime candidate for an interview “gotcha.” Let’s first briefly recap what reference qualifiers are, as described in our reference material:

“Reference Qualifiers are used to restrict the data in reference and List type of fields… 3 Types: Simple, Dynamic, Advanced.”

Reference qualifiers (Simple, Dynamic, Advanced) are designed to control *which records are available for selection in the user interface* for a given reference field. For example, a qualifier might ensure you can only assign incidents to “Active” users or to groups within the same company.

How `setDisplayValue` Interacts (or Doesn’t)

Here’s the critical distinction: `setDisplayValue` does NOT respect reference qualifiers.

When you call `setDisplayValue`, ServiceNow performs a direct database lookup to find a `sys_id` based on the display value you provided. It does not go through the UI’s selection mechanism, and therefore, it does not apply any reference qualifiers that would normally restrict what a user can *see* or *pick* from the lookup list.

Implication: You *can* successfully set a reference field via `setDisplayValue` to a record that would otherwise be filtered out by a reference qualifier in the UI. For example, if your “Assigned to” field has a reference qualifier to only show “Active” users, but you use `setDisplayValue` to set it to an “Inactive” user’s name, the script will likely succeed (assuming the inactive user’s display name resolves to their `sys_id`).

This behavior is a double-edged sword:

  • Flexibility: It gives scripts the power to set values that might be outside normal UI constraints, which can be useful for administrative tasks or specific integrations.
  • Data Integrity Risk: If your business logic *requires* that a reference field always adhere to its qualifier (e.g., an incident *must* be assigned to an active user), then relying solely on `setDisplayValue` without additional validation can bypass this crucial rule. You might end up with “dirty” data that doesn’t conform to your expected business processes.

Best Practice: If data integrity dictated by reference qualifiers is paramount, either:

  1. Perform your own `GlideRecord` query to find the `sys_id`, ensuring your query incorporates the same conditions as your reference qualifier, then use `setValue`.
  2. Use `setDisplayValue`, but immediately follow it with an explicit check to see if the value was set to something that violates your business rules, and then clear or correct it if it does.

Troubleshooting Common `setDisplayValue` Issues

As powerful as `setDisplayValue` is, it’s not immune to issues. Here are some common problems and how to troubleshoot them:

Value Not Setting

The most common issue is that the reference field simply isn’t populated after your script runs.

  • Typo in Display Value: The display value you provided is case-sensitive (or might be depending on the field’s configuration) and must exactly match a record’s display field. Even an extra space can cause failure.
  • No Matching Record Found: The display value simply doesn’t exist in the referenced table. This is common when data comes from external sources with discrepancies.
  • Multiple Records with the Same Display Value: If two users are both named “John Doe,” `setDisplayValue` might pick one arbitrarily (often the first one returned by the database query), or it might fail to set the value because of ambiguity. This is why unique identifiers are always preferred.
  • ACLs Preventing Lookup: The user context under which your script is running might not have the necessary Access Control List (ACL) permissions to read the referenced record. Even if you’re an admin, a Business Rule might run under a specific system user with limited permissions.
  • Incorrect Reference Field Name: Double-check the exact field name (e.g., `caller_id`, not `caller`).

Debugging Tips

  • Use `gs.info()` or `gs.debug()`: Print the display value you are trying to set *before* calling `setDisplayValue`, and then print the `sys_id` of the field *after* the call (e.g., `gs.info(‘Caller sys_id after set: ‘ + current.caller_id);`). This helps you see if the value was successfully resolved.
  • Test Manually in UI: Try searching for the exact display value you’re using in your script within the ServiceNow UI lookup for that reference field. Does it find the record? Does it show multiple results?
  • Check System Logs: Always check your system logs (`System Logs > All`) for any warnings or errors related to your script or the `setDisplayValue` operation.
  • Validate Uniqueness: If you suspect ambiguity, perform your own `GlideRecord` query to see how many records match your display value:
    
var grUser = new GlideRecord('sys_user');
grUser.addQuery('name', 'John Doe'); // Or whatever the display field is
grUser.query();
gs.info('Found ' + grUser.getRowCount() + ' users named John Doe.');

When to Use Which: A Decision Matrix

To help you decide between `setValue` (or direct assignment with `sys_id`) and `setDisplayValue`, here’s a quick decision matrix:

Use `setValue` (or direct `sys_id` assignment) when:

  • You already have the `sys_id` of the referenced record (e.g., from a preceding `GlideRecord` query, a parameter passed to a function, or a relationship in another record).
  • Performance is critical, especially in scripts processing a large number of records. Direct `sys_id` assignment avoids an extra database lookup.
  • You need precise control and want to avoid any ambiguity that might arise from multiple records having the same display value.
  • You want to enforce reference qualifier logic by pre-validating the `sys_id` yourself to ensure it adheres to all business rules.
  • Your data source explicitly provides `sys_id`s.

Use `setDisplayValue` when:

  • You only have the display value (name, email, etc.) from your data source (e.g., integration payload, import file).
  • Developer convenience and code readability are higher priorities than marginal performance gains for single-record operations.
  • You are reasonably confident that the display value you are providing is unique enough within the referenced table to resolve to the correct record.
  • You are working within a Business Rule or similar server-side script on the `current` object, and user input or external data has provided a display value that needs to be resolved.
  • You need to set a value that might temporarily bypass UI-level reference qualifiers for specific administrative or integration purposes (with caution!).

Interview Relevance and Best Practices

Understanding `setDisplayValue` is a strong indicator of a developer’s grasp of ServiceNow’s underlying architecture and best scripting practices. It frequently comes up in technical interviews.

Common Interview Questions

  • “What’s the fundamental difference between `setValue` and `setDisplayValue` for reference fields?”

    Expected Answer: `setValue` uses the `sys_id`, `setDisplayValue` uses the human-readable display value and performs an internal lookup.
  • “When would you prefer to use `setValue` over `setDisplayValue`, and vice-versa?”

    Expected Answer: Refer to the “Decision Matrix” above – performance, data source, uniqueness, validation needs.
  • “Does `setDisplayValue` respect reference qualifiers? Explain why or why not.”

    Expected Answer: No, it bypasses them because it performs a direct database lookup, not a UI-driven selection. Emphasize the implications for data integrity.
  • “What are the performance implications of using `setDisplayValue` extensively?”

    Expected Answer: It’s slightly less performant due to the extra database query. This is usually negligible for single operations but can be a concern for bulk processing.
  • “How would you troubleshoot a situation where `setDisplayValue` isn’t setting the field as expected?”

    Expected Answer: Mention checking for typos, verifying record existence/uniqueness, using `gs.info()`, checking ACLs, and system logs.

Best Practices for Robust Scripting

  • Prioritize `setValue` with `sys_id` when possible: It’s generally the most performant and precise method. If you can get the `sys_id` (e.g., from an earlier query), use it.
  • Ensure uniqueness for `setDisplayValue`: If relying on display values, make sure they are reasonably unique in your instance. If not, consider adding pre-validation steps or fallbacks.
  • Add robust error handling/logging: Especially in integrations or critical workflows, log when `setDisplayValue` fails to resolve a value so you can identify and correct data issues.
  • Be mindful of security context (ACLs): Scripts run under specific user contexts. Ensure the script has permission to read the referenced table and its display field.
  • Understand the trade-offs: Always weigh the convenience of `setDisplayValue` against its performance implications and its interaction (or lack thereof) with reference qualifiers.

Conclusion

The choice between `setValue` and `setDisplayValue` for handling reference fields in ServiceNow isn’t about one being inherently “better” than the other. It’s about understanding their underlying mechanisms, their performance characteristics, and their interaction with other platform features like reference qualifiers.

`setValue` is your workhorse for speed, precision, and when you have the `sys_id`. `setDisplayValue` is your clever assistant, perfect for when you’re dealing with human-readable input and need the platform to do the heavy lifting of resolving values. By thoughtfully applying each method where it makes the most sense, you can write more efficient, readable, and robust ServiceNow scripts, saving yourself headaches and delighting your users.

So, go forth and script wisely! May your reference fields always resolve correctly, and your logs remain clean.


Scroll to Top