Note: This is part one of a series of articles where we will develop Custom Components with the Now Experience UI Framework. This series starts with two articles about custom GraphQL APIs, which we will use to fetch data from the platform for our component.
What is GraphQL?
In short: GraphQL is a query language for APIs that was first developed by Facebook. Today the GraphQL Foundation is the home of that project which is now open source. GraphQL is an alternative to REST-based APIs and offers some advantages:
- The API returns exactly what the client asked for, no overhead
- With one request we can fetch properties of different resources
- We have only one endpoint for every request
- With introspection, clients can discover available objects and fields (don’t activate introspection on productive ServiceNow instances)
If you want more general information about GraphQL you can find it at https://graphql.org/.
GraphQL in Service Now
GraphQL is internally used by ServiceNow for a few releases and starting with Paris we are able to create our own custom GraphQL APIs.
What is part of a custom GraphQL API?
Schema: Where we define the available objects and fields
Scripted Resolver: They are responsible to fetch the needed data.
Resolver Mappings: Map the Resolver to the right fields in the schema
Use case: What are we building here?
The first Component that we are going to create in this series, should be able to display information about Requests [sc_request] from contacts [customer_contact]. It should look roughly like this:
Therefore, our first task will be to create a custom GraphQL API that gives us all Requests, for a given contact, together with the included Requested Items [sc_req_item] and potential variables [sc_item_option].
Create a new GraphQL API
Navigate to “System Web Services > GraphQL > GraphQL APIs” (or sys_graphql_schema) and create a new record.
Name: The name that we have chosen for this record
Schema namespace: Can be anything but must be unique within the application namespace
Remember, there is only one endpoint for every GraphQL APIs that we define. The schema namespace and application namespace are used to prevent conflicts with other schema definitions.
The Schema is the part where it gets interesting. That is the place where we define the available object types and fields for our API. The default value for the schema gives us already a definition of two special types. Query and mutation. These define the entry points for our GraphQL queries. A mutation type is not mandatory, we will look at mutations in one of the later articles. But every schema needs at least one query type. In step one we will create a query that takes a sys_id from a contact and returns all Requests that are opened by this contact.
Within the Query type, we define:
type Query {
contactRequest(contactID: ID!): [Request]
}
If we try to save this, we get an error because we tried to use the type “Request” without defining it.
So let’s first define an empty Request type so that we can save the record.
type Request{
}
contactRequest has one argument, contactID. This argument has the Type ID. ID is a scalar type in GraphQL and represents a unique identifier. For now, let's think of it as a String. The ! behind the ID indicates that this argument is non-nullable, it is mandatory.
Our Query will return an Array of Request Objects, and what a Request is, is what we define next.
We already created the Request type, now we add the fields that we want to be part of a Request.
type Request{
sys_id: ID
number: String
state: String
}
Now we have the first basic schema defined. The next step is to tell the API how to resolve the schema. We create a new record in the related list GraphQL Scripted Resolvers
The Scripted Resolver is a function that returns the data that we need. This function can be assigned to a field in our schema.
Within this function, we have access to an object called env. We can access the sys_id, that the caller passed into the API, using env.getArguments().contactID. We will use a GlideRecord to query the data and return the GlideRecord object. Make sure that the names of the fields that we have defined for our Request type match the field names of the Request table.
The last step before we can test our API is to map the Scripted Resolver to a field in the schema. Therefore, we create a record in the related list GraphQL Resolver Mappings.
Path shows us all the available fields from our schema. We select Query:contactRequest and under Resolver, we pick the Request Resolver that we have just created.
That’s all. Now we can pick our favorite tool, like Postman or Insomnia to send a POST request to
http://<my-instance>.service-now.com/api/now/graphqland test our API.
In the next article, we will extend this API to also return the Requested Items and variables that are part of the Request.
