Using GraphQL in ServiceNow

A Guide to GlideRecord_Query

ServiceNow provides a powerful API called GlideRecord_Query that leverages GraphQL to interact with the platform's data. This guide will walk you through using GraphQL GlideRecord_Query in ServiceNow, focusing on querying records using the GlideRecord_Query API.

Introduction to GraphQL in ServiceNow

GraphQL is a query language for APIs that enables clients to request exactly the data they need. In ServiceNow, GraphQL can be used to perform complex queries efficiently, reducing the amount of data transferred over the network and improving performance.

Prerequisite

Enabling Introspection for GlideRecord_Query in GraphQL Explorer

Introspection in the context of GraphQL is the capability of a GraphQL server to reveal its schema to clients. It allows clients to query the server for information about the available types, fields, queries, and mutations without prior knowledge of the API's structure. By enabling introspection, you allow the GraphQL Explorer to fetch the schema details of the GlideRecord_Query API. This means you can see all the tables, fields, and relationships available for querying.

To introspect the GlideRecord_Query API within the GraphQL Explorer, you need to enable certain system properties. Follow the instrcutions on the image below to enable introspection of the GlideRecord_Query API.

The GlideRecord_Query API

The GlideRecord_Query API is an out-of-the-box (OOTB) feature in ServiceNow that allows you to execute GraphQL queries against the platform's tables. It provides a flexible way to retrieve data, including related records, by leveraging GraphQL's capabilities.

Syntax and Structure

{
  GlideRecord_Query {
    <table_name>(
      queryConditions: "<encoded_query>"
      pagination: {limit: <number>, offset: <number>}
    ) {
      _rowCount
      _results {
        <field1> {
          value
          displayValue
        }
        <field2> {
          value
          displayValue
        }
        <reference_field> {
          _reference {
            <ref_field1> {
              value
            }
            <ref_field2> {
              value
            }
          }
        }
      }
    }
  }
}

Understanding the Query Components

Table Name

Replace <table_name> with the name of the table you want to query. For example, sn_hr_core_case refers to the HR Case table.

Query Conditions

The queryConditions parameter accepts an encoded query string to filter records. For example:

queryConditions: "active=true"

This filters the records where the active field is true.

Pagination

Control the number of records returned and the starting point using the pagination parameter:

• limit: Maximum number of records to return.
• offset: Number of records to skip before starting to return records.

Retrieving Data

Fields and Their Values

Inside the _results object, specify the fields you want to retrieve. Each field returns:

• value: The actual value stored in the database.
• displayValue: A user-friendly representation of the value (useful for choice lists, dates, or references).

Reference Fields and Dot-Walking

To access fields from a referenced record, use the _reference keyword. This is known as "dot-walking." For example:

assigned_to {
  _reference {
    first_name {
      value
    }
    email {
      value
    }
  }
}

This retrieves the first_name and email of the user referenced in the assigned_to field.

Example Query

{
  GlideRecord_Query {
    sn_hr_core_case(
      queryConditions: "active=true"
      pagination: {limit: 10, offset: 0}
    ) {
      _rowCount
      _results {
        sys_id {
          value
        }
        short_description {
          value
        }
        assignment_group {
          value
          displayValue
        }
        assigned_to {
          _reference {
            first_name {
              value
            }
            email {
              value
            }
          }
        }
      }
    }
  }
}

Explanation

• sn_hr_core_case: Queries the HR Case table.
• queryConditions: Filters for active cases.
• pagination: Retrieves the first 10 records.
• _rowCount: Returns the total number of records matching the query.
• _results: Contains the fields to retrieve:
  • sys_id: The unique identifier of the record.
  • short_description: A brief description of the case.
  • assignment_group: The group assigned to the case, including both value and displayValue.
  • assigned_to: Dot-walks into the referenced user record to get first_name and email.

GraphQL Explorer

GraphQL Explorer in ServiceNow is a built-in tool that allows developers to interactively construct, test, and debug GraphQL queries directly within the platform. It provides an interface to explore the GraphQL APIs available in your ServiceNow instance, such as the GlideRecord_Query API. The Explorer offers features like syntax highlighting, auto-completion, and real-time query results, making it easier to work with GraphQL queries.

When you are in the explorer and having turned on introspection, holding down Ctrl + Space will allow intellisense

Conclusion

Using GraphQL with ServiceNow's GlideRecord_Query API provides a powerful and flexible way to interact with your data. By understanding the syntax and structure of GraphQL queries, you can efficiently retrieve exactly the information you need, including related records through dot-walking.