Reference Fields

From ServiceNow Wiki
Jump to: navigation, search
Note
Note: This article applies to Fuji and earlier releases. For more current information, see Reference Field Type at http://docs.servicenow.com

The ServiceNow Wiki is no longer being updated. Visit http://docs.servicenow.com for the latest product documentation.


Fields
Related Topics
Workflow Stage Fields
Get the Book
Knowledge.gif Field Administration

1 Overview

A reference field stores a reference to a field on another table. For example, the Caller field on the Incident table is a reference to the User [sys_user] table. When a reference field is defined, a relationship between the two tables is created. Adding a reference field to a form makes the other fields in the referenced table available to the form.

Administrators can create new reference fields and configure several options for reference fields, including the display value, auto-complete behavior, reference qualifiers, and cascade delete rules.

Note
Note: Reference fields can only refer to records from one other table. To add a field that can refer to records on any table, see Document id Element Type.


2 Adding a Reference Field

Add reference fields to a table by using the same method as any other field. The related table also appears in the Available Tables list for future form customizations.

3 Display Values

Reference fields store a Sys ID, for each referenced record in the database, but the Sys ID is not shown. The reference field shows the display value. For example, an incident's Assigned to field stores the Sys ID of a particular user, but actually displays the user 's name. The following example shows how Charlie Witherspoon, which is the display value of a user record, is shown in the Assigned to field.

The reference field shows the display value, while the Sys ID is in the database

Reference Field Value Stored in Database Display Value Field of Source Table Value Displayed in UI
Assigned to [task.assigned_to] 46b87022a9fe198101a78787e40d7547 Name [sys_user.name] Charlie Whitherspoon

Reference fields show display values in:

3.1 Selecting the Display Value

Only one field can be defined as the display value for a table. When you set the Display value to true, a business rule sets the Display value to false for all other fields on the table. In previous versions, you must manually ensure that no other fields on the table have a value of true in the Display column.

Note
Note: Extended tables inherit the display value of the parent table. Setting a separate display value for the extended table overrides the parent table's display value.


To choose a field as a display value for the table:

  1. Navigate to System Definition > Dictionary.
  2. Filter on Table is <name of the referenced table>.
  3. Locate the desired field and set Display to true.
    For best results, choose a field that is required and unique in each record as the display value field.
Setting the disply value

Note
Note: If you make a field the display field for a table, be sure to translate all values for the field in the Translated Text [sys_translated_text] table into all the languages provided. Display field options left untranslated are not presented by the autocomplete (type ahead) feature.


Reference fields look for the display value in the following order:

  1. A field with display=true in the system dictionary on the lowest sub-table for extended tables.
  2. A field with display=true in the system dictionary on the parent table.
  3. A field named name or u_name.
  4. The Created on field of the referenced record (starting with the Eureka release.)

4 Decorations

Reference decorations are icons which appear next to the reference field. The reference lookup is always visible and is used to select a record to reference. Other reference decorations appear when a record is selected.

4.1 Reference Lookup

Clicking the reference lookup icon (Search icon Heisenberg.png in UI15) displays a list of records on the referenced table in a pop-up window. Customize the columns that appear in this table by personalizing the list.

UI15 reference lookup list

UI11 reference lookup list

4.1.1 Tree Picker Lookup

The reference lookup can be rendered in the tree picker format by modifying the dictionary and adding the attribute tree_picker. You cannot customize the label names used in the tree picker. The label names are taken from the values in the table.

4.2 Reference Icon

When a record is referenced, pointing to the reference icon (Icon-referenceUI15.png in UI15, Icon-reference.png in previous UIs) displays information about the referenced record.

Using the reference icon

Clicking the reference icon updates the current form and navigates to the referenced record. For more information, see Customizing the Reference Icon.

4.3 Related Incidents Icon

The Show Related Incidents icon (Icon-relatedincidentsUI15.png in UI15, Tasks.png in previous UIs) displays other incidents related to the referenced record. Administrators can add this icon to any reference field by modifying the dictionary and adding the ref_contributions=user_show_incidents dictionary attribute. The icon appears only for users who have read or write access to this field.

Note
Note: The icon's behavior is defined by a UI Macro named user_show_incidents. If this UI Macro is not active in your instance, this reference field decoration will not be displayed.


4.4 Show Workflow Icon

If the reference field refers to the Workflow [wf_workflow] table, the show workflow icon ( Icon-relatedincidentsUI15.png in UI15, ShowWorkflow.gif in other UIs ) can be used to open the workflow in the workflow editor, rather than in a form. To add the show workflow icon, modify the dictionary to add the attribute ref_contributions=show_workflow.

5 Reference Styles

Reference styles are specialized field styles that control the appearance of reference fields. For more information, see Defining Reference Styles.

6 Reference Qualifiers

Reference qualifiers restrict the records that are available for reference fields. For more information, see Reference Qualifiers.

7 Cascade Delete Rules

When a record is deleted, there are different options for how the deletion will affect records that reference the deleted record. For example, if you delete a user record that is referenced in the Caller ID field on several incident records, you can configure what happens to those incident records. By default, the references are cleared, so the incident records are maintained with an empty Caller ID field.

To configure what happens to records that reference a record when that record is deleted (starting with the Eureka release):

  1. Navigate to a reference field on a form.
  2. Right-click the field label and select Configure Dictionary (Personalize Dictionary in versions prior to Fuji).
  3. Under Related Links, click Advanced view.
  4. Locate the Reference Specification section.
  5. In the Reference cascade rule field, select one of the following options:
    • Clear or -- None --: deleting a record clears references (default option).
    • Delete or Cascade: deleting a record also deletes all referencing records. For example, when a user record is deleted, any incidents assigned to the user are also deleted. Use this method with caution.
    • Restrict: deleting a record is restricted unless there are no references to the record. For example, prevent the user record from being deleted if any incident includes a reference to the user. This option has no effect for tables with m2m relationships.
    • None: deleting a record does not change records that reference the record.
  6. Click Update.

In versions prior to the Eureka release, personalize the dictionary for the field and enter one of the following values in the Reference cascade rule field:

  • clear: deleting a record clears references (default option).
  • delete: deleting a record also deletes all referencing records.
  • restrict: deleting a record is restricted unless there are no references to the record.
A reference cascade rule

8 Auto-Complete

By default, a reference field auto-completes as the user types in the field. To configure auto-complete options, see Auto-Complete for Reference Fields.

The auto-complete feature

9 Defining the Reference Key

By default, reference fields store the sys_id of the record in the database. By defining a reference key, you can identify a field other than sys_id to use as the unique identifier for the reference field. The value of the reference key field, instead of the sys_id, is stored in the database for that reference field.

  1. Navigate to System Definition > Dictionary.
  2. Open the field record (for example, resolved_by" on the Incident table).
  3. In the Reference key field, enter a field name on the referenced table (for example, email on the sys_user table).
    Note: Always choose a field from the referenced table that is both required and unique.
  4. Click Update.
A reference key

10 Enabling Dynamic Creation

By default, a user must enter a value in a reference field that matches an existing record in the table it refers to. For example, the Caller field in an Incident cannot have a value that isn't an existing user. When dynamic creation is enabled, entering a nonexistent value creates a new record on the referenced table, instead of returning an error.

To enable dynamic creation:

  1. Right-click the field label in the form and select Configure Dictionary (Personalize Dictionary in versions prior to Fuji).
  2. Populate the following fields (you may need to configure the Dictionary form):
    • dynamic_creation: select the check box.
    • dynamic_creation_script: enter a script to dynamically create the record.
  3. Click Update.
    If a user enters a value that does not match an existing record in the referenced table, the line beneath the text appears green, instead of red. When the user points to the field, the tool tip indicates that a new record will be created in the referenced table.

For example, you can use the following simple dynamic_creation_script to create a record on the referenced table.

current.name = value;
current.insert();

For another example, you can create a script include named MyUserReferenceCreator with the following contents:

var MyUserReferenceCreator = Class.create();
MyUserReferenceCreator.prototype = {
    initialize: function() {
    },

    create: function(current, value) {
        current.name=value;
        return current.insert();
    },

    type: 'MyUserReferenceCreator'
}

When the script include is created, the following dynamic_creation_script generates a new location for an invalid reference field value.

new MyUserReferenceCreator().create(current, value);

11 Recent Selections

Reference fields store a list of each user's recent selections to allow users to quickly select past values when filling in a reference field. By default, the system stores up to 15 selections from a reference field for each user in the Recent Selection [sys_ui_recent_selection] table. Users can see the recent selections list by selecting an empty reference field.

Note
Note: The system does not store recent selections for service catalog reference variables.


Recent selections in a reference field

The system uses autocomplete to filter the list of recent selections to match values the user enters.

Recent selections filtered by autocomplete

The system adds a Recent Selection record whenever a user inserts or updates a reference field value. Administrators can control the number of recent selections the system displays with the glide.xmlhttp.max_choices system property. Setting the property to zero disables recent selections.

Note
Note: This system property also controls how many entries the system displays in choice lists.
Was this article helpful?
Yes, I found what I needed
No, I need more assistance