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. Select New.
  3. Complete these fields.
    FieldDescription
    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 avoid conflict with schemas with the same name.
    Active Option to turn the GraphQL schema on or off.
    Schema Schema definition that adheres to the GraphQL SDL format. Must be valid GraphQL syntax. Otherwise, error messages appear on save to indicate the syntax problem.
    Note: The following GraphQL features aren’t 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. In the Security section, fill in the fields.
    FieldDescription
    Requires authentication Select this option to require authentication to access the schema. Clearing this option makes the schema available publicly.
    Requires ACL authorization Select this option to require ACL authorization of the entire API. In the ACLs field, select ACLs with the GraphQL type.

    To use ACL authorization for specific paths only, leave this option cleared and specify the level to evaluate ACLs against in the Path ACL depth field.
    Requires SNC internal Select this option if the schema requires the SNC internal role. This option appears only if the Explicit Roles plugin (com.glide.explicit_roles) is enabled.
    Path ACL depth Specify the level of the GraphQL API to which to apply ACLs. Setting the path depth to 3 or lower uses fewer resources and helps with returning query responses.

    To specify the ACLs to use for the path, you must create an ACL with the GraphQL type and add the exact API path beginning with the schema namespace in the Name field. For example: /<planet>/<findAll>/<name>. Wildcards aren’t supported. For more information, see Configuring an ACL rule.

    Note: The ACLs field applies to the entire API and is independent of the ACLs applied to specific paths.
    ACLs Select ACLs with the GraphQL type to check incoming queries against. The ACLs you select apply to the entire API. This option appears only if Requires ACL authorization is selected.
    Note: The API returns clear error messages to users who don’t have access to a schema, or who aren’t 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 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 don’t 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 select New.
    2. Complete the form.
      FieldDescription
      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. Select Submit.
  7. (Optional) Define the type resolvers for your schema to resolve interfaces and unions into concrete types.
    1. Select the GraphQL Scripted Type Resolvers tab and select New.
    2. Complete the form.
      FieldDescription
      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. Select Submit.
  8. (Optional) Map the resolver and type resolver records to fields in the schema.
    This mapping tells the system what value to return when a component queries a field.
    1. Select the GraphQL Scripted Resolver Mappings tab and select New.
    2. Complete the form.
      FieldDescription
      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. Select Submit.