The Unsung APIs of ServiceNow #3 - CatalogSearch

[SumanthDosapati]

🔎 The Unsung APIs of ServiceNow — Ep. 3: CatalogSearch

We’ve all seen beautifully crafted catalog pages with tiles, filters, and dynamic search features. But have you ever wondered what powers those intelligent search experiences behind the scenes?

Well, it’s time to meet another underrated hero in the ServiceNow platform — the CatalogSearch API.

---

🎯 What is CatalogSearch?

The CatalogSearch API provides a programmatic way to search catalog items from within a scoped application. It's perfect for building custom portals, search widgets, or automation scripts that need to interact with the Service Catalog.

Unlike direct GlideRecord queries on sc_cat_item, this API respects catalog permissions, mobile filters, and search relevance. It also supports deep category traversal and mobile-specific searches.

---

🧪 Real-World Use Case

✅ 1. Search the Catalog item for a Keyword

var catSearchGR = new sn_sc.CatalogSearch().search('', '', 'Apple', false, true);
catSearchGR.query();
while (catSearchGR.next()) {
  gs.info(catSearchGR.getValue('name'));
}

🧠 What’s happening here?

• '' (empty string) means all catalogs

• '' (empty string) means all categories

• 'Apple' is the search keyword

• false means we’re not filtering for mobile catalog items

• true disables subcategory traversal (only searches the current level)

If there are catalog items like “Apple MacBook Pro” or “AppleCare Plan”, they’ll show up in this result.

---

✅ 2. Search All Catalogs and Categories for "ServiceNow"

var now_GR = new sn_sc.CatalogSearch().search('', '', 'ServiceNow', false, false);
now_GR.query();
while (now_GR.next()) {
  gs.log(now_GR.name);
}

Here, false for the last parameter tells the search to include subcategories, making it more exhaustive. You might see results like:

ServiceNow T-shirt
ServiceNow Onboarding
ServiceNow Training Access

---

📚 API Method Summary

Method	Description
search(catalogID, categoryID, term, mobile, noDepthSearch)	Performs a scoped, permission-aware search for catalog items

Parameters:

• catalogID: String – limit search to a specific catalog (use sys_id)

• categoryID: String – limit to a specific category (use sys_id)

• term: String – the search keyword

• mobile: Boolean – whether to restrict to mobile-visible items

• noDepthSearch: Boolean – true = shallow (no subcategories), false = deep (include subcategories)

Returns: GlideRecord on sc_cat_item

---

🤖 Bonus Tip: Use it to Build Custom Search Widgets

Let’s say you're building a Service Portal widget for catalog search. Instead of looping through sc_cat_item with complex encoded queries, use this:

var results = [];
var gr = new sn_sc.CatalogSearch().search('', '', input.term, false, false);
gr.query();
while (gr.next()) {
  results.push({
    name: gr.getValue('name'),
    description: gr.getValue('short_description'),
    id: gr.getUniqueValue()
  });
}
data.results = results;

This respects catalog visibility rules and ensures consistent results across UI and server logic.

---

💡 Why This API Deserves the Spotlight

Most developers either rely on hardcoded GlideRecord queries or use catalog item references directly. But CatalogSearch is:

• Secure: Respects catalog visibility & roles

• Efficient: Filter by catalog, category, keyword, or mobile scope

• Scoped: Safe to use in custom apps or portals

It’s tailor-made for building custom user experiences without sacrificing platform alignment.

---

📝 Final Thoughts

If you're developing a custom portal or building a smarter catalog interface, don’t skip this API. CatalogSearch offers you a clean, safe, and flexible way to access catalog items with powerful filtering baked in.

---

🚀 Up Next in the Series
In the next episode of "The Unsung APIs of ServiceNow", I’ll explore DurationCalculator - an API that allows you to evaluate complex encoded queries programmatically. If you've ever wanted to simulate list filter behavior in a script, this one's for you.

Have an unsung API in mind? Let me know—I’d love to include it in the series and credit you as a contributor.

Until then, happy building!
— Sumanth Dosapati