Getting started with long-term machine job scheduling

Long-term machine job scheduling assigns jobs to machines that take days and weeks to complete, optimizing for production efficiency, minimizing completion time and makespan, and balancing workloads across resources.

This guide introduces Timefold’s Long-Term Machine Job Scheduling model and walks you through the steps to create a machine job schedule.

The steps in this guide can be completed in under 10 minutes.

1. Long-term machine Job Scheduling hello world example

This hello world uses an example with one production line and one job to demonstrate the process of requesting and retrieving a solution from Timefold’s Long-term Machine Job Scheduling model.

1.1. Prerequisites

To follow this guide, you need:

  • An active Timefold Platform account: app.timefold.ai

  • An API client (optional but recommended)

1.2. Creating a dataset

A dataset for the Long-term Machine Job Scheduling model must include information about lines and jobs.

You create your dataset using our predefined model schema which follows the OpenAPI specification.

See API Spec for more information.

The modelInput object contains the dataset to be optimized, which, at a minimum, must include lines and jobs:

{
  "config": {
    "run": {
      "name": "Getting started example"
    }
  },
  "modelInput": {
    "lines": [
      {
        "id": "line1",
        "size": 2000,
        "startDate": "2027-02-01"
      }
    ],
    "jobs": [
      {
        "id": "red-1",
        "durationInDaysOnLines": [
          {
            "line": "line1",
            "durationInDays": 5
          }
        ],
        "size": 1800
      }
    ]
  }
}
Copy this example dataset into a file called sample.json to use in this hello world example.

1.2.1. Lines

In this hello world example, there is one line, but you can include multiple lines. At a minimum lines includes id, size, and startDate.

{
  "lines": [
    {
      "id": "line1",
      "size": 2000,
      "startDate": "2027-02-01"
    },
    {
      "id": "line2",
      "size": 1000,
      "startDate": "2027-02-01"
    }
  ]
}

id identifies the line.

size represents the maximum capacity of the line.

startDate represents the earliest date jobs can be scheduled to this line. Jobs assigned to this line will have start dates that are derived from this date.

1.2.2. Jobs

In this hello world example, there is one job, but you can include multiple jobs. At a minimum jobs includes id, durationInDayOnLines or durationInDays, and size.

{
  "jobs": [
    {
      "id": "red-1",
      "durationInDaysOnLines": [
        {
          "line": "line1",
          "durationInDays": 5
        }
      ],
      "size": 1800
    },
    {
      "id": "red-2",
      "durationInDaysOnLines": [
        {
          "line": "line1",
          "durationInDays": 4
        }
      ],
      "size": 1500
    }
  ]
}

id identifies the job.

durationInDaysOnLines specifies how many days the job will run for on the specified line.

size is the size of the job.

1.3. Post the dataset

To run the examples in this guide, you need to authenticate with a valid API key:

  1. Log in to Timefold Platform.

  2. From the Dashboard, click the drop-down menu for your tenant, and select Tenant settings.

  3. Select API Keys.

  4. Copy the default API key.

In the examples, replace <API_KEY> with the API Key you just copied.

Request the solution for your dataset by posting the sample.json file to the API endpoint /v1/schedules/.

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY> https://app.timefold.ai/api/models/long-term-machine-job-scheduling/v1/schedules [email protected]

1.4. Output from the request

The output to the API request follows:

{
  "id": "ID",
  "name": "Getting started example",
  "submitDateTime": "2024-12-03T04:48:07.586670236Z",
  "startDateTime": null,
  "completeDateTime": null,
  "solverStatus": "SOLVING_SCHEDULED",
  "score": null,
  "tags": null,
  "validationResult": null
}

The output includes an ID and NAME that have been assigned to identify the run associated with the dataset. You’ll use this ID to retrieve the results. Later, you’ll use NAME to locate more information in Timefold Platform.

solverStatus confirms the dataset has been scheduled for solving.

1.5. Request the solution

Append the <ID> from the output you received to the API endpoint /v1/schedules/ and create a GET request to retrieve the solution:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/long-term-machine-job-scheduling/v1/schedules/<ID>

1.5.1. Completed schedule

{
  "run": {
    "id": "ID",
    "name": "Getting started example",
    "submitDateTime": "2024-12-03T04:48:07.586670236Z",
    "startDateTime": "2024-12-03T04:48:17.424913951Z",
    "completeDateTime": "2024-12-03T04:48:18.434557869Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-225soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "lines": [
      {
        "id": "line1",
        "size": 2000,
        "startDate": "2027-02-01",
        "tags": [],
        "unavailableTimeSpans": [],
        "jobs": [
          "red-1"
        ]
      }
    ],
    "jobs": [
      {
        "id": "red-1",
        "durationInDays": null,
        "durationInDaysOnLines": [
          {
            "line": "line1",
            "durationInDays": 5
          }
        ],
        "size": 1800,
        "sizeOnLines": [],
        "requiredLineTags": [],
        "requiredLines": [],
        "minStartDate": null,
        "idealEndDate": null,
        "maxEndDate": null,
        "priority": 1,
        "pinned": false,
        "line": "line1",
        "processingStartDate": "2027-02-01",
        "processingEndDate": "2027-02-06"
      }
    ],
    "tags": []
  },
  "kpis": {
    "unassignedJobs": 0
  }
}

The output shows the solverStatus is SOLVING COMPLETED.

modelOutput contains the solution for the dataset.

{
  "modelOutput": {
    "lines": [
      {
        "id": "line1",
        "size": 2000,
        "startDate": "2027-02-01",
        "tags": [],
        "unavailableTimeSpans": [],
        "jobs": [
          "red-1"
        ]
      }
    ],
    "jobs": [
      {
        "id": "red-1",
        "durationInDays": null,
        "durationInDaysOnLines": [
          {
            "line": "line1",
            "durationInDays": 5
          }
        ],
        "size": 1800,
        "sizeOnLines": [],
        "requiredLineTags": [],
        "requiredLines": [],
        "minStartDate": null,
        "idealEndDate": null,
        "maxEndDate": null,
        "priority": 1,
        "pinned": false,
        "line": "line1",
        "processingStartDate": "2027-02-01",
        "processingEndDate": "2027-02-06"
      }
    ]
  }
}

modelOutput includes the details for the schedule.

processingStartDate specifies the date the job will start on the line, and processingEndDate specifies when the job will end.

Beyond hello world

This example walked you through creating a simple dataset to create a schedule for one job on one line.

Configure a webhook

In this getting started guide, you learned how to retrieve the solution for your dataset through the API and Timefold Platform. However, you can configure a webhook to receive the solution without the need to poll Timefold’s API.

To configure a webhook:

  1. Log in to Timefold Platform app.timefold.ai

  2. From the Dashboard, click the tenant menu drop-down menu and select Tenant settings.

  3. Select Webhook and click New webhook.

  4. Give your webhook a name.

  5. Enter the URL for your webhook and the header values.

  6. Enable the webhook and click Add webhook.

See Configuring webhooks for more information.

Try the demo dataset

Timefold platform includes a demo dataset you can use to explore the functionality of the model.

Access the demo dataset in the UI

To access the demo dataset in the UI:

  1. Log into Timefold Platform: app.timefold.ai

  2. Select the Long-term machine job scheduling tile.

  3. Click New Run.

  4. Select the demo dataset you would like to run from the drop-down menu, and click Schedule run.

Access the demo dataset with the API

To get the list of available demo datasets from the API, make the following call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/long-term-machine-job-scheduling/v1/demo-data

To download the BASIC demo dataset, make the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/long-term-machine-job-scheduling/v1/demo-data/BASIC -o sample.json

To post the demo dataset, use the following API call:

The output from the POST operation includes a run ID that you need for subsequent commands. 
curl -X POST -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/long-term-machine-job-scheduling/v1/schedules [email protected]

To get the current status and score of the dataset, replace <ID> with the identifier from the previous post operation and make the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/long-term-machine-job-scheduling/v1/schedules/<ID>/run

To get the complete route plan, replace <ID> with the identifier from the previous post operation and make the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/long-term-machine-job-scheduling/v1/schedules/<ID>