Quickstart

An introduction to using the Skedulo API

You can begin interacting with Skedulo’s API and GraphQL schema as soon as your Skedulo team is active and you have assigned an API user.

The quickstart links listed below will help you set up basic authentication requirements interacting with the data in your org remotely using GraphQL and the Skedulo API.

Create an API user and generate a token

Set the API user

Skedulo requires an API user for a number of background processing events. An API user must be set in order to use the Skedul API.

Log in to the Skedulo web application as an Admin user.
Click your user profile in the upper-right corner, then click Settings > API user.
Click the dropdown list of users under Select user for system actions and select the user you want to be the API user for your org.
Click Activate. The web app will automatically refresh to apply the change and activate the API user.

Create a long-lived API token using the web application

Users with Admin permissions can create an API token in the Developer tools > API user section of the Skedulo web app.

In the Skedulo web app, click your user profile in the upper-right corner, then click Settings > Developer tools > API tokens.
Click the Create button and select Expires: Never to create a long-lived API token.
Copy the API token.
Open your local configuration file (eg .bash_profile for Mac/Linux users) and create an environment variable called AUTH_TOKEN that references the API token. For example:
```
export AUTH_TOKEN="123456789YOURAPIKEYGOESHERE"
```
This is so that you can use the AUTH_TOKEN variable in requests instead of copying the entire API key into your request headers.

Make API calls

The access token obtained above is a Base64 encoded JavaScript Web Token (JWT). Provide the token in the authorization header of the API request using the Bearer method.

API calls must include the following HTTP headers:

content-type: application/json
authorization: Bearer “$AUTH_TOKEN”

Create a region, a job, and a resource using GraphQL

GraphQL is a query language for APIs. Requests are called either mutations or queries.

Mutations create objects or make changes to existing objects in the Skedulo schema.
Query requests ask for specific information about objects in the schema and return the requested information, such as job details or resource availability.

You can learn more about GraphQL in Use GraphQL or more generally at graphql.org.

Some of the most common Skedulo objects are Job, Resource, and Region. This section of the quickstart will show you how to use GraphQL to create each of these objects.

Use GraphiQL in the web app

The GraphiQL web extension can be enabled in the Skedulo web app so that you can explore the schema documentation and easily create valid requests without leaving the application. For detailed instructions, see the documentation on how to make GraphiQL accessible from the web app navigation menu.

Alternatively, you can make GraphQL requests using your preferred API client.

You can also explore our GraphQL schema documentation here.

Create a region using GraphQL

Create a region using the insertRegions mutation.

The Regions object includes a number of fields, however, only the following fields are mandatory and must be configured to create the object:

Name - the name of the region. This can be any String.
Timezone - the timezone for the region. This must be in a correct CountryName/Region format.

Use the insertRegions mutation to create a new region in your Skedulo org:

mutation createRegion {
  schema{
    insertRegions(input: {
      Name: "Brisbane CBD"
      Timezone: "Australia/Brisbane"
    })
  }
}

The successful JSON response returns a UID for the new region, which you can use when creating jobs or assigning resources to that region.

{
  "data": {
    "schema": {
      "insertRegions": "000396a9-ac46-4412-b015-b212af205f46"
    }
  }
}

Create a job using GraphQL

Create a job using the insertJob GraphQL mutation.

Certain fields are mandatory and should be configured to reflect your Skedulo environment and job requirements:

Duration - the number of minutes allocated to complete the job.
RegionId - the UID of the region in which the job will be assigned and carried out.

All other fields are optional when creating jobs using GraphQL. However, when creating a job using the Skedulo web app, you must also include a date and time.

Start and End - include a date and time for the job using GraphQL, you need to provide Start and End fields with the date and time in ISO8601 format.

The following GraphQL mutation creates a new job in the Brisbane CBD region we created in our Skedulo org in the previous section, and includes a date and time for the work to be carried out:

mutation createJob{
  schema {
    insertJobs(input: {
      Duration: 60
      RegionId: "000396a9-ac46-4412-b015-b212af205f46"
      Start: "2021-09-10T06:00:00.000Z"
      End: "2021-09-10T07:00:00.000Z"
      Description: "This is a new job created using GraphQL"
    })
  }
}

The JSON response shows the job was successfully created and includes the UID of the new job:

{
  "data": {
    "schema": {
      "insertJobs": "00149459-5115-4c86-8272-eb687d67c293"
    }
  }
}

Create a resource using GraphQL

Resources are assigned to jobs and carry out the work created in your Skedulo org. Resources are assigned to at least one region where they will carry out work assigned to that region.

Use the insertResources mutation to create a new Resources in the region we created earlier. The following fields are mandatory to create a new resource:

Name - the name of the resource, usually the person’s first and last name.
RegionId - the UID of the region where the resource will be working.

All other fields are optional, however, there are a few more that we will want to include so that we can dispatch the job to the resource later:

ResourceType - Skedulo supports allocating work to both human and non-human resources, so we will also specify that our resource is a Person type so that we can dispatch it to the resource user later.
NotificationType - specify either sms or push as the preferred resource notification type. This quickstart uses the sms notification, which will notify the resource even if they are not currently logged in to the Skedulo v2 mobile app.
MobilePhone - the phone number of the resource if sms is the preferred notification type.
CountryCode - the country code where the SMS number is located.

The following GraphQL mutation creates a new resource assigned to the Brisbane CBD region we created earlier:

mutation createResources {
  schema {
    insertResources(input: {
      Name: "Robert Resource"
      PrimaryRegionId: "000396a9-ac46-4412-b015-b212af205f46",
      ResourceType: "Person",
      NotificationType: "sms",
      MobilePhone: "0400123456",
      CountryCode: "AU"
    })
  }
}

The JSON response provides the UID for the new resource:

{
  "data": {
    "schema": {
      "insertResources": "0005310d-4383-40f0-a1f2-684c5e93cdbf"
    }
  }
}

Assign a job to a resource using GraphQL

Now that we have created a region, a job, and a resource, we can assign the resource to the job.

Use the insertJobAllocations mutation to allocate the job we created earlier to Robert Resource.

mutation allocateJob {
  schema {
    insertJobAllocations (input: {
      JobId: "00149459-5115-4c86-8272-eb687d67c293"
      ResourceId: "0005310d-4383-40f0-a1f2-684c5e93cdbf"
    })
  }
}

Query information in your Skedulo org using GraphQL

After you have created a job in Skedulo, you can retrieve all of the information about that job using a GraphQL query.

GraphQL query requests navigate the object graph and return the parts of the object included in the request. This is a way for you to look up information about all objects in the schema, or specific information about an object.

You can look up information about all of the Job objects in the Skedulo schema using a simple query:

query allJobs {
  jobs {
    edges {
      node{
        Name
        Description
      }
    }
  }
}

Query specific information using GraphQL and EQL filters

We want to query the specific job we have created in this quickstart, including the details of the region and assigned resource.

To do this, we need to run a query using an EQL filter. The EQL filter allows us to narrow down query results to return more specific information.

query jobsByID {
  jobs (filter: "UID == '00149459-5115-4c86-8272-eb687d67c293'"){
    edges{
      node{
        Name
        Duration
        Description
        Start
        End
        Region {
          Name
          Timezone
        }
        JobStatus
        JobAllocations{
          Name
          Resource {
            UID
            Name
          }
        }
      }
    }
  }
}

The above query returns the data just for the specified job and the specific fields we included in the request, all created in this quickstart:

{
  "data": {
    "jobs": {
      "edges": [
        {
          "node": {
            "Name": "JOB-0185",
            "Duration": 60,
            "Description": "This is a new job created using GraphQL",
            "Start": "2021-09-10T06:00:00.000Z",
            "End": "2021-09-10T07:00:00.000Z",
            "Region": {
              "Name": "Brisbane CBD",
              "Timezone": "Australia/Brisbane"
            },
            "JobStatus": "Pending Dispatch",
            "JobAllocations": [
              {
                "Name": "JA-0727",
                "Resource": {
                  "UID": "0005310d-4383-40f0-a1f2-684c5e93cdbf",
                  "Name": "Robert Resource"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Use the Skedulo REST API to dispatch a job to a resource

The Skedulo API uses REST endpoints for standard GET, POST, PUT, and DEL operations, as well as PATCH.

See the Skedulo API Reference Guide for our full list of APIs.

Now that we have used GraphQL to create a job and assign it, we need to dispatch it to the resource so that they can be notified of the job and to the assigned work.

To do this, we need send a POST request to the Skedulo Lens /notifications REST endpoint and include the jobId and resourceId in the request payload:

curl --request POST \
  --url https://api.skedulo.com/notifications/dispatch \
  --header 'Authorization: Bearer $AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
	"jobId": "00149459-5115-4c86-8272-eb687d67c293",
	"resourceId": "0005310d-4383-40f0-a1f2-684c5e93cdbf"
}'

The request above dispatches the job and sends a notification to the resource. The success (200) response confirms the job has been dispatched to the resource via SMS:

{
  "result": {
    "jobId": "00149459-5115-4c86-8272-eb687d67c293",
    "results": [
      {
        "resourceId": "0005310d-4383-40f0-a1f2-684c5e93cdbf",
        "protocol": "sms",
        "error": null
      }
    ]
  }
}

Modify and delete data using GraphQL

Update schema objects using GraphQL

You can update objects that already exist in your schema using the update GraphQL mutation.

For example, you can change a job’s status from Ready back to Queued, or update a resource’s primary contact phone number.

The following updateJobs mutation adds an address to the job we have been working with throughout the quickstart:

mutation updateJobs {
  schema {
    updateJobs(input: {
      UID: "00149459-5115-4c86-8272-eb687d67c293",
      Address: "47 Warner St, Fortitude Valley QLD 4006, Australia",
    })
  }
}

Address geolocation

While this will update the job object with the address, you will need to verify the address in the Skedulo web application for geolocation purposes so that you can view the job location on the map.

Delete schema objects using GraphQL

You can remove an object from the system entirely using a delete mutation. This will hard delete the object and cascade delete other objects related to it.

The following mutation deletes the job we have worked on throughout this quickstart:

mutation deleteJob {
  schema {
  	deleteJobs(UID: "00149459-5115-4c86-8272-eb687d67c293")
  }
}

When attempting to view the job in the Skedulo web app using its URL, the web app now throws a Job not found: the job does not exist toast notification and redirects to the Skedulo UI console as the job has been completely deleted from the org.

This will also automatically remove the job allocation to Robert Resource and the job will no longer appear in his schedule of allocated work.

Feedback

Was this page helpful?

On this page