GlideRecord

One of the most common JavaScript APIs is the GlideRecord class, which is extremely handy and will fast become a staple of most scripting. GlideRecord is a way of finding and counting records in ServiceNow based on many different queries. It is quite similar to a SQL statement if that is something you are familiar with.

Let's have a look at how to use GlideRecord.

We'll take a look at how to query all the records in a particular table. The format of the GlideRecord script for this is shown in the following, with table_name being the only parameter. This needs to be the table name rather than the table label:

new GlideRecord('<table_name>');

We will set a variable to hold the GlideRecord object and define the table that will be used to query. In this example, we will use the incident table:

var glideRecord = new GlideRecord('incident');

The glideRecord variable now holds a GlideRecord object for the incident table. We then query the table and add any filtering. In this case, we will add no filter and simply return all records for the incident table, therefore showing the full script:

var glideRecord = new GlideRecord('incident');
glideRecord.query();
while (glideRecord.next()) {
    //Code in this loop will be run against all incident records
}

This is a very important part of ServiceNow scripting as it is the way coders can access the records in ServiceNow by cycling through them and applying some code to each relevant record.  

Now that we've seen how to set up a GlideRecord query, let's have a look at the script line that can filter a GlideRecord for us:

variable.addQuery('<field_name>', '<operator>', '<value_to_compare_against_field>')

Here, we filter based on a field name and compare the value in that field using the operator to the value we define. The default operator is that the value equals the value in the field so if this is the operator we need, we can just leave it out.

Let's have a look at another example. This time, we'll look to query all the problem records with a critical priority using our filter line:

var glideRecord = new GlideRecord('problem');
glideRecord.addQuery('priority', 1);
glideRecord.query();
while (glideRecord.next()) {
    //Code in this loop will be run against all problem records with a priority of critical.
}

As you can see in the preceding code, we omitted the operator because we want problem records with a priority equal to 1 and therefore we did not need to include it.

In the examples so far, we have cycled through all of the records, but we can amend the loop to return just one if it exists by changing the while to an if. This is often helpful when checking whether all tasks of a parent record are complete. Let's look at how it would change our script from our last example:

var glideRecord = new GlideRecord('problem');
glideRecord.addQuery('priority', 1);
glideRecord.query();
if (glideRecord.next()) {
    //Code in this loop will be run against one problem record with a priority of 1 if one exists.
}

This code could be used to check whether any priority critical problems exist and will run some code against it if one does.

You can add more than one query and each record that is returned will need to satisfy each filter being defined. In that respect, it is quite like searching for a house. You could just search for all houses, but you more likely would want to build filters up to find exactly what you are looking for – price range, bedrooms, location, and so on.

With all of these filters adding up and essentially creating a series of logical AND statements, we also need a way of creating a logical OR statement. In the same way you can add a query line, you can also add an OR condition line of script. Let's see how it works:

var glideRecord = new GlideRecord('change_request');
var orQuery = glideRecord.addQuery('risk', 1);
orQuery.addOrCondition('risk', 2); 
glideRecord.query();
while (glideRecord.next()) {
    //Code in this loop will be run against all change request records that are a very high or high risk.
}

As you can see, the original condition is stored in a variable, orQuery, and then the OR condition is added to this variable before the query takes place. This type of query is handy if you want certain code to execute when a record is in a certain set of states.

There are many ways to achieve the same goal in ServiceNow and to show this, we can set up the same filter on change records using a different operator. This uses the fact that many values of choice lists in ServiceNow are numbers so we can just search for all change requests with a risk of greater than or equal to 2:

var glideRecord = new GlideRecord('change_request');
glideRecord.addQuery('risk', '>=', 2); 
glideRecord.query();
while (glideRecord.next()) {
    //Code in this loop will be run against all change request records that are a very high or high risk.
}

This second example would usually be considered better than the first, as it is using fewer lines of code.

Now we have looked at how to get the records we want, we will look at how to alter the records we have found. First, we'll take a look at a simple update to a record. In this example, we will update all incident records with a high urgency and move it down to medium:

var glideRecord = new GlideRecord('incident');
glideRecord.addQuery('urgency', 1); 
glideRecord.query();
while (glideRecord.next()) {
    //Change all high urgency incidents to medium urgency
    glideRecord.urgency = 2;
    glideRecord.update();
}

When updating a record, you can amend many of the fields and then use update to save the changes. This is a very important method and is relatively simple to use.

The final examples we will look at are how to delete records. Obviously, be careful when deleting records and ensure the query you have written is correct before executing.

There are two main methods of deleting records: either individually through looping or all in one go. Let's look at deleting individual records first. In this example, we'll delete all of the network category incidents:

var glideRecord = new GlideRecord('incident');
glideRecord.addQuery('category', 'network'); 
glideRecord.query();
while (glideRecord.next()) {    
    glideRecord.deleteRecord();
}

Next, we'll look at how to delete all of the queried records in one go:

var glideRecord = new GlideRecord('incident');
glideRecord.addQuery('category', 'network'); 
glideRecord.deleteMultiple();

As you can see, the script for both of these delete methods is quite different, but the end result is the same. The deleteMultiple method is a quicker, more efficient method; however, it will delete everything in one go. If there is a large amount of data to be deleted, this can cause resources to be tied up for a long time. I have used the deleteRecord method instead in the case of a large volume of data to stagger the deletion of records in smaller groups of records.

That concludes GlideRecord for now, but it will feature again throughout the book, further proving how important it is.