4me GraphQL - Mutations
Integrations GraphQL Training Create and Update via GraphQL

4me 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 4me 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 4me GraphQL mutation string starts with the specification of a 4me 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 4me mutations here. The names of these mutations are self-explaining.

A good example is the requestCreate mutation.

Anatomy of a GraphQL 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 4me 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 4me record you often need to specify in the input string references to other 4me 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 4me records and 4me accounts in a 4me 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 4me 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:

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 a Configurtion Item

Use the query filter to find this reservation offering. Copy the ID, you will need it in the mutation.
Get the ID of a reservation offering

Use the query filter to find this person. Specifiy widget in the x-4me-account header. Copy the ID: you will need it in the mutation.
Get the ID of a person record

Now that you have retrieved the IDs of these records you should be able to create a Reservation with a GraphQL statement.

Exercise:

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.
GraphQL mutation to create a reservation
GraphQL mutation response

Finish