Minutes logged per period

There are different techniques for managing employees' working hours.

For different scenarios see Work limits.

This guide shows you how to manage employees' hours with minutes logged worked per period. A period can be defined as a week, month, or the entire schedule.

When shifts include unpaid breaks, the shift duration and the time employees are paid for (the logged time) is different.

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.

1. Define logged time per period rules

Period rules are defined in contracts:

{
  "periodRules": [
    {
      "id": "Max8LoggedHoursPerDayFullTime",
      "period": "DAY",
      "minutesLoggedMax": 480,
      "satisfiability": "REQUIRED"
    }
  ]
}

PeriodRules must include an ID.

Period is set to DAY.

minutesLoggedMax sets the maximum number of minutes the employee can log for the period.

periodRules can include or exclude shifts based on shift tags.

{
  "periodRules": [
    {
      "id": "Max8LoggedHoursPerDayFullTime",
      "period": "DAY",
      "includeShiftTags": ["Part-time"],
      "shiftTagMatches": "ALL",
      "minutesLoggedMax": 480,
      "satisfiability": "REQUIRED"
    }
  ]
}

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.

When minutesLogged is included in a contract, the shifts need to include loggedTime to specify how much of the shift can be logged.

If neither minutesLogged or loggedTime are included, employees will be paid for the entire duration of the shift.

{
  "shifts": [
    {
      "id": "Mon",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z",
      "loggedTime": "PT6H30M"
    }
  ]
}

loggedTime is the duration (ISO 8601 duration) of the time employees will be paid for the shift.

The satisfiability of the rule can be REQUIRED or PREFERRED. If omitted, REQUIRED is the default.

2. Required logged time per period

When the satisfiability of the rule is REQUIRED, the Logged minutes worked per period not in required range for employee hard constraint is invoked, which makes sure the number of minutes logged does not exceed the limit specified in minutesLoggedMax.

In the following example, there is 1 shift with an 8-hour duration and a loggedTime of 6 hours and 30 minutes.

required minutes logged per period

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": "Required minutes logged per period example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Max8LoggedHoursPerDayFullTime",
            "period": "DAY",
            "minutesLoggedMax": 480,
            "satisfiability": "REQUIRED"
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "loggedTime": "PT6H30M"
      }
    ]
  }
}

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": "Required minutes logged per period example",
    "submitDateTime": "2025-05-23T05:49:54.647292626Z",
    "startDateTime": "2025-05-23T05:50:07.81522701Z",
    "activeDateTime": "2025-05-23T05:50:07.990712062Z",
    "completeDateTime": "2025-05-23T05:50:38.387304461Z",
    "shutdownDateTime": "2025-05-23T05:50:38.666756077Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 1,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 1,
    "unassignedShifts": 0,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 1,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann assigned to the shift.

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

KPIs provides the KPIs for the output including:

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

3. Preferred minutes logged per period

When the satisfiability of the rule is PREFERRED, the Logged minutes worked per period not in preferred range for employee soft constraint is invoked.

With PREFERRED satisfiability you can also use minutesLoggedMin to specify the minimum amount of shift logged time.

{
  "periodRules": [
    {
      "id": "Min7Max8LoggedHoursPerDayFullTime",
      "period": "DAY",
      "minutesLoggedMin": 420,
      "minutesLoggedMax": 480,
      "satisfiability": "PREFERRED"
    }
  ]
}

The Minutes logged per period not in preferred range for employee soft constraint adds a soft penalty to the run score when the number of minutes logged by the employee in a period is below the value of the period rule’s minutesLoggedMin or above the value of the period rule’s minutesLoggedMax, incentivizing Timefold to find an alternative solution.

In the following example, there is 1 shift with an 8-hour duration and a loggedTime of 6 hours and 30 minutes. The employee contract has a rule that states the minimum logged minutes is 420 minutes (7 hours) and the maximum logged time is 480 minutes (8 hours). The shift is assigned to Ann, but the logged time for the shift is below the minium and a soft penalty is applied to the run score.

preferred minutes logged per period

Input
Output