Since the Vancouver release, there is a new API GlideJsonPath¹ that allows to query a JSON string with jsonPath².

The jsonPath can be viewed as the JSON equivalent of the XPath for XML. It allows to perform queries like $.library.bools.*.title for example. Jsonpath is offically a RFC since february 2024³

I suspect the under the hood, it use the implementation JsonPath⁴.

Usage of the GlideJsonPath

The official documentation¹ is very succint and there is a couple of extra information that can help:

• the GlideJsonPath expect a String, not an object as parameter
• the read function seems to return an array of JavaObject, which are not the same as the javascript objects. It might need some kind of converstion before being able to use it.

To ease the usage, I suggest to use a function like this one, that accept an Object as parameter and return also a javascript Object:

/*
	@name executeJSONpath
	@description execute the JSON path on the given object and return the result 
	@param {Object} [obj] - Object on which to execute the json path
	@param {String} [jsonPath] - Json path to use for the query
	@return {Object} Object after applying the jsonPath read
*/
function executeJSONpath (obj, path){
  try{
    // Convert the object to a JSON string
    var jsonString = JSON.stringify(obj);

    // call and retrieve the result from GlideJsonPath
    var gjp = new GlideJsonPath(jsonString);
    var gjpResult = gjp.read(path);

    return gjpResult;
    
  } catch (exception){
    gs.error("Error in function 'executeJSONpath' : " + exception + JSON.stringify(exception));
  }
}

JSON path syntax

The JSON path syntax can be summarized as follow:

dot-notation or bracket-notation

the JsonPath can use either a dot-notation, like $.store.book[0].title or a bracker-notation $['store']['book'][0]['title']

It can also use a mix of both, like this example: $['store']['book'][0].title

Also in the bracket notation, it is possibe to specify mutliple attribute to retrieve, for example: `$[‘store’][‘book’][0].[“title”, “author”]

Elements

The JsonPath can use the following elements ²³⁴:

• $: The root element to query. This starts all path expressions.
• @: The current node being processed by a filter predicate.
• *: Wildcard. Available anywhere a name or numeric are required.
• ..: Deep scan. Available anywhere a name is required.
• .<name>: Dot-notated child
• ['<name>' (, '<name>')]: Bracket-notated child or children
• [<number> (, <number>)]: Array index or indexes
• [start:end]: Array slice operator
• [?(<expression>)]: Filter expression. Expression must evaluate to a boolean value.

Functions

The specification gives several functions (min(), max(), …), but unfortunately it seems thay are not supported by the ServiceNow implementation.

Operators

For use in the expression, we can use the “classic” operator like “==”, “!=”, “>”, “=>”, etc. It also supports:

• =~: left matches regular expression [?(@.name =~ /foo.*?/i)]
• in: left exists in right [?(@.size in [‘S’, ‘M’])]
• nin: left does not exists in right
• subsetof: left is a subset of right [?(@.sizes subsetof [‘S’, ‘M’, ‘L’])]
• anyof: left has an intersection with right [?(@.sizes anyof [‘M’, ‘L’])]
• noneof: left has no intersection with right [?(@.sizes noneof [‘M’, ‘L’])]
• size: size of left (array or string) should match right
• empty: left (array or string) should be empty

Limitations

• functions: functions are not supported, as stated above
• unique values: There is not way to ask for unique values: there can be duplicated entries (for example when listing all categories)

Example of JSON path

This table show the result of various jsonPath from the GitHub JsonPath documentation⁴.

When creating a new jsonPath, you can use this online evaluator⁵ to test it

Sample JSON

Here is the sample JSON used for the tests:

{
    "store": {
        "book": [
            {
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
                "price": 8.95
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
                "price": 12.99
            },
            {
                "category": "fiction",
                "author": "Herman Melville",
                "title": "Moby Dick",
                "isbn": "0-553-21311-3",
                "price": 8.99
            },
            {
                "category": "fiction",
                "author": "J. R. R. Tolkien",
                "title": "The Lord of the Rings",
                "isbn": "0-395-19395-8",
                "price": 22.99
            }
        ],
        "bicycle": {
            "color": "red",
            "price": 19.95
        }
    },
    "expensive": 10
}

The plugin “Transformation Service Plugin” provides a transfomer API that allows to process JSON or XML data by applying transformations and rules and returning a key/value object with the result.

We will see in this post how it work and what are the limitations and go through a few examples.

Before going further, make sure that the plugin “Transformation Service Plugin” (com.glide.transform) is activated in your instance. If not activate it.

Overview of the API

There are in fact 3 APIs designed to work together to achieve the transformation of the data.

The 3 APIs are:

• Transformer API, that provide the necessary functions to perform the transformation and retrieve the results;
• TransformerDefinition API, that allows to define the transformation, using a set of rules and a path;
• TransformerRuleList API, used to defined the transform rules to apply.

In a nutshell, you need to create all the transformation rules with TransformerRuleList, add the rules list to the TransformerDefinition and use the this definition with Transformer to actually process and transform the data.

Test case

For this post, we will use data coming from the user table, via a REST api call.

For the sack of simplicity, we will connect to the same instance. The goal here is just to get the data in a JSON format and play with the transform functionnality.

If necessary, for the REST message creation, you can have a look to the post about Using Remote Tables in Service-Now, as we are reusing the message here.

From now, we will aways use the following code to get the data with the subsequent examples:

var r = new sn_ws.RESTMessageV2('x_12270_remote_tab.my users', 'Get');
var response = r.execute();
var responseBody = response.getBody();

As a result, we get a JSON like this one, containig all the fields from the user table in the variable responseBody:

{
  "result": [
    {
      "calendar_integration": "1",
      "country": "",
      "user_password": "jF9fbZrY7c",
      "last_login_time": "2019-04-05 22:16:30",
      "source": "",
      ....
    },
	.....
  ]
}

Transformation rules

The first step is to define the transformation rules.

In our scenario we will start with rules to :

• Concatenate the first_name and last_name and add a String “User " in front;
• Replace the “email” user name by stars (”***"), but keep the domain part (“user@domain.com” becomes “***@domain.com”);
• Define a “type”, that is either ACTIVE, INACTIVE, based on active field;
• Use a few more fields as it

This gives us the following code, wrapped in a function getTransformerRuleList:

function getTransformerRuleList () {
var transformerRuleList = new sn_tfrm.TransformerRuleList()
  .fromJSON() /* indicate it is from JSON*/
  .setName('Margin per users') /*name of the rule list*/
  /* Rules for user concatenated name */
  .addRule('first_name', '$.first_name')
  .addRule('last_name', '$.last_name')
  .addRule('user')
  .thenConcat('User ')
  .thenConcatSymbol('first_name')
  .thenConcat(' ')
  .thenConcatSymbol('last_name')
  /* Rules for email */
  .addRule('email', '$.email')
  .thenSplit('@', '***@$2')
  /* Rules for active field*/
  .addRule('active', '$.active')
  .thenApplyMap({'true': 'ACTIVE', 'false':'INACTIVE'});
  
  return transformerRuleList;
}

The .fromJSON() is here to indicate that we will parse a JSON source. We would use .fromXML() in case of an XML source.

Then the .setName()is used to give a name to the rule list.

For the rules themself, the logic is always to add a new rule with .addRule() where we give the resulting name and then where the value is coming from in the source. For example .addRule('first_name', '$.first_name').

After the .addRule(), we can add one or several .thenSomething method to further modify the value, like for example concatenate with .thenConcat, map with .thenMap and so on. You can find the full list in the API documentation.

executing the transformation

Now that the rules are defined, we can create a TransformerDefinitionand start the transformation with Transformer.

// Create a transformer definition and use the rule list and the record path 
var path = '$.result.*';  // all the records in the JSON are below "result"
var transformerDefinition = new sn_tfrm.TransformerDefinition(getTransformerRuleList(), path);
 
// Instantiate the transformer object.
var transformer = new sn_tfrm.Transformer(transformerDefinition, responseBody); 

// Transform all the records of the source, push them in array results and display the the row
var results = []; 
while (transformer.transform()) { 
  var row = transformer.getRow() 
  results.push(row);
  gs.info(JSON.stringify(row));
} 

transform()is executing the transaction for the next row and getRow() retrieve the row, in the form of an object with key-value pairs, as defined in the rule list.

Calculation failure

I wanted to explore the calculation functions provided and see how it works. Unfortunatly I couldn’t make them work when involving two differents elements from the source.

For example, in order to play with the calculations, I added some fields to the user table:

• Two currency fields
  • u_invoiced_price_per_hour
  • u_cost_per_hour
• and on integer field:
  • u_hours_by_day

Then I tried to calculate the margin price for a user by substracting the u_cost_per_hour from u_invoiced_price_per_hour.

According the documentation it can be achieved by adding the following code to the getTransformerRuleList function:

/* Rules for margin */
.addRule('margin', '$.u_invoiced_price_per_hour')
.thenSubtract('$.u_cost_per_hour');

Unfortunatly it doesn’t work and return errors like this one:

Evaluator: java.lang.NumberFormatException
   Caused by error in script at line 21

     18: } 
     19: 
     20: function getTransformerRuleList () {
==>  21:     var transformerRuleList = new sn_tfrm.TransformerRuleList()
     22:         .fromJSON() /* indicate it is from JSON*/
     23:         .setName('Margin per users') /*name of the rule list*/
     24:         /* Rules for user concatenated name */

java.math.BigDecimal.<init>(BigDecimal.java:497)
java.math.BigDecimal.<init>(BigDecimal.java:827)
com.glide.transform.adapter.CalculationAdapterRule.<init>(CalculationAdapterRule.java:222)
com.glide.transform.adapter.CalculationAdapterRule.createMultiplicationAdapterRule(CalculationAdapterRule.java:60)
com.glide.transform.transformer.AdapterRuleBuilder.thenSubtract(AdapterRuleBuilder.java:78)
com.glide.transform.transformer.js.TransformerRuleList.jsFunction_thenSubtract(TransformerRuleList.java:85)
sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
java.lang.reflect.Method.invoke(Method.java:498)
... 

I try various syntaxes, I try adding a parseInt()and so on, but I couldn’t make it work.

The only way it work was to replace the '$.u_cost_per_hour' by a number, like in the code below, but this would not by useful in our case.

/* Rules for margin */
.addRule('margin', '$.u_invoiced_price_per_hour')
.thenSubtract(15); /*.thenSubtract('$.u_cost_per_hour');*/

Alternative

Bases on this tests, I have the feeling that simply parsing the JSON and performing the necessary transformation directly would be easier and more flexible.

For example, we can achieve the same without using the Transformation Service Plugin with a script like this one:

// parse the response
var responseObj = global.JSON.parse(responseBody);

// get the records/rows inside the "result"
var records = responseObj["result"]

var altResults = [];

// Loop all records[i]
for (var i = 0; i < records.length; i++){
    var resultObj = {};
    resultObj.first_name = records[i].first_name;
    resultObj.last_name = records[i].last_name;
    resultObj.user = "User " + records[i].first_name + " " + records[i].last_name;
    // email
    var email = "";
    if (records[i].email.indexOf('@') > -1 ){
        email =  "***@" + records[i].email.split('@')[1];
    }
    resultObj.email = email;
    // active field
    var active = "ACTIVE";
    if (!records[i].active){
        active = "INACTIVE";
    }
    resultObj.active = active;
    
    // margin
    invoicePriceHour = parseInt(records[i].u_invoiced_price_per_hour);
    resultObj.u_invoiced_price_per_hour = invoicePriceHour;

    costHour = parseInt(records[i].u_cost_per_hour);
    resultObj.u_cost_per_hour = costHour;
    
    resultObj.margin = invoicePriceHour - costHour;

    altResults.push(resultObj);
    gs.info(JSON.stringify(resultObj));
} 

It is quite straightforward and easy to follow for any ServiceNow developper.

Performances

Also it seems that using Transformation Service Plugin is a bit slower than the JSON parsing alternative.

To figure out how much slower exactly, I added some code to record the time before and after the “transformer” script and the “parser” script and calculate the duratio in milliseconds. Here are the results:

transfomerStart=1592997620426, transfomerEnd=1592997620556, total=130
parserStart=1592997620556, parserEnd=1592997620581, total=25

I ran it several time and get always similar results, with the “transformer” script running about 5 times slower the the “parser” script.

Conclusions

My guess is that it will still be improved and the issues will resolved, but for the time being, unless there is a very specifc reason, I would avoid using this plugin.

For example, it is a pitty that I could not make the calculation work. I odn’t know if I am doing something wrong or if the functionnality is somehow broken, but this would be very usefull.

It is not possible to handle conditional cases by setting values based on the values of other fields.

Also when performing mapping, there is no way to reject the value in case it is not in the mapping definition. similarly, there is no possibility to use a default value in such case.

In my opinion, it is (still?) not as flexible and versatile as using a JSON (or XML) parser directly and adding the necessary code to perform all the concatenations, controls, mapping and calculation directly.

However, I am speaking from my point of view and having in mind the transformations I need to perform regularly. But there should be use cases where this plugin is usefull and where it would be advantageous to use it, but I am currently not aware of them.

References

⚠ When I last checked I noticed that the current documentation for the API is not 100% accurate. For example .fromJSON() and .fromXML() are not detailed (they are just mentionned in the introduction) and in the examples there is sometime methods that doesn’t exist, like a .addMultiply. Also the examples involving calculation using elements of the source are not working well, as we saw above.

1. ServiceNow documentation, Transformer API, accessed 2020 06 22
2. ServiceNow documentation, TransformerDefinition API, accessed 2020 06 22
3. ServiceNow documentation, TransformerRulesList API, accessed 2020 06 22
4. complete script snippet can be accessed here

This overview is mostly a coming from the breakout presentation done by Peter Bell during knowledge 2020.

Currently this feature is not available in the platform but is part of the ITAM plugin. However it will likely be available in future releases like Paris or Quebec.

In the meantime, it is possible to activate GlideQueryin your personal instance. See below the instructions to do so.

There is also a Cheat Sheet available for help you playing around with this functionnality.

What is GlideQuery

• GlideQuery is Server script API
  • it consists of 2 global script includes:
    • GlideQuery, to which we can have a look (non protected)
    • GlideQueryEvaluator, which is protected, therefore it is not possible to have a look at it.
• It is said that it use GlideRecord under the hood, probably inside the GlideQueryEvaluator script
• It also replace GlideAggregate in some cases (in particular for counting records)
• it is 100% JavaScript.

So it will not replace GlideRecord, but it proposes an additional layer on the top of it, that offers several benefits to the developers. Mainly it should reduce the likelihood of errors and mistakes when manipulating GlideRecord and make it’s usage clearer and easier.

Three principles of GlideQuery

Peter Bell states that GlideQuery has 3 principles, that are:

• Fail fast: runs into errors as soon as possible, offering a quick feedback loop
• Be JavaScript: behave like a normal JavaScript library. The GlideRecord is sometime confusing and behave more like Java.
• Be expressive: allows to do more with less code

We will se below more in details what that means.

Fail fast

By “Fail fast” it means that the query should run into error if anything is potentially wrong and therefore this can be spotted and corrected early. For example:

• Field name checking
• Choice value checking
• Type checking
• Check if any Business Rule rejects the update/insert

Here below are some examples that shows the differences between GlideRecord and GlideQuery

Field Name Checking

GlideQuerychecks that the field name used in the query are valid and if not it will raise an error.

For example, running the following code with GlideRecord, it will delete all the records from the Users table, even if the field activated is wrong:

var gr = new GlideRecord('sys_user');
gr.addQuery('actived', '!=', true);
gr.query();
gs.info(gr.getRowCount());
gr.deleteMultiple();

If we run the equivalent with GlideQuery, it will fail and give an error instead:

new GlideQuery('sys_user')
	.where('activated', '!=', true)
	.del();

This will return an error:

*** Script: Unknown field 'closed_date' in table 'task'. Known fields:
[
  "parent",
  "made_sla",
  ...
]

Choice value checking

GlideQueryis also checking for the choice value when choice fields are involved in the query.

For example, running the following code with GlideRecord, it will not return anything.

var gr = new GlideRecord('task');
gr.addQuery('approval', 'donotexist'); // we use an invalid value for the choice field 'approval'
gr.query();
while (gr.next()) {
	gs.info(gr.getDisplayValue());
}

If we run the equivalent with GlideQuery, it will fail and give an error instead:

var tasks = new GlideQuery('task')
	.where('approval', 'donotexist') // we use an invalid value for the choice field 'approval'
	.select('number')
	.forEach(gs.log);

This will return an error:

*** Script: Invalid choice 'donotexist' for field 'approval' (table 'task'). Allowed values:
[
  "not requested",
  "requested",
  "approved",
  "rejected",
  "cancelled",
  "not_required",
  "duplicate"
]: no thrown error

Strangely, it seems to work only with choice fields that have String value. For example this code do not raise any error, despite the state 8 doesn’t exist

var tasks = new GlideQuery('task')
	.where('state', 8 /*do not exist!*/)
	.select('number')
	.forEach(gs.log);

Type checking

GlideQueryis also checking if there the value is of the correct type. For example:

var tasks = new GlideQuery('task')
	.where('approval', 3) // we pass an Integer instead of a String
	.select('number')
	.forEach(gs.log);

Will return an error:

** Script: Unable to match value 3 with field 'approval' in table 'task'. Expecting type 'string': no thrown error
Root cause of JavaScriptException: org.mozilla.javascript.NativeError

Check if any Business Rule rejects the update/insert

This is another difference with GlideRecord: when a Business Rule abort the insert or update action, then the script would continue, ignoring this error. With GlideQuery, it would rather stop.

For example, running the following code with GlideRecord, it will continue executing, despite that a business rule aborted the action due to start date being after the end date.

var gr = new GlideRecord('change_request');
gr.get('c83c5e5347c12200e0ef563dbb9a7190');
gr.setValue('work_end', '2016-01-01');
gr.setValue('work_start', '2020-01-01');
gr.update();

gs.info("executing this line?"); //yes, it will execute this line despite the error in the Business rule preventing the start data after the end date

If we run the equivalent with GlideQuery, it will fail and give an error instead:

new GlideQuery('change_request')
	.where('sys_id', 'c83c5e5347c12200e0ef563dbb9a7190')
    .update({
    	work_end: new GlideDateTime('2016-01-01'),
    	work_start: new GlideDateTime('2020-01-01')
    });

gs.info("executing this line?");

This will return an error:

*** Script: {
  "message": "Failure to update table",
  "table": "change_request",
  "lastGlideError": "Operation against file 'change_request' was aborted by Business Rule 'Actual Start/End Date Validation^c83c5e5347c12200e0ef563dbb9a7190'. Business Rule Stack:Actual Start/End Date Validation",
  "changes": {
    "work_end": {},
    "work_start": {}
  }
}: no thrown error

Be JavaScript

Stringly typed values

WIth GlideRecord there is frequently issues with the type of value returned. For example:

var gr = new GlideRecord('sys_user');
gr.addQuery('first_name', 'Abel');
gr.query();

if (gr.next()) {
    gs.info(gr.first_name); // -> Abel
    gs.info(gr.firt_name === 'Abel'); // -> false 🤔
    gs.info(typeof (gr.first_name)); // -> object
}

The reason is that the first_nameis a java object. Another example with GlideRecord:

var gr = new GlideRecord('sys_user');
gr.query();
if (gr.next()) {
	if (!gr.getValue('active') { // will return "0" or "-1" as string, and it evaluated always as true...
		//doSomething(gr); 
	}
}

Last example with GlideAgregate

var taskGa = new GlideAgregate('task');
taskGa.addAggregate('COUNT');
taskGa.query();
taskGa.next();
var rowCount = taskGa.getAggregate('COUNT'); // -> return a String ("123")

// With GlideQuery
var rowCount = GlideQuery('task').count(); // -> return a number (123)

With GlideQuery all this example are solved: it return a javascript object, where the key is the field name and the value the actual value of the field:

var gr = new GlideQuery('task')
	.whereNotNull('parent');
	.selectOne('description', 'active', 'parent.urgency')
	.get()
gs.info(JSON.stringify(gr));

/* returns
{
  "description": null,
  "active": false,
  "parent": {
    "urgency": 3
  },
  "sys_id": "801a087adba52200a6a2b31be0b8f520"
}
*/

Be expressive

For reading the data, there is Stream, that apply when reading multiple records and Optional, used for a single record.

Here below are code examples that shows some of the methods in action.

Example with map and forEach

new GlideQuery('sys_user')
	.whereNotNull('name')
	.select('name')
	.map(function (user) {return user.name.toUpperCase(); })
	.forEach(gs.log);

// will return a list of name in upper case

Example with some and every

var hasOnlyShortDescription = new GlideQuery('task')
	.whereNotNull('description')
	.select('description')
	.every(function (task) { return task.description.length < 10; })
// checks that all records match the condition

var hasLongDescriptions = new GlideQuery('task')
	.whereNotNull('description')
	.select('description')
	.some(function (task) { return task.description.length < 1000; })
// checks that at least one record matched the condition

Examples with insert, update, delete

// Insert
new GlideQuery('sys_user')
	.insert({
    	active: true,
    	name: 'Sam Meylan',
    	city: 'Geneva'
	})
	.get();

// delete
new GlideQuery('task')
	.where('priority', 5)
	.disableWorkflow() // disable the business rules
	.deleteMultiple();

// update
new GlideQuery('incident')
	.where('sys_id', id)
	.update({priority: 1});

new GlideQuery('incident')
	.where('priority', '>' 2)
	.updateMultiple({order: 1});

Examples with aggregation

var companyCount = new GlideQuery('core_company')
	.where('city', 'Berlin')
	.count();

var maxReopenCount = new GlideQuery('incident')
	.where('priority', 3)
	.max('reopen_count')
	.orElse(0);
// will return the max count or 0 if there is no

new GlideQuery('task')
	.where('active', true)
	.groupBy('priority')
	.aggregate('sum', 'reassignment_count')
	.having('sum', 'reassignement_count', '>', 4)
	.select()
	.toArray(10)
/* return
[
  {
    "group": {
      "priority": 1
    },
    "sum": {
      "reassignment_count": 11
    }
  },
  {
    "group": {
      "priority": 2
    },
    "sum": {
      "reassignment_count": 3
    }
  },
  ...
  */

Flags

Flags are additional indicators that can be added to the field name to request thinks like the display ($DISPLAY) value or the currency code ($CURRENCY_CODE).

new GlideQuery('sys_user')
	.select('company$DISPLAY')
	.forEach(doSomething);

new GlideQuery('core_company')
	.selectOne('market_cap', 'market_cap$CURRENCY_CODE')
	.get()

Complex queries

Complex queries are queries involving OR conditions or nested conditions.

For example with GlideRecord:

var taskGr = new GlideRecord('incident');
taskGr.addQuery('active', true)
	.addCondition('priority', 1)
	.addOrCondition('severity', 1);

How will this be evaluated? it is ambiguous and it could be :

1. (active = true AND priority = 1) OR severity = 1
2. active = true AND (priority = 1 OR severity = 1)

The correct answer is the second one. With GlideRecord, OR has priority over AND.

With GlideQuery, the ambiguity is reduced and things are clearer:

// active = true AND (priority = 1 OR severity = 1)
new GlideQuery('incident')
	.where('active', true)
	.where(new GlideQuery()
          .where('priority', 1)
          .orWhere('severity', 1)
          )
	.select('description', 'assgined_to')
	.forEach(doSomething)

// manager is NULL OR ( title = 'Vice President' AND state = 'CA')
new GlideQuery('sys_user')
	.whereNull('manager')
	.where(new GlideQuery()
          .where('title', 'Vice President')
          .orWhere('state', 'CA')
          )
	.select('name')
	.forEach(doSomething)

The main difference is the use of a GlideQuery inside the GlideQuery. This force the parenthesis explicitly in the query.

performance

The use of the `GlideQuery’ add an overhead of about 4% to 6%, mainly due to the conversions done from java to javascript.

But we need to keep in mind that in many cases we would do this conversions anyway after the query, when using the data retrieved from the database.

Also it force good practices from a performance point of view. For example, when querying for a single record with GlideRecord, we should add .setLimit()but it is often forgotten. GlideQueryuses selectOne() for this purpose.

Also the getRowCountshould not be used to count the record, as the underlying query to the database will query all the records. The GlideAggregatewith a countshoud be used instead. GlideQueryoffers here an easiest way to achieve this with .count().

Immutability and reuse

The GlideQueryis an immutable object. This means that it can be passed to a function and we don’t care what the function is doing with it, unlike with GlideRecord.

It allows also to reuse the query and extend it. Here below some examples:

var highPriorityTasks = new GlideQuery('task')
	.where('active', true)
	.where('priority', 1);
generateReport(highPriorityTasks);
notifyOwner(highPriorityTasks);

var avgReassignmentCount = highPriorityTasks
	.avg('reassignment_count')
	.orElse(0)

How to enable it on your instance (for testing)

So now that we went through a lot of explanations, you will probably want to try by yourself. As stated at the beginning, it is (still) not included in a vanilla instance, but it is part of the ITAM plugin.

Luckily, despite being part of the ITAM plugin, it is possible to enable GlideQuery on your instance and play with it.

Do to so, run the following script:

⚠Try this in your personal instance only. I would not recommend to use this in a productive environment at the moment. It will likely be evolve and will eventually be integrated in Paris or Quebec release.

var pluginArr = ['com.sn_glidequery'];
var pluginMgr= new GlideMultiPluginManagerWorker();
pluginMgr.setPluginIds(pluginArr );
pluginMgr.setProgressName("Plugin Installer");
pluginMgr.setBackground(true);
pluginMgr.start();

Checking the code

Now that is it installed, you can go in the script includes and look for the GlideQuery script include. It is open and you can read all the code. It is quite interesting well documented. It can also gives you some insights about what can be done and how to use it.

Cheat Sheet

There is a Cheat Sheet available for help you playing around with this functionnality.

References

1. Peter Bell, breakout GlideQuery: A modern upgrade to GlideRecord CCB3052, accessed 2020 06 12
2. Jace Benson, What is GlideQuery, 2020 04 28

Since the New York release, ServiceNow offers a new functionality called remote tables.

Remote tables allows to query and retrieves data from other systems, via REST/SOAP and use them almost seamlessly in service-now.

The remote table can be used like a standard, local, table:

• They can be queried by script;
• We can see the records in lists or in forms;
• Reports can be run on the data;
• They can be used as reference from other tables (both local or remote tables);
• They support, like standard tables, sorting, aggregating and filtering like internal tables;

The obvious case is to retrieve data from a remote system, but there is nothing that prevent us to also use local tables or a mix of remote and local tables and present them as one remote table. We can also see the remote tables like a kind of enhanced database view, that allows for example to :

• aggregating data from multiple sources, both local or remote;
• Making calculations;
• Applying logic and complex conditions;

There is also an option to cache the data that has been retrieved for a certain time, to reduce the load and improve performances.

As you can see, Remote tables are a nice feature to use external data in ServiceNow and have them always up to date. It can be use in numerous scenario where external data need to be always up to date and when it is OK to have it read-only in ServiceNow.

In this article, we will play around and try different use of the remote tables. It will of course not cover all the use cases but it will give a good overview of what can be achieved.

The different use cases

For this test case, we will link an external table to ServiceNow using the remote table functionality.

As a first step, we will link the user table from an ServiceNow instance, using REST. We will include a few fields, including one reference field to Company and see how it react.

Then we will see how to retrieve the Company data in the remote table (like the company name) and see how to include also local data and set custom data in the remote table like calculation result.

Next step will be to use our remote table in a reference field on a local table (like on the incident table) and see what happen

Then we will create a new remote table for companies and see how we can make a reference from a remote table to another table

Finally we will see during all the article what should be done to optimize the query of the remote table, as the default behavior of our setup is to query always all the records.

For the sack of simplicity, both the source table and the remote table are on the same instance. But for make it more realistic (like if we are not querying another ServiceNow instance), we will not rely on the sys_id of the remote user table and we will user the UserId as the key. For the company table, we will use the sys_id, in order to not overcomplicate the example.

Creation the Remote Table

Let’s start by creating our remote rable.

There are three main steps:

• Define the table in the dictionary, where we set the table name, the columns and all the standard options for a table;
• Create a REST message to connect to the source table we want to query;
• Create the related Script Definition that query the source with the REST message and present the data in the Remote Table.

⚠Remote table plugin activation

Before using the Remote tables, check that the corresponding plug-in (com.glide.script.vtable) is activated. If this is not the case, activate it.

Define the table in the dictionary

To define the table in the dictionary, go in the menu System Definition - Remote Tables - Tables and click New.

⚠ there is currently no possibility to create Remote Table from the Studio. You need to create them from the menu and only after this they will appear in the Studio.

Fill in the name and choose whether or not you want to create a module, and check all the usual options for table creation (roles, etc.).

Then you need to add in the Columns list all the fields that you want on your Remote Table.

For now, we will keep it simple with only the First Name, Last Name, Company, Active, Phone and Email.

ℹ The Sys_id field is automatically created. Note that there is not the other usual systems fields like sys_created_on, sys_update_by, etc.

Create the REST message

Let’s create a REST message to the user table in our own instance, using the following settings:

• Endpoint : https://xxx.service-now.com/api/now/table/sys_user
• Authentication: basic - Create a profile and set your own user/password for example
• add an HTTP method: Get
• add the HTTP Query parameter (in the HTTP method);

Create the related script definition

Now the next step is to create a script definition for our new Remote Table. Go to System Definition - Remote Tables - Definitions and click New.

In table select the table you created before and let’s start writing the script that will retrieve the remote records and make them available in the Remote Table.

ℹ You will notice that there is a huge comment at the beginning of the script: it contains the explanation about how to prepare the script and how to use the APIs. I suggest you keep it in your script for reference, as there is not this information elsewhere in the documentation.

Now the goal of the script is to add rows to the Remote Table, using v_table.addRow. This function expect an object containing all the values. The name of each property in the object should match the name of the field defined in the Remote Table.

So let’s write the following script, where we query using the REST message and then build and add the rows to our Remote Table.

(function executeQuery(v_table, v_query) {

	try { 
		// get the REST message
		var message = new sn_ws.RESTMessageV2('x_12270_remote_tab.my users', 'Get');

		// execute it
		var response = message.execute();

		// get the response
		var responseBody = response.getBody();
		var httpStatus = response.getStatusCode();

		// if there is an error, log and return
		if (response.haveError()) {
			v_query.setLastErrorMessage(response.getErrorMessage());
			gs.addErrorMessage(response.getErrorMessage());
			return ;
		}

		// Parse response
		var json = new global.JSON();
		var responseObj = json.decode(responseBody);
		var resultArr = responseObj.result; // all the records are contained in an array 'result'

		for (var i=0; i< resultArr.length; i++){
			//build the row
			var row = {};

			// map fields from the result
			row.first_name = resultArr[i].first_name;
			row.last_name = resultArr[i].last_name;
			row.active = resultArr[i].active;
			row.email = resultArr[i].email;
			row.phone = resultArr[i].phone;
			row.company = resultArr[i].company.value;

			// add the row to the remote table
			v_table.addRow(row);
		}
	} catch(ex) {
		v_query.setLastErrorMessage(ex.message);
		gs.addErrorMessage(JSON.stringify(ex));
	}

})(v_table, v_query);

Now we can test it with the following script (to run in Background script):

var grX_12270RTSRU = new GlideRecord('x_12270_remote_tab_st_remote_user');
grX_12270RTSRU.query();
while (grX_12270RTSRU.next()) {
    gs.info('active: ' + grX_12270RTSRU.getValue('active'));
    gs.info('company: ' + grX_12270RTSRU.getValue('company'));
    gs.info('email: ' + grX_12270RTSRU.getValue('email'));
    gs.info('first_name: ' + grX_12270RTSRU.getValue('first_name'));
    gs.info('last_name: ' + grX_12270RTSRU.getValue('last_name'));
    gs.info('phone: ' + grX_12270RTSRU.getValue('phone'));
}

Also if we open the list of the table, you should see records in it:

So far so good: we can see the data from the ‘remote’ table and use it.

However, if we look carefully, we can see that for the company we only have the sys_id. This is because we do not have the display value in the payload. To get a more user friendly information, like the name of the company, we need to query it and use it in the script definition.

Getting the company name instead of the sys_id

One easy solution that comes to mind to solve this is to query the remote system with another HTTP method in the same REST message as before and get the company name. Let’s see how to do this.

First, let’s create a new HTTP method (in the existing REST message) for the company table, in a similar way that the one for querying the users, but with this endpoint: /api/now/table/core_company/${id} (and set a name like GetCompany and use it the the script below).

Then let’s create a function getRemoteCompanyName to retrieve the remote company and get the name.

function getRemoteCompanyName (id) {
    try {
        // get the REST message
        var message = new sn_ws.RESTMessageV2('x_12270_remote_tab.my users', 'GetCompany');

        // set the id of the company we want to retrive
        message.setStringParameter("id", id);

        // execute it
        var response = message.execute();
        // get the response
        var responseBody = response.getBody();
        var httpStatus = response.getStatusCode();

        // if there is not error, continue
        if (!response.haveError()) {
            // Parse response
            var responseObj = new global.JSON().decode(responseBody);
            var resultObj = responseObj.result;

            // check if the reuslt if ok and return the name
            if (resultObj){
                return resultObj.name;
            }
        }

        // default empty string
        return "";


    } catch (ex){
        gs.addErrorMessage(JSON.stringify(ex));
        return "";
    }
}

And replace the mapping line with this one:

row.company = getRemoteCompanyName(resultArr[i].company.value);

If we try it, we now we get the company name, but it pretty slow. The reason is that our script need to query the remote system for each user.

We will see later in this post of the solve this issue. If performances are too bad, for now just comment the mapping on the company.

Adding calculation and local data to the remote table

Now let’s see how we can add calculated data to the rows in the remote table and how we can use local data as well.

The calculated data would be simply to add a prefix to the phone number coming from the remote instance.

And local data would be looking incidents where the caller email matches the remote user email and give a count of how many incidents are found.

Both addition to the remote table are quite straightforward: we just need to add the required data in the row.

Add prefix to the phone number

Simply amend the script to add the prefix to the phone number, like this:

// add prefix to phone
var phone = resultArr[i].phone;
if (phone != ""){
    phone = "+123 - " + phone;
}
row.phone = phone;

Now the users that have a phone number will have the prefix added in front

Add an incident counter

This requirement is a bit more complicated. First of all let’s create a new field *incident count" on the Remote User table.

To do this, go in the menu System Definition - Remote Tables - Tables, select the Remote User table and add a new field.

Then in the script definition, let’s create a function getIncidentCount.

function getIncidentCount(email){
    try{
        // get the incident count where caller email match the given email
        var incidentGr = new GlideAggregate("incident");
        incidentGr.addQuery("caller_id.email", email);
        incidentGr.addAggregate('COUNT');
        incidentGr.query();
        if (incidentGr.next()) {
            return incidentGr.getAggregate("COUNT");
        }
        return 0;
    } catch (ex){
        gs.addErrorMessage(JSON.stringify(ex));
        return 0;
    }
}

And add the result of the function into the new field on the row:

// add incident count 
row.incident_count = getIncidentCount(resultArr[i].email);

Now the remote user have the incident counter filled:

Referencing a remote table from a local table

Now that we have the Remote User table defined and working, let’s use it in other tables. For example, let’s add a new field on the incident table, referencing the Remote User table.

First, let’s create a new reference field on the incident table, with reference to the Remote User table.

Then let’s try to use it: open the pop-up related list and choose a random Remote User. Before doing so, you will need to edit the reference list layout to add some meaningful fields, like First Name, Last Name and Email.

What happen after selecting the record? The field Remote User is still empty…

Why is this? The reason is simple: there is no sys_id defined on our remote table. This means that the reference field don’t know how to related to the correct row in the remote table, as sys_id is empty for all the rows of the remote table.

To solve this, we need to populate the sys_id of our rows. This need to be done, as you probably guess, in the definition script.

We could take the remote system sys_id, but let’s pretend we are not retrieving the records from another service-now instance and that we do not have a sys_id coming in. Let’s use instead the user ID (user_name), with a prefix ‘remote_’ added.

Let add this line to our script:

row.sys_id = 'remote_' + resultArr[i].user_name;

If we now go back in the incident and try again to select a Remote User, the value is set in the field and if we save the incident, it remains. We can even preview the record like with a local table (but read-only).

Technically, it stores what we have set as a sys_id into the reference field:

Change the display value of the remote table

It would be nicer if we can have something else that the sys_id set as a display value. Is this possible? Yes, of course: just go in the table definition and set the field you want to have as a display value.

Back in the incident, we now have the First Name as the display value:

Query optimization

Each time we go in the Remote Table, or we open a specific record, or use it like in the incident, the Remote Table queries the remote system and retrieve all the existing records. This is not optimal and could lead to poor response time.

We could of course enable the caching, but first let’s try to optimize the queries.

First let’s make a check to know how many records are coming in each time we query the Remote Table:. Add the following the the Remote Table definition script:

gs.addInfoMessage("querying remote users return "+  resultArr.length);`

If we now refresh the incident, we see that we query a lot of users, even if we want to display only one record.

Getting a single record

To optimye the query, we need somehow to get only the record that is interesting us.

The query helper method v_query.isGet() indicate if the query is a get and that only one record is expected.

We can then query the remote system with a different API call, using this endpoint /api/now/table/sys_user/${id}. The id will be provided by v_query.getSysId().

That would work like a charm if we didn’t decided to use a custom sys_id (“remote_” + user_name).

To overcome this, we need instead to use the same endpoint and build a query using the user_name. Luckily, v_query.getSysId() returns the sys_id stored in the reference field (or coming from a get from GlideRecord), so we can use it in our query.

Let’s add the following code:

// handle the get case
if (v_query.isGet()){
    // get the sys_id
    var sys_id = v_query.getSysId();
    // remove the remote_ from sys_id
    sys_id = sys_id.replace("remote_", ""); 
    // build the query
    message.setQueryParameter("sysparm_query", "user_name=" + sys_id);
}

and try to refresh the incident:

Our query is now retrieving only the record that is needed.

Getting onl y the records matching a filter

There are multiple cases where we filter the records, for example in a list, in a reference qualifier, etc.

Without anything in place, the remote table don’t care about the filer and always triggers a full query to the remote table.

But we can restrict the query to the remote system according the filter set in the query to the remote table.

Restrict the query to the remote system

If we go to the Remote User table and filter, we can see that anyway the Remote Table query all the records from the remote system

To avoid this, we need to add a filter on the outgoing REST message.

We can know about the query with the helper function v_query.getEncodedQuery().

We can also get rid of the part with the isGetthat we put in place before, because the encoded query contains in this case 'sys_id=xxx'.

⚠ Of course, depending the backend system, it will probably not be possible to simply use the encoded query. An ad-hoc query would need to be built. There are two functions that can help achieving this, if needed: v_query.getCondition() and v_query.getParameter().

For the sys_id, here we need something to put a special handling in place to basically to parse the encoded query, replace sys_idwith the name of the field we want (user_name) and remove the prefix remote_. For more clarity this sys_id handling it is placed in a separate function adaptSysIdQuery().

So we can modify the script as follow:

// get the encoded query
var query = v_query.getEncodedQuery();

// set the query, if not empty
if (query != "" ){
    message.setQueryParameter("sysparm_query", adaptSysIdQuery (query, "user_name", "remote_"));
}
// Function to adapt the sysid for the REST query - replace sys_id with the field name and remove the prefix
function adaptSysIdQuery (query, idField, prefix){
		// if there is no sys_id in the query, return
		if (query.indexOf('sys_id') == -1){
			return query;
		}
		// split each condition
		var queryArr = query.split('^');
		for (var i = 0; i < queryArr.length; i++){
			var elementStr = queryArr[i];
			// split each term of the condition
			var elementArr = elementStr.split("=");
			if (elementArr[0] == "sys_id"){
				// replace sys_id by the field name
				elementArr[0] = idField;
				// remove the prefix
				elementArr[1] = elementArr[1].replace(prefix, "");
				// reassemble elementArr and set back in queryArr
				queryArr[i] = elementArr.join("=");
			}
		}
		// reassemble query and return
		query = queryArr.join('^');
		return query;
	}

Now back on the list, if we refresh we can see that we are querying only the record we need from the list.

References between remote tables

Remember above? With the company field on the Remote User table, we added a function that retrieve the company information from the remote instance and set it in the row.

What about, instead, creating a new remote table for the company and make the reference work between the existing Remote User table?

Create the Remote Company table

To do this, create a Remote Company remote table, in a similar way that for the incident

Add the fields you need on that table. At the moment we really only need the field name. As you are in the dictionnary, set this field name as the display value.

Create a HTTP method

Create a new HTTP method (in the existing REST message) for the company table, in a similar way that the previous for querying the company, but with this endpoint: /api/now/table/core_company (and set a name like GetCompanies and use it the the script below). The difference with the previous endpoint is that now we want to be able to query all the companies, not just only a specific company, hence the use of a different endpoint.

Create the script definition

Then create the related script definition for the Remote Company table and use the script below. Note that, not like with incident, we are now using the remote record sys_id as a sys_id.

(function executeQuery(v_table, v_query) {
	try { 

		// get the REST message
		var message = new sn_ws.RESTMessageV2('x_12270_remote_tab.my users', 'GetCompanies');

		// get the encoded query
		var query = v_query.getEncodedQuery();

		// set the query if not empty
		if (query != "" ){
			message.setQueryParameter("sysparm_query",  query);
		}

		// execute it
		var response = message.execute();

		// get the response
		var responseBody = response.getBody();
		var httpStatus = response.getStatusCode();

		// if there is an error, log and return
		if (response.haveError()) {
			v_query.setLastErrorMessage(response.getErrorMessage());
			gs.addErrorMessage(response.getErrorMessage());
			return ;
		}

		// Parse response
		var json = new global.JSON();
		var responseObj = json.decode(responseBody);

		var resultArr = responseObj.result; // all the records are contained in an array 'result'
        
		for (var i=0; i< resultArr.length; i++){
			//build the row
			var row = {};

			// map fields from the result
			row.name = resultArr[i].name;

			// build sys_id
			row.sys_id = resultArr[i].sys_id;

			// add the row to the remote table
			v_table.addRow(row);
		}
	} catch(ex) {
		v_query.setLastErrorMessage(ex.message);
		gs.addErrorMessage(JSON.stringify(ex));
	}

})(v_table, v_query);

Now we can try the Remote Company table and check that we get all the records.

Adapt the Remote User table

Let’s do now the required adaptation on the Remote User table.

First, go in the dictionary and change the type of the field company to Reference and make it reference to the new Remote Company table.

Then adapt the script definition of the Remote User table to set the value of the field company to the sys_id of the company coming in the payload:

row.company =resultArr[i].company.value;

Now let’s try to open a Remote User and see if it works:

It looks fine. Also from the list:

Conclusion

We cover quite some use cases in the examples above. The main idea was to discover this remote tables functionality and to play a bit with them.

The key take away is that remote table are a powerful feature to add in out toolbox. It can be used to help in numerous use case, either using remote data or calculating data on local tables.

Please leave you comments or questions below.

References

1. ServiceNow documentation, Retrieving external data using remote tables and scripts, accessed 2020 06 09
2. Chuck Tomasi, NOWCommunity Live Stream - Topical Deep Dive - Remote tables, broadcasted 2020 05 04

This cheat sheet was build with elements gathered from presentations and blog posts and also from reading the script include. It may not be accurate, might evolve and all comments and corrections are welcome !

invoking GlideQuery

In a similar way that GlideRecord, the table name is passed as a parameter:

var myTable = new GlideQuery('table_name');

Cheat sheet

Selections, insert, update

get()

Returns a single record by querying primary key key.

Parameters

Example

var user = new GlideQuery('sys_user')
     .get('5137153cc611227c000bbd1bd8cd2005', ['first_name', 'last_name'])
     .orElse({ first_name: 'Default', last_name: 'User' });

getBy()

Returns a single record, using keyValues as a set of key-values to query by. getBy assumes the ‘=’ operator for each key-value.

Parameters

Example

var user = new GlideQuery('sys_user')
    .getBy({
        first_name: 'Fred',
        last_name: 'Luddy'
    }, ['first_name', 'last_name', 'city', 'active']) // select first_name, last_name, city, active
    .orElse({
         first_name: 'Nobody',
        last_name: 'Found',
        city: 'Nowhere',
        active: false
    });

insert()

Inserts a single record

Parameters

Example

new GlideQuery('sys_user') 
    .insert({
         active: true,
         name: 'Sam Meylan', 
        city: 'Geneva' 
    }) 
    .get();

insertOrUpdate()

Updates an existing record (just like update), however instead of requiring where calls, it uses the primary key(s) in the recordValues object passed in. If the primary key(s) isn’t there, insertOrUpdate will insert a new record instead. Returns an Optional of the newly created/updated record. Often useful when you want to want to ensure a record exists and has the correct values, as you don’t need to check for the record’s existence beforehand.

Parameters

Example

// insert a new record
var user = new GlideQuery('sys_user')
    .insertOrUpdate({
        first_name: 'George',
        last_name: 'Griffey'
    })
    .orElse(null);

// update existing record
var user = new GlideQuery('sys_user')
    .insertOrUpdate({
        sys_id: '2d0efd6c73662300bb513198caf6a72e',
        first_name: 'George',
        last_name: 'Griffey' })
    .orElse(null);

update()

Updates an existing record. Requires a where call, specifying all existing primary keys (usually sys_id). Returns an Optional of the newly-updated record.

Parameters

Example

new GlideQuery('sys_user')
    .where('sys_id', userId)
    .update({ city: 'Los Angeles' });

updateMultiple()

Updates all records in the table (specified by preceding where clause with the values contained in the changes object. Returns # of records updated.

Parameters

Example

new GlideQuery('sys_user')
    .where('active', false)
    .where('last_name', 'Griffey')<r>    .updateMultiple({ active: true });

select()

Specifies which fields to return and returns a Stream containing the results of the query. Note that records aren’t actually read from the database until a terminal Stream method is called (such as reduce() or toArray()). The Stream is intended for reading multiple records in a similar fashion to Java’s Stream class.

Parameters

Example

var stream = new GlideQuery('sys_user')
    .select('first_name', 'last_name');

selectOne()

Similar to select(), however only returns an Optional which may contain a single record. This is more efficient than select() if you only need one record, or want to test if a record exists.

Parameters

Example

var user = new GlideQuery('sys_user')
    .where('zip', '12345')
    .whereNotNull('last_name')
    .selectOne('first_name', 'last_name')
    .get();

Del()

Deletes all records in the table specified by preceding where clauses

Example

new GlideQuery('sys_user')
    .where('active', true)
    .where('last_name', 'Jeter')
    .del();

Conditions

where()

Returns a new GlideQuery containing where clause

Parameters

Example

new GlideQuery('sys_user')
    .where('active', true)
    .where('last_login', '>', '2016-04-15');

whereNotNull()

Returns a new GlideQuery containing NOT NULL clause

Parameters

Example

new GlideQuery('sys_user') 
    .whereNotNull('first_name')

whereNull()

Returns a new GlideQuery containing WHERE NULL clause

Parameters

Example

new GlideQuery('sys_user') 
    .whereNull('first_name')

Aggregations

avg()

Returns the aggregate average of a given numeric field

Parameters

Example

var faults = new GlideQuery('cmdb_ci')
    .avg('fault_count')
    .orElse(0);

max()

Returns the aggregate minimum of a given field

Parameters

Example

var faults = new GlideQuery('cmdb_ci')
    .max('first_name')
    .orElse('');

min()

Returns the aggregate maximum of a given field

Parameters

Example

var faults = new GlideQuery('cmdb_ci')    
	.min('sys_mod_count')
    .orElse(0);

sum()

Returns the aggregate sum of a given numeric field

Parameters

Example

var totalFaults = new GlideQuery('cmdb_ci')
    .sum('fault_count')
    .orElse(0);

count()

Returns the row count of records matching the query

Example

var userCount = new GlideQuery('sys_user')
    .where('active', true)
    .count();

groupBy()

Groups query results. Used with aggregate()

Example

new GlideQuery('task')
    .aggregate('count')
    .groupBy('contact_type')
    .select();

aggregate()

Aggregates a field using an aggregate function. Used to buildqueries which aggregate against multiple fields and/or multipleaggregate functions. If you only need to aggregate against one field with one function, and you don’t need to use groupBy(), then use one of the terminal functions instead: avg() min() max() count()

Parameters

Example

new GlideQuery('task')
    .aggregate('avg', 'reassignment_count')
    .groupBy('contact_type')
    .select();

having()

Filters aggregate groups. Used with aggregate() and groupBy.

Parameters

Example

* new GlideQuery('task')
    .where('description', description)
    .groupBy('priority')
    .aggregate('sum', 'reassignment_count')
    .having('sum', 'reassignment_count', '>', 4)
    .select()

Miscellanious

disableAutoSysFields()

Returns a GlideQuery which does not update sys fields such as sys_created_on, sys_updated_on, and sys_mod_count. This is the equivalent of using autoSysFields(false) with GlideRecord.

Example

new GlideQuery('task')
    .disableAutoSysFields()
    .insert({ description: 'example', priority: 1 });

forceUpdate()

Returns a GlideQuery which forces an update even when no changes are made. Useful when you want to force a business rule to execute.

Example

new GlideQuery('task')
    .forceUpdate()
    .where('sys_id', taskId)
    .update()

orderBy()

Returns a GlideQuery which specifies that the records should be returned in ascending order by a given field.

Example

var query = new GlideQuery('incident')
    .orderBy('number');

orderByDesc()

Returns a GlideQuery which specifies that the records should be returned in descending order by a given field. Can be used with aggregate queries

Example

var query = new GlideQuery('incident')
    .orderByDesc('number');

 new GlideQuery('incident')
    .aggregate('sum', 'child_incidents')
    .groupBy('category')
    .orderByDesc('sum', 'child_incidents')

limit()

Returns a GlideQuery which limits the number of records returned.

Parameters

Example

var incidents = new GlideQuery('incident')
    .limit(20)
    .select('priority', 'description');

withAcls()

By default GlideQuery uses GlideRecord for database interactions. By calling withAcls() GlideQuery will use GlideRecordSecure, which honors ACLs.

Example

var users = new GlideQuery('sys_user')
    .withAcls()
    .limit(20)
    .orderByDesc('first_name')
    .select('first_name')
    .toArray(100);