Product documentation Docs
    • English
    • Deutsch
    • 日本語
    • 한국어
    • Français
  • More Sites
    • Now Community
    • Developer Site
    • Knowledge Base
    • Product Information
    • ServiceNow.com
    • Training
    • Customer Success Center
    • ServiceNow Support Videos
  • Log in

Product documentation

  • Home
How search works:
  • Punctuation and capital letters are ignored
  • Special characters like underscores (_) are removed
  • Known synonyms are applied
  • The most relevant topics (based on weighting and matching to search terms) are listed first in search results
Topics are ranked in search results by how closely they match your search terms
  • A match on the entire phrase you typed
  • A match on part of the phrase you typed
  • A match on ALL of the terms in the phrase you typed
  • A match on ANY of the terms in the phrase you typed

Note: Matches in titles are always highly ranked.

  • Release version
    Table of Contents
    • Now Platform App Engine
Table of Contents
Choose your release version
    Home Paris Now Platform App Engine Now Platform App Engine Web services GraphQL API framework

    GraphQL API framework

    • Save as PDF Selected topic Topic & subtopics All topics in contents
    • Unsubscribe Log in to subscribe to topics and get notified when content changes.
    • Share this page

    GraphQL API framework

    Create a custom GraphQL API to query record data from a component or a third-party system.

    For example, you can create a component that displays the cases associated with an SLA. You can use the Now® Experience UI Framework to develop the component you need, and access case data from the platform by creating a GraphQL schema that defines data in the Case table.

    To learn more about developing components, see Developing components for Workspace.

    Benefits of GraphQL

    GraphQL is a web query language optimized for client-side development. Using scripted GraphQL, you can:

    • Discover fields and objects available to query through introspection.
    • Query the exact data you need from a component.
    • Manage multiple possible queries from a single API, as opposed to multiple endpoints for a REST request.
    • Integrate with third-party systems by making the schema public.
    • Generate the GraphQL query from your component and handle the response.

    What to know before you begin

    Before you start creating custom GraphQL APIs, make sure you have:

    • GraphQL knowledge to create a schema.
    • JavaScript knowledge to define the API behavior.
    • General knowledge of web component concepts.
    • A custom Workspace component to consume record data.
    • Understanding of the ServiceNow data model that you want to expose in the schema.
    • GlideRecord knowledge to map fields to record data in your resolver scripts.

    GraphQL overview

    Creating a scripted GraphQL API includes these parts:

    GraphQL Schema Definition Language (SDL)
    Define the structure and data type of fields available in a GraphQL query. You can define the SDL using the Schema script field in the GraphQL Scripted Schemas [sys_graphql_schema] table. The SDL only supports Query and Mutation operations.
    Resolvers
    Define the data returned by each field. You can define the resolvers for each field in the GraphQL Scripted Resolvers related list on the GraphQL Scripted Schemas form.
    Typeresolvers
    Resolve interfaces and unions into concrete GraphQL types. For example, you might define a union between an incident type and a problem type. Use the typeresolver script to define when to return which. You can define the typeresolvers in the GraphQL Scripted Typeresolvers related list on the GraphQL Scripted Schemas form.
    Resolver mappings
    Map resolvers to fields in the schema. You can define resolver mappings in the GraphQL Scripted Resolver Mappings related list on the GraphQL Scripted Schemas form.

    To learn more about the GraphQL query language, see the GraphQL website.

    Limitations

    The following GraphQL features are not supported:

    • Subscription operations
    • Custom scalar types

    Introspection

    By default, introspective queries into your custom schemas are not allowed. To allow introspection, set a system property. See GraphQL system properties.

    Namespaces

    GraphQL APIs have two different namespaces:

    Application namespace
    The namespace for the custom application. To learn more about application namespaces, see Application scope.
    Schema namespace
    The namespace for the schema to ensure that all queries are unique. You can have multiple schema namespaces in a single application.

    When querying data, you must include both namespaces in your query. For example, the following query is searching for data with the following namespaces:

    • Application namespace: x_graph_scope
    • Schema namespace: planet
    query {
      x_graph_scope {
        planet {
          findAll {
            name
            mass
            distance
          }
        }
      }
    }

    Directives and global functions

    @source schema directive

    Maps a graphQL field to the value of a property of the parent object. If the field has a separate resolver script, the system uses the record that it resolves to instead of the parent object.

    Use in your schema script.

    Resolver functions

    These functions are available on the global env object.

    • getArguments(): Returns the arguments of the previous field.
    • getSource(): Returns the parent object.

    Use in your resolver script.

    Typeresolver functions

    These functions are available on the global env object.

    • getArguments(): Returns the arguments of the previous field.
    • getObject(): Returns the parent object.
    • getTypeName(): Returns the name of the interface or union type.

    Use in your typeresolver script.

    Demo application

    To see a demo GraphQL PTO calendar schema with mutations and queries, enable the Demo Data for GraphQL Schemas plugin (com.glide.graphql.schemas.demo).

    • Create a GraphQL schema

      Create a GraphQL schema to make data available to GraphQL queries.

    • Test a GraphQL schema

      Test your GraphQL schema using a third-party tool.

    • Query a GraphQL schema from a component

      Access record data in a component by querying your scripted GraphQL schema.

    • GraphQL system properties

      Configure GraphQL API framework behavior. For example, you can configure whether to allow introspective queries into your schema.

    Tags:

    Feedback
    On this page

    Previous topic

    Next topic

    • Contact Us
    • Careers
    • Terms of Use
    • Privacy Statement
    • Sitemap
    • © ServiceNow. All rights reserved.

    Release version
    Choose your release version

      GraphQL API framework

      • Save as PDF Selected topic Topic & subtopics All topics in contents
      • Unsubscribe Log in to subscribe to topics and get notified when content changes.
      • Share this page

      GraphQL API framework

      Create a custom GraphQL API to query record data from a component or a third-party system.

      For example, you can create a component that displays the cases associated with an SLA. You can use the Now® Experience UI Framework to develop the component you need, and access case data from the platform by creating a GraphQL schema that defines data in the Case table.

      To learn more about developing components, see Developing components for Workspace.

      Benefits of GraphQL

      GraphQL is a web query language optimized for client-side development. Using scripted GraphQL, you can:

      • Discover fields and objects available to query through introspection.
      • Query the exact data you need from a component.
      • Manage multiple possible queries from a single API, as opposed to multiple endpoints for a REST request.
      • Integrate with third-party systems by making the schema public.
      • Generate the GraphQL query from your component and handle the response.

      What to know before you begin

      Before you start creating custom GraphQL APIs, make sure you have:

      • GraphQL knowledge to create a schema.
      • JavaScript knowledge to define the API behavior.
      • General knowledge of web component concepts.
      • A custom Workspace component to consume record data.
      • Understanding of the ServiceNow data model that you want to expose in the schema.
      • GlideRecord knowledge to map fields to record data in your resolver scripts.

      GraphQL overview

      Creating a scripted GraphQL API includes these parts:

      GraphQL Schema Definition Language (SDL)
      Define the structure and data type of fields available in a GraphQL query. You can define the SDL using the Schema script field in the GraphQL Scripted Schemas [sys_graphql_schema] table. The SDL only supports Query and Mutation operations.
      Resolvers
      Define the data returned by each field. You can define the resolvers for each field in the GraphQL Scripted Resolvers related list on the GraphQL Scripted Schemas form.
      Typeresolvers
      Resolve interfaces and unions into concrete GraphQL types. For example, you might define a union between an incident type and a problem type. Use the typeresolver script to define when to return which. You can define the typeresolvers in the GraphQL Scripted Typeresolvers related list on the GraphQL Scripted Schemas form.
      Resolver mappings
      Map resolvers to fields in the schema. You can define resolver mappings in the GraphQL Scripted Resolver Mappings related list on the GraphQL Scripted Schemas form.

      To learn more about the GraphQL query language, see the GraphQL website.

      Limitations

      The following GraphQL features are not supported:

      • Subscription operations
      • Custom scalar types

      Introspection

      By default, introspective queries into your custom schemas are not allowed. To allow introspection, set a system property. See GraphQL system properties.

      Namespaces

      GraphQL APIs have two different namespaces:

      Application namespace
      The namespace for the custom application. To learn more about application namespaces, see Application scope.
      Schema namespace
      The namespace for the schema to ensure that all queries are unique. You can have multiple schema namespaces in a single application.

      When querying data, you must include both namespaces in your query. For example, the following query is searching for data with the following namespaces:

      • Application namespace: x_graph_scope
      • Schema namespace: planet
      query {
        x_graph_scope {
          planet {
            findAll {
              name
              mass
              distance
            }
          }
        }
      }

      Directives and global functions

      @source schema directive

      Maps a graphQL field to the value of a property of the parent object. If the field has a separate resolver script, the system uses the record that it resolves to instead of the parent object.

      Use in your schema script.

      Resolver functions

      These functions are available on the global env object.

      • getArguments(): Returns the arguments of the previous field.
      • getSource(): Returns the parent object.

      Use in your resolver script.

      Typeresolver functions

      These functions are available on the global env object.

      • getArguments(): Returns the arguments of the previous field.
      • getObject(): Returns the parent object.
      • getTypeName(): Returns the name of the interface or union type.

      Use in your typeresolver script.

      Demo application

      To see a demo GraphQL PTO calendar schema with mutations and queries, enable the Demo Data for GraphQL Schemas plugin (com.glide.graphql.schemas.demo).

      • Create a GraphQL schema

        Create a GraphQL schema to make data available to GraphQL queries.

      • Test a GraphQL schema

        Test your GraphQL schema using a third-party tool.

      • Query a GraphQL schema from a component

        Access record data in a component by querying your scripted GraphQL schema.

      • GraphQL system properties

        Configure GraphQL API framework behavior. For example, you can configure whether to allow introspective queries into your schema.

      Tags:

      Feedback

          Share this page

          Got it! Feel free to add a comment
          To share your product suggestions, visit the Idea Portal.
          Please let us know how to improve this content

          Check any that apply

          To share your product suggestions, visit the Idea Portal.
          Confirm

          We were unable to find "Coaching" in Jakarta. Would you like to search instead?

          No Yes
          • Contact Us
          • Careers
          • Terms of Use
          • Privacy Statement
          • Sitemap
          • © ServiceNow. All rights reserved.

          Subscribe Subscribed Unsubscribe Last updated: Tags: January February March April May June July August September October November December No Results Found Versions Search preferences successfully updated My release version successfully updated My release version successfully deleted An error has occurred. Please try again later. You have been unsubscribed from all topics. You are now subscribed to and will receive notifications if any changes are made to this page. You have been unsubscribed from this content Thank you for your feedback. Form temporarily unavailable. Please try again or contact  docfeedback@servicenow.com  to submit your comments. The topic you requested does not exist in the release. You were redirected to a related topic instead. The available release versions for this topic are listed There is no specific version for this documentation. Explore products Click to go to the page. Release notes and upgrades Click to open the dropdown menu. Delete Remove No selected version Reset This field is required You are already subscribed to this topic Attach screenshot The file you uploaded exceeds the allowed file size of 20MB. Please try again with a smaller file. Please complete the reCAPTCHA step to attach a screenshot
          Log in to personalize your search results and subscribe to topics
          No, thanks Login