Open Site Navigation

Service Catalog Data Lookup

Updated: Oct 21, 2021

I've been searching for years for more documentation on Service Catalog matching tables and haven't been able to find any. There's plenty out there for matcher/lookup tables that can be applied to this concept, but I really wanted something that shot some lightbulbs off in my head about what these things could do specifically for the Service Catalog. This being said, this article is purely from experience and my own understanding of what matchers can do.


Service Catalog Matchers, so low code, so amaze. This functionality came out in the Istanbul low code era of ServiceNow. When I say low code era, I mean when ServiceNow really started focusing on solutions for users who didn't know code to use the platform. Service Catalog Matchers was a result of this, but, unfortunately they didn't get their time in the spotlight, and I know all too many organizations today that still use Catalog Client Scripts to accomplish many things that matchers can accomplish. I have no clue why ServiceNow hasn't promoted this functionality more as they move on to low code, no code. Perhaps they don't play with Flow Designer nicely, I'm not sure, that's another article for another time. For this article I'm going to be using Ye Olde Graphical Workflow Editor.

One thing to note, matcher tables are excluded (i.e. Free) according to ServiceNow's documentation on the new custom table licensing model.

I've only been at one organization that really utilized matchers for their Service Catalog. They were able to set things such as hardware type to assignment group, and I'll try to replicate that here in this article. I really enjoyed the use of assignment group on matcher tables, as this totally replaces having assignment groups scripted in on Workflows or Flows for most (not very complicated) scenarios. I'm going on the assumption most of you have catalog items with select boxes. For this article I went ahead and created a small select box noted below, as well as an Assignment Group variable. I housed this in a variable set to showcase the concept this could be used across Catalog items. Note: You can choose to show/hide the Assignment group variable if you want to your users on the Catalog Item form, but since we're setting it with matchers, it probably should be read only.

Service Catalog Setup

Here's the demo data I created for the Service Catalog for this article. It's also in the attached update set.

  1. Catalog Item: Service Catalog Matcher POC

  2. Variable Set: Assignment Group Matcher

  3. Variable: Assignment Group (Reference - Group)

  4. Variable: Support Type (Select Box, with the choices of Hardware, Software, Network)

  5. Workflow: Service Catalog Matcher POC - I just created a simple catalog task with the following script:

task.assignment_group = current.variables.assignment_group_var;	

So here's a run down of what you have to do to get started.

1. If you don't have the Data Lookup and Record Matching Support for Service Catalog plugin enabled (I think it's enabled by default on most new instances) go ahead and enable it. You may receive some message about $$, but you should be doing this in a Development instance anyways. I *think* it's bundled with Request Management, but please check with your ServiceNow representative before enabling this in Production.

Matcher Table

2. So here's where it starts to get complicated. You have to create a Matcher Table to house the data you're storing. Here's where a decision point needs to be made if you're planning on using this and scaling it. Do you have one big matcher table for all your Service Catalog items and keep adding variables to it, or do you create a Matcher Table per catalog item, or perhaps group of catalog items in order to not have one big sprawling table. The choice is yours, I state this because it's a question I asked myself when looking into this functionality for about 200+ catalog items.

For some reason the documentation doesn't state ANYTHING at all about creating and managing matcher tables for Service Catalog lookups, so here ya go. You'll see right off the bat a Matcher Table is mandatory, and you don't have any that really apply to what you're doing. I guess you could re-use the out-of-the-box tables, but I'm thinking you don't want a bunch of Service Catalog fluff in your Assignment or Priority lookups, so it's best to create a new table.

So what you're going to want to do in this step is head over to System Definition > Tables & Columns and create a new table EXTENDED from the Data Lookup Matcher Rules table. If you get lost just look at the Assignment Data Lookup table for guidance.

I'm going to name my table: Service Catalog Assignment Group Data Lookup, and I'm going to copy what the out-of-the-box tables use and append u_dl to my table name. This just lets me know at a quick glance this is a data lookup table.

I've created a module for my table, because I want to be able to access it easily, and potentially give others access to manage it in the future. This is where your design decision is really important, as the more granular your tables are, the more access you can give out.

I'm also going to put this under the Service Catalog menu, because it makes sense, but this can go wherever makes sense.

I'm going to keep the default access controls so I can give these out at a later time, as I may want Service Owners or Catalog Developers to update this table and not me. :)

Click 'Submit' to save the table. Now we can add some fields to our table that we're going to use for this walkthrough.

Create an 'Assignment group' reference field referencing Group (sys_user_group)

Create a 'Support Type' choice field with the same values created in the catalog item variable: Hardware, Software, Network.

Configure the form layout, and list layout to show these two fields.

Catalog lookup definition

3. Create a catalog lookup definition

Hooray, now we can start using these things. Head over to System Policy > Data Lookup Definitions, and choose 'Catalog Data Lookup Rule'

Fill out whatever you'd like for the name, for my purposes I'm just copying the catalog item name: Service Catalog Matcher POC. Leave Applies To as Catalog Item, choose the catalog item we created: Service Catalog Matcher POC, and select the matcher table we created above.

Note: You can have the matcher apply to a variable set as well, so if we wanted to extend this outside of this particular catalog item and have it effect the variable set we created above across multiple catalog item, then we would set Applies To as 'A Variable Set.'

Now we define the Catalog Matcher Variable Definitions and Catalog Setter Variable Definitions.

Catalog Matcher Variable Definitions

4. Click 'New' under Catalog Matcher Variable Definitions. Fill out the form as follows:

Source Variable name: Assignment Group Matcher > support_type_var

Matcher table field: Support Type

Exact lookup match: True

Note: The Exact lookup match checkbox - if checked only exact matches apply (e.g. Matcher fields that contain no data will not match against a record whose corresponding field contains data.)

You can set multiple matcher definitions, i.e. the row has to meet this condition AND this condition.

Catalog Setter Variable Definitions

5. Click 'New' under Catalog Setter Variable Definitions. Fill out the form as follows:

Source Variable name: Assignment Group Matcher > assignment_group_var

Matcher table field: Assignment Group

Always replace: True

Note: The Always replace checkbox - if checked a matching lookup will update the source field even if the matching field is blank.

You can define multiple Setter Definitions based upon one Matcher Variable definition, i.e set the Assignment Group AND another variable based upon the matcher, in our case Support Type.

Populate the Data Lookup table

6. Now that we have our matchers and setters setup, it's time to populate our table with data. We're going to align our support type with our assignment group.

Basically this is a lateral by row relationship. You match the Support Type variable with whichever Assignment Group you wish in that variable. I've set up the data as follows:

Notice the blank definition, we want the Assignment Group to clear out if the user selects none, so that's why this row exists.

Let's Test

7. Navigate to your catalog item and test out your matcher fields.

Here's our workflow at work, reflecting the Assignment Group on the task is set based upon our variable:


There are a few roles for Service catalog data lookup outside of the access roles for the specific matcher tables themselves. If you just want users to modify the matcher table rows, they can be granted the write access roles to the matcher table(s). If you want to allow users to modify/read the Matcher/Setter definitions the the following roles are provided:

  1. catalog_lookup_admin - Similar to data_lookup_admin. Can create, update, and delete catalog data lookup definitions, matcher variable definitions, and setter variable definitions.

  2. catalog_lookup_manager - Can read catalog data lookup definitions, matcher variable definitions, and setter variable definitions. The role can be granted to anyone using catalog data lookups so they can see the definitions for which they are creating rules. As required, grant create, read, write, or delete access to the individual data lookup rules tables created to delegate maintenance.


I hope this helped to demystify Service Catalog Data Lookup definitions and what they can do. While this is a very basic example, it shows the power of matchers without using (mostly) any code! It allows for on the fly changes to catalog item variables and even workflow driven values by leaving the base code in place while updating the matcher table. Next time you think about creating a Catalog Client Script, give matchers a try!


Service catalog data lookup

Tech Shorts Ep 10 - Data Lookup - This video isn't specific to Service Catalog, but is a great summary of Data Lookup tables.

Community Post - If you want an update set for this blog, it's housed on my community post.

1,423 views0 comments