Dot-walking

Dot-walking provides access to fields on related tables from a form, list, or script.

The table may contain references to the other tables and the fields in these tables can be accessed using dot-walking.

Dot-walking builds a chain of field names separated by dots (periods). For example, incident.assigned_user.company references to the company of the user assigned to an incident.

Dot-walking in a choice list field

You can use dot-walking in the Condition Builder. To understand which fields are reference fields and are available for dot-walking, look for the fields marked bold and arrow right. Clicking on this arrow, you'll be referenced to the field related to this form. The reference path will be displayed in the breadcrumbs.

Dot-walking in layouts

When selecting a list of fields (for example, when you are configuring a form or a list), you can also dot-walk to fields from other forms. To understand which fields are reference fields and are available for dot-walking, look for the fields marked bold and arrow down.

Dot-walking in scripts

You can use this feature in your scripts by invoking the appropriate syntax.

The example script below will return an email of a person responsible for current assignment group:

const current = new SimpleRecord('itsm_incident');
current.get('158557395619812771');
ss.info(current.assignment_group.responsible.email);
// Info: john.doe@example.com

To speed up the script execution, use the getValue(property) method to get values of the fields of the Reference type instead of using dot-Walking.

As an example, it is preferable to use the current.getValue('reference_field') structure instead of current.reference_field.sys_id one.

Context processing

To move further this topic, we need to consider a business case first.

An administrator works with Task records. At some point, it becomes necessary to get information about any specific task caller (who is, technically, should be an object of the User table). After getting this information, the administrator realizes that a caller is an object of the Employee table which is a child of the User table and has an extended fieldset.

Considering this, an administrator needs to get the manager's phone of this employee. This information exists in the Employee table record for this user but is missing in the User table. For this, a script can be used to implement calling record attributes within a current element context.

const current = new SimpleRecord('task');
current.get('161157603117108419'); // a task record where a caller is an Employee object.
ss.info( "VIP: " + current.caller.$$vip) // Info: VIP: true
ss.info( "Non-existing attribute: " + current.caller.$$NonExisting) // Info: Non-existing attribute: null
if (!!current.caller.$$manager) {
  ss.info("Manager: " + current.caller.manager.getDisplayValue()) // Info: Manager: John Doe
}

In this example, a current object is an object of the Task table.

A caller field relates to the User table, therefore, only fields of this table are available directly.

So, to get values of attributes existing only in child tables we need to reload a record within a necessary table context. For this, '$$' symbols before the attribute name you are calling should be added.

When we doing this, a record reloads within a necessary table context, and all fields related to this table become available.