Create a GraphQL schema

  • Release version: Washingtondc
  • Updated February 1, 2024
  • 3 minutes to read

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

    Before you begin

    Role required: graphql_schema_admin or admin

    Procedure

    1. Navigate to All > System Web Services > GraphQL > GraphQL APIs.
    2. Click New.
    3. Complete these fields.
      Field Description
      Name Name of the schema.
      Schema namespace Must be unique within the name of the application.
      Application Read-only application that the schema is a part of.
      Application namespace Read-only. Works with the Schema namespace to prevent conflict with schemas with the same name.
      Active Checked if active, unchecked if not active.
      Schema Schema definition that adheres to the GraphQL SDL format. Must be GraphQL valid syntax. Otherwise, error messages appear on save to indicate the syntax problem.
      Note:
      The following GraphQL features are not supported:
      • Subscription operations
      • Custom scalar types

      You can use this directive in your schema:

      @source: 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.

      This example defines an Incident object type in the schema and uses a resolver script to map the type to a GlideRecord from the Incident table. Using the @source directive maps the fields within the Incident type to the value or display_value in the Incident GlideRecord.

      type Incident {
    id: String @source(value: "sys_id.value")
    active: Boolean @source(value: "active.display_value")
    state: String @source(value: "state.display_value")    
    priority: String @source(value: "priority.display_value")
    severity: String
    description: DisplayableString
    resolvedBy: User @source(value: "resolved_by.value")
    openedBy: User @source(value: "opened_by.value")
    child_incidents: String
    opened_at: String
    resolved_at: String
    closed_at: String
    work_notes: String    
    comments: String @source(value: "comments.display_value")
    parent_incident: String
}
    4. Select the Security tab and complete the form.
      Field Description
      Requires authentication Checked if the schema requires authentication, unchecked if the schema doesn't require authentication and is available publicly.
      Requires SNC internal Appears only if the Explicit Roles plugin is enabled. Checked if the schema requires the SNC internal role, unchecked if the schema doesn't require the SNC internal role.
      Requires ACL authorization Checked if the schema requires ACL authorization, unchecked if the schema doesn't require ACL authorization.
      ACLs Appears only if Requires ACL authorization is checked. Checks incoming queries against ACLs of type GraphQL.
      Note:
      The API returns clear error messages to users who do not have access to a schema, or who are not authenticated when the API requires authentication to access.
    5. Save the form.
    6. Optional: Create a resolver script to define what value the schema returns when a component queries a specific field.
      If you don't define a resolver for a field, the query returns any matching field value from the parent object type. For example, suppose you have an Incident object type in your schema with a worknotes field. The Incident object type has a resolver that maps to a GlideRecord from the Incident table. If you do not create a resolver mapping for the worknotes field, the system searches the parent object's data source, which is the GlideRecord from the Incident table, for a worknotes field and assigns the associated value.
      1. Select the GraphQL Scripted Resolvers tab and click New.
      2. Complete the form.
        Field Description
        Name Name of the resolver.
        Schema Read-only schema namespace.
        Application Read-only application that the schema is a part of.
        Script Define the value returned when the field is queried. Functions available on the global env object:
        • getArguments(): Returns the arguments of the previous field.
        • getSource(): Returns the parent object.

        This script has access to GlideRecord.

        This example returns a record from the User table when the associated field is queried:

        (function process(/*ResolverEnvironment*/ env) {

    var userid = env.getArguments().id != null ? env.getArguments().id : env.getSource();
    var now_GR = new GlideRecord('sys_user');
    gr.addQuery('sys_id', userid);
    gr.queryO;
    return gr;

})(env);
      3. Click Submit.
    7. Optional: Define the typeresolvers for your schema to resolve interfaces and unions into concrete types.
      1. Select the GraphQL Scripted Typeresolvers tab and click New.
      2. Complete the form.
        Field Description
        Schema Read-only schema namespace.
        Type The interface or union type defined in the schema.
        Application Read only application that the schema is a part of.
        Script Define the value returned for union and interface types. Functions 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.

        This script has access to GlideRecord.
      3. Click Submit.
    8. Optional: Map the resolver and typeresolver records to fields in the schema.
      This mapping lets the system know what value to return when a component queries a specific field.
      1. Select the GraphQL Scripted Resolver Mappings tab and click New.
      2. Complete the form.
        Field Description
        Path Path to the field in the schema you want to map.
        Resolver Resolver to use to define the data returned by the field.
        Application Read-only application that the schema is a part of.
        Schema Read-only schema namespace.
      3. Click Submit.