Create a scheduled optimization

Create large scheduling queries to be run at a specified time daily, weekly, or monthly.

Batch optimization creates valid schedules for large data sets of work that takes into account location and routing, resource skill requirements, and inclusion/exclusion lists.

Some limitations apply to the number of items included in an optimization request. See Usage limitations for more information about optimization request limits.

Batch optimization relies on the optimization solver to solve work and resource scheduling problems over a period of time to produce a valid schedule.

The longer the solver is allowed to run, the better the schedule is likely to be with regards to job and resource constraints such as travel time and availability.

Batch optimization can be scheduled to run at a later time, and can be made to run on a recurring schedule.

This means that schedulers can have the same optimization query scheduled to run at the same time daily, weekly, or monthly to produce schedules in advance.

Create an optimization schedule

The /optimization endpoint handles up to 2000 jobs, 200 resources, and 1000 unique locations in an optimization request. We anticipate being able to work with a higher number of jobs and resources in the near future.

See the API documentation for more information about the /optimization endpoint.

Using the API to schedule batch optimization requests requires knowledge of GraphQL and EQLFilters.

The jobQuery and resourceQuery request fields require an EQLFilter to identify which jobs and resources are to be included in the optimization request.

The following EQL filters are an example of filters that might be useful in batch queries:

Filter	Description
`JobStatus == "Queued"`	All jobs with a `Queued` status
`EmploymentType == "Full-time"`	All employees with the `Full-time` employment type
`UID IN ['<JobUID>', '<JobUID>', etc]`	Add specific jobs by their UID

In the following example, the batch optimization will run daily, starting no earlier than 8PM and finish no later than 11PM. It will optimize all Queued jobs in the Brisbane region for all available Full-time resources.

{
  "name": "Brisbane",
  "jobQuery" : "UID IN ['00140338-dd6c-4154-8e6e-1356d88f5817', '0014f816-8797-4f7a-aee4-404c4b63f3fa', '0014eb38-09d2-4392-b1dc-50d68460a5bf']",
  "resourceQuery" : "EmploymentType == 'Full-time'",
  "region" : "00030443-08b8-4612-a55a-75cb600e2729",
  "runDate" : "2020-06-10",
  "timezone": "Australia/Brisbane",
  "earliestStartTime" : "20:00:00",
  "latestEndTime" : "23:00:00",
  "dayRange" : 1,
  "dayOffset" : 1,
  "recurring" : {
    "step" : 1,
    "repeatMode" : "daily",
    "endAfterNumberOccurrences" : 1,
    "repeatOnWeekDays" : [
      "sun",
      "mon",
      "tue",
      "wed",
      "thu",
      "fri",
      "sat"
    ]
  }
}

When created successfully, the request returns an ID for the batch, which can be used to update or modify the batch optimization:

{
  "id": "d6af2490-b9de-4a75-b3fd-b591bce928ef"
}

Return a list of existing batch optimization runs by making a GET request to /optimization/batch/schedule.

This returns all optimization batch runs scheduled for your organization.

Delete optimization schedules

You can delete an optimization schedule using the Skedulo web application or the API.

To delete the optimization schedule using the UI:

Open Settings -> Optimization schedules page in the web application.
Select the schedule or schedules that you would like to delete.
Click the Delete icon in the menu bar above the schedule table.

To delete a schedule using the API:

Get the schedule ID for the batch run you want to delete. You can find this using aGET request to the /optimization/batch/schedule endpoint, which lists all current batch optimization schedules.
Send a DELETE request to the /optimization/batch/schedule/{schedule_id}.

Saving optimization schedules

Most APIs have a way to automatically apply the run. If you sent a /optimization/batch/schedule or /optimization/schedule request with {"persistenceStategy": "save"} they will automatically be applied to your schedule, or will attempt to apply to your schedule.

When you have completed an optimization run, you can apply it to your schedule. To save a run, all you require is the run ID.

Batch

To begin, you’ll need to get a list of batch optimizations that have been run so that you can save them.

If you used the /optimization/batch/schedule endpoint, you will have been given a response similar to the following:
```
{
    "result": {
        "id": "537b288a-6a08-4f34-9b18-5e92189c7baf"
    }
}
```
The id is the schedule ID for the batch run, which is unique for each schedule.

With the id returned in step one, we can create a request to get all of the runs for that specific schedule.

Using this id in the request GET /optimization/run?scheduleId=537b288a-6a08-4f34-9b18-5e92189c7baf&type=batch&limit=10&offset=0 endpoint returns a JSON blob with all of the data needed to start saving your runs.

The response should look like:

{
  "paging": {
    "limit": 10,
    "total": 2
  },
  "result": [
    {
      "autoSaved": false,
      "savedByUserId": "user-1",
      "savedByDate": "2022-02-15T19:03:00Z",
      "saveState": "saved",
      "start": "2022-08-18T19:00:00Z",
      "status": "complete",
      "scheduleId": "a15c285f-2c69-4a3c-9b9b-c9a8c5252db6",
      "createdByUserId": "user-1",
      "label": "label-1",
      "optimizationType": "pvrp",
      "completedAt": "2022-02-15T19:02:00Z",
      "summary": {
        "totalPlannedJobs": 3,
        "totalScheduledJobs": 3
      },
      "evaluateOnly": false,
      "id": "20ecb249-8331-491f-9049-565a2252df76"
    },
    {
      "autoSaved": false,
      "saveState": "error",
      "errors": [
        {
          "message": "error-1"
        }
      ],
      "start": "2022-08-18T19:00:00Z",
      "status": "failed",
      "scheduleId": "a15c285f-2c69-4a3c-9b9b-c9a8c5252db6",
      "createdByUserId": "user-1",
      "label": "label-1",
      "optimizationType": "pvrp",
      "completedAt": "2022-02-15T19:02:00Z",
      "summary": {
        "totalPlannedJobs": 3,
        "totalScheduledJobs": 3
      },
      "evaluateOnly": false,
      "id": "20ecb249-8331-491f-9049-565a2252df76"
    }
  ]
}

Note

If you didn’t save the id you can use the endpoint GET /optimization/run to get a list of all runs for your organization.

To retrieve more optimization runs, modify the limit=10 and offset=0.

The offset starts from the latest run, so by using offset=5 we ignore the first five runs then take the limit (in this case 10) from that point on-wards.

There is no way to filter at the API level (yet). To remove runs that are still in progress, you will have to go through the response and manually remove runs with {"saveState": "pending"} in the returned JSON.

Review the result field of the returned JSON to identify the run/s you want to save.

For this tutorial you can just take the top id from the array. In practice, you can pragmatically go through the returned runs and do some useful things before saving each one.

When you’ve identified a runId that you want to save, you can save it by making a POST request to the https://docs.skedulo.com/skedulo-api/#post-/optimization/schedule/run/-runId-/save API as follows:
```
curl -X POST "https://api.skedulo.com/optimization/schedule/run/20ecb249-8331-491f-9049-565a2252df76/save" \ -H "accept: application/json" \
```

Applying optimization schedules

Sometimes saving can be referred to as apply in the optimization API. You can follow the same steps defined in the Saving optimization schedules

Feedback

Was this page helpful?

On this page