Version: Quebec

API Reference - Server Side Scoped

ServiceNow provides JavaScript APIs for use within scripts running on the ServiceNow platform to
deliver common functionality. This reference lists available classes and methods along with
parameters, descriptions, and examples to make extending the ServiceNow platform easier.

Please note: The APIs below are intended for scoped applications and may behave differently in the
global scope.

GlideAggregate
GlideAggregate enables creating database aggregation queries.
The scoped GlideAggregate class is an extension of GlideRecord and provides database aggregation (AVG,
COUNT, MIN, MAX, STDDEV, SUM) queries. This functionality can be helpful when creating customized reports or
in calculations for calculated fields. The GlideAggregate class works only on number fields.

When you use GlideAggregate on currency or price fields, you are working with the reference currency value. Be
sure to convert the aggregate values to the user's session currency for display. Because the conversion rate
between the currency or price value (displayed value) and its reference currency
(https://docs.servicenow.com/bundle/quebec-platform-
administration/page/administer/currency/concept/currency.html) value (aggregation value) might change, the result
may not be what the user expects.

Note: When using an on-premise system, the database server time zone must be set to GMT/UTC for this class to
work properly.

GlideAggregate(String tableName)
Creates a GlideAggregate object on the specified table.

Parameters

Name Type Description

tableName String Name of the table.

Example

var count = new GlideAggregate('incident');

addAggregate(String agg, String name)
Adds an aggregate to a database query.

Parameters

Name Type Description

Name of an aggregate to include in a database query.

Valid values:

AVG
COUNT
agg String
MIN
MAX
STDDEV
SUM

Optional. Name of the field to group the results of the aggregation by.
name String
Default: Null

Returns

Type Description

void Method does not return a value

Example

The following shows how to add aggregates to a query on the category and software fields in the Incident
[incident] table.

var incidentGA = new GlideAggregate('incident');

incidentGA.addQuery('category', 'software');

incidentGA.setGroup(false);

incidentGA.addAggregate('COUNT', 'sys_mod_count');
incidentGA.addAggregate('SUM', 'sys_mod_count');
incidentGA.addAggregate('AVG', 'sys_mod_count');
incidentGA.addAggregate('MIN', 'sys_mod_count');
incidentGA.addAggregate('MAX', 'sys_mod_count');
incidentGA.addAggregate('STDDEV', 'sys_mod_count');

incidentGA.query();

if (incidentGA.next()) {
gs.info('COUNT: ' + incidentGA.getAggregate('COUNT', 'sys_mod_count'));
gs.info('SUM: ' + incidentGA.getAggregate('SUM', 'sys_mod_count'));
gs.info('AVG: ' + incidentGA.getAggregate('AVG', 'sys_mod_count'));
gs.info('MIN: ' + incidentGA.getAggregate('MIN', 'sys_mod_count'));
gs.info('MAX: ' + incidentGA.getAggregate('MAX', 'sys_mod_count'));
gs.info('STDDEV: ' + incidentGA.getAggregate('STDDEV', 'sys_mod_count'));
}
 COUNT: 13
SUM: 273
AVG: 21.0000
MIN: 3
MAX: 95
STDDEV: 32.7694

addEncodedQuery(String query)
Adds an encoded query to the other queries that may have been set for this aggregate.

Parameters

Name Type Description

query String An encoded query to add to the aggregate.

Returns

Type Description

void Method does not return a value

Example

//Number of incidents varies depending on the current state

//of the incident table
var count = new GlideAggregate('incident');
count.addEncodedQuery('active=true');
count.addAggregate('COUNT');
count.query();
var incidents = 0;
if (count.next())
incidents = count.getAggregate('COUNT');
gs.info(incidents);

addNotNullQuery(String fieldName)
Adds a not null query to the aggregate.

Parameters

Name Type Description

fieldname String The name of the field.

Returns
 Type Description

GlideQueryCondition The scoped query condition.

Example

var count = new GlideAggregate('incident');

count.addNotNullQuery('short_description');
count.query(); // Issue the query to the database to get all records
while (count.next()) {
// add code here to process the aggregate
}

addNullQuery(String fieldName)
Adds a null query to the aggregate.

Parameters

Name Type Description

fieldName String The name of the field.

Returns

Type Description

GlideQueryCondition The scoped query condition.

Example

var count = new GlideAggregate('incident');

count.addNullQuery('short_description');
count.query(); // Issue the query to the database to get all records
while (count.next()) {
// add code here to process the aggregate
}

addQuery(String name, String operator, String value)

Adds a query to the aggregate.

Parameters
 Name Type Description

name String The query to add.

operator String The operator for the query.

value String The list of values to include in the query.

Returns

Type Description

GlideQueryCondition The query condition.

Example

//Number of incidents varies depending on the current state

//of the incident table
var count = new GlideAggregate('incident');
count.addQuery('active', '=','true');
count.addAggregate('COUNT', 'category');
count.query();
while (count.next()) {
var category = count.category;
var categoryCount = count.getAggregate('COUNT', 'category');
gs.info("There are currently " + categoryCount + " incidents with a category of " + category);
}

There are currently 1 incidents with a category of database

There are currently 5 incidents with a category of hardware
There are currently 42 incidents with a category of inquiry
There are currently 4 incidents with a category of network
There are currently 4 incidents with a category of request
There are currently 7 incidents with a category of software

addTrend(String fieldName, String timeInterval, Number numUnits)

Adds a trend for a specified field.

Parameters
 Name Type Description

fieldName String Name of the field for which trending should occur.

Time interval for the trend.

Valid values:

date
dayofweek
hour
timeInterval String
minute
quarter
value
week
year

Optional. Only valid when timeInterval = minute. Number of minutes to

include in the trend.
numUnits Number
Default: 1

Returns

Type Description

void Method does not return a value

Example

var ga = new GlideAggregate('incident');

ga.addAggregate('COUNT'); // Count all incidents opened each quarter
ga.addTrend('opened_at', 'quarter');
ga.query();
while(ga.next()) {
gs.info([ga.getValue('timeref'), ga.getAggregate('COUNT')]);
}

3/2018, 9
4/2018, 2
1/2019, 38
2/2019, 310

getAggregate(String agg, String name)

Returns the value of an aggregate from the current query.

Parameters
 Name Type Description

Type of aggregate.
Valid values:

AVG
COUNT
agg String
MIN
MAX
STDDEV
SUM

name String Name of the field on which to obtain the aggregation.

Returns

Type Description

Value of the aggregation.

If the values being aggregated are FX Currency values, the returned value is in the
String format <currency_code;currency_value> , such as: USD;134.980000.
Note: If the specified field contains FX Currency values of mixed currency types, the
method is not able to aggregate the values and returns a semicolon (;).

Example

This shows a COUNT aggregation that returns the number of records in the Incident table.

var count = new GlideAggregate('incident');

count.addAggregate('COUNT');
count.query();
var incidents = 0;
if (count.next()) {
incidents = count.getAggregate('COUNT');
}
//Number of incidents varies depending on the current state
//of the incident table
gs.info('Number of incidents: ' + incidents);

Number of incidents: 63

Example

This shows the aggregation of an FX Currency field.

var ga = new GlideAggregate('laptop_tracker');

ga.addAggregate('SUM', 'cost');
ga.groupBy('name');
ga.query();
while (ga.next()) {
gs.info('Aggregate results ' + ga.getValue('name') + ' => ' + ga.getAggregate('SUM', 'cost'));
}
 *** Script: Aggregate results Apple MacBook Air => USD;1651.784280000000
*** Script: Aggregate results Apple MacBook Pro => USD;1651.784280000000
*** Script: Aggregate results Dell XPS => USD;470.852672000000
*** Script: Aggregate results LG =>
*** Script: Aggregate results Samsung Galaxy => USD;225.320000000000
*** Script: Aggregate results Surface3 => USD;2895.560369520000
*** Script: Aggregate results Toshiba => USD;9385.202875800000

getAggregateEncodedQuery()
Gets the query necessary to return the current aggregate.

Returns

Type Description

String The encoded query to get the aggregate.

Example

var count = new GlideAggregate('incident');

count.addAggregate('MIN', 'sys_mod_count');
count.groupBy('category');
count.query();
while (count.next()) {
gs.info(count.getAggregateEncodedQuery());
}

category=database
category=hardware
category=inquiry
category=network
category=request
category=software

getEncodedQuery()
Retrieves the encoded query.

Returns

Type Description

String The encoded query.

Example
 var count = new GlideAggregate('incident');
count.addAggregate('MIN', 'sys_mod_count');
count.addAggregate('MAX', 'sys_mod_count');
count.addAggregate('AVG', 'sys_mod_count');
count.groupBy('category');
count.query();
gs.info(count.getEncodedQuery());

ORDERBYcategory^GROUPBYcategory

getRowCount()
Retrieves the number of rows in the GlideAggregate object.

Returns

Type Description

Number The number of rows in the GlideAggregate object.

Example

var count = new GlideAggregate('incident');

count.addAggregate('MIN', 'sys_mod_count');
count.addAggregate('MAX', 'sys_mod_count');
count.addAggregate('AVG', 'sys_mod_count');
count.groupBy('category');
count.query();
gs.info(count.getRowCount());
while (count.next()) {
var min = count.getAggregate('MIN', 'sys_mod_count');
var max = count.getAggregate('MAX', 'sys_mod_count');
var avg = count.getAggregate('AVG', 'sys_mod_count');
var category = count.category.getDisplayValue();
gs.info(category + " Update counts: MIN = " + min + " MAX = " + max + " AVG = " + avg);
}

6
Database Update counts: MIN = 8 MAX = 48 AVG = 28.0000
Hardware Update counts: MIN = 4 MAX = 14 AVG = 6.6250
Inquiry / Help Update counts: MIN = 0 MAX = 34 AVG = 6.5714
Network Update counts: MIN = 3 MAX = 37 AVG = 18.6000
Request Update counts: MIN = 5 MAX = 39 AVG = 13.4000
Software Update counts: MIN = 4 MAX = 98 AVG = 24.0000

getTableName()
Retrieves the table name associated with this GlideAggregate object.

Returns
 Type Description

String The table name.

Example

var count = new GlideAggregate('incident');

count.addAggregate('MIN', 'sys_mod_count');
count.addAggregate('MAX', 'sys_mod_count');
count.addAggregate('AVG', 'sys_mod_count');
count.groupBy('category');
count.query();
gs.info(count.getTableName());

getValue(String name)
Returns the value of the specified field.

Parameters

Name Type Description

name String Name of the field within the current table to return.

Returns

Type Description

String Value of the specified field.

Example

var count = new GlideAggregate('incident');

count.addAggregate('MAX', 'sys_mod_count');
count.groupBy('category');
count.query();
while (count.next()) {
gs.info(count.getValue('category') + " category had " + count.getAggregate('MAX', 'sys_mod_count') + " updat
}

category had 12 updates

hardware category had 15 updates
inquiry category had 36 updates
network category had 37 updates
software category had 95 updates

groupBy(String name)
Provides the name of a field to use in grouping the aggregates.

May be called numerous times to set multiple group fields.

Parameters

Name Type Description

name String Name of the field.

Returns

Type Description

void Method does not return a value

Example

var count = new GlideAggregate('incident');

count.addAggregate('MIN', 'sys_mod_count');
count.addAggregate('MAX', 'sys_mod_count');
count.addAggregate('AVG', 'sys_mod_count');
count.groupBy('category');
count.query();
while (count.next()) {
var min = count.getAggregate('MIN', 'sys_mod_count');
var max = count.getAggregate('MAX', 'sys_mod_count');
var avg = count.getAggregate('AVG', 'sys_mod_count');
var category = count.category.getDisplayValue();
gs.info(category + " Update counts: MIN = " + min + " MAX = " + max + " AVG = " + avg);
}

Database Update counts: MIN = 8 MAX = 48 AVG = 28.0000

Hardware Update counts: MIN = 4 MAX = 14 AVG = 6.6250
Inquiry / Help Update counts: MIN = 0 MAX = 34 AVG = 6.5714
Network Update counts: MIN = 3 MAX = 37 AVG = 18.6000
Request Update counts: MIN = 5 MAX = 39 AVG = 13.4000
Software Update counts: MIN = 4 MAX = 98 AVG = 24.0000

hasNext()
Determines if there are any more records in the GlideAggregate object.

Returns

Type Description

Boolean True if there are more results in the query set.

Example
 var agg = new GlideAggregate('incident');
agg.addAggregate('AVG', 'sys_mod_count');
agg.groupBy('category');
agg.query();
while (agg.hasNext()) {
agg.next();
var avg = agg.getAggregate('AVG', 'sys_mod_count');
var category = agg.category.getDisplayValue();
gs.info(category + ': AVG = ' + avg);
}

Database: AVG = 32.5000

Hardware: AVG = 12.0000
Inquiry / Help: AVG = 7.6667
Network: AVG = 24.0000
Request: AVG = 16.4000
Software: AVG = 27.0833

next()
Moves to the next record in the GlideAggregate.

Returns

Type Description

Boolean True if there are more records in the query set; otherwise, false.

Example

var count = new GlideAggregate('incident');

count.addAggregate('COUNT');
count.query();
var incidents = 0;
if (count.next()) {
incidents = count.getAggregate('COUNT');
gs.info(incidents);
}

orderBy(String name)
Orders the aggregates using the value of the specified field. The field will also be added to the group-by list.

Parameters

Name Type Description

name String Name of the field to order the aggregates by.

Returns
 Type Description

void Method does not return a value

Example

var agg = new GlideAggregate('incident');

agg.addAggregate('count', 'category');
agg.orderBy('category');
agg.query();
while (agg.next()) {
var category = agg.category;
var count = agg.getAggregate('count', 'category');
var agg2 = new GlideAggregate('incident');
agg2.addAggregate('count', 'category');
agg2.orderBy('category');
gs.info(category + ": Current number of incidents:" + count);
}

database: Current number of incidents:2

hardware: Current number of incidents:8
inquiry: Current number of incidents:28
network: Current number of incidents:5
request: Current number of incidents:5
software: Current number of incidents:11

orderByAggregate(String agg, String fieldName)

Orders the aggregates based on the specified aggregate and field.

Parameters

Name Type Description

agg String Type of aggregation.

fieldName String Name of the field to aggregate.

Returns

Type Description

void Method does not return a value

Example
 ga.addAggregate(‘COUNT’, ‘category’);

ga.orderByAggregate('count', 'category');

ga.query();

while(ga.next()) {
gs.info(‘Category ’ + ga.category + ‘ ‘ + ga.getAggregate(‘COUNT’, ‘category’));
}

Category inquiry 18
Category software 11
Category hardware 7
Category network 5
Category request 5
Category 4
Category database 2

orderByDesc(String name)
Sorts the aggregates in descending order based on the specified field. The field will also be added to the group-
by list.

Parameters

Name Type Description

name String Name of the field.

Returns

Type Description

void Method does not return a value

Example

var agg = new GlideAggregate('incident');

agg.addAggregate('count', 'category');
agg.orderByDesc('category');
agg.query();
while (agg.next()) {
var category = agg.category;
var count = agg.getAggregate('count', 'category');
var agg2 = new GlideAggregate('incident');
agg2.addAggregate('count', 'category');
agg2.orderBy('category');
gs.info(category + ": Current number of incidents:" + count);
}
 software: Current number of incidents:11
request: Current number of incidents:5
network: Current number of incidents:5
inquiry: Current number of incidents:28
hardware: Current number of incidents:8
database: Current number of incidents:2

query()
Issues the query and gets the results.

Returns

Type Description

void Method does not return a value

Example

var count = new GlideAggregate('incident');

count.addAggregate('COUNT');
count.query();
var incidents = 0;
if (count.next()) {
incidents = count.getAggregate('COUNT');
}
gs.info('Number of incidents: ' + incidents);

setGroup(Boolean b)
Sets whether the results are to be grouped.

Parameters

Name Type Description

b Boolean When true the results are grouped.

Returns

Type Description

void Method does not return a value

Example
var ga = new GlideAggregate('incident');
ga.addAggregate('COUNT', 'category');

ga.setGroup(true);
ga.groupBy("category");

ga.query();

while(ga.next()) {
gs.info('Category ' + ga.category + ' ' + ga.getAggregate('COUNT', 'category'));
}

Category database 2
Category hardware 7
Category inquiry 18
Category network 5
Category request 5
Category software 11