GlideRecord - Global

GlideRecord - Global

GlideRecord - Global

GlideRecord is used for database operations.

A GlideRecord contains both records and fields. For information about GlideRecordSecure, which
is a class inherited from GlideRecord that performs the same functions as GlideRecord, and also
enforces ACLs, see the
Using GlideRecordSecure.

Always test queries on a
sub-production instance prior to deploying them on a production instance. An incorrectly
constructed encoded query, such as including an invalid field name, produces an invalid
query. When the invalid query is run, the invalid part of the query condition is dropped,
and the results are based on the valid part of the query, which may return all records from
the table. Using an insert(), update(),
deleteRecord(), or deleteMultiple() method on bad
query results can result in data loss.

You can set the glide.invalid_query.returns_no_rows system
property to true to have queries with invalid encoded queries return no records.

Scoped equivalent

GlideRecord - addDomainQuery(Object glideRecord)

Changes the domain used for the query from the user's domain to the domain of the
provided GlideRecord.

Always test queries on a
sub-production instance prior to deploying them on a production instance. An incorrectly
constructed encoded query, such as including an invalid field name, produces an invalid
query. When the invalid query is run, the invalid part of the query condition is dropped,
and the results are based on the valid part of the query, which may return all records from
the table. Using an insert(), update(),
deleteRecord(), or deleteMultiple() method on bad
query results can result in data loss.

You can set the glide.invalid_query.returns_no_rows system
property to true to have queries with invalid encoded queries return no records.

Table 3. Parameters

Name

Type

Description

glideRecord

Object

GlideRecord from which to obtain the domain.

Table 4. Returns

Type

Description

void

//This example requires the Domain plugin be active, the Group table is the specified
//Domain table, and the ITIL user is in the Database Atlanta domain
//From any domain (using queryNoDomain()) look up the incidents that an ITIL user can only see
//who is in the Database Atlanta domain, should expect all incidents with the global or the
//Database Atlanta domain specified.
var domain = new GlideRecord('sys_user');
domain.addQuery('user_name', 'itil');
domain.queryNoDomain();
if (domain.next()) {
var domainQuery = new GlideRecord('incident');
domainQuery.addQuery('active', true);
domainQuery.addDomainQuery(domain);
domainQuery.query();
gs.print('Number of Incidents for ITIL user: ' + domainQuery.getRowCount());
while (domainQuery.next())
gs.print(domainQuery.number);
}

Scoped equivalent

This method is not available in scoped applications.

GlideRecord - addEncodedQuery(String query)

Adds an encoded query to other queries that may have been set.

Always test queries on a
sub-production instance prior to deploying them on a production instance. An incorrectly
constructed encoded query, such as including an invalid field name, produces an invalid
query. When the invalid query is run, the invalid part of the query condition is dropped,
and the results are based on the valid part of the query, which may return all records from
the table. Using an insert(), update(),
deleteRecord(), or deleteMultiple() method on bad
query results can result in data loss.

You can set the glide.invalid_query.returns_no_rows system
property to true to have queries with invalid encoded queries return no records.

Scoped equivalent

GlideRecord - addJoinQuery(String table)

Adds a filter to return records based on a relationship in a related table.

For example, find all the users that are in the database group (users via sys_user_grmember
table). Another example would be find all problems that have an assigned incident (problems
via the incident.problem_id relationship).

This is not a true database join; rather, addJoinQuery() adds a
subquery. So, while the result set is limited based on the join, the only fields that you
have access to are those on the base table (those which are in the table with which the
GlideRecord was initialized).

Always test queries on a
sub-production instance prior to deploying them on a production instance. An incorrectly
constructed encoded query, such as including an invalid field name, produces an invalid
query. When the invalid query is run, the invalid part of the query condition is dropped,
and the results are based on the valid part of the query, which may return all records from
the table. Using an insert(), update(),
deleteRecord(), or deleteMultiple() method on bad
query results can result in data loss.

You can set the glide.invalid_query.returns_no_rows system
property to true to have queries with invalid encoded queries return no records.

Table 11. Parameters

Name

Type

Description

table

String

Table name

Table 12. Returns

Type

Description

QueryCondition

Records where the relationships match.

Find problems that have an incident attached. This example returns problems that have
associated incidents. However, it won't pull values from the incidents that are returned as
a part of the query.

Scoped equivalent

GlideRecord - addJoinQuery(String table, String primaryField)

Adds a filter to return records based on a relationship in a related table.

For example, find all the users that are in the database group (users via sys_user_grmember
table). Another example would be find all problems that have an assigned incident (problems
via the incident.problem_id relationship).

This is not a true database join; rather, addJoinQuery() adds a
subquery. So, while the result set is limited based on the join, the only fields that you
have access to are those on the base table (those which are in the table with which the
GlideRecord was initialized).

Always test queries on a
sub-production instance prior to deploying them on a production instance. An incorrectly
constructed encoded query, such as including an invalid field name, produces an invalid
query. When the invalid query is run, the invalid part of the query condition is dropped,
and the results are based on the valid part of the query, which may return all records from
the table. Using an insert(), update(),
deleteRecord(), or deleteMultiple() method on bad
query results can result in data loss.

You can set the glide.invalid_query.returns_no_rows system
property to true to have queries with invalid encoded queries return no records.

Adds a filter to return records based on a relationship in a related table.

For example, find all the users that are in the database group (users via sys_user_grmember
table). Another example would be find all problems that have an assigned incident (problems
via the incident.problem_id relationship).

This is not a true database join; rather, addJoinQuery() adds a
subquery. So, while the result set is limited based on the join, the only fields that you
have access to are those on the base table (those which are in the table with which the
GlideRecord was initialized).

Always test queries on a
sub-production instance prior to deploying them on a production instance. An incorrectly
constructed encoded query, such as including an invalid field name, produces an invalid
query. When the invalid query is run, the invalid part of the query condition is dropped,
and the results are based on the valid part of the query, which may return all records from
the table. Using an insert(), update(),
deleteRecord(), or deleteMultiple() method on bad
query results can result in data loss.

You can set the glide.invalid_query.returns_no_rows system
property to true to have queries with invalid encoded queries return no records.

Table 15. Parameters

Name

Type

Description

table

String

Table name

primaryField

String

If other than sys_id, the primary field.

joinTableField

String

If other than sys_id, the field that joins the tables

Table 16. Returns

Type

Description

QueryCondition

Records where the relationships match.

Find problems that have incidents associated where the incident caller_id field value
matches that of the problem opened_by field.

GlideRecord - addNotNullQuery(String fieldName)

Adds a filter to return records where the specified field is not null.

Table 17. Parameters

Name

Type

Description

fieldName

String

The field name.

Table 18. Returns

Type

Description

QueryCondition

QueryCondition of records where the parameter field is not null.

var target = new GlideRecord('incident');
target.addNotNullQuery('short_description');
target.query(); // Issue the query to the database to get all records
while (target.next()) {
// add code here to process the incident record
}

var target = new GlideRecord('incident');
target.addNullQuery('short_description');
target.query(); // Issue the query to the database to get all records
while (target.next()) {
// add code here to process the incident record
}

Scoped equivalent

GlideRecord - addQuery(String name, Object operator, Object value)

Provides the ability to build a request, which when executed, returns the rows from the
specified table that match the request.

If you are familiar with SQL, this method is similar to the "where" clause. One or more
addQuery() calls can be made in a single query; in this case the
queries are AND'ed. If any of the query statements need to be OR'ed, use the class GlideQueryCondition - Global.

addQuery() is typically called with three parameters; table field,
operator, and comparison value. It can be called with only two parameters, table field and
comparison value, such as myObj.addQuery('category','Hardware');. The
operator in this case is assumed to be "equal to".

Always test queries on a
sub-production instance prior to deploying them on a production instance. An incorrectly
constructed encoded query, such as including an invalid field name, produces an invalid
query. When the invalid query is run, the invalid part of the query condition is dropped,
and the results are based on the valid part of the query, which may return all records from
the table. Using an insert(), update(),
deleteRecord(), or deleteMultiple() method on bad
query results can result in data loss.

You can set the glide.invalid_query.returns_no_rows system
property to true to have queries with invalid encoded queries return no records.

Table 21. Parameters

Name

Type

Description

name

String

Table field name

operator

Object

Query operator. The available values are dependent on the data type of the
value parameter.

GlideRecord - autoSysFields(Boolean e)

Enables or disables the update to the fields sys_updated_by, sys_updated_on,
sys_mod_count, sys_created_by, and sys_created_on. This is often used for manually updating
field values on a record while leaving historical information unchanged.

Note: This is not available for scoped apps, starting with the Fuji release. See the Scoped
GlideRecord API Reference for a list of what APIs are available for scoped apps.

Caution: Use caution if you use this method. When you use this method the
sys_mod_count field will not be incremented, and other sys_ fields will not be updated. This
can break functionality including, but not limited to, the Activity Formatter, History Sets,
and Metrics.

GlideRecord - deleteMultiple()

Deletes multiple records according to the current "where" clause.

This method does not delete attachments.

Dot-walking is not supported for this method. When using the
deleteMultiple() function on referenced tables, all the records in the
table are deleted. Also, when using deleteRecord() to cascade delete,
prior calls to setWorkflow() on the same GlideRecord object are ignored.

Do not use deleteMultiple() on tables with currency fields. Always
delete each record individually. Also, do not use this method with the
chooseWindow() or setLimit() methods when working
with large tables.

Scoped equivalent

GlideRecord - find(String columnName, String value)

Returns true if any record has a matching value in the specified column. If found, it
also moves to the first record that matches, essentially executing next()
until the record is returned.

Table 41. Parameters

Name

Type

Description

columnName

String

Specifies the field name.

value

String

Specifies the value to check for in the specified field.

Table 42. Returns

Type

Description

Boolean

True if any record has a matching value in the specified field.

GlideRecord - get(Object name, Object value)

Creates a GlideRecord based on a specified 'name = value' pair.

If the value parameter is not specified, then the method assumes the
name parameter contains the sys_id.

Note: If you only pass a single parameter into this method, and that parameter is not the
sys_id, the system performs a search across multiple fields (sys_id, name, number, so on).
This action causes the system to try to create multiple records, which fails, and
generates "duplicate record" error messages. To fix this problem, modify your method call
to either contain both parameters or ensure that the passed-in parameter is the
sys_id.

This method is meant for the query of single records. Therefore, the system performs a
'next' operation on the record before returning.

Scoped equivalent

GlideRecord - insertWithReferences()

Inserts a new record and also inserts or updates any related records with the
information provided.

Table 92. Parameters

Name

Type

Description

None

Table 93. Returns

Type

Description

String

sys_id for the record inserted, or null if the record was not inserted.

If a reference value is not specified (as below), then a new user record is created with
the provided first_name, last_name, and the caller_id value is set to this newly created
sys_user record. The result is a new sys_user record with the provided first_name, last_name
and a new incident record with the provided short_description and caller_id.

If a caller_id value is specified, then that caller_id is updated with the provided
first_name, last_name. The result is a newly created incident record with values set for
short_description and caller_id.

GlideRecord - isNewRecord()

Determines whether the current record has been inserted into the database. This method
returns true only if the newRecord() method has been called. This method is
useful for scripted ACL, and in the condition of UI actions, but should not be used in
background scripts.

Note: This method returns true for any new record during a business rule, or if the
newRecord() method is used to initialize a record with default values
and a unique ID (sys_id). In all other cases, it returns false.

Table 96. Parameters

Name

Type

Description

None

Table 97. Returns

Type

Description

Boolean

True if the current record is new (has not been inserted into the
database.)

Scoped equivalent

GlideRecord - _query(Object field, Object value)

Identical to query(). This method is intended to be used on tables
where there is a column named query, which would interfere with using the
query() method.

Runs the query against the table based on the filters specified by the
addQuery() and addEncodedQuery() methods. This will
query the GlideRecord table as well as any references of the table. One argument adds a
query string. Usually this is performed without arguments, but a name/value pair can be
specified.

GlideRecord - restoreLocation()

Sets the current record to be the record that was saved with
saveLocation(). If saveLocation() has not been called,
the current record is set to be the first record of the GlideRecord.

Table 122. Parameters

Name

Type

Description

None

Table 123. Returns

Type

Description

void

GlideRecord - saveLocation()

Saves the current row number so that we can get back to this location using the
restoreLocation() method.

Table 124. Parameters

Name

Type

Description

None

Table 125. Returns

Type

Description

void

GlideRecord - setAbortAction(Boolean b)

Sets a flag to indicate if the next database action (insert, update, delete) is to be
aborted.

Use in an onBefore business rule
to prevent the database action from being done. The business rule continues to run after
setAbortAction() is called. Calling setAbortAction()
does not stop subsequent business rules from executing. Calling this method only prevents
the database action from occurring.

GlideRecord - setQueryReferences(Boolean queryReferences)

Enables or disables using the reference field's display name when querying a reference
field.

Table 140. Parameters

Name

Type

Description

queryReferences

Boolean

If true, will generate a string of display names. If false, will generate a
string of sys_ids.

Table 141. Returns

Type

Description

void

GlideRecord - setUseEngines(Boolean e)

Disables or enables the running of any engines (approval rules / assignment
rules).

Table 142. Parameters

Name

Type

Description

e

Boolean

If true, enables engines. If false disables engines.

Table 143. Returns

Type

Description

void

GlideRecord - setValue(String name, Object value)

Sets the specified field to the specified value.

Normally a script would do a direct assignment, for example, gr.category =
value. However, if in a script the element name is a variable, then
gr.setValue(elementName, value) can be used. When setting a value, ensure
the data type of the field matches the data type of the value you enter. This method cannot
be used on journal fields.

If the value parameter is null, the record is not updated, and an error is not thrown.

Table 144. Parameters

Name

Type

Description

name

String

Field name

value

Object

A value to be assigned.

Table 145. Returns

Type

Description

void

Scoped equivalent

GlideRecord - setWorkFlow(Boolean e)

Enables or disables the running of business rules that might normally be triggered by
subsequent actions. If the e parameter is set to false, an insert/update will not be audited.
Auditing only happens when the parameter is set to true for a GlideRecord operation.

Note: The setWorkFlow() method is ignored when subsequently using either
the deleteProblem() or deleteMultiple() methods to
cascade delete.

Table 146. Parameters

Name

Type

Description

e

Boolean

If true (default) enables business rules, and if false to disables
them.

Scoped equivalent

GlideRecord - updateMultiple()

Updates each GlideRecord in the list with any changes that have been made.

When changing field values, use setValue() instead of directly setting
the field (field = something). When using
updateMultiple(), directly setting the field (gr. state =
4) results in all records in the table being updated instead of just the records
returned by the query.

Do not use this method with the chooseWindow() or
setLimit() methods when working with large tables.

Scoped equivalent

GlideRecord - updateWithReferences(Object reason)

Updates a record and also inserts or updates any related records with the information
provided.

Table 152. Parameters

Name

Type

Description

reason

Object

A string designating the reasons for the updates. The reason is displayed in
the audit record.

Table 153. Returns

Type

Description

String

The sys_id for the record being updated.

If processing an incident where the Caller ID is set to reference sys_user record 'David
Loo,' then the following code would update David Loo's user record. If processing an
incident where there is no Caller ID specified, then the following code would create a new
sys_user record with the provided information (first_name, last_name) and set the Caller ID
value to the newly created sys_user record.

var inc = new GlideRecord('incident');
inc.get(inc_sys_id); // Looking up an existing incident record where 'inc_sys_id' represents the sys_id of a incident record
inc.caller_id.first_name = 'John';
inc.caller_id.last_name = 'Doe';
inc.updateWithReferences();
}