Minutes logged per period

There are different techniques for managing employees' working hours.

For different scenarios see Work limits.

Some shifts can include unpaid breaks, in this situation the shift duration and the time the employee is paid for (the logged time) are different.

A period can be defined as a week, month, or the entire schedule.

This guide explains managing employees' hours with minutes logged worked per period:

1. Define logged time per period rules

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.

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.

period sets the period the rule applies to, for instance, DAY, WEEK, MONTH, SCHEDULE.

Further information about period:

DAY spans a single day and occurs every day in the schedule.

WEEK spans 7 days and occurs every week (including partial weeks) in the schedule. The default start of the week is Monday, but this can be overridden to any day in the week:

{
  "scheduleParameterization": {
    "weekStart": "THURSDAY"
  }
}

MONTH spans the entire month. MONTH has a variable number of days depending on the days in the month and occurs every month (including partial months) in the schedule.

SCHEDULE spans the entire schedule.

You can define custom periods to apply to this rule in the following way: 
{
  "scheduleParameterization": {
    "periods": [
      {
        "id": "PAY_PERIOD",
        "dateSpans": [
          {
            "start": "2023-01-01",
            "end": "2023-01-15"
          }
        ]
      }
    ]
  }
}

The start and end dates are inclusive.

Learn about counting days in period rules:

By default, period rules count shifts within the defined period if the shift starts within the defined period. For instance, if you define a rule that an employee can only work 1 shift a day, a night shift that started on the previous day but ends the following morning will not be counted and another shift might be assigned on the same day as the night shift ended.

To change this behavior change the field periodShiftOverlapKind from START_ONLY to START_AND_END.

{
  "periodRules": [
    {
      "id": "Max8HoursPerDayFullTime",
      "period": "DAY",
      "minutesWorkedMax": 480,
      "satisfiability": "REQUIRED",
      "periodShiftOverlapKind": "START_AND_END"
    }
}

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>
{
  "metadata": {
    "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
  }
}

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.

REQUIRED satisfiability is not supported with `minutesLoggedMin'. 
{
  "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 dataset 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.

Every soft constraint has a weight that can be configured to change the relative importance of the constraint compared to other constraints.

Learn about constraint weights.
This rule is more likely to be satisfied for employees with a higher employee priority.

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 dataset score.

preferred 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": "Preferred minutes logged per period example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Min7Max8LoggedHoursPerDayFullTime",
            "period": "DAY",
            "minutesLoggedMin": 420,
            "minutesLoggedMax": 480,
            "satisfiability": "PREFERRED"
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T13:00:00Z",
        "loggedTime": "PT3H30M"
      }
    ]
  }
}
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>
{
  "metadata": {
    "id": "95b8fba8-ae65-4804-b8cc-3a0cea22962e",
    "name": "Preferred minutes logged per period example",
    "submitDateTime": "2025-05-23T06:09:18.871410228Z",
    "startDateTime": "2025-05-23T06:09:30.827365798Z",
    "activeDateTime": "2025-05-23T06:09:31.00561085Z",
    "completeDateTime": "2025-05-23T06:10:01.349325732Z",
    "shutdownDateTime": "2025-05-23T06:10:01.726599978Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-420soft",
    "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
  }
}

4. Managing overtime

Rules with a satisfiability of REQUIRED put a hard limit on how much work employees can be assigned (minutes, hours, days, shifts), and does not assign overtime.

A rule with a satisfiability of REQUIRED that states an employee can work a maximum of 480 logged minutes per period, will never assign the employee more than 480 logged minutes per period, even if assigning overtime would be beneficial to the overall schedule.

To allow for the possibility of overtime, use rules with a satisfiability of PREFERRED.

Set a rule with a PREFERRED satisfiability for the maximum number of logged minutes per period. Now, a rule with a satisfiability of PREFERRED that states an employee can preferably work a maximum of 480 logged minutes per period will allow the employee to be assigned more logged minutes per period (overtime) than specified by the rule when it is necessary to do so.

To place a limit on the total amount of overtime employees can be assigned, include both:

  • A rule with PREFERRED satisfiability for the maximum number of logged minutes per period that is equivalent to the employees normal logged minutes per period.

  • A rule with REQUIRED satisfiability for the maximum number of logged minutes per period (regular hours plus overtime).

The difference between the PREFERRED maximum logged minutes per period and REQUIRED maximum logged minutes per period is the total amount of overtime that can be assigned to employees.

Next