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
