Real-time planning

Employee shift schedules are typically published a few weeks in advance to allow employees to plan the rest of their lives around the shifts they’ll be working.

This means employees don’t need to organize things (social events, appointments, child care, life administration) at the last minute which reduces stress and improves their job satisfaction.

However, even the best schedule can be disrupted at the last minute by employees calling in sick or a sudden need for additional staff.

Real-time planning makes it possible to assign new employees to shifts, due to sick leave or additional demand, and to minimize the disruption caused by the re-planning process.

This guide explains real-time planning with the following examples:

Real-time planning due to illness
Real-time planning due to increased demand
Minimizing disruption due to real-time planning
Real-time planning and on-call shifts

Prerequisites

To run the examples in this guide, you need to authenticate with a valid API key for the Employee Shift Scheduling model:

Log in to Timefold Platform: app.timefold.ai
From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.
Create a new API key or use an existing one. Ensure the list of models for the API key contains the Employee Shift Scheduling model.

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

Real-time planning due to illness

In the following example, the wait staff at a restaurant are scheduled with staggered start and end times to ensure there are enough people to cover the busy period. A typical night at the restaurant requires 4 wait staff working the following shifts:

1 person from 16:00 to 20:00 to set up, take early orders, and cover the busy period.
2 people from 17:00 to 21:00 to cover the busy period.
1 person from 18:00 to 22:00 to cover the busy period, help pack up, and prepare for the following day.

The schedule was generated with the following input dataset:

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

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

{
  "config": {
    "run": {
      "name": "Published restaurant schedule"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Dan",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Elsa",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Flo",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "2027-02-01-dinner-early",
        "start": "2027-02-01T16:00:00Z",
        "end": "2027-02-01T20:00:00Z"
      },
      {
        "id": "2027-02-01-dinner-1",
        "start": "2027-02-01T17:00:00Z",
        "end": "2027-02-01T21:00:00Z"
      },
      {
        "id": "2027-02-01-dinner-2",
        "start": "2027-02-01T17:00:00Z",
        "end": "2027-02-01T21:00:00Z"
      },
      {
        "id": "2027-02-01-dinner-late",
        "start": "2027-02-01T18:00:00Z",
        "end": "2027-02-01T22:00:00Z"
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

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

{
  "run": {
    "id": "ID",
    "name": "Published restaurant schedule",
    "submitDateTime": "2025-02-03T07:37:53.753457408Z",
    "startDateTime": "2025-02-03T07:38:00.02735691Z",
    "activeDateTime": "2025-02-03T07:38:00.122121923Z",
    "completeDateTime": "2025-02-03T07:43:00.263111216Z",
    "shutdownDateTime": "2025-02-03T07:43:00.391541184Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "2027-02-01-dinner-early",
        "employee": "Ann"
      },
      {
        "id": "2027-02-01-dinner-1",
        "employee": "Beth"
      },
      {
        "id": "2027-02-01-dinner-2",
        "employee": "Carl"
      },
      {
        "id": "2027-02-01-dinner-late",
        "employee": "Dan"
      }
    ]
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null
  }
}

modelOutput contains the shift assignments for the schedule.

Unfortunately, Carl has called in sick for his shift, so the schedule needs to be regenerated.

The input dataset needs to be updated and resubmitted.

First, make Carl unavailable by removing his availableTimeSpans and adding an unavailableTimeSpan. Carl is sick for the entire day and unavailable for any shifts that day:

{
  "id": "Carl",
  "unavailableTimeSpans": [
    {
      "start": "2027-02-01T00:00:00Z",
      "end": "2027-02-02T00:00:00Z"
    }
  ]
}

Learn more about Employee availability.

Next, the shifts that have already been assigned need to be pinned with the name of the employee they have been assigned to, to prevent changes to those shift assignments. Because Carl is ill, the shift he was assigned to is not pinned.

{
  "shifts": [
    {
      "id": "2027-02-01-dinner-early",
      "start": "2027-02-01T16:00:00Z",
      "end": "2027-02-01T20:00:00Z",
      "pinned": true,
      "employee": "Ann"
    },
    {
      "id": "2027-02-01-dinner-1",
      "start": "2027-02-01T17:00:00Z",
      "end": "2027-02-01T21:00:00Z",
      "pinned": true,
      "employee": "Beth"
    },
    {
      "id": "2027-02-01-dinner-2",
      "start": "2027-02-01T17:00:00Z",
      "end": "2027-02-01T21:00:00Z"
    },
    {
      "id": "2027-02-01-dinner-late",
      "start": "2027-02-01T18:00:00Z",
      "end": "2027-02-01T22:00:00Z",
      "pinned": true,
      "employee": "Dan"
    }
  ]
}

Finally, submit the updated input dataset:

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

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

{
  "config": {
    "run": {
      "name": "Real-time restaurant schedule due to illness"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "unavailableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-02T00:00:00Z"
          }
        ]
      },
      {
        "id": "Dan",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Elsa",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Flo",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "2027-02-01-dinner-early",
        "start": "2027-02-01T16:00:00Z",
        "end": "2027-02-01T20:00:00Z",
        "pinned": true,
        "employee": "Ann"
      },
      {
        "id": "2027-02-01-dinner-1",
        "start": "2027-02-01T17:00:00Z",
        "end": "2027-02-01T21:00:00Z",
        "pinned": true,
        "employee": "Beth"
      },
      {
        "id": "2027-02-01-dinner-2",
        "start": "2027-02-01T17:00:00Z",
        "end": "2027-02-01T21:00:00Z"
      },
      {
        "id": "2027-02-01-dinner-late",
        "start": "2027-02-01T18:00:00Z",
        "end": "2027-02-01T22:00:00Z",
        "pinned": true,
        "employee": "Dan"
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

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

{
  "run": {
    "id": "ID",
    "name": "Real-time restaurant schedule due to illness",
    "submitDateTime": "2025-02-03T08:00:19.893547713Z",
    "startDateTime": "2025-02-03T08:00:26.191535664Z",
    "activeDateTime": "2025-02-03T08:00:26.265615945Z",
    "completeDateTime": "2025-02-03T08:05:26.428686234Z",
    "shutdownDateTime": "2025-02-03T08:05:26.557861632Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "2027-02-01-dinner-early",
        "employee": "Ann"
      },
      {
        "id": "2027-02-01-dinner-1",
        "employee": "Beth"
      },
      {
        "id": "2027-02-01-dinner-2",
        "employee": "Elsa"
      },
      {
        "id": "2027-02-01-dinner-late",
        "employee": "Dan"
      }
    ]
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null
  }
}

modelOutput contains the updated shift assignments for the schedule with Elsa assigned to the shift Dan dropped.

In the new schedule, Ann, Beth, and Dan all have the same shifts they were originally assigned.

Real-time planning due to increased demand

If the restaurant has an unexpectedly busy night, for instance, a last minute booking for a large party, new shifts can be added to the input dataset, and the original shift assignments can be pinned to avoid changing employees' assigned shifts at the last minute.

In the following example, Carl doesn’t call in sick, but two more staff members are needed to cover the additional work.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

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

{
  "config": {
    "run": {
      "name": "Real-time restaurant schedule due to increased demand"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Dan",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Elsa",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Flo",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "2027-02-01-dinner-early",
        "start": "2027-02-01T16:00:00Z",
        "end": "2027-02-01T20:00:00Z",
        "pinned": true,
        "employee": "Ann"
      },
      {
        "id": "2027-02-01-dinner-1",
        "start": "2027-02-01T17:00:00Z",
        "end": "2027-02-01T21:00:00Z",
        "pinned": true,
        "employee": "Beth"
      },
      {
        "id": "2027-02-01-dinner-2",
        "start": "2027-02-01T17:00:00Z",
        "end": "2027-02-01T21:00:00Z",
        "pinned": true,
        "employee": "Carl"
      },
      {
        "id": "2027-02-01-dinner-late",
        "start": "2027-02-01T18:00:00Z",
        "end": "2027-02-01T22:00:00Z",
        "pinned": true,
        "employee": "Dan"
      },
      {
        "id": "2027-02-01-dinner-3",
        "start": "2027-02-01T17:00:00Z",
        "end": "2027-02-01T21:00:00Z"
      },
      {
        "id": "2027-02-01-dinner-late-extra",
        "start": "2027-02-01T18:00:00Z",
        "end": "2027-02-01T22:00:00Z"
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

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

{
  "run": {
    "id": "ID",
    "name": "Real-time restaurant schedule due to increased demand",
    "submitDateTime": "2025-02-03T08:30:29.025201073Z",
    "startDateTime": "2025-02-03T08:30:35.194175247Z",
    "activeDateTime": "2025-02-03T08:30:35.320436545Z",
    "completeDateTime": "2025-02-03T08:35:35.467520964Z",
    "shutdownDateTime": "2025-02-03T08:35:35.6188066Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "2027-02-01-dinner-early",
        "employee": "Ann"
      },
      {
        "id": "2027-02-01-dinner-1",
        "employee": "Beth"
      },
      {
        "id": "2027-02-01-dinner-2",
        "employee": "Carl"
      },
      {
        "id": "2027-02-01-dinner-late",
        "employee": "Dan"
      },
      {
        "id": "2027-02-01-dinner-3",
        "employee": "Elsa"
      },
      {
        "id": "2027-02-01-dinner-late-extra",
        "employee": "Flo"
      }
    ]
  },
  "kpis": {
    "assignedShifts": 6,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null
  }
}

modelOutput contains the updated schedule with Elsa and Flo assigned to the new shifts.

Minimizing disruption due to real-time planning

It’s not always possible (or even preferable) to pin every existing shift when real-time planning is necessary, however, you can minimize the disruption real-time planning causes with a global configuration rule.

{
  "globalRules": {
    "disruptionRules": [
      {
        "id": "minimizeDisruptionShortTerm",
        "start": "2027-02-01",
        "end": "2027-02-02",
        "multiplier": 1
      }
    ]
  }
}

disruptionRules must include an id, and start and end times that specify when the rule is applied.

Any disruption to the schedule will invoke the Employee assignment disrupted on replanning soft constraint and impact the soft score of the final solution, which incentivizes Timefold to minimize the disruption.

A multiplier can also be included, which multiplies the soft score by the multiplier. The multiplier can be between 1 and 5 inclusive.

Multiple disruption rules can be configured with different multipliers to give extra weight to shifts happening sooner in the schedule:

{
  "globalRules": {
    "disruptionRules": [
      {
        "id": "minimizeDisruptionShortTerm",
        "start": "2027-02-01",
        "end": "2027-02-07",
        "multiplier": 5
      },
      {
        "id": "minimizeDisruptionLongTerm",
        "start": "2027-02-08",
        "end": "2027-0-14",
        "multiplier": 1
      }
    ]
  }
}

In the following example, Ann, Beth, Carl, and Dan are assigned shifts in the restaurant, but Carl calls in sick. This time, instead of pinning Ann’s, Beth’s, and Dan’s shifts, the employees who were originally assigned to the shifts are added to the shift, pinned is set to false (or omitted altogether), Carl is unavailable, and a disruption rule is applied.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

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

{
  "config": {
    "run": {
      "name": "Real-time restaurant schedule with minimize disruptions"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "unavailableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-02T00:00:00Z"
          }
        ]
      },
      {
        "id": "Dan",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Elsa",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      },
      {
        "id": "Flo",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T22:00:00Z"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "2027-02-01-dinner-early",
        "start": "2027-02-01T16:00:00Z",
        "end": "2027-02-01T20:00:00Z",
        "employee": "Ann"
      },
      {
        "id": "2027-02-01-dinner-1",
        "start": "2027-02-01T17:00:00Z",
        "end": "2027-02-01T21:00:00Z",
        "employee": "Beth"
      },
      {
        "id": "2027-02-01-dinner-2",
        "start": "2027-02-01T17:00:00Z",
        "end": "2027-02-01T21:00:00Z",
        "employee": "Carl"
      },
      {
        "id": "2027-02-01-dinner-late",
        "start": "2027-02-01T18:00:00Z",
        "end": "2027-02-01T22:00:00Z",
        "employee": "Dan"
      }
    ],
    "globalRules": {
      "disruptionRules": [
        {
          "id": "minimizeDisruptionShortTerm",
          "start": "2027-02-01",
          "end": "2027-02-02",
          "multiplier": 1
        }
      ]
    }
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

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

{
  "run": {
    "id": "ID",
    "name": "Real-time restaurant schedule with minimize disruptions",
    "submitDateTime": "2025-02-04T07:03:22.754638826Z",
    "startDateTime": "2025-02-04T07:03:28.712553852Z",
    "activeDateTime": "2025-02-04T07:03:28.767089103Z",
    "completeDateTime": "2025-02-04T07:08:28.987668189Z",
    "shutdownDateTime": "2025-02-04T07:08:29.138631503Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-480soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "2027-02-01-dinner-early",
        "employee": "Ann"
      },
      {
        "id": "2027-02-01-dinner-1",
        "employee": "Beth"
      },
      {
        "id": "2027-02-01-dinner-2",
        "employee": "Flo"
      },
      {
        "id": "2027-02-01-dinner-late",
        "employee": "Dan"
      }
    ]
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 25.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null
  }
}

modelOutput contains the updated schedule with Flo assigned to the shift Carl dropped.

The output includes the disruptionPercentage KPI which shows 25% of the shifts were disrupted due to the change.

Real-time planning and on-call shifts

In some industries it is important to have employees on standby (or on call) who can step in to take over a shift if another employee is suddenly unavailable. Real-time planning can take advantage of this kind of backup planning.

Shifts can be assigned different priorities, where 1 is the highest priority and 10 is the lowest:

{
  "shifts": [
    {
      "id": "2027-02-01-icu-1",
      "start": "2027-02-01T08:00:00Z",
      "end": "2027-02-01T16:00:00Z",
      "priority": "1"
    },
    {
      "id": "2027-02-01-icu-2",
      "start": "2027-02-01T08:00:00Z",
      "end": "2027-02-01T16:00:00Z",
      "priority": "1"
    },
    {
      "id": "2027-02-01-icu-3",
      "start": "2027-02-01T08:00:00Z",
      "end": "2027-02-01T16:00:00Z",
      "priority": "1"
    },
    {
      "id": "2027-02-01-icu-on-call",
      "start": "2027-02-01T08:00:00Z",
      "end": "2027-02-01T16:00:00Z",
      "priority": "5"
    }
}

If there are enough employees, 3 will be assigned to the high priority shifts, and 1 will be assigned to the lower priority on-call shift. If one of the 3 employees assigned to the high priority shifts calls in sick, the on-call employee will be ready to step in and take their place.

See the Employee Shift Scheduling User Guide
Understand the constraints of the Employee Shift Scheduling model.
See the full API spec or try the online API.
Manage schedules with Time zones and Daylight Saving Time (DST) changes.
Manage Employee availability.