Reference Qualifiers

Reference Qualifiers
Overview
Use reference qualifiers to restrict the data that is selectable for a reference field. For example, if you want records
with the San Diego location name to be referenced by another record, you can create a reference qualifier on the
Location field of the record. The qualifier specifies that the user can choose only location records with the City field
set to San Diego for the Location field.

Types of Reference Qualifiers

These types of reference qualifiers are available:
Simple qualifiers provide choice lists for you to specify a reference qualifier condition on the table where the
reference field is located (starting with the Eureka Release).
Dynamic qualifiers allow you to use a dynamic filter to run a query against a reference field without having to
enter JavaScript code or query strings (starting with the Eureka Release).
Advanced qualifiers provide a text field for you to create either of the following:
A static encoded query string, which is a single string that specifies a database query, such as active=true.
JavaScript code, which references script includes or functions in global business rules.
Prior to the Eureka release, only advanced reference qualifiers were available.
Note: If you are trying to define a reference qualifier on an extended table differently from the reference qualifier on the parent
table, see Dictionary Overrides instead.

Configuring Reference Qualifiers

System administrators can configure reference qualifiers through the system dictionary. The Dictionary Entry form
provides both a Default view and an Advanced view (starting with the Eureka release).
1. Navigate to the reference field on the form you want to edit.
2. Right-click the form label and select Personalize Dictionary.

3.
4.
5.
6.

The Dictionary Entry form opens. The simple reference qualifier is available on both the Default view and the
Advanced view. The dynamic and advanced reference qualifiers are available only in the Advanced view.
To change views, select Default view or Advanced view under Related Links.
In the Reference Specification section, verify that the table already present in the Reference field is the correct
one, or select another table if necessary.
Select the type of qualifier in the Use reference qualifier choice list.
Configure the qualifier:

Simple: Build the condition using the choice lists.

Dynamic: Select a dynamic filter option.
Advanced: Enter the encoded query string or the JavaScript that returns a query string in the Reference qual
field.
7. In the Reference Specification - Additional Customization section, configure these options if necessary:
Reference key: allows you to identify a field other than sys_ID to use as the unique identifier for the reference
field.

Reference Qualifiers

Reference cascade rule: allows you to define what happens to a record if the record it references is deleted.
Reference floats: enables the Edit button on related lists for one-to-many relationships
Dynamic creation: lets you determine if the system should create a new record when a value for the reference
field does not match an existing record. If you select this option, enter a script in the Dynamic creation script
field that specifies how to create the record.
8. Click Update.

Example Reference Qualifiers

The following examples show each type of reference qualifier.

Simple Reference Qualifier Example

Use simple reference qualifiers when you want to limit the values for a reference field based on other values in the
referenced table or or related tables.
The base system provides several simple reference qualifiers by default. An example is the reference qualifier on the
Vendor field on asset forms, such as the Hardware form. The qualifier restricts the companies you can select for this
field to only those companies with the Vendor field set to true.

Dynamic Reference
Qualifier Example

A simple reference qualifier

Use dynamic reference qualifiers when

you want to limit the values for a
reference field based on a dynamic
filter option that uses a scripted filter.
The advantage of using a dynamic
reference qualifier is that you can
create one dynamic filter option and in

as many dynamic reference qualifiers as needed.

The base system provides several dynamic filter options by default. An example is the dynamic filter option for the
reference qualifier on the Model ID field. This field appears on a configuration item form, such as the default
Computer form. The reference qualifier calls the CI Model Qualifier dynamic filter option, which in turn calls the
ModelAndCategoryFilters script include. This script include refines the reference qualifier based on the class
of the CI so that the only options for the model ID are those that belong to the same class as the current CI. For
example, only CIs that belong to the Computer class are available in the Model ID field on a Computer
configuration item form.

Advanced Reference
Qualifier Example
Use advanced reference qualifiers if
you want to enter an encoded query
string or make a JavaScript call to a
script include that returns a query
A dynamic reference qualifier

Reference Qualifiers

string. To create advanced reference qualifiers, enter the query string or JavaScript code in the Reference qual field
on the Dictionary Entry form.
Note: As a good practice, make JavaScript calls to functions in a script include instead of a global business rule. See Business Rules
Best Practices for more information.

Encoded Query Strings

An example of an encoded query string is vendor=true, which returns all companies that are designated as
vendors. Entering this string is the same as using the condition builder as shown in the example for the simple
reference qualifier.

JavaScript Calls
An example of a JavaScript call is the
following code:

An advanced reference qualifier with an encoded query string

javascript:new myScriptInclude().my_refqual()
This code calls a function named my_refqual() in a script include named myScriptInclude(). The
function must return a query string that can filter the options available on a reference field.
JavaScript Example: Limiting the Assigned to Field by Users with a Specified Role
This example shows how to restrict an incident's Assigned to choices to only the users with the itil_admin role. You
could also change itil_admin to any other role on a refernece field that refers to the User table.
1.
2.
3.
4.
5.

Open an incident.
Right-click the Assigned to field and select Personalize Dictionary.
In the Reference qual field, enter javascript:"sys_idIN"+getRoledUsers("itil_admin").join(",").
Save the record.
To see the base-system business rule that this JavaScript code calls, navigate to System Definitions > Business
rules.
6. Open getRoledUsers.
7. The business rule uses the following JavaScript code:
// Return an array of sys_ids of the users that have at least one role
// optional parameters allow the exclusion (NOT IN) of some roles or
// look for specific roles (IN)
//
// optional: queryCondition - 'IN' or 'NOT IN'
// optional: roleList - a comma separated list of role names
//
function getRoledUsers(queryCondition, roleList) {
var roleListIds;

Reference Qualifiers
if (queryCondition && roleList) {
roleListIds = getRoleListIds(roleList);
}
var users = {};
var gr = new GlideRecord('sys_user_has_role');
if (roleListIds) {
gr.addQuery('role', queryCondition, roleListIds);
}
gr.query();
while (gr.next()) {
users[gr.user.toString()] = true;
}
var ids = [];
for (var id in users)
ids.push(id);
return ids;
}
// get sys_id's for the named roles
function getRoleListIds(roleList) {
var ids = [];
var gr = new GlideRecord('sys_user_role');
gr.addQuery('name','IN',roleList);
gr.query();
while (gr.next()) {
ids.push(gr.sys_id.toString());
}
return ids;
}
JavaScript Example: Constraining the Assignment Group Field
This example shows how to restrict an incident's Assignment group choices to only the groups that contain the user
already specified in the Assigned to field.
1.
2.
3.
4.
5.
6.
7.

Open an incident.
Right-click the Assignment group field and select Personalize Dictionary.
Enter javascript:new BackfillAssignmentGroup().BackfillAssignmentGroup() in the Reference qual field.
Save the record.
Navigate to System Definitions > Script Includes.
Click New.
Create a script include with the following JavaScript code:

var BackfillAssignmentGroup = Class.create();

BackfillAssignmentGroup.prototype = {
initialize: function() {
},

Reference Qualifiers

BackfillAssignmentGroup:function() {
var gp = ' ';
var a = current.assigned_to;
//return everything if the assigned_to value is empty
if(!a)
return;
//sys_user_grmember has the user to group relationship
var grp = new GlideRecord('sys_user_grmember');
grp.addQuery('user',a);
grp.query();
while(grp.next()) {
if (gp.length > 0) {
//build a comma separated string of groups if
there is more than one
gp += (',' + grp.group);
}
else {
gp = grp.group;
}
}
// return Groups where assigned to is in those groups we
use IN for lists
return 'sys_idIN' + gp;
},
type: 'BackfillAssignmentGroup'
}
The next time you create an incident, select a user in the Assigned to field. Then click the Assignment group
lookup icon. Only the groups that contain the user you just selected appear. For example, if Bob Smith belongs to the
Database group and the Networking group and you assign an incident to Bob, the only options you can select for the
assignment group are Database and Networking.

Related Lists and Reference Qualifiers

Whenever you edit a reference field from a related list, it might be necessary to know which related list the reference
field is on in order to properly build the reference qualifier for the field. This occurs when the same field appears on
different related lists and the context is necessary to know how to properly qualify the reference values.
To do this, personalize the List Control for the related list and fill in the List edit tag with any tag you choose. This
tag value will be available to the advanced reference qualifier function as a variable named listEditRefQualTag. For
example, your advanced reference qualifier script include can look like this:
// Advanced reference qualifier on the CI Relationship Child field that
takes into account
// the related list that we are editing the child field on, if the
field is being editing
// from a tagged related list.

Reference Qualifiers
cmdb_rel_ci_child_refQual:function()

6
{

if (listEditRefQualTag == "application")
return "sys_class_name = cmdb_ci_appl";
if (listEditRefQualTag == "database")
return "sys_class_name = cmdb_ci_database"
}

Using the INSTANCEOF Operator

Use the INSTANCEOF operator in a reference qualifier to shorten or simplify a complex class qualifier.
For example, you can use the INSTANCEOF operator for a reference field to the cmdb_ci table to specify that you
want all subclasses of a class included in the results. The following reference qualifier returns all servers, including
linux, UNIX, windows, and so on, because each of those subclasses extend the cmdb_ci_server class:
sys_class_nameINSTANCEOFcmdb_ci_server
Likewise, the following reference qualifier can be similarly simplified:
u_active=true^sys_class_name=cmdb_ci_acc
^ORsys_class_name=cmdb_ci_computer
^ORsys_class_name=cmdb_ci_server
^ORsys_class_name=cmdb_ci_win_server
^ORsys_class_name=cmdb_ci_unix_server
^ORsys_class_name=cmdb_ci_linux_server
^ORsys_class_name=cmdb_ci_appl
^ORsys_class_name=cmdb_ci_netgear
If you use the INSTANCEOF operator, the reference qualifier is as follows:
u_active=true^sys_class_name=cmdb_ci_acc
^ORsys_class_nameINSTANCEOFcmdb_ci_computer
^ORsys_class_name=cmdb_ci_appl
^ORsys_class_name=cmdb_ci_netgear

Troubleshooting
If you receive a Bad Gateway Error in Internet Explorer when searching in a reference lookup window, then you
cannot use ref_qual_elements=* in the advanced reference qualifier.

Enhancements
Eureka
Administrators can create reference qualifiers using a simple condition builder, dynamic filtering options, or an
advanced query or script.

Article Sources and Contributors

Article Sources and Contributors

Reference Qualifiers Source: http://wiki.servicenow.com/index.php?title=Reference_Qualifiers Contributors: Boonetp, CapaJC, Cheryl.dolan, Don.Goodliffe, Emily.partridge, Eric.jacobson,
Eric.schroeder, G.yedwab, Gflewis, Guy.yedwab, Jacebenson, Jared.laethem, Jay.berlin, Jessi.graves, Joe.Westrich, John.roberts, Joseph.messerschmidt, Mark.stanger, Neola, Pat.Casey,
Phillip.salzman, Publishing.user, Rob.phillips, Rob.woodbyrne, Steven.wood, Suzanne.smith, Vaughn.romero, Vhearne

Image Sources, Licenses and Contributors

Image:Warning.gif Source: http://wiki.servicenow.com/index.php?title=File:Warning.gif License: unknown Contributors: CapaJC
Image:simple_ref_qualifier.png Source: http://wiki.servicenow.com/index.php?title=File:Simple_ref_qualifier.png License: unknown Contributors: Phillip.salzman, Publishing.user
Image:dynamic_ref_qualifier.png Source: http://wiki.servicenow.com/index.php?title=File:Dynamic_ref_qualifier.png License: unknown Contributors: Phillip.salzman
Image:advanced_ref_qualifier_string.png Source: http://wiki.servicenow.com/index.php?title=File:Advanced_ref_qualifier_string.png License: unknown Contributors: Phillip.salzman,
Publishing.user