Xurrent GraphQL - Mutations
The previous topics were all about the first GraphQL operation or root type, the Query. In this topic we will explore the second operation that is supported by the Xurrent GraphQL API: the Mutation type. A mutation allows you to create, update or delete GraphQL objects.
The Anatomy of a GraphQL Mutation
Now let’s have a look into the basic anatomy of a GraphQL mutation string.
While a GraphQL query starts with a field that can act as an entry point to the objects in the ‘graph of nodes’, a Xurrent GraphQL mutation string starts with the specification of a Xurrent mutation. A mutation represents the action you want to perform like requestCreate (indeed, to create a new request) or ConfigurationItemUpdate (… to update a Configuration Item). Check the list of Xurrent mutations here. The names of these mutations are self-explaining.
A good example is the requestCreate mutation.
As for queries you can define an attribute between parentheses, with the difference that a mutation only accepts one argurment, input, while you could specify multiple arguments (for paging, filtering,..) in a query.
The input argument is a JSON string of value pairs with at least all the mandatory fields of the object you want to create.
On a mutation, you will always define the Error object. The Xurrent GraphQL API will set the error message and indicate from which input value the error came from (path) whenever an error occurs.
Finally you need to define the fields of the object that was created or updated, that you want to get in the response.
The (Node) ID or Globally Unique Identifier
When you create a new Xurrent record you often need to specify in the input string references to other Xurrent records. For the creation of a Request for example, you will probably specify the Requested for user. In GraphQL you can reference another object by the uniqe (node) ID. To continue with the example of the requestCreate mutation, the input field for the Requested for user is requestedForId.
The ID is unique over all Xurrent records and Xurrent accounts in a Xurrent environment (QA environment or PROD environment). The ID is not intended to be human-readable. It is different from the recordId (for example requestId) which is the ID displayed in the UI.
Preparing a GraphQL Mutation
When you want to create a new Xurrent record with some IDs of referenced objects in the input string, you will need to write GraphQL queries to get the IDs of these records.
In the follwoing exercise you will write a GraphQL mutation to create a Reservation.
To create the reservation, you will need to reference a Configuration Item, a Reservation Offering and a Person Record.
Exercises:
Get the ID of the Configuration Item with label ‘wdc-01’.
You need to add view rights on the record type configuration item to the scope of the personal access token. Use the query filter. Copy the ID, you will need it in the mutation.
Get the ID of the Reservation Offering ‘Xurrent training environment’
Use the query filter to find this reservation offering. Copy the ID, you will need it in the mutation.
Get the ID of the person with name ‘Beatrice Baldwin’. Be aware that in the demo environment the people from the Widget are defined in the directory account (id = widget).
Use the query filter to find this person. Specifiy widget in the x-Xurrent-account header. Copy the ID: you will need it in the mutation.
Now that you have retrieved the IDs of these records you should be able to create a Reservation with a GraphQL statement.
Exercise:
Create a reservation for Beatrice Baldwin for the Xurrent training environment ‘wdc-01’. The reservation must start today and has a duration of 2400 minutes. Give a name and a decription to your reservation. Include the ID and the name of the reservation in the response.
You need to add create and view rights on the record type reservation to the scope of the personal access token. The view rights are required because GraphQL will need to add data from the created reservation in the response.
