GraphQL mutations

Using GraphQL mutations to make changes to the schema.

You can use GraphQL to create new objects in your Skedulo application using mutations. GraphQL mutations are used to modify data and can be thought of as a write operation.

A mutation can contain multiple fields that are run in series, with the first field always finishing before the second begins. This is to prevent race conditions.

Mutations with aliases

Skedulo GraphQL supports mutations that include aliases for performing multiple actions. All mutations in a schema block are performed in a transaction, which reduces the number of mutations required to create, allocate, schedule, update, and dispatch a job.

Update multiple jobs using an alias prefix

You can use aliases as a prefix on update or insert operations to update multiple objects at a time. For example, the following mutation updates the Duration field to 60 on three jobs:

mutation updateMultipleJobs {
  schema {
    _j0: updateJobs(input: {
      UID: "00146e2f-c8db-4593-adc2-084abc866785"
      Duration: 60
    })
    _j1: updateJobs(input: {
      UID: "0014586b-3fa3-4f74-a5b1-a47f22a4b3a2"
      Duration: 60
    })
    _j2: updateJobs(input: {
      UID: "001419d8-ea58-40d8-8fc9-7e5e114af0e0"
      Duration: 60
    })
  }
}

This returns a successful response that provides an ID for each successful update:

{
  "data": {
    "schema": {
      "_j0": "00146e2f-c8db-4593-adc2-084abc866785",
      "_j1": "0014586b-3fa3-4f74-a5b1-a47f22a4b3a2",
      "_j2": "001419d8-ea58-40d8-8fc9-7e5e114af0e0"
    }
  }
}

Use idAlias to perform multiple actions in a single mutation

Because you require the job UID to make any changes to a job, the above method of using an alias as a prefix cannot be used to perform updates on a job that is being created in the same mutation.

The following mutation returns an error, as we are unable to identify the UID of the job being created in the insertJob part of the mutation:

mutation createMultipleJobsWithAllocations {
  schema {
    _j0: insertJobs(input: {
      RegionId: "00036206-7555-4280-b1b7-86d566437391"
      Start: "2019-08-02T00:00:00+00:00"
      End: "2019-08-02T01:30:00+00:00"
      Duration: 90
      Address: "1/47 Warner St, Fortitude Valley QLD 4006"
      Description: "MultipleJobQuery test"
    })
  	_ja0: insertJobAllocations(input: {
      ResourceId: "000520bd-63a1-47a0-9c80-9a343cb35ec6"
    })
    _j1: insertJobs(input: {
      RegionId: "00036206-7555-4280-b1b7-86d566437391"
      Start: "2019-08-02T03:00:00+00:00"
      End: "2019-08-02T03:30:00+00:00"
      Duration: 30
      Address: "Ann St, Fortitude Valley QLD 4006"
      Description: "MultipleJobQuery test"
    })
    _ja1: insertJobAllocations(input: {
      ResourceId: "0005a7e9-b1aa-44da-937f-310b921b75cc"
    })
  }
}

The above mutation returns the following error that insertJobAllocations requires an ID for the job:

"message": "Field 'NewJobAllocations.JobId' of required type 'ID!' was not provided. (line 95, column 38):\n  \t_ja0: insertJobAllocations(input: {\n

To perform additional actions in the same mutation, the Skedulo schema includes idAlias variable. This allows you to make subsequent mutations using the value you have assigned to idAlias. The actual value of the ID is replaced at run time.

The following GraphQL mutation includes two actions:

  • insertJobs - creates a new job, including required fields.
  • insertJobOffers - creates a job offer for the job created in the first part of the mutation and assigns it to a resource.
mutation createMultipleJobsWithAllocations{
  schema {
    insertJobs(input: {
      RegionId: "00036206-7555-4280-b1b7-86d566437391"
      Start: "2019-08-02T00:00:00+00:00"
      End: "2019-08-02T01:30:00+00:00"
      Duration: 90
      Address: "1/47 Warner St, Fortitude Valley QLD 4006"
      Description: "New Job testing Aliases"
      Type: "Maintenance"
      Urgency: "Normal"
    }, idAlias: "NEW_JOB_ID")
    
    insertJobOffers(input: {
      JobId: "NEW_JOB_ID"
    }, idAlias: "NEW_JOB_OFFER_ID")
    insertResourceJobOffers(input: {
      JobOfferId: "NEW_JOB_OFFER_ID"
      ResourceId: "0005a7e9-b1aa-44da-937f-310b921b75cc"
    })
  }
}

The response confirms that the job has been created and job offer has been made by providing ID strings for each successful mutation:

{
  "data": {
    "schema": {
      "insertJobs": "0014d653-af0d-4c73-b15d-e77afee2be01",
      "insertJobOffers": "00237199-0e4c-434c-a4c1-86f9326c59e5",
      "insertResourceJobOffers": "002427a8-036f-4024-91d3-740bd816c4eb"
    }
  }
}