let gr = new GlideRecord(someTable);
gr.addQuery(someField, someValue);
gr.addNotNullQuery(someOtherField);
gr.query();
while (gr.next()) {
  // do the thing...
}

new GlideQuery(someTable)
  .where(someField, someValue)
  .whereNotNullQuery(someOtherField)
  .select(someFields)
  .forEach((record) => {
    // do the thing...
  });

The difference might be subtle or it might jump out at you right away. They’re the same number of lines and they seem to be doing all the same steps in the same order (indeed they are). What is it about GlideRecord and GlideQuery that makes the syntax appear so different, and, if this is important, why is it important?

GlideRecord is founded on object mutation

In the GlideRecord example, we first instantiate an object and assign it to a variable. From that point on we call methods on the object that cause the object to change. We don’t have to assign the output of those method calls to any new variable, because each time we add a new query the object itself changes. When we execute the query the object changes again, and each time we iterate to the next record the object changes yet again. And the whole time it remains assigned to the same variable name.

These changes in the object are sometimes called mutations or side effects, and some consider it best practice to avoid them. But aren’t variables meant to vary? After all, it’s right there in the name “variable”. What’s really wrong with allowing the GlideRecord object to mutate like this? We saw one extreme (and thankfully uncommon) example in Part 0 and Part 2 where mutation due to the next method caused undesirable behavior, but are there other drawbacks?

GlideQuery objects are immutable

In functional programming there’s a design pattern called a pure function. Pure functions always produce the same output given the same input and have no observable side effects. All GlideQuery objects are immutable, meaning there’s no way to change them after they’re created. All the methods of the GlideQuery API are pure functions, so, when you call any of them, instead of mutating the object, the method leaves the original object unchanged and returns a new object that’s like the old one but with the new step applied.

This is cumbersome, but it helps to see what’s really going on if we rewrite the GlideQuery example above like this:

let query1 = new GlideQuery(someTable)
let query2 = query1.where(someField, someValue)
let query3 = query2.whereNotNullQuery(someOtherField)
let stream = query3.select(someFields)
stream.forEach((record) => {
  // do the thing...
});

Here you can see clearly that with each new step we get back a new GlideQuery or Stream object (we’ll talk more about Stream and Optional objects in Part 4). In this example we’re assigning each object to a new variable, then using that variable to call the method for the next step.

Fluent method chaining

One immediate benefit of this pure function architecture is it enables GlideQuery’s fluent method chaining style. We usually don’t have any need to keep all those intermediate objects so we don’t bother assigning them to variables. Each chained method call simply acts on the new object returned from the preceding method call. This generally leads to shorter and cleaner-looking lines of code and fewer overall keystrokes.

When you chain methods like this, even though the method calls span multiple lines, you’re actually creating one long single expression. This means in some cases, like our first GlideQuery example above, you don’t need to assign anything to a variable. If you do start with declaring a variable, keep in mind the value assigned to the variable will be the result of the entire expression.

let n = new GlideQuery(table)
  .where(someField, someValue)
  .count()

The GlideQuery object instantiated on the first line never gets assigned to n. Instead, the entire method chain is evaluated and, ultimately, the variable will be assigned the return value from the count method.

And notice the indentation convention used here. Indenting each of the chained method call lines with a single tab is deliberate and recommended since it reminds us the whole thing is one long expression, not a series of individual expressions or statements.

Object re-usability

A less obvious but very powerful feature of this pure functional architecture is object re-use. Since the intermediate objects are never mutated, if we do decide to save one by assigning it to a variable, we can go back and re-use it later.

Let’s say we want to send an e-mail to everyone in our department who got an above average score on the most recent customer satisfaction survey. In order to do that, we first need to know what the average is. For simplicity, let’s assume we’ve already calculated each team member’s score and stored it in a custom field on the User [sys_user] table.

Without GlideQuery, the best way to do this is with GlideAggregate to get the average and then GlideRecord to loop through the users and send the e-mails.

let ga = new GlideAggregate('sys_user');
ga.addQuery('department', someDepartment);
ga.addQuery('active', true);
ga.addNotNullQuery('u_csat_score');
ga.addAggregate('AVG', 'u_csat_score');
ga.query();
ga.next();
let average = ga.getAggregate('AVG', 'u_csat_score');

let gr = new GlideRecord('sys_user');
gr.addQuery('department', someDepartment);
gr.addQuery('active', true);
gr.addNotNullQuery('u_csat_score');
gr.addQuery('u_csat_score', '>', average);
gr.query();
while (gr.next()) {
  // send e-mail...
}

Notice how the first four lines are nearly identical in the two different blocks of our script? This is a simple example, but imagine if our query were even more complicated. Wouldn’t it be great if we could somehow only write those lines once? We can’t do that with GlideAggregate and GlideRecord, but we can with GlideQuery.

let query = new GlideQuery('sys_user')
  .where('department', someDepartment)
  .where('active', true)
  .whereNotNull('u_csat_score');

let average = query  // using query once
  .avg('u_csat_score')
  .get();

query  // using query a second time
  .where('u_csat_score', '>', average)
  .select(someFields)
  .forEach((user) => {
    // send e-mail...
  });

After calling the avg and get methods you might think the query object is all used up, but since it doesn’t mutate like a GlideRecord object we can re-use it—even adding an additional where clause—to send the e-mails.¹

I’ve used this in Script Includes where many different methods start by executing nearly the same query. The query can be assigned to a property of the object and then re-used across all the methods. They’re also great for enabling more dynamic function behavior since immutable GlideQuery objects can safely be passed around as function arguments. Once you know what’s possible you’ll find all sorts of uses for this feature.

Conclusion

Hopefully I’ve convinced you GlideQuery’s stateless, immutable design is safer than GlideRecord overall and enables both a more fluid syntax and some handy new use cases. Stay tuned for Part 4 where we’ll cover the myriad ways you can process Streams and Optionals. 

JavaScript native variable types

A big part of how GlideQuery acts like JavaScript is its consistent use of JavaScript native types. For example, if you ask GlideQuery to return the contents of an Integer or Decimal column in the ServiceNow database, GlideQuery will give you the value as a native JavaScript number. If you ask it to return the contents of a True/False field, you’ll get a native JavaScript boolean.

var inc = new GlideQuery('incident')
  .get(exampleID, ['description', 'sys_mod_count', 'active'])
  .get();

typeof inc.description === 'string';    // true
typeof inc.sys_mod_count === 'number';  // true
typeof inc.active === 'boolean';        // true

As you can see, they’re not Java types nor are they Java objects. Refreshingly, GlideElement is nowhere to be found here.

In hindsight, GlideRecord is more sane than I thought

Years ago I adopted the best practice of just always using getValue() whenever interacting with columns on a GlideRecord object (and many other people have also, or have advocated for some alternative). But in researching this series I’ve come to realize GlideElement objects actually behave more intuitively than I remembered.

Because Integer and Decimal columns are evaluated to GlideElementNumeric objects, you can do math with them directly. Similarly, because Boolean columns come out as GlideElementBoolean objects (and Java booleans), they work fine in logic operations and conditionals.

But there are two significant issues with GlideRecord and GlideElement objects that drove us all to adopt getValue() in the first place, and they’re both handily avoided by GlideQuery’s use of native types.

No mutable object shenanigans

As I explained in Part 0, GlideElement objects mutate when the next() method is called, producing some unexpected behavior. Since column values returned by GlideQuery are just JavaScript native types (strings, numbers, and booleans) and not GlideElement objects or any other Java types, they’re naturally immutable:

var result = [];

new GlideQuery('incident')
  .select('number')
  .forEach(function (inc) {
    result.push(inc.number);
  });

result;  // ['INC0010001', 'INC0010002', 'INC0010003', ...]

(Note there are better ways to load values into an array with GlideQuery, so don’t follow this example—I’ll give you a better one in Part 4 of the series.)

We already know using getValue() turns GlideElement objects into JavaScript primitive types, preventing unexpected behavior, but GlideQuery shines here for not having the problem in the first place. And stay tuned as I’ll have more to say about object mutation in Part 3.

Strict comparisons are possible

Another benefit of GlideQuery’s use of native types is they can safely be strictly compared with other values.

var inc = new GlideQuery('incident')
  .getBy({ number: 'INC0010005' }, [ 'number' ])
  .get();

inc.number == 'INC0010005';   // true
inc.number === 'INC0010005';  // true

As I mentioned in Part 0, GlideRecord’s inconsistent behavior here made me distrust strict equality in JavaScript in my early ServiceNow days. Continuing the pattern, using getValue() and/or casting to the appropriate native type works the same way, but GlideQuery gives us the value in the correct native type without any casting or coercion. Easy peasy.

JavaScript native objects

In addition to column values being native types, even whole objects returned by GlideQuery are native JavaScript objects. I can think of three reasons why this is useful (and you can probably think of more).

Easier debugging

Maybe the simplest implication of GlideQuery returning native objects is the whole object can be logged out for quick and easy debugging.

var inc = new GlideQuery('incident')
  .get(exampleID, ['number', 'short_description'])
  .get();

gs.debug(inc);

// {
//   "sys_id": "...",
//   "number": "INC0010005",
//   "short_description": "Email server is down"
// }

Easier JSON serialization

Another nice use case for this is that objects returned by GlideQuery can be directly serialized into JSON for sending across a REST connection. How many Scripted REST APIs have you written where you had to copy data out of a GlideRecord object into a native object before it could be serialized? Consider this example I found in ServiceNow’s documentation (“Scripted REST API example - streaming vs object serialization”):

(function runOperation(request, response) {
  result_arr = [],
  
  gr = new GlideRecord('incident');
  gr.setLimit(100);
  gr.query();

  // iterate over incident records and build JSON
  // representations to be streamed out
  while (gr.next()) {
    var incidentObj = {};
    incidentObj.number = gr.number + '';
    incidentObj.short_description = gr.short_description + '';
    result_arr.push(incidentObj);
  }
  
  return result_arr;
})(request, response);

This looks simple enough, but imagine we had a lot more fields to load into the objects to be serialized—the more fields we had, the more lines of code we’d need.

This is much nicer to implement with GlideQuery. Since the objects are already native objects, we can push each one onto the array as is and return the array with full confidence it can be safely stringified into JSON.

(function runOperation(request, response) {
  result = [],

  new GlideQuery('incident')
    .limit(100)
    .select('number', 'short_description')
    .forEach(function (inc) {
      result.push(inc);
    });
  
  return result;
})(request, response);

(As before, note this is a poor way to create arrays with GlideQuery. I kept this similar to the GlideRecord example for a more apples-to-apples comparison. Again, keep an eye out for better array examples in Part 4.)

Native object methods

Yet another benefit to GlideQuery’s native objects is all of JavaScript’s object methods can be used such as hasOwnProperty(). We can also use helper functions like Object.keys() and features like for...in loops.

var inc = new GlideQuery('incident')
  .get(exampleID, ['number', 'short_description'])
  .get()

for (var field in inc) {
  gs.debug(field + ': ' + inc[field]);
}

// sys_id: ...
// number: INC0010005
// short_description: Email server is down

(And if you’re lucky enough to be on the Tokyo release or later and in a context where you can use modern JavaScript language features, you might find a use for Object.entries() or Object.values().)

Conclusion

Because GlideQuery behaves so much more predictably in always returning JavaScript native types and native objects, a lot of confusion and potential bugs are avoided. We get the simple convenience of rarely if ever having to convert values and objects into other kinds of values and objects, and we get the benefits of JavaScript native methods for the various types. I’m certain I would’ve more intuitively understood and had a lot more trust in the platform in my early years if I’d cut my teeth scripting with GlideQuery instead of GlideRecord. 

Next in the series: Part 3: Pure Functions, Fluent Method Chaining, and Object Re-usability →

One of the problems I mentioned in Part 0 is that GlideRecord is squirrelly when it comes to precedence of logical AND and OR. GlideQuery avoids this issue by disallowing ambiguous boolean logic.

Mind your ANDs and ORs

To avoid uncertainty in queries, GlideQuery’s interface requires you to nest AND’s and OR’s that could have more than one possible order of operation.

For example, “A AND B AND C” raises no cause for alarm, as does “A OR B OR C”, but “A OR B AND C” is problematic. How so? You could simply evaluate the logic in order, taking the OR first and then the AND. However, in most programming languages and query languages, including JavaScript, AND takes precedence over OR (without any need for parentheses; cf. how multiplication takes natural precedence over addition in arithmetic), but, curiously, in ServiceNow queries—both encoded queries and GlideRecord queries—OR has always taken precedence over AND. In fact, with normal calls to addQuery and addOrCondition, it’s not even possible to force AND to take precedence over OR (you have to switch to using an encoded query with the ^NQ operator).

Given the inconsistency, you can see there’s a lot of potential for confusion here. Rather than simply evaluating a query from left to right, and rather than letting either logical operator take precedence over the other, GlideQuery takes the approach of simply always requiring parentheses (in a manner of speaking) so that there is never any ambiguity about order of operations in a query.

The following is fine in GlideQuery:

new GlideQuery('incident')
  .where('active', true)
  .where('short_description', 'CONTAINS', 'blue smoke')
  .where('assigned_to.name', 'ITIL User');

And this is fine, too:

new GlideQuery('incident')
  .where('active', true)
  .orWhere('short_description', 'CONTAINS', 'blue smoke')
  .orWhere('assigned_to.name', 'ITIL User');

But the following will throw what GlideQuery calls a “nice error”:

new GlideQuery('incident')
  .where('active', true)
  .orWhere('short_description', 'CONTAINS', 'blue smoke')
  .where('assigned_to.name', 'ITIL User');

Nice errors

You might think this is annoying, but GlideQuery throws a lot more errors than GlideRecord very much on purpose. It’s trying to help you discover bugs or potential problems immediately after writing your code, rather than silently failing in such a way that you may not notice problems until weeks down the road (and probably in the production environment by then). We’ll talk a lot more about nice errors in Part 5 of this series.

In the case of our third example above, the error is “Ambiguous query: cannot contain multiple where() expressions with an orWhere() expression”, and, as with all nice errors, execution of your script will simply stop. GlideQuery refuses to go any further in order to avoid the possibility of any data corruption or worse. I’m almost never jazzed when I see a nice error, but I’m really glad GlideQuery throws them because that little bit of pain up front helps me identify the problem immediately and avoid what would probably have been a lot more pain later.

How to write “parentheses” in GlideQuery

The way GlideQuery disambiguates whether AND should come before OR and vice versa is by having you pass a new table-agnostic GlideQuery object as the only parameter to a where or orWhere clause, like these examples:

// (active OR blue smoke) AND itil user
new GlideQuery('incident')
  .where(new GlideQuery()
    .where('active', true)
    .orWhere('short_description', 'CONTAINS', 'blue smoke'))
  .where('assigned_to.name', 'ITIL User');
  
// active OR (blue smoke AND itil user)
new GlideQuery('incident')
  .where('active', true)
  .orWhere(new GlideQuery()
    .where('short_description', 'CONTAINS', 'blue smoke')
    .where('assigned_to.name', 'ITIL User'));

Doing it this way feels somewhat cumbersome (count your parentheses carefully!), but if a little awkwardness is the price to pay for clearer code, I’m here for it. Usually, writing them the way I have above is readable enough, but you could make this look less busy and complicated by assigning the sub-queries to variables beforehand.

Conclusion

ServiceNow’s inexplicable “OR” bias has always bothered me, but the way these GlideQuery clauses can be nested addresses my gripe and makes the boolean logic more transparent and precise. And recall that with GlideRecord you can’t make AND take precedence over OR without resorting to encoded queries, so being able to do so with normal calls to where and orWhere with GlideQuery is a massive improvement.

That’s it for this installment. I hope this starts to persuade you GlideQuery is superior to GlideRecord and should be the way forward for all pro-code solutions on the ServiceNow platform, and I hope you’re looking forward to future articles in the series. Cheers! 

Next in the series: Part 2: JavaScript Not Java →

For example, we might’ve hardcoded some specific user to be an approver on a request, but of course it’s only a matter of time before that user transfers departments, gets a promotion, or leaves the company and then that process is broken. In an effort to mitigate the issue, we might use a group instead, but if nobody’s paying attention it doesn’t take long for all the users in the group to rotate out and then we’re right back in the same boat.

Though it probably deserves a blog post all its own, preventing/solving this problem by establishing better practices up front isn’t my topic today. Instead I want to share a project I worked on recently that’s enabled us to be more proactive in reducing incidents related to the problem.

The Script Include

Here’s a Script Include that can help you locate hardcoded values in legacy Workflows and Flow Designer Flows:

var HardcodedValuesLocator = function (table, tableQuery) {
  return (function () {

    /////// INITIALIZATION ///////

    if (typeof tableQuery === 'undefined')
      tableQuery = new GlideQuery();

    var displayColumn = gs.getDisplayColumn(table);

    var records = new GlideQuery(table)
      .where(tableQuery)
      .whereNotNull(displayColumn)
      .select(displayColumn)
      .reduce(function (acc, record) {
        acc[record.sys_id] = record[displayColumn];
        return acc;
      }, {});

    var recordIDs = Object.keys(records);

    /////// PUBLIC FUNCTIONS ///////

    function findInFlows(flowQuery) {
      flowQuery = flowQuery || new GlideQuery()
        .where('active', true);

      var flows = new GlideQuery('sys_hub_flow')
        .where(flowQuery)
        .select()
        .reduce(function (acc, flow) {
          return acc.concat(flow.sys_id);
        }, []);

      var actions = new GlideQuery('sys_hub_action_instance')
        .where('flow', 'IN', flows)
        .select('flow', 'flow$DISPLAY')
        .reduce(function (acc, action) {
          acc[action.sys_id] = action;
          return acc;
        }, {});

      var result = new GlideQuery('sys_element_mapping')
        .where('id', 'IN', Object.keys(actions))
        .whereNotNull('value')
        .select('value', 'id')
        .map(function (mapping) {
          mapping.values = mapping.value.split(/\b/); // split on word boundaries
          return mapping;
        })
        .filter(function (mapping) {
          return mapping.values.some(function (value) {
            return Boolean(records[value]);
          });
        })
        .reduce(function (acc, mapping) {
          return acc.concat(mapping);
        }, []);

      result = result.concat(
        new GlideQuery('sys_variable_value')
          .where('document', 'sys_hub_action_instance')
          .where('document_key', 'IN', Object.keys(actions))
          .where('variable.reference', table)
          .whereNotNull('value')
          .select('value', 'document_key')
          .map(function (variable) {
            variable.id = variable.document_key;
            variable.values = variable.value.split(',');
            return variable;
          })
          .filter(function (variable) {
            return variable.values.some(function (value) {
              return Boolean(records[value]);
            });
          })
          .reduce(function (acc, variable) {
            return acc.concat(variable);
          }, [])
      );

      function getDisplayValuesWithReferences() {
        return result.reduce(function (acc, mapping) {
          var flow = actions[mapping.id].flow$DISPLAY.trim();
          if (typeof acc[flow] === 'undefined') {
            acc[flow] = [];
          }

          var intersection = mapping.values
            .reduce(function (acc, value) {
              var record = records[value];
              if (record) acc.push(record.trim());
              return acc;
            }, []);

          acc[flow] = acc[flow].concat(intersection);
          return acc;
        }, {});
      }

      function getSysIds() {
        return result.reduce(function (acc, mapping) {
          var flowId = actions[mapping.id].flow;
          if (acc.indexOf(flowId) == -1)
            acc.push(flowId);
          return acc;
        }, []);
      }

      return {
        getDisplayValuesWithReferences: getDisplayValuesWithReferences,
        getSysIds: getSysIds
      };
    }

    function findInWorkflows(workflowVersionQuery) {
      workflowVersionQuery = workflowVersionQuery || new GlideQuery()
        .where('published', true);

      var workflowVersions = new GlideQuery('wf_workflow_version')
        .where(workflowVersionQuery)
        .select()
        .reduce(function (acc, workflow) {
          return acc.concat(workflow.sys_id);
        }, []);

      var activities = new GlideQuery('wf_activity')
        .where('workflow_version', 'IN', workflowVersions)
        .select('workflow_version', 'workflow_version$DISPLAY')
        .reduce(function (acc, activity) {
          acc[activity.sys_id] = activity;
          return acc;
        }, {});

      var result = new GlideQuery('sys_variable_value')
        .where('document', 'wf_activity')
        .where('document_key', 'IN', Object.keys(activities))
        .where('variable.reference', table)
        .whereNotNull('value')
        .select('value', 'document_key')
        .map(function (variable) {
          variable.values = variable.value.split(',');
          return variable;
        })
        .filter(function (variable) {
          return variable.values.some(function (value) {
            return Boolean(records[value]);
          });
        });

      function getDisplayValuesWithReferences() {
        return result.reduce(function (acc, variable) {
          var workflow = activities[variable.document_key].workflow_version$DISPLAY.trim();
          if (typeof acc[workflow] === 'undefined') {
            acc[workflow] = [];
          }

          var intersection = variable.values
            .reduce(function (acc, value) {
              var record = records[value];
              if (record) acc.push(record);
              return acc;
            }, []);

          acc[workflow] = acc[workflow].concat(intersection);
          return acc;
        }, {});
      }

      function getSysIds() {
        return result.reduce(function (acc, variable) {
          var workflowId = activities[variable.document_key].workflow_version;
          if (acc.indexOf(workflowId) == -1)
            acc.push(workflowId);
          return acc;
        }, []);
      }

      return {
        getDisplayValuesWithReferences: getDisplayValuesWithReferences,
        getSysIds: getSysIds
      };
    }

    /////// RETURN ///////

    return {
      findInFlows: findInFlows,
      findInWorkflows: findInWorkflows
    };

  })();
};

Basic usage

So far we’ve been using this by just calling it manually in a background script and having it log out the results, but you could conceivably call it from a scheduled job to either notify someone or raise tasks to clean up newly discovered issues. Even better might be calling it from an ATF test.

When you call the HardcodedValuesLocator you must provide a table you’re looking for hardcoded values from (sys_user and sys_user_group are the common ones, but go nuts if you have something else you’re looking for). You get back an object with a couple of methods, findInFlows and findInWorkflows, which do pretty much what they say on the tin. You can of course assign the object to a variable and then make the subsequent method call like this:

var hvl = HardcodedValuesLocator('sys_user');
var result = hvl.findInFlows();

Or I like to chain the method calls together more fluidly like this:

var result = HardcodedValuesLocator('sys_user')
  .findInFlows();

The result here is another object that has the data you’re after, but not yet in a form that’s immediately useful. You have two options at this step, (1) get the data as sys_ids by calling the getSysIds method. This would be useful if you’re building some automated process and you need the result to be machine-readable so you can perform subsequent processing yourself.

var machineReadableResult = HardcodedValuesLocator('sys_user')
  .findInFlows()
  .getSysIds();
  
// Your processing logic goes here...

Or (2) get the data in human-readable display values with the getDisplayValuesWithReferences method, and here you’ll probably want to send the result to the System Log:

var humanReadableResult = HardcodedValuesLocator('sys_user')
  .findInFlows()
  .getDisplayValuesWithReferences();
  
gs.info(JSON.stringify(humanReadableResult, null, 2);

Advanced options

There are a few more parameters you can pass to these functions to make your searches more targeted. First, when you call the HardcodedValuesLocator Script Include you can optionally pass a GlideQuery object as the second parameter. This is useful if you’re only looking for specific users, like inactive ones:

HardcodedValuesLocator('sys_user', new GlideQuery().where('active', false);

Additionally, you can filter which Workflows you’re searching by optionally passing a GlideQuery object to the findInFlows method, for example, if you only want to search in currently published Flows:

hvl.findInFlows(new GlideQuery().where('active', true));

Your use cases for this will likely vary from mine, so you’re welcome to call these methods with whatever queries you need, but here’s an example script I’ve been using to categorize and sort hardcoded users and groups by most concerning to least concerning:

(function () {
  // Get some useful data up front
  var catalogWorkflows = new GlideQuery('sc_cat_item')
    .where('active', true)
    .whereNotNull('workflow')
    .select('workflow')
    .reduce(function (acc, catItem) {
      return acc.concat(catItem.workflow);
    }, []);

  var catalogWorkflowVersions = new GlideQuery()
    .where('published', true)
    .where('active', true)
    .where('workflow', 'IN', catalogWorkflows);

  var otherWorkflowVersions = new GlideQuery()
    .where('published', true)
    .where('active', true)
    .where('table', '!=', 'sc_req_item');

  var groups = new GlideQuery('sys_user_grmember')
    .whereNotNull('user')
    .whereNotNull('group')
    .groupBy('group')
    .aggregate('count');

  var groupsWithActiveMembers = groups
    .where('user.active', true)
    .select()
    .reduce(function (acc, groupMember) {
      return acc.concat(groupMember.group.group);
    }, []);

  var groupsWithInactiveMembers = groups
    .where('user.active', false)
    .select()
    .reduce(function (acc, groupMember) {
      return acc.concat(groupMember.group.group);
    }, []);

  // Define searches we want to perform from most to least concerning
  var searches = [
    {
      description: 'Hardcoded inactive users',
      table: 'sys_user',
      query: new GlideQuery()
        .where('active', false)
    },
    {
      description: 'Hardcoded groups with no active members',
      table: 'sys_user_group',
      query: new GlideQuery()
        .where('sys_id', 'NOT IN', groupsWithActiveMembers)
    },
    {
      description: 'Hardcoded groups with at least one inactive member',
      table: 'sys_user_group',
      query: new GlideQuery()
        .where('sys_id', 'IN', groupsWithInactiveMembers)
    },
    {
      description: 'Hardcoded active users',
      table: 'sys_user',
      query: new GlideQuery()
        .where('active', true)
    }
  ];

  for (var i = 0; i < searches.length; i++) {
    // Do each search in all three places and output the results
    var flowsResult = HardcodedValuesLocator(searches[i].table, searches[i].query)
      .findInFlows(new GlideQuery().where('active', true))
      .getDisplayValuesWithReferences();
    
    if (Object.keys(flowsResult).length) {
      gs.print('\n' + searches[i].description + ' in flows:');
      gs.print(JSON.stringify(flowsResult, null, 2));
    }

    var catalogWorkflowsResult = HardcodedValuesLocator(searches[i].table, searches[i].query)
      .findInWorkflows(catalogWorkflowVersions)
      .getDisplayValuesWithReferences();
    
    if (Object.keys(catalogWorkflowsResult).length) {
      gs.print('\n' + searches[i].description + ' in catalog workflows:');
      gs.print(JSON.stringify(catalogWorkflowsResult, null, 2));
    }

    var otherWorkflowsResult = HardcodedValuesLocator(searches[i].table, searches[i].query)
      .findInWorkflows(otherWorkflowVersions)
      .getDisplayValuesWithReferences();
    
    if (Object.keys(otherWorkflowsResult).length) {
      gs.print('\n' + searches[i].description + ' in other workflows:');
      gs.print(JSON.stringify(otherWorkflowsResult, null, 2));
    }
  }
})();

Note I’m using gs.print() in the above sample, which works fine in a background script or in Xplore, but you may need to use gs.info() instead depending on context.

Conclusion

I hope this helps you find and clean up some of the skeletons in your ServiceNow closet. If you do find it useful or have any questions, feel free to reach out on SNDevs Slack or Mastodon. 

Converting from Base64?

At first I looked for ways to “re-hydrate” the attachments from records exported in XML format. Attachment files are embedded in XML exports in a kind of Base64 encoding that’s probably not proprietary to ServiceNow, but I tried several different ways to convert that encoded data back into files with no luck. If you know a way to do this, please reach out and share, as I’m still curious to know if it can be done.

Server-side script and/or Processor?

The next approach I took was writing a server-side script (like a Fix Script or a Background Script) to initiate bulk downloading of attachments in my browser. I stumbled across a few promising Community posts going in a similar direction, including one that suggested creating a UI Action that utilized a custom Processor. That and similar answers all seemed to be linking to a now-missing post on the ServiceNow Guru blog.

There’s apparently an out-of-box Processor called DownloadAllAttachmentsProcessor that will (what it says on the tin) download all attachments for a single record as a zip file. Handy! But I needed something that would download attachments in bulk, and custom Processors are not only deprecated but completely disabled (you need the maint role to create them and you can’t edit the ACLs) so all this was a dead end.

Attachment API and Python to the rescue

Fortunately, all that thinking about Processors got me on the related subject of REST APIs. At first I thought I might have to create a Scripted REST API, but then I discovered there is an out-of-box Attachment API. The last missing piece fell into place when I found Hitoshi Ozawa using a Python script to hit the Attachment API from the command line on his local machine.

Ozawa’s solution seemed promising, but he was still only downloading the attachments on a single record. So here’s my own version of a Python script that downloads all attachments for all records in a specified table matching a specified encoded query, organizing them in a nice folder hierarchy (don’t miss some notes on usage after the script, including a very important one about security):

import requests
import os
import re

### set options here ###

instance = 'https://<your-instance>.service-now.com'
username = ''
password = ''

table = 'incident'
display_field = 'number'
query = 'active=true'
limit = '5' # set to 'None' (without quotes) to remove limit

directory = './Attachments'

### shouldn't have to edit anything below ###

# helper dict for converting mime types to file extensions
mime_type_to_ext = {
  'application/json': ['.json'],
  'application/xml': ['.xml'],
  'image/png': ['.png'],
  'image/jpeg': ['.jpg', '.jpeg'],
  'image/gif': ['.gif'],
  'text/csv': ['.csv'],
  'text/plain': ['.txt'],
  'application/pdf': ['.pdf'],
  'application/msword': ['.doc'],
  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ['.docx'],
  'application/vnd.ms-excel': ['.xls'],
  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ['.xlsx'],
  'application/application/vnd.ms-powerpoint': ['.ppt'],
  'application/vnd.openxmlformats-officedocument.presentationml.presentation': ['.pptx'],
}

# helper function for hitting any endpoint, returns response object
def get_response(endpoint, mime_type, params={}):
  headers = { "Accept": mime_type }
  response = requests.get(endpoint, auth=(username, password), headers=headers, params=params)
  if response.status_code != 200:
    print('Status:', response.status_code, 'headers:', response.headers, 'Error Response:', response.json())
    exit()
  return response

# helper function for table api, returns list of dicts
def get_records(table, query, limit=None):
  endpoint = f'{instance}/api/now/table/{table}'
  params = {
    'sysparm_query': query,
    'sysparm_display_value': 'true',
  }
  if limit:
    params['sysparm_limit'] = limit

  return get_response(endpoint, 'application/json', params).json().get('result')

# helper function to make directory and file names safer
def sanitize_filename(filename):
  filename = re.sub(r'[<>:"/\\|?*]', '', filename) # remove invalid characters
  filename = re.sub(r'^\.+', '', filename) # remove leading period
  return filename[:255] # truncate to 255 characters
  
# Helper function to generate a unique filename if file exists
def unique_filename(path):
    base, extension = os.path.splitext(path)
    counter = 1
    while os.path.exists(path):
        path = f"{base}_{counter}{extension}"
        counter += 1
    return path

# helper function for attachment api, writes files to disk
def get_attachment(sys_id, mime_type, path):
  path = unique_filename(path)
  endpoint = f'{instance}/api/now/attachment/{sys_id}/file'
  response = get_response(endpoint, mime_type)

  with open(path, 'wb') as f:
    for chunk in response.iter_content(chunk_size=1024):
      if chunk:
        f.write(chunk)

# call table api to get specified table records and iterate over results
for record in get_records(table, query, limit):
  class_name = sanitize_filename(record.get('sys_class_name'))
  display_value = sanitize_filename(record.get(display_field))
  print(f'{class_name}: {display_value}')

  # call table api again to get attachment metadata and iterate over results
  attachment_query = f"table_sys_id={record.get('sys_id')}"
  attachments = get_records('sys_attachment', attachment_query)

  if attachments:
    # make folders if they don't exist
    path = os.path.join(directory, class_name, display_value)
    os.makedirs(path, exist_ok=True)

    for attachment in attachments:
      # get mime type and file name
      mime_type = attachment.get('content_type')
      file_path = os.path.join(path, sanitize_filename(attachment.get('file_name')))

      # Append file extension to file name if not already
      file_ext_list = mime_type_to_ext.get(mime_type, [''])
      file_ext = file_ext_list[0]  # Choose first extension as default
      if not any(file_path.endswith(ext) for ext in file_ext_list):
        file_path += file_ext

      # call attachment api to download file and write to disk
      get_attachment(attachment.get('sys_id'), mime_type, file_path)

Usage notes

Here’s how to use the script:

1. Copy and paste it into your favorite text editor (worth noting here: unlike in JavaScript, indentation matters in Python, so copy carefully)
2. Update the settings at the top of the script to your liking
3. Save it as attachments.py (or whatever you want)
4. On the command line, navigate to the same folder where you saved the script
5. Run it with the command python attachments.py (you might have to start the command with python3 depending on your environment)

When you run the script, it creates an “Attachments” folder in the same location. It then begins downloading the attachments into that folder, neatly organizing them in a folder hierarchy by table name and record display value. It also helpfully adds appropriate file extensions to any files that don’t have them.

I can’t put a fine enough point on this: It’s super dangerous to put your ServiceNow username and password directly in a plain text file like this. If you’re using it as a one-off like I am, it may be fine, though I’d be sure to delete the password from the script (or just delete the whole script) when you’re done. If this script is going to be used on a regular basis you should investigate dynamically populating the username and password from environment variables or an encrypted password vault. Also, if you can get what you need from a sub-production instance, it’s always safer to go that route. If my script gets you reprimanded or fired over some kind of security breach, don’t @ me.

Lastly, you’ll (obviously) need Python installed on your local machine to run this. Instructions for doing that are outside the scope of this article, partly since they’ll be different depending on your operating system. In addition to Python, I found I had to separately install the requests package using the package installer for Python (pip). Google is your friend for figuring out how to get everything installed and running on your computer.

Questions or feedback?

If you find a use case for downloading attachments in bulk, I hope the script helps. I’d love to hear about your experience and answer any questions you might have. Feel free to reach out on SNDevs Slack or Mastodon. Cheers! 

What is it?

In a nutshell, GQ is a library of helper functions designed for use with GlideQuery, particularly with the filter, map, and reduce methods of the Stream object. In the video, Bell demonstrates the use of GQ.jsonDebug() with the map method to send whole records to the system log with pretty formatting, a bit like this:

new global.GlideQuery('incident')
  .where('active', true)
  .limit(5)
  .select('number', 'short_description', 'caller_id$DISPLAY')
  .map(global.GQ.jsonDebug)
  .forEach((incident) => {
    // do something
    // ...
  });

Don’t miss this: the jsonDebug() method isn’t being invoked. Instead it’s being passed to the map() method as the callback function parameter. If you’re not familiar, JavaScript is a first-class functions language. Functions are also variables and can be passed in and out of other functions as parameters and return values.

Partially-applicable functions

The GQ script include has a really awesome feature called partially-applicable functions. The labelDebug() method is a great example. It takes two parameters, a string label and some value (usually a record object). If you call it with both, it system logs a prettified JSON string of the value parameter with the label parameter prepended. The system log can be pretty chatty, so a label can make it easier to find the debug statements you’re looking for.

But if you know how map() works, you know it only passes one argument to the callback function you pass in, so how do you get a version of labelDebug() that only takes one argument? This is the beauty of partially-applicable functions. If you call labelDebug() with just the first argument, the label, it doesn’t immediately send output to the debug log. Instead, it returns a new purpose-built function. The returned function, which has the label permanently baked in, only requires one parameter, the value.

So, unlike jsonDebug(), you do invoke this one when you use it with map(), but you only pass the first of the two arguments causing a new function to get returned and passed into map(). Each time through its own loop, the map() method will then supply the second argument to the new function.

new global.GlideQuery('incident')
  .where('active', true)
  .limit(5)
  .select('number', 'short_description', 'caller_id$DISPLAY')
  .map(global.GQ.labelDebug('Active Incident: '))
  .forEach((incident) => { // ... });

My favorite and probably the most useful method in the whole GQ utility is get(). It’s partially-applicable like labelDebug(), taking a field name as it’s first parameter and some value (again, usually a record object) as its second parameter. It takes the field name and returns the value of that property from the record object. Use it like this:

let names = new global.GlideQuery('sys_user')
  .whereNotNull('first_name')
  .select('first_name')
  .map(global.GQ.get('first_name'))
  .toArray(20);

If all you need is a list of sys_ids or a list of names, get() is a very handy way to convert a Stream of record objects into the simpler list you need.

GQX

The GQ utility has other functions like merge() and values() that I highly recommend you check out, but I also want to share with you another utility I made myself that complements GQ with a few helpful functions if its own. I call it GQX, and it has functions mainly for use with Stream’s reduce() method.

In my early experience using GlideQuery I got annoyed that Stream’s toArray() method would only handle up to 100 records. To avoid poorly-performing nested queries I’ll frequently pull data from one table and store it in a data structure before pulling related data from a different table and then mashing the two data sets up somehow in memory. Because of the record limit of toArray(), I found myself writing this pattern a lot to store records in an intermediate data structure:

let problemIDs = new global.GlideQuery('problem')
  .select()
  .map(global.GQ.get('sys_id'))
  .reduce((problemIDs, problemID) => {
    problemIDs.push(problemID);
    return problemIDs;
  }, []);

With the GQX utility, this same code can be shortened to:

let problemIDs = new global.GlideQuery('problem')
  .select()
  .map(global.GQ.get('sys_id'))
  .reduce(global.GQX.toArray, []);

In addition to the toArray() method, GQX has methods for reducing a Stream to an object or even an ES6 Set or Map. If you find a cool use for it, please let me know. Cheers! 

Settings

Script

/**
 * GQX is a utility class intended for use with GlideQuery.
 * @namespace
 */
function GQX() {}

/**
 * Returns the accumulator array after pushing the value.
 * Handy as a reduce function.
 * @example
 * var names = new GlideQuery('sys_user')
 *     .whereNotNull('first_name')
 *     .select('first_name')
 *     .reduce(GQX.toArray, []);
 * @param {array} accumulator
 * @param {any} value
 * @returns {array} accumulator
 */
GQX.toArray = function toArray (accumulator, value) {
  accumulator.push(value);
  return accumulator;
};

/**
 * Returns the accumulator Set after adding the value.
 * Handy as a reduce function.
 * @example
 * var names = new GlideQuery('sys_user')
 *     .whereNotNull('first_name')
 *     .select('first_name')
 *     .reduce(GQX.toSet, new Set());
 * @param {Set} accumulator
 * @param {any} value
 * @returns {Set} accumulator
 */
GQX.toSet = function toSet (accumulator, value) {
  return accumulator.add(value);
};

/**
 * Returns the accumulator object after adding the
 * specified key and value from the record.
 * Handy as a reduce function.
 * @example
 * var names = new GlideQuery('sys_user')
 *     .whereNotNull('first_name')
 *     .select('first_name')
 *     .reduce(GQX.toObject('sys_id', 'first_name'), {});
 * @param {string} key property name
 * @param {string} value property name
 * @param {object} accumulator
 * @param {object} record
 * @returns {object} accumulator
 */
GQX.toObject = GQ.partial(function toObject (key, value, accumulator, record) {
  accumulator[record[key]] = value ? record[value] : record;
  return accumulator;
});

/**
 * Returns the accumulator Map after adding the
 * specified key and value from the record.
 * Handy as a reduce function.
 * @example
 * var names = new GlideQuery('sys_user')
 *     .whereNotNull('first_name')
 *     .select('first_name')
 *     .reduce(GQX.toMap('sys_id', 'first_name'), new Map());
 * @param {string} key property name
 * @param {string} value property name
 * @param {Map} accumulator
 * @param {object} record
 * @returns {Map} accumulator
 */
GQX.toMap = GQ.partial(function toMap (key, value, accumulator, record) {
  return accumulator.set(record[key], value ? record[value] : record);
});

The problem

Imagine you’re working in a before business rule and you need to interact with the current record. It’s possible earlier business rules have already changed some values, so using GlideQuery to retrieve the current record from the database will give you, at best, stale data or, at worst, no data at all (i.e. if the record is new and won’t even be inserted until after the before business rules finish). In this and other scenarios, your only option is to interact with the GlideRecord object you’ve been given.

The annoying thing about GlideRecord is what I’ve already been discussing over in my GlideQuery series: the property gr.short_description isn’t a native JavaScript string. It’s a weird Frankenstein of a Java GlideElement object and a Java string, and it behaves counterintuitively. Strict equality for comparisons fails in mysterious ways, and if you store the value for later use (say in an array) you’ll find it changes out from under you the next time you call gr.next().

We all have our favorite tricks like using gr.getValue() to cast everything to strings, but that’s less than ideal for numeric and boolean fields.

There is a better way

Dan and I workshopped a tool and put it up on Share last year. We call it BetterGetter. It’s a wrapper for GlideRecord with its own magic getValue() method that returns native JavaScript types rather than weird GlideElement objects or Java types.

Use it like this:

var bg = new BetterGetter(current);
bg.getValue('short_description');  // string
bg.getValue('priority');       // number
bg.getValue('active');         // boolean
bg.getValue('watch_list');       // array of strings

Note that BetterGetter is only a getter, not a setter, so if you need to set values you would just use current.setValue() as usual. The neat thing is your BetterGetter object becomes sort of quantum entangled with the GlideRecord object passed to it, so you can get some values with BetterGetter, set a value or two the normal way, then get them later with BetterGetter and you’ll get the updated values.

If you do happen to be iterating over a GlideRecord, you can make a single BetterGetter object outside your while loop, then refer to it inside the loop. Since it maintains a reference to the original GlideRecord object you’ll get appropriate values for each new record after calling gr.next(), but they’ll be native JavaScript values so you can safely store them for later use.

If this sounds awesome and you want to try it out, grab the Update Set from Share or copy/paste the Script Include below. Let us know if you find a cool use for this. Cheers! 

Settings:

Script:

// Directly accessing GlideRecord elements gives you Java native types,
// and GlideRecord's getValue() method always returns JavaScript strings.
// Neither is very helpful! Using GlideQuery is the recommended best
// practice, but sometimes you are forced to work with GlideRecord
// objects, e.g. the `current` object in Business Rules.
// 
// BetterGetter's getValue method returns the correct JavaScript native
// type based on the data type of an element's dictionary entry. BetterGetter
// also provides convenient methods for converting an element to any other
// preferred JavaScript native type, if possible.
// 
// Use it like this:
//    var active = new BetterGetter(current).getValue('active');
// 
// Or like this:
//    var getter = new BetterGetter(current);
//    var active = getter.getValue('active');

function BetterGetter(gr) {
  // In case caller omits the new keyword
  if (!(this instanceof BetterGetter)) return new BetterGetter(gr);
  this._gr = gr;
}

BetterGetter.prototype.getValue = function(element) {
  switch (this._gr[element].getED().getInternalType() + '') {
    case 'boolean':
      return this.getBoolean(element);
    case 'glide_date':
      return this.getDate(element);
    case 'glide_date_time':
      return this.getDateTime(element);
    case 'glide_list':
      return this.getList(element);
    case 'decimal':
    case 'float':
    case 'integer':
    case 'longint':
    case 'long':
    case 'numeric':
      return this.getNumber(element);
    default:
      return this.getString(element);
  }
};

BetterGetter.prototype.getBoolean = function(element) {
  return Boolean(this._gr[element]);
};

BetterGetter.prototype.getDate = function(element) {
  return (this._gr[element] + '').slice(0, 10) || null;
};

BetterGetter.prototype.getDateTime = function(element) {
  return this._gr[element] + '' || null;
};

BetterGetter.prototype.getList = function(element) {
  if (this._gr[element].nil()) return null;
  return (this._gr[element] + '').split(',');
};

BetterGetter.prototype.getListDisplay = function(element) {
  if (this._gr[element].nil()) return null;
  return (this._gr.getDisplayValue(element)).split(',');
};

BetterGetter.prototype.getNumber = function(element) {
  if (this._gr[element].nil()) return null;
  return Number(this._gr[element]);
};

BetterGetter.prototype.getString = function(element) {
  return this._gr[element] + '' || null;
};

It is sometimes necessary to script the due date value in the Ask For Approval action. For example, if you wanted an approval to automatically cancel when left unresponded after 14 calendar days. At first glance this seems entirely possible using the relative due date configuration options, until you get to the “From” date/time value input that must be provided. How can you specify that you want the timer to start at the time of Approval record creation? To my knowledge you cannot, at least not without writing a script. As with all other inputs in Flow Designer it would like you to drag and drop a date/time pill value and move on. If this flow is based on a Catalog Item it can be tempting to drag and drop the Created On date/time pill from the RITM, and in some cases (depending on where this Action is in your Flow) this may not be much of a problem.

One workaround that I have used after my failed attempts at using the script input has been to populate a flow variable with the desired date/time string value. I can populate the variable via script using the Set Flow Variables action. While I dislike this solution for a number of reasons it does work.

I was recently building a flow using this workaround when I happened to see that a due date configured with pills generates a JSON configuration that you can view from the Flow Execution Context.

After finding this I immediately made some assumptions on other possible values and began to test my theories. The JSON object below is the result of my testing. I have documented each property’s purpose and possible values along with an example script.

Due Date Configuration Template

{
    "action": "", // approve, cancel, reject
    "date_type": "", // actual, relative
    "date": "", // Date/Time string used as the static date/time value, or as the starting date/time value for relative due dates.
    // The following can be ignored for static due date configurations
    "duration": 1, // The duration value (e.g. 1 minute, 1 hour, 1 day, etc.). ** Default value is 1 **
    "duration_type": "days", // minutes, hours, days, weeks, months, quarters, years. ** Default value is days ** 
    "schedule": "", // Sys ID of the Schedule [cmn_schedule] record to be used when calculating relative due dates
    "schedule_label": "" // Label of the Schedule [cmn_schedule] record to be used when calculating relative due dates
}

Scripted Due Date Example

var gdt = new GlideDateTime();
gdt.addDaysLocalTime(14);
var config = {
    "action": "cancel", // approve, cancel, reject
    "date_type": "actual", // actual, relative
    "date": gdt.getValue(), // Date/Time string used as the static date/time value, or as the starting date/time value for relative due dates.
    // The following can be ignored for static due date configurations
    "duration": 1, // The duration value (e.g. 1 minute, 1 hour, 1 day, etc.). ** Default value is 1 **
    "duration_type": "days", // minutes, hours, days, weeks, months, quarters, years. ** Default value is days ** 
    "schedule": "", // Sys ID of the Schedule [cmn_schedule] record to be used when calculating relative due dates
    "schedule_label": "" // Label of the Schedule [cmn_schedule] record to be used when calculating relative due dates
}
return JSON.stringify(config);

While I am delighted to have solved this riddle, I can’t emphasize enough that to my knowledge all of this is completely undocumented, at least as of the Utah release, and is likely unrecommended as any instances of this action using a scripted input are subject to break in the event that the action is updated. I cannot guarantee that this will work for you or that it will continue to work. Now that I have seen how the action works I suspect that in the event you find yourself in a scenario like the one described above, the intended solution would be to use a flow variable or similar steps of scripting a dynamic date/time and provide that value via pill. 

Mind you, I’m not presenting any of the following as pre-requisites to my series. I won’t assume you’ve engaged with any of this material beforehand. But likewise, I’ll do my best not to just regurgitate what others have said. Though of necessity I’ll be covering a lot of the same ground, wherever possible I’ll try to give it my own unique spin and share my own original usage examples.

So feel free to engage with as much or as little of what follows, or ignore it for now and explore it later if the rest of my series piques your interest.

Official documentation

Of course, the best place to start is arguably the official documentation. There are Docs pages for GlideQuery, Stream, and Optional. There are also mirrors of the same documentation on the Developer site (GlideQuery, Stream, and Optional).

Content featuring Peter Bell

Peter Bell is the senior engineer within ServiceNow who created GlideQuery as a side project to help him with his normal day job on the IT Asset Management team. Naturally, his own content is very well worth checking out.

Bell’s original CreatorCon 2020 breakout session, GlideQuery: A modern upgrade to GlideRecord (CCB3052) (and accompanying slide deck), is, as far as I know, the first time GlideQuery was announced officially to the public. It’s a great introduction to the API and all of its benefits over GlideRecord.

From January to April 2021, Bell published a series of excellent blog posts explaining how to use GlideQuery. There’s a lot of overlap here with the official documentation, but, where the docs simply list methods alphabetically, these posts order the topics more pedagogically:

In April 2021 Bell did an episode of Creator Toolbox on YouTube with Chuck Tomasi, Brad Tilton, and Andrew Barnes, “GlideQuery”. They work on refactoring some existing GlideRecord code to use GlideQuery instead, and along the way Bell shares a few interesting undocumented features.

In June 2021 Bell did another interview with Chuck Tomasi, this time on the Breakpoint podcast, “GlideQuery with Peter Bell”. This one is largely a review of the material in the original CreatorCon session, but he talks about some of the inspirations for GlideQuery and shares some useful info about the performance of GlideQuery compared to GlideRecord.

Community resources

GlideQuery shipped in an early form as part of the ITAM suite in the Orlando release. A few people discovered it, but this post by Jace Benson is the only thing I can find that predates the official announcement: “What is GlideQuery”. After the official CreatorCon session came out (GlideQuery shipped officially in the Paris release), Benson followed his first post up with a full rundown of GlideQuery’s feature set: “Glide Freaking Query Wow”.

Others have since posted cheat sheets for GlideQuery, such as Samuel Meylan’s “GlideQuery Cheat Sheet”, Alberto Colombo’s “GlideQuery Cheat Sheet”, and Thiago Periera’s “GlideQuery Cheat Sheet”.

The above are the most important/useful bits of community content, but a number of other folks have blogged or published YouTube videos about GlideQuery (listing these in chronological order as far as dates could be ascertained):

• Dhruv Gupta: “GlideQuery Not GlideRecord”
• Lubos Strejcek: “GlideRecord or GlideQuery? That’s the question”
• John Skender: “GlideAggregate, GlideQuery or GlideRecord?”
• ServiceNow 911: “GlideRecord vs. GlideQuery”
• Steven Bell: “GlideQuery vs. GlideRecord: A Comparison”, Part 1 and Part 2
• Ahmed Drar: Querying with GlideQuery
• ismr: “GlideQuery API”, “GlideQuery Debug Functions”, and “GlideQuery Parse()”

Conclusion

Well, there you have it. That’s every single resource I can find online about GlideQuery. Have you found some additional documentation or a blog post, YouTube video, TikTok, or some other kind of media that I missed? Find me in the ServiceNow Developers Slack workspace or on Mastodon and let me know. Next up in the series I’ll start to dive into GlideQuery’s many benefits. Stay tuned! 

Next in the series: Part 1: Unambiguous Boolean Logic →

The preferred way using modern JavaScript is with the Fetch API. Here’s an example to pull the ten oldest Incident records:

const table = 'incident';
const params = [
  'sysparm_query=active=true^ORDERBYsys_created_on',
  'sysparm_fields=number,short_description,description',
  'sysparm_limit=10',
  // 'sysparm_display_value=all', // true for display values, all for both
].join('&');

const endpoint = `/api/now/table/${table}?${params}`;

fetch(endpoint, { headers: { 'X-UserToken': g_ck } }) // user auth token
  .then((response) => {
    if (!response.ok)
      throw `HTTP status ${response.status} on ${endpoint}`;
      
    return response.json();
  })
  .then((response) => {
    // Do stuff (e.g. number will be response.result[i].number)
    // ...
  });

I know what you’re gonna say, this looks like more code than a typical GlideAjax call. That actually depends on how many parameters you use and whether you need error handling, but keep in mind this is all the code. There’s no need for you to make any server-side component because the Table API does all the heavy lifting for you. One Client Script and you’re done.

Note, the g_ck variable is a client-side variable that stores the logged-in user’s session token. It’s the easiest way to authenticate the current user to the Table API so you don’t have to pass along any other credential. Be aware ACLs will be honored, so you may need to find another way to do this if your Client Script needs to fetch records the user can’t otherwise read.

Also note, the Fetch API has pretty broad support (and don’t forget this is running in your end users’ browsers, so you’re not stuck on ES5 like you are most everywhere else in ServiceNow), but if your environment won’t allow it for whatever reason (say your company mandates Internet Explorer), here’s the same example using bog standard XMLHttpRequest instead:

var table = 'incident';
var params = [
  'sysparm_query=active=true^ORDERBYsys_created_on',
  'sysparm_fields=number,short_description,description',
  'sysparm_limit=10',
  // 'sysparm_display_value=all', // true for display values, all for both
];

var endpoint = '/api/now/table/' + table + '?' + params.join('&');

var xhr = new XMLHttpRequest();
xhr.open('GET', encodeURI(endpoint));
xhr.setRequestHeader('X-UserToken', g_ck); // user auth token
xhr.send();

xhr.onreadystatechange = function () {
  if (xhr.readyState !== XMLHttpRequest.DONE)
    return;
    
  if (xhr.status < 200 || xhr.status >= 300)
    throw 'HTTP status ' + xhr.status + ' on ' + endpoint;

  var response = JSON.parse(xhr.responseText);
  
  // Do stuff (e.g. number will be response.result[i].number)
  // ...
};

Of course, you could refactor either of these examples to use any endpoint you like. Maybe you really need to crunch some data server-side and deliver it to the client in a way the Table API just can’t accommodate. You could create your own Scripted REST API endpoint and ping that from the client instead. The world is your oyster, but please, and I say this as a friend, never use GlideAjax again. You’re welcome!