There are a few tools that every ServiceNow administrator should be equipped with; reference qualifiers are one of them. Simply put, reference qualifiers allow you to specify a filter to restrict the data available for reference values. And filtering, as you may know, drastically improves the user experience by simplifying the data input process. It reduces the number of values available for selection, ensures accuracy by not displaying invalid or inappropriate values, and increases security by restricting values that are not retrieved or presented to the user.
Reference fields are such a case, where you specify the reference qualifier in the sys_dictionary record defining that field in a particular table. In the Service Catalog, they are used by reference variables to restrict the available values for several different variable types based on the result of a script or other variables on the catalog item. Before we get into the specifics of how how they are used in Service Catalog, let's do an overview of reference qualifiers in general.
Three types of reference qualifiers are available in the ServiceNow platform:
- Simple reference qualifiers: Provide choice lists for you to specify a reference qualifier condition on the table where the reference field is located
- Dynamic reference 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.
- Advanced reference qualifiers: Provide a text field for you to create either a static encoded query string or JavaScript code that references script includes or functions in global business rules
ServiceNow offers many standard reference qualifiers in the base system. You can view them by navigating to System Navigation > Dictionary and filtering on records where Reference qual is not empty.
Simple reference qualifiers
When you're looking for a solution, sometimes it's best to start with the simplest. Simple reference qualifiers (like the name suggests) achieve your requirements without in the simplest and most straightforward way possible. Before exploring other avenues - such as scripts, which can be complicated, unnecessary, and are not always guaranteed to work - first try to determine if you can accomplish what you need to do with a simple reference qualifier. If you want to limit the values for a reference field based on other values in the reference table, this is the qualifier you'll want to use. You can always configure a simple reference qualifier by building the condition using the choice lists.
The base system provides several simple reference qualifiers by default. For instance, the reference qualifier on the Vendor field on asset forms (e.g. the Hardware form) 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.
Dynamic reference qualifiers
Dynamic reference qualifiers allow you to create one dynamic filter option and in as many dynamic reference qualifiers as needed. They are useful when you want to limit the values for a reference field based on the Create a dynamic filter option that uses Create scripted filters. Most of all, they allow you to use existing scripts in the base system without having to re-invent the wheel, saving you lots of time and effort. Likewise, any dynamic scripts you create can be used elsewhere, which is good practice for code reusability. For example, the dynamic reference qualifier Me saves you time from coming up with a script to return your user ID.
One of the many dynamic filter options that the base system offers by default is on the Model ID field, which appears on a configuration item form (e.g. 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 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 qualifiers
In some cases, a simple or dynamic reference qualifier does not provide enough control over filtering. This is where advanced reference qualifiers come in handy. They allow you to enter an encoded query string or make a JavaScript call to a script include that returns a query string. But while they are available for your use, advanced reference qualifiers should only be used as a last resort. Like the script field in an ACL rule, there is always a risk of failing, which can cause spurious results or performance issues. For example, if you're using advanced reference qualifiers in the Service Catalog to get choices from the Change Request Type field, a better alternative would be to have your script go to the sys_choice table and filter it (table=change_request^field=type). In addition, if you plan to script a reference qualifier you will want to delegate most of that script to a Script Include for efficiency.
To create these types of qualifiers, enter the query string or JavaScript code in the Reference qual field on the Dictionary Entry form.
It's good practice to make JavaScript calls to functions in a script include instead of a global business rule. Here is more information on JavaScript calls.
How reference qualifiers work in Service Catalog
Now that you have a brief understanding of reference qualifiers, here's a rundown on how they work they can be applied in Service Catalog. As mentioned above, reference qualifiers work a little differently in Service Catalog because they apply to catalog variables, not fields. They can be used to filter the values available for input in certain variable types, and they allow you to script the filtering for maximum flexibility. This includes the capability of scripting one variable so the acceptable values are filtered by the values set in other fields on the Catalog Item ordering screen. They also apply if inputs are allowed in those variables on the Requested Item form or Catalog Task form.
First of all, in Service Catalog, reference qualifiers only apply to these four variable types:
- List Collector (uses the list collector (aka slushbucket) interface to add multiple records from a table)
- Lookup Multiple Choice (creates radio buttons using data from a table)
- Lookup Select Box (creates a choice list using data queried from a table)
- Reference (references a record in another table, similar to a reference field)
Secondly, it's important to note that all four variable types are supported by the Advanced reference qualifier. However, only Reference variables are supported by the Simple, Dynamic, and Advanced reference qualifiers. When creating a new Reference variable, in the Type Specifications tab you have the option to choose between these three reference qualifiers:
If you're creating a new List Collector, Multiple Choice, or Select Box variable, there is no drop-down menu - you will only see the Reference qual field (which corresponds to the Advanced reference qualifier):
Keep these restrictions in mind when applying reference qualifiers to your Service Catalog, and you'll be good to go!
More resources
- danny.mortensen gives step-by-step instructions on the tricky process of creating an advanced reference qualifier for a record producer
- Known Error: Advanced reference qualifier does not use "current" correctly on the catalog task form when first lo...
- Product documentation on how to configure reference qualifiers
- See how you can create a reference qualifier on the List Collector to view a specific filter: Filtering on the List Collector or SlushBucket variable in Helsinki
1 Comment
