Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 39 ยท Tables and Data Model

Reference Fields and Dot-Walking

Master relationships in ServiceNow: reference fields, reference qualifiers, related lists, dot-walking through caller.manager.email, and one-to-many and many-to-many patterns.

Real data is connected: an incident has a caller, the caller has a manager, the manager has an email. ServiceNow models connections with reference fields. Dot-walking lets you follow them from one table to the next in forms, lists, filters, reports and scripts. This lesson shows how both work and how to design relationships well.

Reference fields

A reference field stores the sys_id of one record in another table. On incident, caller_id references sys_user, assignment_group references sys_user_group, and cmdb_ci references cmdb_ci. This is a many-to-one relationship: many incidents point to one caller.

To create one, add a column of type Reference and set the Reference table. Options in the dictionary entry:

  • Reference qualifier: limits the choices. A simple qualifier uses a condition (active=true), an advanced one uses a script (javascript:new GroupFilters().myGroups()), and a dynamic one reuses a named filter.
  • Use reference qualifier and Cascade rule: what happens to the referencing records when the target is deleted (None, Clear, Delete, Restrict).
  • Display column of the target table decides what the user reads.
Python A reference field and its qualifier (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Dot-walking

Dot-walking follows a chain of references by separating field names with dots. From an incident:

  • caller_id.name is the caller's name.
  • caller_id.manager.email is the caller's manager's email.
  • cmdb_ci.location.city is the city of the affected item's location.

You can dot-walk in:

  • List columns and filters: in the condition builder, click the field chooser and use the > arrow to step into the referenced table. You can filter incidents by Caller > Department is Finance.
  • Forms: some field-level features accept dot-walked names; for example, the Email notification body can show ${caller_id.manager.email}.
  • Reports: group or filter by a dot-walked field.
  • Scripts: current.caller_id.manager.email (a GlideElement, so use .toString() or getDisplayValue() when you need text) or getRefRecord().

Each dot is a join in the database query. A couple of dots is fine; long chains on large lists slow things down.

JavaScript
// Read-only example (server-side script)
var gr = new GlideRecord('incident');
gr.addQuery('caller_id.department.name', 'Finance');   // dot-walk in a query
gr.query();
while (gr.next()) {
  gs.info(gr.number + ' ' + gr.caller_id.manager.getDisplayValue());
}
Python Dot-walking over linked records (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A reference points one way. The related list at the bottom of a form shows records from other tables that point back at this one. On a user form, the related list "Incidents" (as caller) is every incident whose caller_id is this user. Related lists come from existing reference fields, or from Relationships, where an administrator defines the query manually under System Definition > Relationships.

That gives you the three relationship shapes:

Shape How it is modeled Example
One-to-many Reference field on the "many" side Many incidents, one caller
Many-to-many A many-to-many definition (a third table with two references) Users and groups (sys_user_grmember)
Multi-value Glide List field Watch list of several users

Use a many-to-many table when each link has its own attributes or when you must query from either side efficiently. Use a Glide List only for short, simple lists, because it is stored as comma-separated ids and is harder to report on.

Good design with references

  • Prefer a reference to copying text. A reference stays correct when the user's name changes.
  • Always set a sensible reference qualifier so users cannot choose inactive or irrelevant records.
  • Choose the cascade rule deliberately: Restrict stops deleting a department that is still in use.
  • Keep dot-walks short in lists and reports.
  • Choose a clear display field on your own tables (the column with Display ticked) so lookups read well.
Python Many-to-many through a link table (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a reference field store?

    The value is the target record's sys_id, shown as its display value.
  2. 2. What does caller_id.manager.email mean?

    Each dot follows one reference to the next table.
  3. 3. How is a many-to-many relationship modeled?

    A third table holds one row per pair, as sys_user_grmember does for users and groups.
  4. 4. Why should you keep dot-walk chains short in lists and reports?

    Long chains add joins; keep them short on large tables.

Summary

  • Reference fields store a sys_id and model many-to-one links.
  • Qualifiers limit choices; cascade rules protect data when targets are deleted.
  • Dot-walking follows references in lists, filters, reports and scripts.
  • Related lists show the reverse direction; link tables model many-to-many.

Next: Dictionary and Schema Tools