Balance shift count

Ensuring fairness in assigned schedules is an important factor in employee shift scheduling.

This guide demonstrates how to manage fairness in employee shift scheduling by creating balance shift count rules.

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 balance shift count rules

balanceShiftCountRules are defined in globalRules.

{
  "globalRules": {
    "balanceShiftCountRules": [
      {
        "id": "balanceShifts"
      }
    ]
  }
}

balanceShiftCountRules must include an id.

balanceShiftCountRules can include or exclude employees based on employee tags.

{
  "globalRules": {
    "balanceShiftCountRules": [
      {
        "id": "balanceShifts",
        "includeEmployeeTags": [
          "Part time"
        ],
        "employeeTagMatches": "ALL"
      }
    ]
  }
}
Further information about including or excluding employees with employee tags:

Employees with specific tags can be included or excluded by the rule. Tags are defined in employees:

{
  "employees": [
    {
      "id": "Ann",
      "tags": "Part-time"
    }
}

Use includeEmployeeTags to include employees with specific tags or excludeEmployeeTags to exclude employees with specific tags.

employeeTagMatches can be set to ALL or ANY. The default behavior for employeeTagMatches is ALL, and if omitted, the default ALL will be used.

The rule can define either includeEmployeeTags or excludeEmployeeTags, but not both.

{
  "includeemployeeTags": ["Part-time", "Relief"],
  "employeeTagMatches": "ALL"
}

With employeeTagMatches set to ALL, all tags defined by the rule’s includeEmployeeTags attribute must be present in the employee. With employeeTagMatches set to ANY, at least one tag defined by the rule’s includeEmployeeTags attribute must be present in the employee.

{
  "excludeEmployeeTags": ["Part-time", "Weekend"],
  "employeeTagMatches": "ALL"
}

With employeeTagMatches set to ALL, all tags defined by the rule’s excludeEmployeeTags attribute cannot be present in the employee. This is useful when you want to exclude things in combination with each other. For instance, excluding the employee tags Part-time and Relief with employeeTagMatches set to All, would exclude employees that include the tags Part-time and Relief from the rule. Employees tagged only Part-time or only Relief will not be excluded.

With employeeTagMatches set to ANY, any of the tags defined by the rule’s excludeEmployeeTags attribute cannot be present in the employee. This is useful when you need to exclude tags regardless of their relationship to other tags. For instance, excluding the employee tags Part-time and Weekend with employeeTagMatches set to ANY, would exclude any employee that includes the tags Part-time or Relief, whether they occur together or not.

balanceShiftCountRules can include or exclude shifts based on shift tags.

{
  "globalRules": {
    "balanceShiftCountRules": [
      {
        "id": "balanceShifts",
        "includeShiftTags": [
          "NIGHT"
        ],
        "shiftTagMatches": "ALL"
      }
    ]
  }
}
Further information about including or excluding shifts with shift tags:

Shifts with specific tags can be included or excluded by the rule. Tags are defined in shifts:

{
  "shifts": [
    {
      "id": "2027-02-01",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z",
      "tags": ["Part-time"]
    }
  ]
}

Use includeShiftTags to include shifts with specific tags or excludeShiftTags to exclude shifts with specific tags.

shiftTagMatches can be set to ALL or ANY. The default behavior for shiftTagMatches is ALL, and if omitted, the default ALL will be used.

The rule can define either includeShiftTags or excludeShiftTags, but not both.

{
  "includeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute must be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute must be present in the shift.

{
  "excludeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you want to exclude things in combination with each other. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to All, will exclude shifts that include the tags Part-time and Weekend from the rule. Shifts tagged only Part-time or only Weekend will not be excluded.

With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you need to exclude tags regardless of their relationship to other tags. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to ANY, will exclude any shift that includes the tags Part-time or Weekend, whether they occur together or not.

1.1. Factoring in work history

By default, only the current planning window is considered in determining the fairness of the schedule. However, shifts worked in the past can also be considered to provide a fairer distribution over a longer period of time.

The timespan to determine fairness over could be the previous month or quarter, but by including specific time periods, for instance, the previous December, it can also be used so that the same people aren’t scheduled to work over the holidays each year.

To include previous shifts worked in the fairness calculation, add employeeToPublishedShiftCount with the total number of shifts worked in previous periods for the employees.

For the fairness calculation to be accurate, it’s important to ensure the shifts worked for all employees are from the same period of time, and that the employees are generally available for the same number of shifts over the period. 
{
  "globalRules": {
    "balanceShiftCountRules": [
      {
        "id": "balanceShifts",
        "employeeToPublishedShiftCount": {
          "Ann": 5,
          "Beth": 3
        }
      }
    ]
  }
}

2. Balance shift count example

The Balance shift count soft constraint fairly balances assigned shifts between employees. When there is no alternative employees will be assigned shifts that are not entirely fair, but the constraint adds a soft penalty to the run score for any matches to the constraint, incentivizing Timefold to find an alternative solution.

In the following example, there are 3 employees and 6 shifts. The shifts are assigned fairly.

balance shift count

  • 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": "Balance shift count example"
    }
  },
  "modelInput": {
    "globalRules": {
      "balanceShiftCountRules": [
        {
          "id": "balanceShifts"
        }
      ]
    },
    "employees": [
      {
        "id": "Ann"
      },
      {
        "id": "Beth"
      },
      {
        "id": "Carl"
      }
    ],
    "shifts": [
      {
        "id": "2027-02-01-a",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "2027-02-01-b",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "2027-02-02-a",
        "start": "2027-02-02T09:00:00Z",
        "end": "2027-02-02T17:00:00Z"
      },
      {
        "id": "2027-02-02-b",
        "start": "2027-02-02T09:00:00Z",
        "end": "2027-02-02T17:00:00Z"
      },
      {
        "id": "2027-02-03-a",
        "start": "2027-02-03T09:00:00Z",
        "end": "2027-02-03T17:00:00Z"
      },
      {
        "id": "2027-02-03-b",
        "start": "2027-02-03T09:00:00Z",
        "end": "2027-02-03T17: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",
    "parentId": null,
    "originId": "ID",
    "name": "Balance shift count example",
    "submitDateTime": "2025-06-25T04:45:23.583692486Z",
    "startDateTime": "2025-06-25T04:45:37.128145399Z",
    "activeDateTime": "2025-06-25T04:45:37.293974338Z",
    "completeDateTime": "2025-06-25T04:46:08.383167465Z",
    "shutdownDateTime": "2025-06-25T04:46:08.61292827Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "2027-02-01-a",
        "employee": "Ann"
      },
      {
        "id": "2027-02-01-b",
        "employee": "Beth"
      },
      {
        "id": "2027-02-02-a",
        "employee": "Carl"
      },
      {
        "id": "2027-02-02-b",
        "employee": "Ann"
      },
      {
        "id": "2027-02-03-a",
        "employee": "Beth"
      },
      {
        "id": "2027-02-03-b",
        "employee": "Carl"
      }
    ]
  },
  "inputMetrics": {
    "employees": 3,
    "shifts": 6,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 6,
    "unassignedShifts": 0,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 3,
    "assignedMandatoryShifts": 6,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the shift schedule with Ann, Beth, and Carl assigned a fair share of the shifts.

modelOutput contains the schedule with the shifts fairly assigned to the employees.

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

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 6,
  "activatedEmployees": 3,
  "assignedMandatoryShifts": 6
}

Next