Using Reference Qualifiers with Lookup Select Box Variables in ServiceNow

In ServiceNow, reference qualifiers are used to filter the data that is returned for a reference field or variable. When applied to Service Catalog variables – especially the Lookup Select Box variable type – reference qualifiers become powerful tools for creating dynamic, dependent fields. For example, you can have one dropdown's options filter automatically based on the selection of another, improving the user experience and ensuring valid data entry. This article provides a comprehensive guide to setting up reference qualifiers on lookup select box variables, troubleshooting common issues, and exploring advanced techniques (like GlideAjax) for dynamic filtering. The goal is to help you leverage ServiceNow best practices to build intuitive, efficient catalog forms.

Overview of Reference Qualifiers and Lookup Select Boxes

What is a Reference Qualifier? In ServiceNow, a reference qualifier defines conditions or a script to restrict the records that appear in a reference field’s lookup or a lookup select box. In other words, it "qualifies" which records from the target table should be available for selection. This is essential in scenarios where you have a large dataset or need to enforce context-specific filtering (such as showing only active users, or only records related to a certain category).

What is a Lookup Select Box Variable? A lookup select box is a type of Service Catalog variable that presents a dropdown list of records from a specified table, similar to a reference field but rendered as a choice list. You can configure which table it pulls from and which field to display as the choice label. Lookup select box variables are useful for presenting a finite list of options retrieved from live data (for example, a list of locations, categories, assets, etc.). They are more powerful than static choice lists because they query real-time data and can display values and labels from any table, and they often behave like reference fields under the hood. By using reference qualifiers with lookup select boxes, you can make these dropdowns dynamic – for instance, showing dependent options based on earlier answers or other conditions.

Why use them together? Combining reference qualifiers with lookup select boxes allows you to create dependent field relationships and dynamic lookups in ServiceNow’s Service Catalog. For example, if you have a "Country" and "City" pair of variables, the City options should narrow down to the cities in the selected country. A reference qualifier on the City lookup select box can accomplish this filtering. This not only improves usability but also prevents incorrect combinations from being chosen.

Setting Up a Reference Qualifier on a Lookup Select Box Variable

Setting up a reference qualifier for a lookup select box involves configuring the variable and defining the filter conditions. Below are the general steps to do this, along with tips for ensuring it works correctly:

1. Create the Lookup Select Box Variable: In your catalog item or record producer, add a new variable with Type Lookup Select Box.

2. In the variable's Type Specifications, you will need to specify:

   • Lookup from table: The table that contains the records you want to display. For example, sys_user for users, cmdb_ci_server for servers, sys_choice for choice list values, etc.

   • Lookup value field: The field that will be stored as the value (usually the unique identifier, like sys_id or a code).

   • Lookup label field: The field that will be shown to the user as the choice label (e.g. name or display value).

   • (Other settings like Include none or default value can be set as needed.)

3. Define the Reference Qualifier Condition: Locate the Reference qualifier field in the variable's definition (on the Type Specifications tab).

   Here you can specify how to filter the options from the lookup table:

   • For a simple/static filter, choose Simple qualifier and enter a condition (encoded query) that records must meet. For example, if you only want active records, you might put active=true as the qualifier.

     This condition works like a query on the target table and will ensure only records where active is true will appear.

   • For a dynamic filter or more complex logic, change the qualifier type to Advanced. In the advanced reference qualifier, you can write a script (preceded by javascript:) that returns an encoded query string.

     This script can reference values of other variables or system properties.

     For instance, you might use:

 javascript: 'category=' + current.variables.selected_category;

This example assumes the target table has a field named "category" and you want to filter by the value of another variable selected_category on the form. The script needs to output a string in encoded query format (e.g. "category=<value>").

In ServiceNow catalog item scripts, you can access other variable values through the current.variables object in an advanced reference qualifier. (Ensure you use the variable name of the field, not the question text, when referencing it in scripts.)

4. Use the ref_qual_elements Attribute for Dependent Fields: If your reference qualifier should re-evaluate when another variable changes (i.e. the lookup is dependent on one or more other fields), you must add a variable attribute called ref_qual_elements. This attribute is a comma-separated list of the names of the "parent" variables that should trigger an update. For example, if your lookup select box should filter based on a "Category" variable, set the attribute ref_qual_elements=category on the dependent variable. This tells ServiceNow to send the specified field(s) back to the server whenever they change, so it can re-calculate the reference qualifier and refresh the options.

   Without this, the lookup options might not update dynamically when the user changes the controlling field. (In fact, a common cause of dependent reference qualifiers not working is forgetting to add ref_qual_elements, which is resolved by simply adding the attribute to the variable configuration.)

5. Verify the Qualifier Logic: After configuring the above, test the catalog item in the Service Portal or Platform view. Select or input values in the controlling fields and ensure that the lookup select box variable filters its choices accordingly. If the filter isn't applied, double-check the following:

   • The reference qualifier condition or script is correct (no typos in field names, correct syntax for current.variables.x references, etc.).

   • The ref_qual_elements attribute includes the right variable names (and uses the internal variable Name, not the label).

   • The qualifier type (Simple vs Advanced) is set correctly for the kind of input you provided. (Advanced qualifiers should start with javascript: and return a string.)

   • If using an advanced script, ensure it returns a valid encoded query string. You can test the query by running it in a filter or script to see if it fetches the expected records.

By following these steps, you set the groundwork for a dependent lookup. Next, we'll illustrate with concrete examples how these configurations come together in real use cases.

Use Case Example: Dependent Lookup Select Boxes (Dynamic Filtering)

One of the most common use cases for reference qualifiers on lookup select boxes is to create dependent dropdowns. This means one field’s options are filtered based on the selection of another field. Let's walk through a practical example to demonstrate how to set this up: filtering Subcategory choices based on the selected Category in an Incident record producer.

Scenario: You have a record producer for creating an Incident. You want to include Category and Subcategory fields on the form. When the user picks a Category, the Subcategory choices should update to show only the subcategories relevant to that Category (just like the behavior on the regular Incident form). The challenge is that on a record producer or catalog item, the Category and Subcategory aren’t standard fields by default, so you must recreate this linkage using lookup select box variables and reference qualifiers.

Solution Outline: We will use two lookup select box variables, both sourcing data from the Choice [sys_choice] table, which stores choices for choice-type fields in the platform. The reason to use sys_choice is that Category and Subcategory on the Incident table are technically choice lists (not reference fields).

By querying sys_choice, we can dynamically pull the available Category choices and their dependent Subcategory choices.

Here’s how to set it up:

1. Category Variable Setup:

   1. Add a variable Category of type Lookup Select Box.

   2. Map to Field: (If this is a record producer and you want to map the selection to the actual incident Category field) Set Map to field = true and choose Field = Category. This ensures the selected value will populate the incident's Category when the record producer is submitted. If it's a regular catalog item not mapping to incident, you can just use the variable for context without mapping.

   3. Lookup from table: Choice (sys_choice) – We will retrieve Category entries from the choices table.

   4. Lookup value field: value – This is the value that gets stored (e.g., the actual internal value of the choice).

   5. Lookup label field: label – This is what the user sees (the human-friendly label of the choice).

   6. Reference qualifier: Set a condition to get only choices for the Incident Category. In this case, we want all sys_choice records where the name field is "incident" (table name) and element is "category".

      We can use a simple encoded query:

name=incident^element=category

This qualifier ensures the lookup will only show Category choices that belong to the Incident table’s Category field. (The ^ symbol denotes an AND condition in ServiceNow query syntax.)

2. Subcategory Variable Setup:

   1. Add a variable Subcategory of type Lookup Select Box.

   2. Map to Field:  (If this is a record producer and you want to map the selection to the actual incident Subcategory field) Set Map to field = true and choose Field = Subcategory. This ensures the selected value will populate the incident's Subcategory when the record producer is submitted. If it's a regular catalog item not mapping to incident, you can just use the variable for context without mapping.

   3. Lookup from table: Choice (sys_choice) – We will retrieve Subcategory choices from the same table.

   4. Lookup value field: value – This is the value that gets stored (e.g., the actual internal value of the choice).

   5. Lookup label field: label – This is what the user sees (the human-friendly label of the choice).

   6. Reference qualifier: This one needs to filter subcategories by the selected category. We’ll use an advanced qualifier with a script. Set the qualifier to Advanced and use a script like:

javascript:'name=incident^element=subcategory^dependent_value=' + current.variables.category;

Here's what this does: it builds a query string where name=incident and element=subcategory (so we're looking at Subcategory choices for the Incident table) and additionally dependent_value=<selected category value>. In the sys_choice table, the field dependent_value stores the value of the parent Category that a Subcategory is tied to. By appending the value of the Category variable (current.variables.category), the query will return only those subcategory choices whose dependent value matches the user's selected Category. If the user picks "Hardware" as Category, the qualifier becomes name=incident^element=subcategory^dependent_value=hardware, effectively showing only Subcategory choices under "Hardware".

3. Variable Attributes: Now, very importantly, add the attribute ref_qual_elements=category on the Subcategory variable. This ensures that whenever the Category variable changes, the Subcategory field's options are refreshed to reflect the new selection. Without this, the Subcategory lookup would only query once (on form load) and not update when Category changes.

   The ref_qual_elements tells ServiceNow which field(s) to watch; in this case, it watches the category variable. When category’s value updates, the platform knows to re-run the reference qualifier script for Subcategory, pulling in the new filtered choices.

   
   

4. Test the Dependent Behavior: After setting up both variables, try the record producer or catalog item. Initially, the Subcategory list may be empty or show a placeholder until a Category is chosen. When you select a Category, the form will make a server call in the background to fetch the relevant subcategories (thanks to ref_qual_elements). You should then see the Subcategory dropdown populated with only the choices tied to that Category. For example, if Category = "Inquiry / Help", Subcategory might show only "Password Reset, How to..., etc." (whatever is defined for that category in Incident choices). If you switch Category, the Subcategory list should instantly refresh to the new filtered set. This demonstrates a working dependent lookup select box setup – the Subcategory options are dynamic and driven by the Category selection.

   
   

This Category/Subcategory example is a practical demonstration of using reference qualifiers in a lookup select box to create linked dropdowns.

You can adapt this approach to many other scenarios:

• Country and City: Two lookup select boxes where City options filter based on the selected Country. For instance, if you have a custom table of cities with a reference to country, you could set City’s reference qualifier to country=<country_sys_id> using the script:

javascript:'country='+current.variables.country;

and set ref_qual_elements=country on the City variable

Then only cities from the chosen country appear in the list.

• Location and Assets: Select a Location in one variable, and filter an Assets lookup to show only assets at that location.

• User and Group Members: Choose a Group in one field, then have a second field list users who are members of that group.

• Category and Catalog Items: In a custom scenario, pick a Category and then show relevant Catalog Items or records tied to that category in a lookup.

  
  

The pattern is generally: identify the field that links the two tables (e.g., a common key or reference), then use the value of the first variable to filter the second. Always remember to include the ref_qual_elements attribute so that the dependency is recognized and the query updates dynamically.

Common Issues and Troubleshooting Tips

Using reference qualifiers with lookup select boxes is straightforward, but there are a few common pitfalls and issues you might encounter.

Here we highlight these issues and how to resolve them:

• Dependent Lookup Not Refreshing: The most frequent issue is that the dependent dropdown does not update when the controlling variable changes. This almost always comes down to a missing or incorrect ref_qual_elements attribute. If you forget to add ref_qual_elements (or misconfigure its value), the lookup select box will not know it needs to fetch new data on change.

  The solution:

  Add the appropriate ref_qual_elements with the name(s) of the parent variable(s).

  For example, if Subcategory isn't updating when Category changes, make sure Subcategory’s variable attributes include ref_qual_elements=category. After adding it, test again – you should see the dependent field refresh properly. (In platform terms, this attribute causes the client to send the specified field's value to the server to get updated reference results whenever that field changes.)

• Incorrect or No Filtering Applied: If the lookup is showing data, but not filtering as expected (e.g., it shows all records, ignoring your qualifier), verify the reference qualifier configuration:

  • Make sure the qualifier is saved in the variable record and that you set the qualifier Type to the correct mode (Simple or Advanced). If you wrote a script (using current.variables or other JavaScript), the qualifier must be set to Advanced, otherwise the system treats it as a static query string and your script might be ignored.

  • Check the syntax of your qualifier. For Simple qualifiers, ensure the condition string is valid (field names and values correctly spelled, using ^ for AND, etc.). For Advanced scripts, ensure your JavaScript is error-free and returns a string.

    A common mistake is forgetting to concatenate properly or not returning anything. For instance, javascript:'state='+current.variables.my_state; will work, but just writing 'state='+current.variables.my_state without the javascript: prefix or not in the Advanced field will not execute as script.

  • Confirm you're referencing the correct variable names in scripts. Use the internal variable Name (often auto-generated when you create the variable, but you can also set it). This is typically lowercase and may differ from the question's text. For example, a variable labeled "Requested For" might have the name requested_for. It's this name that should be used in current.variables.requested_for.

  • If your qualifier uses a field that stores a reference (like a sys_id), ensure you're comparing the right values. Sometimes you might need to use current.variables.field_name.sys_id if the variable itself is a reference and you need the actual sys_id. However, in most cases current.variables.field_name will give the sys_id of the selected record, which is what you want for filtering another reference field by it.

• Variables in a Variable Set or Container not working: If your variables are inside a Variable Set (reusable set of variables) or a container, the logic for reference qualifiers is the same, but be careful with naming conflicts and ensure the ref_qual_elements names match the variable in that item. Variable Sets could have the same variable included in multiple items – the system usually handles this by context, but always test the specific item. In rare cases, if you see issues, you might consider making the variables item-specific instead of in a shared set when doing complex dependencies.

• Reference Qualifier Script Not Running: If you suspect the script in an advanced qualifier isn't running at all:

  • Confirm that you published or saved all changes to the item and variables (in the ServiceNow builder, unsaved changes might not be active).

  • If this is on an older ServiceNow release or in Service Portal, try testing in the Platform UI vs the Service Portal. Historically, some early versions had quirks where certain variable attributes didn't function in Service Portal.

    For modern releases, this is much less of an issue, and the above approach works in both the portal and the platform. However, if you find it not working in Service Portal but working in the platform, it could be a version-specific defect. A possible workaround is to use a Catalog Client Script to force a refresh (see the advanced techniques below).

  • Check the browser console for errors when you change the controlling field. A scripting error (maybe from a typo in the qualifier) could be preventing the lookup from updating. Adjust the script accordingly.

• Performance Concerns (Slow Loading): A lookup select box will query the database to load all qualifying options. If your filter is too broad or the table large, it could slow down the catalog item loading or the responsiveness when changing fields. For example, pulling thousands of records into a dropdown is not ideal. To mitigate this:

  • Always apply a reasonable reference qualifier (filter) to limit results. If you truly need to let users pick from a huge list, consider using a Reference variable type instead, which allows searching rather than displaying all at once.

  • Monitor client-side performance: if the dropdown is slow to respond, check if your script (in advanced qualifier or client script) is doing excessive work.

  • ServiceNow also has a property for maximum reference qualifier results; huge result sets may be truncated. If users complain they don't see all options, they might be hitting a limit. In such cases, again, a reference with search might be better than a lookup select box.

• Order of Execution / Timing Issues: Normally, the platform handles the refresh automatically when using ref_qual_elements. However, if you have multiple dependencies (e.g., A filters B, and B filters C), make sure you set ref_qual_elements on each dependent properly (B should list A, and C should list B, possibly A as well if C indirectly depends on A). The updates will cascade. If a script include or complex script is used, ensure it can handle empty or null values (like when the form first loads, subcategory has no category selected yet). It's often wise to code the qualifier script to return something like active=false or an always-false condition when the controlling variable is empty, to avoid showing unintended results.

  
  

By anticipating these issues and following best practices, you can usually resolve most problems with reference qualifiers. In summary, the key troubleshooting takeaway is: if your dependent lookup isn't behaving, check the ref_qual_elements attribute and the qualifier script carefully, as these are the usual culprits.

Advanced Techniques: Dynamic Filtering with GlideAjax and Script Includes

In most cases, the built-in reference qualifier approach (as described above) is sufficient and is the recommended method. In fact, it's considered best practice to use an advanced reference qualifier or script include at the variable level to handle complex filters, rather than relying solely on client-side scripts. However, there are scenarios where you might need more flexibility or have to work around certain limitations. This is where using GlideAjax and script includes can help create dynamic filters or even populate options on the fly.

Using Script Includes in Reference Qualifiers

One way to keep complex logic out of the inline qualifier script is to use a script include. ServiceNow allows you to call script include methods from advanced reference qualifiers. For example, suppose you have a very complex query to determine which records to show (maybe involving multiple table lookups or conditions). You can create a server-side Script Include (visible to the client, i.e., marked as client-callable if needed) with a static method that returns an encoded query string. Then, in your variable's reference qualifier, you simply call that function.

Example: You have a lookup select box that should show a list of support technicians, but filtered by location and expertise based on what the user selected earlier in the form. Crafting a query string might take a dozen lines of code, so you put that in a script include:

// Script Include (Server-side)
var TechFilter = Class.create();
TechFilter.prototype = {
    initialize: function() {},
    getTechnicianFilter: function(location, skill) {
        // Build a complex query based on location and skill
        var query = '';
        if (location) {
            query += 'location=' + location;
        }
        if (skill) {
            query += '^u_skill=' + skill;
        }
        query += '^active=true'; // only active techs
        return query;
    },
    type: 'TechFilter'
};

Now in the reference qualifier for the Technician lookup variable, you can use:

javascript:TechFilter.getTechnicianFilter(current.variables.location, current.variables.skill)

When the form needs to load the technician options, it will call that script include method (server-side) and use the returned query to filter the results. This keeps your logic organized and allows reusing the script include in other contexts if needed. It also makes debugging easier – you can test the Script Include in a background script or use logging.

Remember to still use ref_qual_elements to list both "location" and "skill" in the above example, so that changing either triggers an update. The combination of script include + ref_qual_elements yields a powerful, maintainable dynamic filter solution.

GlideAjax and Client-Side Filtering

GlideAjax is a technique to call server-side code from client-side (asynchronously) without full page reload. In the context of Service Catalog, you might use GlideAjax in a Catalog Client Script to get data for dynamic operations. While not commonly needed just for reference qualifiers (since the platform handles the lookup refresh if configured correctly), GlideAjax can be used in advanced scenarios such as:

• Populating a regular select box with custom options retrieved from server (bypassing the need for a lookup variable).

• Forcing a reference qualifier to re-evaluate at a specific time or with additional parameters not directly tied to a single variable change.

• Working around any portal limitations (for example, if ref_qual_elements didn’t work in an older version on Service Portal, a client script with GlideAjax could fetch the needed options and set them manually).

  
  

Example scenario: Suppose you have two variables, but the filtering logic requires looking up some additional info from a third table or doing a calculation. You might decide to handle it via client script:

1. Create an onChange Catalog Client Script on the controlling variable (e.g., Country). In this script, you will call GlideAjax to get the filtered results for the dependent field (City).

2. Set up a Script Include (as shown before) or a GlideAjax Processor that can accept a country and return a list of cities (perhaps in a comma-separated string or JSON format).

3. In the client script, use something like:

// CityLookupAjax is a Script Include
var ga = new GlideAjax('CityLookupAjax');
// function to execute
ga.addParam('sysparm_name', 'getCitiesByCountry');
// pass the selected country
ga.addParam('sysparm_country', g_form.getValue('country')); 
ga.getXMLAnswer(function (response) {
	// assume this returns a comma-separated list or JSON of city options
	var cityList = response;
	// Now use the result to populate the City field
	g_form.clearOptions('city');
	// placeholder
	g_form.addOption('city', '', '-- Select a city --'); 
	if (cityList) {
		var cities = cityList.split(',');
		cities.forEach(function (city) {
			// city could be 'value:label' or similar format depending on how you return it
			var parts = city.split(':');
			g_form.addOption('city', parts[0], parts[1]);
		});
	}
});

In this pseudo-code, the GlideAjax call gets a list of cities for the given country and then the script manually populates a normal select box variable called 'city'. Note that this approach is populating a Select Box variable (not a Lookup select box) that you would have configured with no hard-coded choices. Alternatively, if using a lookup select box for City, you can't directly add options to it (since it derives from a table). But what you could do is use GlideAjax to compute an encoded query and then use g_form.setFilter or similar methods to set the reference qualifier on the fly. However, ServiceNow's API for catalog items is limited; the g_list object method was mentioned by some for modifying filters on the client side, but that generally applies to list collectors or older interfaces. A simpler method is to design your variable as a select box and populate it via script as shown.

GlideAjax is a more advanced solution and typically would be used if the out-of-box ref qualifier approach isn't sufficient. It requires writing client scripts and server code, which is more effort to maintain. Therefore, use it judiciously – for instance, when you need to retrieve complex data that a simple reference qualifier can't handle, or to refresh multiple fields at once in a very custom way.

When to Use Which Method?

• Use Simple or Advanced Reference Qualifiers with ref_qual_elements for most dependent field needs. This is declarative, easier to configure, and aligned with ServiceNow best practices. It keeps the logic tied to the variable itself, which is clean and typically upgrade-safe.

• Use Advanced with Script Include when the qualifier logic is complex or used in multiple places. This keeps scripts modular and reusable.

• Consider GlideAjax + Client Scripts as a fallback for edge cases, such as when the dynamic behavior needed can't be achieved with the standard qualifier setup or if you encounter a limitation in certain contexts (like an odd behavior in Service Portal or a need to dynamically generate options beyond just filtering a table query).

Always test in both the Service Catalog (platform UI) and the Service Portal if your users use both, to ensure the behavior is consistent.

By combining these methods, you can handle virtually any scenario of dynamic filtering or dependent selections in ServiceNow.

Conclusion

Using reference qualifiers with lookup select box variables in ServiceNow allows you to create interactive, user-friendly catalog forms with dependent dropdowns and dynamic choices. By carefully setting up the reference qualifier conditions and the ref_qual_elements attribute, you can ensure that one field’s input intelligently filters another field’s options in real-time, all in line with ServiceNow best practices. This not only enhances the user experience but also enforces data relationships (so users can’t pick mismatched values).

We explored how to configure these qualifiers, from simple static filters to advanced scripted queries, and provided a detailed example of Category/Subcategory dependency (a common requirement in ITSM scenarios). We also covered common issues – like a filter not working or a list not refreshing – and how to troubleshoot them. Remember, if you encounter issues, double-check your variable names, qualifier syntax, and the presence of the ref_qual_elements attribute (it’s often the missing puzzle piece in dynamic lookups).

For more complex requirements, we discussed alternative solutions like using GlideAjax and script includes to achieve dynamic filtering. While the out-of-the-box reference qualifier mechanism should be your first choice, these advanced techniques are available for scenarios where you need extra control or logic.

In summary, reference qualifiers are a powerful feature in ServiceNow that, when used with lookup select box variables, enable you to deliver dependent fields and context-driven choices in Service Catalog. This leads to cleaner data and a better overall experience for end-users filling out forms. By following the guidelines and examples in this article, you can confidently implement and troubleshoot reference qualifiers on lookup select boxes, creating catalog items that are both robust and user-friendly. Keep experimenting with use cases in your environment, and you'll uncover even more ways to streamline user input through dynamic filtering in ServiceNow. Happy building!