R

eference qualifiers are a powerful tool that every ServiceNow administrator and consultant should have in their tool belt. They allow you to dynamically filter the available options from a reference field. The ServiceNow wiki has some good documentation on this topic so I won’t re-hash that here. What I do want to address is the topic of Advanced Reference Qualifiers…specifically how to leverage a Script Include instead of a global Business Rule to run your qualifier script.

Reference Qualifier Script Include

Up until recently, the only way to get Advanced Reference Qualifiers to work was to create a global business rule to run the qualifier script. This works great, but it results in a global script that gets loaded all the time when it really isn’t necessary. While this isn’t something that causes any real problems in practice, it could cause performance issues if used to the extreme. The best practice guidance for advanced reference qualifiers should be to use a Script Include rather than a global Business Rule to run the qualifier script. Using a Script Include means that the script only gets loaded and used when you actually need to use it! In this article I’ll show you how this can be done using a common example of filtering the ‘Assignment group’ to display only groups for the ‘Assigned to’ value.

The first piece is the ‘Reference qual’ field value on the dictionary entry of the reference field (Assignment group in this case). The ‘javascript:’ prefix is the same, but you need to reference your Script Include function instead of the business rule function. In this case, I’m using a Script Include named ‘u_backfillAssignmentGroup’. Since these scripts can potentially interfere with each other, it’s best to prefix any of your custom scripts with ‘u_’ or something similar in order to distinguish them from any that ServiceNow may introduce in the future.

javascript:u_backfillAssignmentGroup();

The other piece is obviously the Script Include. Since Script Includes now allow you to use On-Demand functions, your script is identical to the one you would use in a global business rule.

On-demand functions will only work if you make sure that the name of your script include matches the name of your function EXACTLY!
function u_backfillAssignmentGroup() {
   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;
}