Minimize gaps between shifts

When employees work multiple shifts in the same day (or split shifts), it is often desirable to keep the gap between shifts as short as possible.

For instance if an employee works at 3-hour shift between 09:00 and 12:00 and another shift in the afternoon, a shift that starts at 12:30 would be preferable to a shift that starts at 13:45 as it reduces the employees work day.

For other options related to managing split shifts, see Single day shift sequence patterns.

Prerequisites

Learn how to configure an API Key to run the examples in this guide:

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

  2. From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.

  3. 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.

1. Define minimize gaps between shift rules

minimizeGapsBetweenShiftsRules are defined in contracts.

{
  "contracts": [
    {
      "id": "splitShiftContract",
      "minimizeGapsBetweenShiftsRules": [
        {
          "id": "minimizeGapsBetweenShiftsRule",
          "requiredPriorShiftTags": [
            "Split-shift"
          ],
          "requiredAfterShiftTags": [
            "Split-shift"
          ],
          "shiftTagMatches": "ANY",
          "maximumMinutesBetweenSplitShifts": 120
        }
      ]
    }
  ]
}

minimizeGapsBetweenShiftsRules must include an id.

requiredPriorShiftTags specifies the shift tags that can be considered the first shift of a pair to be assigned with another shift.

requiredAfterShiftTags specifies the shift tags that can be considered the last shift of a pair to be assigned with another shift.

shiftTagMatches can be set to ALL or ANY. When set to ALL, all tags defined by the rule must be present in the shift. When set to ANY, at least one tag defined by the rule must be present in the shift. The default behavior for shiftTagMatches is ALL, and if omitted, the default ALL will be used.

maximumMinutesBetweenSplitShifts specifies the maximum time between shifts that will trigger this constraint.

When triggered, the Minimize gaps between shifts for employee rewards shifts more the closer they are together.

Defining maximumMinutesBetweenSplitShifts makes sure that shifts that are further apart than the limit specified are not rewarded and do not influence the solution.

By default, every constraint has a weight of 1, meaning that all constraints are equally important.

Learn about changing the weight of this constraint:

Use the constraint configuration’s minimizeGapsBetweenShiftsForEmployeeWeight attribute to update the weight of the constraint. 0 disables the constraint. A constraint weight of 10, means the constraint is 10 times more important than a constraint with a weight of 1.

"overrides": { "minimizeGapsBetweenShiftsForEmployeeWeight": 10 }
This rule is more likely to be satisfied for employees with a higher employee priority.

In the following example, there are 3 shifts on the same day and 1 employee.

minimizeGapsBetweenShiftsRules states that for shifts with 2 hours or less between the end of the first shift and the start of the next shift it is preferable to assign shifts as close together as possible to the same employee.

In this example, the employee works a maximum of 8 hours a day.

Ann is assigned the shift that starts at 12:00 with a duration of 3 hours, she has 30 minutes off work and is assigned the shift that starts at 15:30 with a duration of 3 hours.

The shifts that start at 15:30 and 16:00 both start within 120 minutes of the 12:00 shift that ends at 15:00. The shift that starts at 15:30 has the shortest gap from the end of the 12:00 shift and is assigned to Ann.

The 16:00 shift is left unassigned.

Between the end of the 06:00 and the start of the 12:00 shifts there is a gap of 3 hours. The 06:00 shift is left unassigned.

minimize gaps between shifts

  • 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": "Minimize gaps between shifts example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "splitShiftContract",
        "periodRules": [
          {
            "id": "Max8HoursPerDay",
            "period": "DAY",
            "satisfiability": "REQUIRED",
            "minutesWorkedMax": 480
          }
        ],
        "minimizeGapsBetweenShiftsRules": [
          {
            "id": "minimizeGapsBetweenShiftsRule",
            "requiredPriorShiftTags": [
              "Split-shift"
            ],
            "requiredAfterShiftTags": [
              "Split-shift"
            ],
            "shiftTagMatches": "ANY",
            "maximumMinutesBetweenSplitShifts": 120
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "splitShiftContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon 06",
        "start": "2027-02-01T06:00:00Z",
        "end": "2027-02-01T09:00:00Z",
        "tags": ["Split-shift"]
      },
      {
        "id": "Mon 12",
        "start": "2027-02-01T12:00:00Z",
        "end": "2027-02-01T15:00:00Z",
        "tags": ["Split-shift"]
      },
      {
        "id": "Mon 15-30",
        "start": "2027-02-01T15:30:00Z",
        "end": "2027-02-01T18:30:00Z",
        "tags": ["Split-shift"]
      },
      {
        "id": "Mon 16",
        "start": "2027-02-01T16:00:00Z",
        "end": "2027-02-01T19:00:00Z",
        "tags": ["Split-shift"]
      }
    ]
  }
}
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": "fe0b8156-bd6f-4778-812b-19820b738045",
    "parentId": null,
    "originId": "fe0b8156-bd6f-4778-812b-19820b738045",
    "name": "Minimize gaps between shifts example",
    "submitDateTime": "2025-07-07T07:53:49.680265693Z",
    "startDateTime": "2025-07-07T07:54:07.869582717Z",
    "activeDateTime": "2025-07-07T07:54:08.033874591Z",
    "completeDateTime": "2025-07-07T07:54:38.859082797Z",
    "shutdownDateTime": "2025-07-07T07:54:39.11539151Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-2medium/1140soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon 06"
      },
      {
        "id": "Mon 12",
        "employee": "Ann"
      },
      {
        "id": "Mon 15-30",
        "employee": "Ann"
      },
      {
        "id": "Mon 16"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 4,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 2,
    "unassignedShifts": 2,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 2,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann assigned to 2 shifts close together.

inputMetrics provides a breakdown of the inputs in the input dataset.

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 2,
  "unassignedShifts": 2,
  "activatedEmployees": 1,
  "assignedMandatoryShifts": 2
}

Next