Dot-walking provides access to fields of 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 by 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 the 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. Click on this arrow to be referenced to the field related to this form. The reference path will be displayed in the breadcrumbs.
Please keep in mind the dot-walking limitations for fields of the List type:
- For conditions in Condition Builder, the limit is one-level-depth.
- You cannot use dot-walking to add fields of the List type to the list and form views.
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.
For example, the script below will return the email of the person responsible for the 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 the 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
An example of a business case:
The administrator works with Task records. At some point, it is necessary to get information about a specific task caller (who is, technically, should be an object of the User table). After getting the information, the administrator realizes that the caller is an object of the Employee table, which is a child of the User table and has an extended field set.
The administrator needs to get the manager's phone of this employee. This information exists in the Employee table record of this user, but is not mentioned in the User table. To get the phone number, a script can be used. The script will implement the attributes of the calling record in the 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, the current object is the object of the Task table.
The Caller field relates to the User table, therefore, only fields of this table are available directly.
So, to get the values of the attributes existing only in the child tables, you need to reload the record within the necessary table context. To do this, add '$$' symbols before the attribute name you are calling.
When you do this, the record reloads within the necessary table context, and all fields related to this table become available.
When calling a non-existing attribute this way, the script returns 'null'.
When applying this script to a record where the caller is not the object of the Employee table, the script returns 'null' to all requests.
