Subscribe to Skedulo objects

GraphQL schema subscriptions.

Skedulo API GraphQL subscription support is provided through the Apollo subscription transport protocol.

The websocket subscription endpoint is available at /graphql/subscriptions. Only subscription operations can be performed using this endpoint.

Subscriptions can be created on the Job, JobAllocation, and Shift objects.

Customers using Skedulo and Skedulo for Salesforce have access to all fields on these objects including any custom fields they have defined.

A subscription can also provide the previous values of fields on the changed object.

Customers using Skedulo also have access to the Activities and Availabilities objects.

You can use an introspection query to determine exactly which fields are available to you. You can also use the GraphiQL page in the web application to search for available fields in the Docs section.

Schema subscriptions

When creating a schema subscription, results will only be returned when changes occur to one of the fields you have requested.

In the following example, only the UID and Duration fields are requested, and the subscription will only return results when either of those two fields changes.

In addition to this implicit filtering, you can also explicitly filter which operations are returned and add additional filters on the data using an EQL filters query.

The example below will only provide a response when an UPDATE occurs that increases the duration of the job to more than one hour.

subscription {
  schemaJobs(operation: UPDATE, filter: "Duration > duration(3600 seconds)") {
    operation
    timestamp
    data {
      UID
      Duration
    }
    previous {
      Duration
    }
  }
}

Connect to the server

As per the subscription protocol, clients must send the Sec-WebSocket-Protocol header with a value of graphql-ws when connecting. Once connected a connection_init message should be sent with the payload containing authentication information in the form of a bearer authorization header. An example is displayed below.

{
  "type": "connection_init",
  "payload": {
    "Authorization": "Bearer $ACCESS_TOKEN"
  }
}

If the credentials are successful, the server will respond with a connection_ack message.

{
  "type": "connection_ack"
}

After this message has been received, you can send subscription queries. Each subscription must have a unique ID and contain a valid GraphQL subscription query. As multiple subscriptions can be started, the id field allows you to determine which response belongs to which subscription.

When creating a schema subscription, results will only be returned when one of the fields that you requested changes. In the following example as only the UID and Duration fields are requested this subscription will only return results when either of those two fields changes.

{
  "id": "1",
  "type": "start",
  "payload": {
    "query": "subscription {\n  schemaJobs {\n    operation\n    timestamp\n    data {\n      UID\n      Duration\n    }\n    previous {\n      Duration\n    }\n  }\n}",
    "variables": {}
  }
}

The server will only respond to a start message if there is a problem.

{
  "type": "error",
  "id": "2",
  "payload": {
    "data": null,
    "errors": [
      {
        "message": "Cannot query field 'UIDs' on type 'SchemaSubscriptionJobs'. Did you mean 'UID'? (line 6, column 7):\n      UIDs\n      ^",
        "locations": [
          {
            "line": 6,
            "column": 7
          }
        ]
      }
    ]
  }
}

Events that match the subscription are sent with the data message type.

{
  "type": "data",
  "id": "1",
  "payload": {
    "data": {
      "schemaJobs": {
        "operation": "INSERT",
        "timestamp": "2018-06-08T05:48:51.091Z",
        "data": {
          "UID": "0014f570-c710-4a20-863f-2b33d583a49d",
          "Duration": 90
        },
        "previous": {
          "Duration": 90
        }
      }
    }
  }
}