Reference Qualifiers in ServiceNow
With Zach Koch
In this article, we're going to go over reference qualifiers. A reference qualifier is a tool that helps you filter out data that's returned by reference field, list collector, or anything that goes and grabs info from another table and brings it back to your reference field. There are three different types: simple, dynamic, and advanced.
Setting Up a Simple Reference Qualifier
We're going to go ahead and start off with the easiest one, which would be the simple reference qualifier. Our catalog item is going to use the simple reference qualifier. The first field will bring back any user who's active and the email contains test. We'll go ahead and click the search button; the results show that everybody has test in their email and they're all active. The second reference field will bring back all users who do not have test in their email. We’ll go ahead and click the search button; we can see there's no test in the emails shown.
Let's take a look at how to set one of these up. Shown is the variable is for the users who are active and email contains test. After you set up your type as a reference, and you come down to the type specification, you would set your reference to your reference table; this is the table you want to grab data from and bring it back. In your reference qualifier, you’ll select simple. With a simple reference qualifier, it uses a condition builder to bring back the data, and it will only bring back whatever is met by this condition. In this example, our conditions are set as: active is true and email contains test.
Setting Up an Advanced Reference Qualifier
Next, we’ll go over advanced reference qualifiers; they'll make the use of dynamic reference qualifiers a little easier to understand. Whenever you need to filter out the data and it's more complex and requires a scripted solution, you would use an advanced reference qualifier. There are a few steps we'll go over with this one, as it has more pieces than just the condition on the variable.
We have the catalog item (reference video at 2:40) that we're going to use as an example. You can select the user that you wish to edit, and in the remove from group field, It will bring a list of groups that the user is currently in. In the add to the group field, it will bring back all the groups they are not a part of. If we change the user, we'll see that change around, and all the groups have shifted.
Let's take a look at how that's achieved. We're going to look at the remove from group variable first. In our example, you can see it is a list collector type, which is also referencing another table. In your type specifications, you'll have to select the list table that you wish to grab data from. Where this varies is that you're not going to use that condition builder; you're actually going to call a script include in a function (reference video at 3:44).
Let’s take a look at that script include. Using that function, it's feeding it that user that we selected. We're going to the table here, and we're going to query it for that user that we selected. While it finds any records, it's going to push those groups into an array. After you have everything that you want from your GlideRecord query, you will return that information. This next line is making sure that admin is not a selectable group, and then it's returning the group selected array that we pushed from there. It's going to only return the groups that they're in, so that they can be removed; it won't let you try to remove someone from a group that they're not in.
Looking at the next variable, it's pretty much the opposite. We have the same thing here —the script include, the function, and then what we're going to give to the function. The same script is shown for simplicity sake. You could always combine this into one script function on the same script (reference video at 5:13). For our example, we split it up to make the example a bit more clear. The only difference here is we're going to be returning the groups they're not in, so that they can be added. To clarify, it won't return any groups that they are already in. only the ones they're not in. Again this is the advanced reference qualifier. Now that we've gone over that, we'll go over the last example, which is the dynamic reference qualifier.
Setting Up a Dynamic Reference Qualifier
The dynamic reference qualifier is essentially the same as an advanced reference qualifier, it's just reusable. They still require that initial setup, where you set up the script include and the function, but they're easier to reuse if you have multiple variables which you wish to use the exact same advanced reference qualifier. We'll go ahead and look at an example of that.
Here, we did use something similar to the previous example just to make it a little bit easier to understand. In the first field, we can select a user, and what it will do is return all the groups that they're not in, so that you can add them to those groups. You can see the results are different each time. Now we'll go to the variable and take a look at what's different in a dynamic versus an advanced.
You're going to have a type of reference field selected and in your type specifications, you're going to select your table that you're referencing. In the user reference qualifier field, you're going to select dynamic and this will show the dynamic reference qualifier field, which you can populate yourself. This is where you're selecting the dynamic reference qualifier and where this table is coming from (reference video at 7:16). You can see here is pulling off the dynamic filter options table, so we'll go ahead and look at that.
That was user groups, so we're on that table here. This is the dynamic filter; looking at that you can see the name of it. In addition, here is where you would set up that same script include and function that you did for the advanced reference qualifier. We're calling that script include with the function, and the variable that we're feeding it. Now obviously when you're using a dynamic reference qualifier, you're going to want to try to make your variables as general as possible because the more specific it is, the more specific it's going to be in its use case.
The only difference in this field versus the other one is that you do not need to prefix javascript to your script include after you put it in the label field. Next, you're going to select your reference table. This is important because, going back to our variable page, if you select a different table, you're actually going to get different dynamic filters.
For our example, we’ll choose a table and clear out the dynamic reference qualifier field. We’ll then search that table. There's no dynamic filters on this table, so if we want to use that user groups dynamic filter that we created earlier, we're going to need to go to the sys_user_group table. Now that we're on that table again, we can check and see, there was our dynamic filter, so we can select that.
Again, the main difference between an advanced reference qualifier and a dynamic one is that after you set up a dynamic reference qualifier on the dynamic filters options table, you can reuse that anytime you select dynamic reference qualifier, as long as your function and your script include take into account whatever item you're going to use it on, or whatever variables it needs.
Did you find this Introduction to Reference Qualifiers in ServiceNow article helpful? Are you ready to start your journey with ServiceNow? If you want to find out more information about GlideFast Consulting and our ServiceNow implementation services, you can reach out to us here.
About GlideFast Consulting
GlideFast is a ServiceNow Elite Partner and professional services firm that provides tailored solutions and professional services for ServiceNow implementations, integrations, managed support services, application development, and training. Reach out to our team here.