Balance time worked

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

This guide demonstrates how to manage fairness in employee shift scheduling by creating balance time worked 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 time worked rules

balanceTimeWorkedRules are defined in globalRules.

{
  "globalRules": {
    "balanceTimeWorkedRules": [
      {
        "id": "balanceTime"
      }
    ]
  }
}

balanceTimeWorkedRules must include an id.

balanceTimeWorkedRules can include or exclude employees based on employee tags.

{
  "globalRules": {
    "balanceTimeWorkedRules": [
      {
        "id": "balanceTime",
        "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.

balanceTimeWorkedRules can include or exclude shifts based on shift tags.

{
  "globalRules": {
    "balanceTimeWorkedRules": [
      {
        "id": "balanceTime",
        "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, time 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 minutes worked in the fairness calculation, add employeeToPublishedMinutesWorked with the total number of minutes worked in previous periods for the employees.

For the fairness calculation to be accurate, it’s important to ensure the minutes worked for all employees are from the same period of time, and that the employees are generally available for the same number of minutes over the period. 
{
  "globalRules": {
    "balanceTimeWorkedRules": [
      {
        "id": "balanceTime",
        "employeeToPublishedMinutesWorked": {
          "Ann": 2400,
          "Beth": 1200
        }
      }
    ]
  }
}

1.2. Factoring in full time equivalent

Employees have different contracts that require they work different hours. A full-time employee might generally work 40 hours a week, while a part-time employee works 20 hours a week.

To take this difference into account, an FteConfiguration is added to the contracts:

{
  "contracts": [
    {
      "id": "partTimeContract",
      "fteConfiguration": {
        "fixedFte": 0.5
      },
      "periodRules": [
        {
          "id": "Max20HoursPerWeekPartTime",
          "period": "WEEK",
          "minutesWorkedMax": 1200,
          "satisfiability": "PREFERRED"
        }
      ]
    },
    {
      "id": "fullTimeContract",
      "fteConfiguration": {
        "fixedFte": 1.0
      },
      "periodRules": [
        {
          "id": "Max40HoursPerWeekFullTime",
          "period": "WEEK",
          "minutesWorkedMax": 2400,
          "satisfiability": "PREFERRED"
        }
      ]
    }
  ]
}

fteConfiguration must include fixedFte which sets the full-time equivalent for the contract.

fixedFte can include 3 decimal places, it can have a maximum value of 1.000 and the minimum value must be 0.001 or greater.

A contract for a full-time employee has 1.0, while a part-time contract for half the hours of a full-time contract has 0.5. With this configuration a schedule that assigns a full-time employee 40 hours and a part-time employee 20 hours will be considered fair.

[NOTE] Employees can only have a single FTE configuration. If an FTE configuration is included in 2 of the employee’s contracts, the input will fail validation.

Employees must include which contract applies to them:

{
  "employees": [
    {
      "id": "Ann",
      "tags": "PartTimeContract"
    }
  ]
}

2. Balance work time example

The Balance time worked soft constraint fairly balances the time worked 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 time worked

  • 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 time worked example"
    }
  },
  "modelInput": {
    "globalRules": {
      "balanceTimeWorkedRules": [
        {
          "id": "balanceTime"
        }
      ]
    },
    "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 time worked example",
    "submitDateTime": "2025-06-25T04:41:57.386648554Z",
    "startDateTime": "2025-06-25T04:42:14.485884386Z",
    "activeDateTime": "2025-06-25T04:42:14.607873718Z",
    "completeDateTime": "2025-06-25T04:42:45.542806723Z",
    "shutdownDateTime": "2025-06-25T04:42:45.726162996Z",
    "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,
    "workingTimeFairnessPercentage": 100.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,
  "workingTimeFairnessPercentage": 100.0
}

Next