washington_dc_now_platform_administration_4-5-2024

Washington DC Now Platform Administration
Washington DC Now
Platform Administration
Last updated: April 5, 2024
PDF generated on April 5, 2024

©2024 ServiceNow. All rights reserved. Terms of Use Privacy Statement
ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in
the United States and/or other countries. Other company and product names may be trademarks of the respective companies with which
they are associated.
Some examples and graphics depicted herein are provided for

illustration only. No real association or connection to ServiceNow
products or services is intended or should be inferred.
This PDF was created from content on docs.servicenow.com. The web
site is updated frequently. For the most current ServiceNow product
documentation, go to docs.servicenow.com.
Company Headquarters
2225 Lawson Lane
Santa Clara, CA 95054
United States
(408)501-8550
PDF generated on April 5, 2024 2

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the
United States and/or other countries. Other company and product names may be trademarks of the respective companies with which they are
associated.
Reference qualifiers
Use reference qualifiers to filter the data that is returned for a reference
field.
A reference field stores a link (reference) to a field on another table,

making the records/fields in the referenced table available to the form
containing the reference field.
For example, the Assigned to field on the Incident table is a reference

to the User [sys_user] table. By default, all values for the field that is
being referenced appear in the reference lookup and can be directly
accessed through the reference field (type ahead). Expanding on the
prior example, if a reference qualifier is not defined, all users in the User
table appear in the reference lookup. Including those users that are
inactive. Sometimes, this might be the desired functionality. In other cases
however, only a subset of the available values may be desired. In this
case, create a reference qualifier to filter the available data so that only
the desired values are returned and made available to the form. Such
as only the active users or users that have a specific role. Reference
qualifiers are robust and can consist of simple AND/OR conditions, inline
JavaScript, or complex script include.
You can modify the reference qualifier for a table, and any table based
on that table (parent or extended), by defining a reference qualifier
through the Dictionary Entry form. You can also modify the reference
qualifier only on an extended table and its children (not the parent
table), through a dictionary override. You can only define a single
reference qualifier per field, per form/table. Reference qualifiers are
not applicable to condition builders. For information on using filtering in
condition builders, see Create a dynamic filter option.
Note:
• Creating reference qualifiers requires knowledge of the underlying

ServiceNow data model (tables and fields) and knowledge of the
Web services and Scripts.
• To restrict what data specific users can access, use ACLs not
reference qualifiers.

associated.
You can define a reference qualifier using one of the following methods.
Simple reference qualifier
Simple reference qualifiers use AND/OR statements (conditions) to create

simple filters. Use simple reference qualifiers when filtering on conditions
such as whether a company is active, a user has a specific role, and/or
a caller is in a specific time zone. Simple reference qualifiers can have a
maximum of 13 reference qualifier conditions. For additional information
on how to use condition builders, see Condition builder.
Simple reference qualifier example
Dynamic reference qualifiers
Dynamic reference qualifiers enable you to use a Create a dynamic filter

option to run a query against a reference field to filter the returned data
set. Dynamic filter options are stored filters that can contain Encoded
query strings, JavaScript, or script includes, and can be used in multiple
dynamic reference qualifiers. Changes made to a dynamic filter option
automatically apply to all reference qualifiers that use the same dynamic
filter option. Use this type of reference qualifier when you want to use the
same filter on multiple forms or to provide filter functionality to "non-code
savvy" implementers.
The base instance provides several OOB dynamic filter options. If a

dynamic filter option that meets your needs does not exist, you can
create a new dynamic filter option that is specific to your requirements.
An example of an OOB dynamic filter option is the reference qualifier on
the Model ID field on a configuration item form, such as the Computer
form. The reference qualifier calls the CI Model Qualifier dynamic filter
option, which in turn calls the ModelAndCategoryFilters script include. This
script include filters the data set based on the class of the CI. The only
options for the model ID are options that belong to the same class as the

associated.
current CI. For example, only CIs that belong to the Computer class are
available in the Model ID field on the Computer form.
To locate the available dynamic filter options, navigate to System

Definition → Dynamic Filter Options. In the right-corner of the Dynamic
Filter Options list, click the filter icon and create the filter condition
Available for ref qual is true. All dynamic filter options that can
be used in dynamic reference qualifiers appear.
Dynamic reference qualifier example
Advanced reference qualifier

Advanced reference qualifiers enable you to define an inline encoded
query string or JavaScript (actual code or the name of an existing script
include or business rule) filter directly in the Reference qual field of the
reference qualifier. Similar to the other reference qualifier types, when the
form loads, the filter is executed, and only the records that match the
filter appear in the reference field. Use this type of reference qualifier for
implementations that only require a simple, unique filter, that cannot be
handled by a simple reference qualifier, and is not used across multiple
reference fields.
Note: As a good practice, make JavaScript calls to functions in a
script include instead of a global business rule.
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. For additional information on valid encoded
query string syntax and examples, see Encoded query strings.
Advanced reference qualifier examples

associated.
An example of a JavaScript call is javascript:new

myScriptInclude().my_refqual(). This code calls the function
my_refqual() in the script include myScriptInclude(). The function must
return a query string that can filter the options available on a reference
field.
Note: You can also use encoded JavaScript
filters such as javascript:'u_active=true^' +
"u_hr_service="+current.hr_service in reference qualifiers.
In another example, if you are trying to filter based on the current
company, you don't have use a lookup script but can simply add this
line to your dynamic qualifier:
return "company=" + current.company;
You can also simplify this and use an advanced reference qualifier
instead of a dynamic one:
javascript:"company=" + current.company

associated.
Related lists and reference qualifiers

When a field appears on multiple Related lists on a single form view,
it may be necessary to validate which related list is being referenced
to properly build the reference qualifier for the field. In this situation,
configure the list control for the related list and enter a unique tag in
the List edit tag field. This tag value is available to filter scripts as a
variable named listEditRefQualTag. The following script include code is
an example of a function that uses this type of tag.
// Advanced reference qualifier on the CI Relationship Chi
ld field that takes into account
// the related list that we are editing the child field on
, if the field is being edited
// from a tagged related list.
cmdb_rel_ci_child_refQual:function(){
if(listEditRefQualTag =="application") return "sys_clas

s_name = cmdb_ci_appl";
if(listEditRefQualTag =="database") return "sys_class_n

ame = cmdb_ci_database"
Using Javascript current syntax in reference qualifiers
current is a JavaScript object that contains the fields and field values of
the active (current) record. For forms, this is the record that is displayed
(loaded) in the form. Within advanced and dynamic reference qualifiers,
you can use the JavaScript current object to define filters such as
javascript:"company=" + current.company.
This JavaScript, within a reference qualifier, only returns the records from
the referenced table that are equal to the company field value of the
current record. So, if the value that appears in the Company field is
Acme, the JavaScript returns all reference field records whose company
value is equal to Acme (company="Acme"). If you then bring up a
record whose company value is "ViewRite", the JavaScript resolves to
company="ViewRite."
All fields within the currently loaded form (tables) are available for use
with the current object. Use dot-walking to access values in a table,

associated.
including the referenced table. For example, on the Incident form, the
Assigned To field references the User table. To access the email address
of the user, use the following syntax: javascript:"emailAddress=" +
current.assigned_to.email.
• Configure reference qualifiers
System administrators can configure reference qualifiers that enable

filtering of the associated reference field.
• The INSTANCEOF operator in reference qualifiers
You can use the INSTANCEOF operator in a reference qualifier to

shorten or simplify a complex class qualifier.
Configure reference qualifiers

System administrators can configure reference qualifiers that enable
filtering of the associated reference field.
About this task
This task walks you through creating a reference qualifier in the system
dictionary. When creating a reference qualifier in the system dictionary, it
not only applies to that table, but also to all the children of the table.
Note: You can also create reference qualifiers on extended tables

through dictionary overrides. Dictionary overrides only impact the
extended table and any of its children, not the parent table.
Procedure
1. Navigate to the reference field on the form or table on which you

want to define a reference qualifier.
2. Right-click the reference field label and select Configure Dictionary.
3. Under Related Links, select Advanced view.

The simple reference qualifier is available in both the default view
and the advanced view. The dynamic and advanced reference
qualifiers are available only in the advanced view.

associated.
4. In the Reference Specification section, verify that the table in the

Reference field contains the table that you want associated with the
reference field, or select another table if necessary.
5. From the Use reference qualifier choice list, select the reference
qualifier to implement.
6. Configure the qualifier based on the type of reference qualifier.
• Simple: Build the condition using the choice lists.
• Dynamic: Either select an existing dynamic filter option or Create

a dynamic filter option.
• Advanced: In the Reference qual field, enter an Encoded query

strings, JavaScript that returns a query string, or the name of a
script include or business rule to run.
7. Complete the Reference Specification — Additional Customization

section, as appropriate.
Field Description
Identifies a field other than sys_ID

Reference key to use as the unique identifier for
the reference field.
Defines what happens to a

record if the record it references
is deleted. Possible options
include:
• None
Reference cascade rule • Cascade
• Clear
• Delete
• Delete no workflow
• Restrict

associated.
Field Description
Flag that determines whether to

Reference floats Configure the edit option for
one-to-many relationships.
Flag that determines if the

system should create a new
record when a value for the
reference field does not match
Dynamic creation an existing record. If you select
this option, enter a script that
specifies how to create the
record in the Dynamic creation
script field.
8. Click Update.
• Constrain the assigned to field by role
This example shows how to use JavaScript and a business rule to

restrict the incident Assigned to field choices to only the users with the
itil_admin role.
• Constrain the assignment group field
This example shows how to use an advanced reference qualifier with

JavaScript and a script include to restrict the incident Assignment
group choices to only the groups that contain the user specified in the
Assigned to field.
Constrain the assigned to field by role

This example shows how to use JavaScript and a business rule to restrict
the incident Assigned to field choices to only the users with the itil_admin
role.
Before you begin
Role required: personalize_dictionary or admin

associated.
About this task
You can also change itil_admin to any other role on a reference field
that refers to the User [sys_user] table.
Procedure
1. Open an incident.
2. In the upper-left corner of the screen, click the form context menu,
and then select Configure > Dictionary.
3. In the Reference qual field, enter

javascript:"sys_idIN"+getRoledUsers("itil_admin").join(",").
4. Save the record.
5. To see the base system business rule that this JavaScript code calls,
navigate to System Definition > Business Rules.
6. Open getRoledUsers.
The business rule uses the following JavaScript code.
// Return an array of sys_ids of the users that have a
t least one role
// optional parameters allow the exclusion (NOT IN) o
f some roles or
// look for specific roles (IN)
//
// optional: queryCondition - 'IN' or 'NOT IN'
// optional: roleList - a comma separated list of rol
e names
//
function getRoledUsers(queryCondition, roleList) {
var roleListIds;
if (queryCondition && roleList) {
roleListIds = getRoleListIds(roleList);
}
var users = {};

var now_GR = new GlideRecord('sys_user_has_role');
if (roleListIds) {
now_GR.addQuery('role', queryCondition, roleList
Ids);

associated.
}
now_GR.query();
while (now_GR.next()) {
users[now_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 now_GR = new GlideRecord('sys_user_role');
now_GR.addQuery('name','IN',roleList);
now_GR.query();
while (now_GR.next()) {
ids.push(now_GR.sys_id.toString());
}
return ids;
}
Constrain the assignment group field

This example shows how to use an advanced reference qualifier with
JavaScript and a script include to restrict the incident Assignment group
choices to only the groups that contain the user specified in the Assigned
to field.
Before you begin
Role required: personalize_dictionary or admin
Procedure
1. Open an incident.
2. Right-click the Assignment group label and select Configure

Dictionary.

associated.
3. If the form appears in Default view, under Related Links, click

Advanced view.
4. In the Use reference qualifier field, ensure that the Advanced option
is selected.
5. In the Reference qual field, enter javascript:new

ReferenceQualifierHelper().backfillAssignmentGroup().
6. Save the record.
7. Navigate to System Definitions > Script Includes.
8. Click New.
9. Name your script includes as ReferenceQualifierHelper to match

the Javascript in the following step.
This name ensures the API Name is generated correctly, based on the
Name field.
10. Script includes with the following JavaScript code.

Ensure that the Accessible form field is properly set for the
environment.
var ReferenceQualifierHelper = Class.create();
ReferenceQualifierHelper.prototype = {
backfillAssignmentGroup:function() {
var assigneeGroupsQualifier = '';
var assignee = current.assigned_to;
//return if the assigned_to value is e

mpty (this causes all groups to be returned)
if(!assignee)
return;
//sys_user_grmember has the user to gr

oup relationship
var grAssigneeGroups = new GlideRecor
d('sys_user_grmember');
grAssigneeGroups.addQuery('user',assig
nee);
grAssigneeGroups.query();

associated.
while(grAssigneeGroups.next()) {
if (assigneeGroupsQualifier.len
gth == 0) {
// Create the beginnin
g of the qualifier and add the 1st group
assigneeGroupsQualifier
= 'sys_idIN' + grAssigneeGroups.getValue('group');
}
else {
// build a comma separ
ated string of groups if there is more than one
assigneeGroupsQualifier
+= (',' + grAssigneeGroups.group);
}
}
// return Groups where assigned to is
in those groups we use IN for lists
gs.log('DP: RefQual = ' + assigneeGrou

psQualifier);
return assigneeGroupsQualifier;
},
type: 'ReferenceQualifierHelper'
};
What to do next
To test, create an incident and select a user in the Assigned to field.

Click the Assignment group lookup icon. Only the groups that contain the
user you selected appear. For example, you assign an incident to Bob
Smith, who belongs to the Database group and the Networking group.
The only options that appear in the assignment group are Database and
Networking.
The INSTANCEOF operator in reference qualifiers

You can use the INSTANCEOF operator in a reference qualifier to shorten
or simplify a complex class qualifier.
For example, use the INSTANCEOF operator for a reference field to the
cmdb_ci table to specify that all subclasses of a class are included in the
results. The following reference qualifier returns all servers, including Linux,

associated.
UNIX, Windows, and so on, because each of those subclasses extend the
cmdb_ci_server class.
sys_class_nameINSTANCEOFcmdb_ci_server
In another example, you can simplify the following reference qualifier in a

similar way.
u_active=true^sys_class_name=cmdb_ci_acc
ÔRsys_class_name=cmdb_ci_computer
ÔRsys_class_name=cmdb_ci_server
ÔRsys_class_name=cmdb_ci_win_server
ÔRsys_class_name=cmdb_ci_unix_server
ÔRsys_class_name=cmdb_ci_linux_server
ÔRsys_class_name=cmdb_ci_appl
ÔRsys_class_name=cmdb_ci_netgear
Using the INSTANCEOF operator, the reference qualifier is rewritten as

follows because the server subclasses extend the cmdb_ci_computer
class.
u_active=true^sys_class_name=cmdb_ci_acc
ÔRsys_class_nameINSTANCEOFcmdb_ci_computer
ÔRsys_class_name=cmdb_ci_appl
ÔRsys_class_name=cmdb_ci_netgear

associated.

washington_dc_now_platform_administration_4-5-2024

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

washington_dc_now_platform_administration_4-5-2024

Uploaded by

Copyright:

Available Formats

Washington DC Now Platform Administration

PDF generated on April 5, 2024

Some examples and graphics depicted herein are provided for

PDF generated on April 5, 2024 2

A reference field stores a link (reference) to a field on another table,

For example, the Assigned to field on the Incident table is a reference

• Creating reference qualifiers requires knowledge of the underlying

PDF generated on April 5, 2024 3

Simple reference qualifier

Simple reference qualifiers use AND/OR statements (conditions) to create

Simple reference qualifier example

Dynamic reference qualifiers

Dynamic reference qualifiers enable you to use a Create a dynamic filter

The base instance provides several OOB dynamic filter options. If a

PDF generated on April 5, 2024 4

To locate the available dynamic filter options, navigate to System

Advanced reference qualifier

PDF generated on April 5, 2024 5

An example of a JavaScript call is javascript:new

PDF generated on April 5, 2024 6

Related lists and reference qualifiers

if(listEditRefQualTag =="application") return "sys_clas

if(listEditRefQualTag =="database") return "sys_class_n

Using Javascript current syntax in reference qualifiers

PDF generated on April 5, 2024 7

• Configure reference qualifiers

System administrators can configure reference qualifiers that enable

• The INSTANCEOF operator in reference qualifiers

You can use the INSTANCEOF operator in a reference qualifier to

Configure reference qualifiers

About this task

Note: You can also create reference qualifiers on extended tables

1. Navigate to the reference field on the form or table on which you

2. Right-click the reference field label and select Configure Dictionary.

3. Under Related Links, select Advanced view.

PDF generated on April 5, 2024 8

4. In the Reference Specification section, verify that the table in the

6. Configure the qualifier based on the type of reference qualifier.

• Simple: Build the condition using the choice lists.

• Dynamic: Either select an existing dynamic filter option or Create

• Advanced: In the Reference qual field, enter an Encoded query

7. Complete the Reference Specification — Additional Customization

Identifies a field other than sys_ID

Defines what happens to a

Reference cascade rule • Cascade

PDF generated on April 5, 2024 9

Flag that determines whether to

Flag that determines if the

• Constrain the assigned to field by role

This example shows how to use JavaScript and a business rule to

• Constrain the assignment group field

This example shows how to use an advanced reference qualifier with

Constrain the assigned to field by role

Before you begin

Role required: personalize_dictionary or admin

PDF generated on April 5, 2024 10

About this task

3. In the Reference qual field, enter

4. Save the record.

var users = {};

PDF generated on April 5, 2024 11

var ids = [];

// get sys_id's for the named roles

Constrain the assignment group field