---
sourceDocument: Xanadu ServiceNow AI Platform Administration
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/platform-administration
Release :
- xanadu
ft:locale :
- en-US
ft:publication_title :
- Xanadu ServiceNow AI Platform Administration
ft:clusterId :
- platadm
bundleId :
- platadm
workflow :
- Platform
---
# Auto-complete for reference fields
# Auto-complete for reference fields {#ariaid-title1}
* Release version: Xanadu
*
* Updated August 1, 2024
*
*  7 minutes to read
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 auto-complete to display any options. Figure 1. Auto complete
## Dictionary attributes for auto-completion of reference fields {#c_AutoCompleteForReferenceFields__section_ckv_yxt_w1b}
There are dictionary attributes that are specific to reference fields and that determine
auto-complete behavior.
{#c_AutoCompleteForReferenceFields__table_r5y_s13_rt__entry__2}
| Attribute | Description |
|-|-|
| 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. {#c_AutoCompleteForReferenceFields__ul_nqh_zyl_44} |
| 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_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. |
[Table 1. Reference field auto-completion dictionary attributes]
{#c_AutoCompleteForReferenceFields__table_r5y_s13_rt}
## Auto-complete UI features {#c_AutoCompleteForReferenceFields__section_qwm_byt_w1b}
The AJAX table completer class has a number of UI improvements.
* The table completer always displays the number of records the auto-complete query finds.
* The table completer highlights the entire selected row by changing the color of the background and text.
* The table completer lists a value for every column.
* The first time a value appears in a column, the table completer displays it in black text.
* The table completer displays subsequent duplicate values in grey text. Previously, the table completer displayed an empty cell in a column containing a duplicate value.
{#c_AutoCompleteForReferenceFields__ul_xqv_d1m_44}
{#c_AutoCompleteForReferenceFields__ul_and_11m_44} Figure 2. Selected row highlight
Set the ref_auto_completer=AJAXTableCompleter dictionary attribute to
use these improvements.
## Define auto-complete attributes for all references to a table {#ariaid-title2}
A field inherits and uses the reference table's auto-complete attributes unless the
field has its own value for the same attributes. You can define the attributes for
references to a table, and it affects every form that references that table.
### Before you begin
Role required: personalize_dictionary
### About this task
A field-level attribute overrides a table-level attribute of the same name. If a
field uses different reference attributes from those that are 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 describes how to define auto-complete attributes for all references to the User \[sys_user\] table.
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.
### Procedure
1. Navigate to a list of the target table, such as AllUser AdministrationUsers.
2. Perform the appropriate action for your list version.
| Version | Action |
| List v2 | Right-click the column header and click ConfigureDictionary. |
| List v3 | Open the list title menu and click Configure, and then click Dictionary. |
|-|-|
{#t_DefAutoComplAttribsAllRefsToATbl__choicetable_vrh_trd_sv}
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.
4. Under Related Links, click Advanced view.
5. 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
6. Click Update.
### What to do next
To test the new auto-complete attributes, open a form that references the User \[sys_user\] table, such as an open incident. Enter a single character in the Assigned to field. The auto-complete options now include both the user name and department.
## Remove the display value column {#ariaid-title3}
You can remove the display value column from a reference field by setting the
ref_ac_display_value attribute to false.
### Before you begin
Role required: personalize_dictionary
### About this task
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:
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 action against a selector, such as the Impersonate User list, can only match text against the display value.
This example describes how to remove the display value column from references to the
User \[sys_user\] table and replace it with references to the first_name and last_name
columns.
### Procedure
1. Navigate to a list of the target table, such as AllUser AdministrationUsers.
2. Perform the appropriate action for your list version.
| Version | Action |
| List v2 | Right-click the column header and click ConfigureDictionary. |
| List v3 | Open the list title menu and click Configure, and then click Dictionary. |
|-|-|
{#t_RemoveTheDisplayValueColumn__choicetable_vrh_trd_sv}
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.
4. Under Related Links, click Advanced view.
5. 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 the following.
ref_auto_completer=AJAXTableCompleter,ref_ac_columns=first_name;last_name,ref_ac_columns_search=true,ref_ac_display_value=false
6. Click Update.
### What to do next
To test the new auto-complete attributes, open a form that references the User \[sys_user\] table, such as an open incident. 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.
## Improve auto-complete queries {#ariaid-title4}
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.
### Before you begin
Role required: admin
### About this task
The following example illustrates a contains query. Note that the letter "d" appears anywhere in the user's first or last name.
This procedure describes how to change the
glide.ui.ref_ac.startswith system property to always use a
starts with query.
### Procedure
1. In the navigation filter, enter sys_properties.list and press the Enter key.
2. Select the glide.ui.ref_ac.startswith property.
To search for the property, enter *startswith in the Go to search filter for the Name column.
3. In the Value field, replace false with true.
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.
4. Click Update.
5. Test the change by opening a record with a reference field and entering a character in it, as illustrated in the example below.
{#t_ImproveAutoCompleteQueries__steps_vsx_wtx_rt}
## Configure auto-complete to match text from any reference field {#ariaid-title5}
By default, auto-complete only matches text in the display value column. You can
configure a reference field to match text from any additional column the reference field
displays.
### Before you begin
Role required: personalize_dictionary
### About this task
You 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.
### Procedure
1. Right-click the label of a reference field.
2. Select Configure Dictionary from the choice list.
3. Under Related Links, click Advanced view.
4. In the Attributes 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
Figure 3. Auto-complete attribute
5. Click Update.
### Example
The following example describes how to set the Configuration Item field display the CI class names from auto-complete choices for the Configuration item \[cmdb_ci\] table.
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:
The ref_contributions attribute controls the icons that appear next to the reference field.
## Enable contains auto-complete searches {#ariaid-title6}
By default, the reference auto-complete uses a starts with search. A
user preference can be created to implement a contains search.
### Before you begin
Role required: admin
### Procedure
1. Disable the glide.ui.ref_ac.startswith system property.
For more information, see [Improve auto-complete queries](https://servicenow-prod.fluidtopics.net/gpfxsNyiqgguxeEs2lCCqQ#t_ImproveAutoCompleteQueries "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.").
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 auto-complete query method for all users regardless of preferences.
2. Navigate to User AdministrationUser Preferences.
3. Select the preference "'\.autocomplete.contains"'.
4. Set the value field to true.
5. Click Update.
{#t_ContainsAutoCompleteSearch__steps_ihx_2lm_44}
### What to do next
Log out and log back in to display the updated search.
## Wildcards in reference auto-completes {#ariaid-title7}
Wildcard searches use the auto-complete functionality.
Use an asterisk in the reference field for wildcard searches.
Figure 4. One asterisk wildcard search ![]()
If two asterisks are entered, a list of available records display in the auto-complete
suggestions.
Figure 5. Two asterisk wildcard search
**Related concepts**
* [Wildcard characters allow searching for patterns and variations](https://servicenow-prod.fluidtopics.net/JeHZpFfVkIA37py0kFABDQ "Expand search results to match any non-space character. Zing supports both single-character and multiple-character wildcards.")
*[\>]: and then