Auto-Complete for Reference Fields

From ServiceNow Wiki
Home > Administer > Managing Data > Field Administration > Auto-Complete for Reference Fields
Jump to: navigation, search
Fields
Related Topics
Workflow Stage Fields
Get the Book
Knowledge.gif Field Administration

1 Overview

By default, a reference field auto-completes as the user types in the field. Administrators can configure additional auto-complete options. A user must have table-level read permission on the referenced table for autocomplete to display any options.

RefAutoComplete.png

2 Supporting Dictionary Attributes

These dictionary attributes are specific to reference fields and determine auto-complete behavior:

ref_auto_completer Specifies the name of the client-side JavaScript class that creates the drop-down auto completion choices. Valid class values include:
  • AJAXReferenceCompleter: Displays matching auto-complete choices as a drop-down choice-list. The list only displays the reference table's display value column. Reference fields automatically use this class if there is no other auto-completion class specified.
  • AJAXTableCompleter: Displays matching auto-complete choices as rows in a table. The table displays the reference table's display value column and any columns listed in the ref_ac_columns attribute.
  • AJAXReferenceChoice: Displays matching auto-complete choices as a drop-down choice-list. The list only displays the reference table's display value column. Furthermore, the list only displays up to 25 matching choices. If there are more than 25 auto-complete choices, the reference field instead displays the choices with the AJAXTableCompleter class.
ref_ac_columns Specifies the list of reference table columns to display. Separate column names with a semi-colon. For example, ref_ac_columns=user_name;email;sys_created_on allows auto-complete to match text from the user_name, email, and sys_created_on columns.
ref_ac_columns_search Enables auto-complete to match text in the columns listed in the ref_ac_columns attribute. Set this attribute to true to enable auto-complete to match text in all reference field columns. By default (or when this attribute is false) auto-complete only matches text in the display value column.
ref_ac_order_by Specifies the reference table column that sorts the auto-completion choices. For example, ref_ac_order_by=name sorts the auto-completion choices alphabetically by name.

Administrators can also set a user preference to use a contains auto-complete search.

3 UI Features

Set the ref_auto_completer=AJAXTableCompleter dictionary attribute to enable the following UI features.

  • Display the number of records the auto-complete query finds.
  • Highlight the entire selected row by changing the color of the background and text.
  • List a value for every column.
    • Display the first instance of a value in a column in black text.
    • Display subsequent duplicate values in grey text.

autocomplete_highlighting.png

4 Defining Auto-Complete Attributes for all References to a Table

A field inherits and uses the reference table's auto-complete attributes unless the field has its own value for the same attributes. A field-level attribute overrides a table-level attribute of the same name. If a field uses different reference attributes than those defined for the reference table, then the field uses both sets of attributes.

Use these steps to define auto-complete attributes for all fields in a table that do not already have their own auto-complete attributes. This example illustrates defining auto-complete attributes for all references to the User (sys_user) table.

Note
Note: A field's auto-complete attribute value supersedes a table's auto-complete attribute value. This means that any existing field-level value for an auto-complete attribute supersedes any value the administrator applies to the auto-complete attribute from the reference table.


  1. Navigate to a form of the target table, such as User Administration > Users.
  2. Right-click the form header and select the appropriate option for your version:
    • Fuji or later: Configure > Dictionary
    • Eureka or earlier: Personalize > Dictionary
  3. Select the row that does not list a column name. This row is typically the first row in the list. For example, select the first sys_user link.
    autocomplete_table_attributes.png
  4. In the Attributes field, enter a comma-separated list of auto-complete attributes you want to apply to all fields in the table. For example, to display the user's department with all references to the sys_user table, enter:
    ref_auto_completer=AJAXTableCompleter,ref_ac_columns=department,ref_ac_order_by=department
    
  5. Click Update.
  6. View the new auto-complete attributes. For example:
    1. Navigate to Incident > Open.
    2. Click the Number link for any incident.
    3. Enter a single character in the Assigned to field. The auto-complete options now include both the user name and department.
      autocomplete_table_attributes2.png

5 Removing the Display Value Column

You can remove the display value column from a reference field by setting the ref_ac_display_value attribute to false. This causes the reference field to remove the display value column and only display the columns listed in the ref_ac_columns attribute. This feature requires the use of the AJAXTableCompleter class and the ref_ac_columns, ref_ac_columns_search, and ref_ac_display_value attributes.

Note
Note: Auto-complete cannot match text from additional columns when the reference field is a product of the ui_reference UI macro. This means any auto-complete against a selector, such as the Impersonate User list, can only match text against the display value.


This example illustrates removing the display value column from references to the User (sys_user) table and replacing it with references to the first_name and last_name columns.

  1. Navigate to a form of the target table, such as User Administration > Users.
  2. Right-click the form header and select the appropriate option for your version:
    • Fuji or later: Configure > Dictionary
    • Eureka or earlier: Personalize > Dictionary
  3. Select the row that does not list a column name. This row is typically the first row in the list. For example, select the first sys_user link.
    autocomplete_table_attributes.png
  4. In the Attributes field, add the ref_auto_completer, ref_ac_columns, ref_ac_columns_search, and ref_ac_display_value attributes. For example, to hide the display value column and only display the user's first and last names enter:
    ref_auto_completer=AJAXTableCompleter,ref_ac_columns=first_name;last_name,ref_ac_columns_search=true,ref_ac_display_value=false
    
  5. Click Update.
  6. View the new autocomplete attributes. For example:
    1. Navigate to Incident > Open.
    2. Click the Number link for any incident.
    3. Enter a single character in the Assigned to field. The auto-complete options now hide the display value column (user_name) and only display the first_name and last_name columns.
      autocomplete_no_display_value.png

6 Improving Auto-Complete Queries

By default, all reference fields use a starts with query to search for matching text in the reference table. This prevents auto-complete from executing inefficient contains queries every time a user searches a reference field. You can require all reference fields to use a starts with query by setting the glide.ui.ref_ac.startswith system property.

Note
Note: Setting the glide.ui.ref_ac.startswith system property to true overrides any existing "autocomplete.contains" settings in both user and system level preferences. This property changes the autocomplete query method for all users regardless of preferences.


This example illustrates changing all reference field queries from a "contains" query to a "starts with" query.

  1. View the current contains query results.
    1. Navigate to Incident > Open.
    2. Click the Number link for any incident.
    3. Enter a single character in the Assigned to field. Auto-complete matches any record that contains the search string.
      autocomplete_contains.png
  2. In the navigation filter, enter sys_properties.list.
  3. In the Go to Name search, enter glide.ui.ref_ac.startswith.
  4. Click the Name link for the glide.ui.ref_ac.startswith property.
  5. In the Value field, replace false with true.
  6. Click Update.
  7. View the new starts with query results. For example:
    1. Navigate to Incident > Open.
    2. Click the Number link for any incident.
    3. Enter a single character in the Assigned to field. Auto-complete only matches records that starts with the search string.
      autocomplete_startswith.png

7 Configuring Auto-Complete to Match Text From the Display Value Only

By default, auto-complete only matches text in the display value column. Administrators can configure a reference field to display additional columns of information that auto-complete ignores when searching for matching text.

  1. Right-click on the label of a reference field.
  2. Select Configure Dictionary (Personalize Dictionary in versions prior to Fuji).
  3. In the Dictionary record for the field, add the desired auto-completion attributes. For example, these attributes add the department field to the caller list and sort callers by their department:
    ref_auto_completer=AJAXTableCompleter,ref_ac_columns=department,ref_ac_order_by=department
    
    Additional_user_attributes.png
  4. Update the record.


To get a Configuration Item field to display the CI class names from auto-complete choices, use these attributes:

ref_auto_completer=AJAXTableCompleter,ref_ac_columns=sys_class_name,ref_ac_order_by=sys_class_name,ref_contributions=task_show_ci_map;ci_show_incidents
Note
Note: The ref_contributions attribute controls the icons that appear next to the reference field.


Additional_ci_attributes.png

8 Configuring Auto-Complete to Match Text From Any Reference Field

Administrators can configure a reference field to match text from any additional column the reference field displays. Administrators can add the ref_ac_columns_search attribute to enable auto-complete to match text in any column listed in the ref_ac_columns attribute. Set the ref_ac_columns_search attribute to true to match text from all reference field columns. By default (or when this attribute is false) auto-complete only matches text in the display value column.

  1. Right-click on the label of a reference field.
  2. Select Configure Dictionary (Personalize Dictionary in versions prior to Fuji).
  3. In the Dictionary record for the field, add the desired auto-completion attributes. For example, these attributes add the department field to the caller list and sort callers by their department:
    ref_auto_completer=AJAXTableCompleter,ref_ac_columns=department,ref_ac_order_by=department,ref_ac_columns_search=true
    Auto-Complete Attribute.png
  4. Update the record.

9 Displaying the Reference Field as a Choice List

  1. Navigate to the dictionary entry for the reference field.
  2. Change the field Choice to be either:
    • Dropdown with --None--
    • Dropdown without --None--
  3. Add the attribute ref_auto_completer=AJAXReferenceChoice to the list of attributes.
  4. Save.
Note
Note:
  • When a reference field is displayed as a choice list, the maximum number of choices is limited by the glide.ui.max_ref_dropdown property value (default value is 25). Administrators can modify this property, but should test any modifications for performance and usability impact.
  • Administrators can also override the property value for a specific field by adding the max_ref_dropdown attribute to the field's dictionary entry.
  • If a reference qualifier returns more choices than the limit for the field, then the field is displayed as a reference field, not a choice list.


Referencechoice.png

10 Contains Auto-Complete Search

By default, the reference auto-complete uses a starts with search. A user preference can be created to implement a contains search.

To use the contains search:

  1. Disable the glide.ui.ref_ac.startswith system property . See Improving Auto-Complete Queries.
  2. Navigate to User Administration > User Preferences.
  3. Select the preference "'<referenced table>.autocomplete.contains"'.
  4. Set the value field to true.
  5. Log out and log back in to immediately display the updated search.

AutocompleteContains1.png

Note
Note: Setting the glide.ui.ref_ac.startswith system property to true overrides any existing "autocomplete.contains" settings in both user and system level preferences. This property changes the autocomplete query method for all users regardless of preferences.
Was this article helpful?
Yes, I found what I needed
No, I need more assistance