Dot-Walking

From ServiceNow Wiki
Jump to: navigation, search
Navigation and User Interface
Related Topics

1 Overview

Dot-walking provides access to fields on related tables from a form, list, or script. If the current table contains a reference to another table, any field on the referenced table can be accessed using dot-walking.

Dot-walking references a field by building a chain of field names separated by dots (periods). For instance, incident.assigned_to.company references the company of the user assigned to an incident. The recommended limit for chain length is three levels.

2 Video Tutorial

The following video tutorial demonstrates how to use dot-walking and database views to include data from related tables in reports. Also shows how to apply dynamic filters to run a set query against a reference field without entering JavaScript code in the condition builder. Applies to ServiceNow instances starting with the Fuji release.

Reporting: How to Access Related Tables

3 Dot-walking in Field Drop-Downs

Users can dot-walk to related fields in a drop-down list, such as the field list in a filter.

This example demonstrates how to filter the incident table by the company of the caller who registered the incident.

First, open the choice list of fields to filter by. This presents a list of the fields which are present on the Incident table. Reference fields are followed by related fields, which are presented in blue. For instance: Caller is followed by Caller > User fields. This means that Caller is a reference field, and the related fields are User fields on the Caller record. If the blue related fields are not present in the list, select Show Related Fields in blue at the bottom of the list:

Dotwalking5.png

When the related fields are present, select a set of related fields.

Dotwalking1.png

After the related field is selected, the menu reloads with the related table's fields.

Dotwalking2.png

Now, it is possible to select a field from the Caller record.

Dotwalking3.png

The new field is: caller.company

When looking at the list, it is easy to see where in the dot-walk the user currently is. Each selected reference is stored at the top, and the number of dots in front indicate how many dots from the initial record the user has reached.

Dotwalking4.png

In this picture, the user is currently at incident.caller.company. It is possible to return to higher levels in the hierarchy by selecting the blue records. For instance, selecting Incident fields returns to the list of incident fields.

The related fields can be dismissed by selecting Remove Related Fields in blue at the bottom of the list:

Dotwalking6.png

4 Dot-walking in List Collectors

When selecting a list of fields from a list collector (for instance, when configuring a form), it is also possible to dot-walk to fields from other forms.

To see which fields are reference fields (and thus can be dot-walked), look for green fields with the plus symbol beside them.

Dotwalking7.png

Once a reference field is highlighted, the Expand icon appears above the Add icon.

Dotwalking8.png

Selecting the Expand icon opens the list of fields from the related list in the Available pane. In this picture, the user has opened the Assigned to fields. Like before, the previous lists of fields appear at the top of the list in blue.

Dotwalking9.png

Once the field is added to the "Selected" pane, it appears with its full dot-walked syntax. In the next picture, the user has selected Assigned_to.active. Dotwalking10.png

5 Dot-walking in Variables

Variables can often be added into templates, notifications, or other forms where a value is being called from the form. For instance, the following is the variable for Assigned to:

  • ${assigned_to}

As above, it is possible to dot-walk to fields on any reference field's original record. In the case above, it is possible to dot-walk to any field on the assigned_to record, for instance:

  • ${assigned_to.manager}

As is always the case with dot-walking, this can be a longer chain if desired:

  • ${assigned_to.department.manager.mobile_phone}

Sometimes this variable can be selected from a Tree Picker.

6 Dot-Walking in a Tree Picker

The Tree Picker interface presents an expandable, hierarchical view that may be used when selecting fields (Picker.png).

For example, this Users glide list field has a select fields icon:

TPDT1.png

Clicking this icon presents a list of fields available on the current record:

TPDT2.png

Reference fields have + icons next to their name. Clicking on the + expands a list of the fields on that referenced field. In this example, expanding the Assigned To field shows the User fields for that record:

TPDT3.png

Selecting the Manager field adds the variable ${assigned_to.manager}:

TPDT4.png


7 Dot-walking in Script

Just as above for field variables, it is possible to dot-walk within a script simply by invoking the dot-walk syntax. This functionality requires a knowledge of JavaScript.

For scripts which run on the server side (such as Business Rules), however, it is necessary to add current.

The following script, for instance, is a scripted approval rule that requests an approval from the manager of the user who opened the ticket:

try {
    current.opened_by.manager;
} catch (err) {
}

For scripts which run on the client side (such as Client Scripts), current is not necessary. For instance, the Highlight VIP Caller script runs on the client side:

function onChange(control, oldValue, newValue, isLoading) {

    //wait until there is a valid record in the field
    if (newValue) {

      //get the caller object so we can access fields
      var caller = g_form.getReference('caller_id');

      var callerLabel = document.getElementById('label.incident.caller_id');
      var callerField = document.getElementById('sys_display.incident.caller_id')

      //check for VIP status
      if (caller.vip=='true') {

        //change the caller label to red background
        //style object is CSSStyleDeclaration, style names are not standard css names
        if (callerLabel)
           document.getElementById('label.incident.caller_id').style.backgroundColor='red';

        //change the caller's name field to red text
        if (callerField)
           document.getElementById('sys_display.incident.caller_id').style.color='red';
      }
      else {
    //not a VIP, remove temporary styles
        if (callerLabel)
           document.getElementById('label.incident.caller_id').style.backgroundColor='';
        if (callerField)
           document.getElementById('sys_display.incident.caller_id').style.color='';
      }
    }
}

8 Access Control Requirements

Dot-walking requires read access to the target table and field. Administrators should verify that the intended users have access to the target field, such as by impersonating an intended user and verifying that the user can access the field. If the user cannot access the field, an administrator can add a record access control rule to grant the user read access.

Was this article helpful?
Yes, I found what I needed
No, I need more assistance