Set a reference field with display value

Reference fields in ServiceNow have two pieces of data: the sys_id (the actual value) and the display value (what users see). When you set a reference field with g_form.setValue() using only two parameters, ServiceNow doesn't automatically fetch the display value. This leaves users staring at blank labels in read-only reference fields, even though the underlying sys_id is correctly stored. The three-parameter version prevents this by explicitly setting both the value and what users see.

When to use this

• Setting reference fields from AJAX responses where you already have the display value
• Populating dependent reference fields based on user selections
• Pre-populating forms where the reference field may become read-only
• Client scripts that need immediate visual feedback without server round-trips

When NOT to use this

• Don't use when you only have the sys_id — use two parameters and let ServiceNow fetch the display value
• Don't set display values that don't match the actual record — users will see inconsistent data
• Don't use in server-side scripts — use GlideRecord.setValue() with just the sys_id

Key behaviors and gotchas

• Two-parameter setValue() on reference fields leaves display value blank until form refresh
• The display value parameter accepts any string — ServiceNow doesn't validate it matches the record
• Setting a reference field triggers onChange events — check isLoading to prevent loops
• Invalid sys_id values will be accepted but cause validation errors on submit
• Reference field choice list filters are applied after setValue() — field may appear invalid if value doesn't match filters