Make changes to the data records using GraphQL mutations

Use GraphQL mutations to make changes to data records.

You can use GraphQL mutations to insert, update and delete data records in your Skedulo application.

A mutation can contain multiple operations that are run in sequence within a transaction. This means that if one operation fails, the entire transaction is rolled back, ensuring data integrity.

A basic GraphQL mutation

The following example shows a basic mutation that inserts a new record of type Jobs into the Skedulo tenant:

mutation {
  schema {
    insertJobs(input: {
      RegionId: "00030652-6144-431b-8c04-41b8563be992"
      Duration: 60
    })
  }
}

The result is a JSON object includes the UID of the newly inserted record:

{
  "data": {
    "schema": {
      "insertJobs": "00146e2f-c8db-4593-adc2-084abc866785"
    }
  }
}

Operate on multiple records in one request

Multiple independent mutations of any type can be combined in a single request.

When multiple records of the same type are inserted or updated, you need to assign an identifier to each operation so that the results can be distinguished from each other.

Note the unique keys for the insertJobs and updateJobs operations, _j0 and _j1, in the example below. Because there is only one updateContacts operation, it does not require a unique key.

mutation updateMultipleJobs {
  schema {
    j0: insertJobs(input: {
      RegionId: "00030652-6144-431b-8c04-41b8563be992"
      Duration: 60
    })
      
    j1: updateJobs(input: {
      UID: "0014586b-3fa3-4f74-a5b1-a47f22a4b3a2"
      Duration: 60
    })

    updateContacts(input: {
      UID: "001619d8-8fc9-3fa3-8fc9-084abc866785"
      FirstName: "Bill"
      LastName: "Smith"
    })
  }
}

This returns a successful response that reflects the provided keys and returns the UID of the record for each successful operation:

{
  "data": {
    "schema": {
      "j0": "00146e2f-c8db-4593-adc2-084abc866785",
      "j1": "0014586b-3fa3-4f74-a5b1-a47f22a4b3a2",
      "updateContacts": "001619d8-8fc9-3fa3-8fc9-084abc866785"
    }
  }
}

Getting data back from a mutation

GraphQL mutations can return data in the response via a get operation. This can be useful if you want to know the status of a field that is set automatically such as JobStatus. For example, you can retrieve the new status of an updated job by adding a getJobs operation to the mutation:

mutation updateJob {
  schema {
    updateJobs(input: {
      UID: "0014586b-3fa3-4f74-a5b1-a47f22a4b3a2"
      Start: "2025-02-06T10:00:00.000Z"
      End: "2025-02-06T11:00:00.000Z"
    })
    getJobs(input: {
      UID: "0014586b-3fa3-4f74-a5b1-a47f22a4b3a2"
    }) {
      JobStatus
    }
  }
}

The response includes the new status of the job:

{
  "data": {
    "schema": {
      "updateJobs": "0014586b-3fa3-4f74-a5b1-a47f22a4b3a2",
      "getJobs": {
        "JobStatus": "Pending Dispatch"
      }
    }
  }
}

Mutations with aliases

If you need to perform multiple related operations in a single mutation, you can use ID aliases to refer to the ID of an inserted record in a subsequent mutation. See Perform multiple actions using GraphQL aliases for more information on GraphQL ID aliases.

Large bulk mutations

When performing large quantities of mutations via GraphQL (such as a large data import), it is important to set the X-Skedulo-Bulk-Operation custom HTTP header value to true in the GraphQL API request. A large quantity of mutations is defined as more than 500 mutations within a 5-minute period.

This extra information lets the Skedulo platform know the operation is part of a large bulk operation, which allows it to prioritize background processing accordingly in order to avoid overloading the system. When this header is set, mutations are performed immediately. However, background processing tasks such as rule evaluation and triggered actions may experience slight delays.

Example request:

curl --request POST \
  --url https://api.skedulo.com/graphql/graphql \
  --header 'Authorization: Bearer <auth_token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Skedulo-Bulk-Operation: true' \
  --data '{"query":"mutation { schema { insertJobs(input: { RegionId: \"000312b2-e568-4c09-b8b4-5e22127866df\"Description: \"Test Job\", Start: \"2024-02-06T10:00:00.000Z\", End: \"2024-02-06T11:00:00.000Z\", Duration: 60}) } }"}'