Use g_form.getReference to get a reference record client-side

The g_form.getReference() method looks synchronous but is actually asynchronous — it makes a server call to fetch the referenced record and returns the result via callback. This trips up developers who expect immediate access to the returned record or who try to use the result outside the callback function. The platform designed it this way to avoid blocking the UI thread during the server roundtrip, but the synchronous-looking method signature creates a mental model mismatch that leads to timing bugs in production.

When to use this

• When you need to populate dependent fields based on a reference field change in onChange client scripts
• When you need to access dot-walked fields from the referenced record (like manager.email or department.name)
• When you want to avoid the overhead of creating a dedicated GlideAjax script include for simple reference field access
• When working with reference fields that have ACL restrictions — getReference respects the current user's read permissions

When NOT to use this

• Don't use this in onLoad client scripts for initial form population — the async nature can create race conditions with other form initialization logic
• Don't use this when you need complex queries or multiple records — use GlideAjax with a proper script include instead
• Don't chain multiple getReference calls in nested callbacks — you'll create a pyramid of callbacks that's hard to debug
• Don't use this when the referenced record might be frequently changing — each call makes a fresh server request with no client-side caching

Key behaviors and gotchas

• The method always passes null to the callback if the reference field is empty, the record doesn't exist, or the user lacks read access
• Boolean field values return as strings — 'true' or 'false' — not JavaScript booleans, so use string comparison
• Dot-walking works in the getValue() call — you can access manager.email directly without chaining getReference calls
• The returned record object only supports getValue() and getDisplayValue() — it's not a full GlideRecord object
• Each call makes a separate AJAX request — there's no automatic caching, so avoid calling it multiple times for the same reference field
• If called during isLoading in onChange scripts, it can interfere with form initialization and cause dependent field timing issues