Reference qualifiers

Use reference qualifiers to restrict the data that is selectable for a reference field.

For example, to allow another record to reference records with the San Diego location name, 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.

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.

Note: Reference qualifiers are available when using a reference lookup (magnifying glass icon) from forms. It applies the qualifier condition and the filtered information appears in the displayed list. They are not applicable for condition builders.

Simple reference qualifier

The following types of reference qualifiers are available:

Simple reference qualifiers provide choice lists for you to specify a reference qualifier condition on the table where the reference field is located. Simple qualifiers only apply when using "type-ahead" functionality on a form.

The base system provides several simple reference qualifiers. 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. Simple reference qualifiers can have a maximum of 13 reference qualifier conditions.
Figure 1. Simple reference qualifier example
Simple reference qualifier

Dynamic reference qualifiers

Dynamic qualifiers allow you to use a dynamic filter to run a query against a reference field without having to enter JavaScript code or encoded query strings. The advantage of using a dynamic reference qualifier is that you can create one dynamic filter option and then use it in multiple dynamic reference qualifiers.

The base system provides several dynamic filter options. An example is the dynamic filter option for 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 refines the reference qualifier based on the class of the CI. The only options for the model ID are options 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 the Computer form.
Figure 2. Dynamic reference qualifier example
Dynamic reference qualifier

Advanced reference qualifier

To create advanced reference qualifiers, enter the encrypted query string or JavaScript code (actual code or call to a script include or business rule) in the Reference qual field. The encoded query string or JavaScript can contain one or more filter conditions.
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.
Figure 3. Advanced reference qualifier example
Encoded query string in an advanced referenced qualifier

An example of a JavaScript call is 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.

Related lists and reference qualifiers

When a field appears on multiple related list 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 tag in the List edit tag field. This tag value is available to the advanced reference qualifier function as a variable named listEditRefQualTag. The following script include code is an example of an advanced reference qualifier using tags.
// 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 edited
// 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"
 
  }

Additional reference qualifier uses

The ref_qual_elements attribute can be used to specify dependent fields in the following cases:
  • Catalog Item ordering page
  • Requested Item form
  • Catalog Task form
In the JavaScript function called by the advanced reference qualifier, the current record (current) is in scope, allowing access to additional information. For example:
  • Variable information for the ordered item is available with current.variables.variablename.
  • The Request for user is available with current.cart.requested.for.

The following example defines an advanced reference qualifier for a user (sys_user) reference variable. It filters the available user records to those records where Name contains the value of a variable named textmatch on the same item.

function getBlackberryUsers ( ) { 
  var answer  = ''; 
  var includes  = current.variables.textmatch;
  var usr = new GlideRecord('sys_user'); 
  usr.addQuery('name','CONTAINS',includes); 
  usr.query(); 
  while (usr.next()) { 
    if (answer.length > 0 ) {
      answer += (',' + usr.sys_id); } 
    else { 
      answer  = '' + usr. sys_id; } 
    } 
  return 'sys_idIN' + answer; }