Reference Qualifiers

From ServiceNow Wiki
Home > Script > Server Scripting > Reference Qualifiers
Jump to: navigation, search
Note
Note: 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

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.

2 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
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.


3 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 Configure Dictionary (Personalize Dictionary in versions prior to Fuji).
    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.
  3. To change views, select Default view or Advanced view under Related Links.
  4. 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.
  5. Select the type of qualifier in the Use reference qualifier choice list.
  6. Configure the qualifier:
  7. In the Reference Specification - Additional Customization section, configure these options if necessary:
  8. Click Update.

4 Example Reference Qualifiers

The following examples show each type of reference qualifier.

4.1 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.

A simple reference qualifier

Note
Note: Simple reference qualifiers can have a maximum of thirteen reference qualifier conditions.


4.2 Dynamic Reference Qualifier Example

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.

A dynamic reference qualifier

4.3 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 string. To create advanced reference qualifiers, enter the query string or JavaScript code in the Reference qual field on the Dictionary Entry form.

Note
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.


4.3.1 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.

An advanced reference qualifier with an encoded query string

4.3.2 JavaScript Calls

An example of a JavaScript call is the following code:

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.

4.3.2.1 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. Open an incident.
  2. Right-click the Assigned to field and select Configure Dictionary (Personalize Dictionary in versions prior to Fuji).
  3. In the Reference qual field, enter javascript:"sys_idIN"+getRoledUsers("IN","itil_admin").join(",").
  4. Save the record.
  5. 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;
   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;
}

4.3.2.2 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. Open an incident.
  2. Right-click the Assignment group field and select Configure Dictionary (Personalize Dictionary in versions prior to Fuji).
  3. Enter javascript:new BackfillAssignmentGroup().BackfillAssignmentGroup() in the Reference qual field.
  4. Save the record.
  5. Navigate to System Definitions > Script Includes.
  6. Click New.
  7. Create a script include with the following JavaScript code:
var BackfillAssignmentGroup = Class.create();
BackfillAssignmentGroup.prototype = {
	initialize: function() {
	},
	
	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.

4.4 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, configure 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. 

 cmdb_rel_ci_child_refQual:function()  { 

  if (listEditRefQualTag == "application")
    return "sys_class_name = cmdb_ci_appl";

  if (listEditRefQualTag == "database")
    return "sys_class_name = cmdb_ci_database"

  }

4.5 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

5 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.

6 Enhancements

6.1 Eureka

  • Administrators can create reference qualifiers using a simple condition builder, dynamic filtering options, or an advanced query or script.
Was this article helpful?
Yes, I found what I needed
No, I need more assistance