Unique tags per period

Tags and tagTypes can be used to assign shifts to employees.

Tags can be grouped into tagTypes, for example, tagTypes could be department, employment type, or specific task types.

By grouping tags into a tagType, employees can be assigned shifts that belong to a tagType without specifying each and every tag for the employee.

PeriodRules can include uniqueTagsLimit to limit the number of tags that can be used to assign individual employees to shifts. This is useful when employees can be assigned shifts that focus on a range of different tasks, but it’s counterproductive to have employees switching to different types of tasks every day. With uniqueTagsLimit you can limit the different number of tasks employees are assigned across a period.

This could include shifts that involve operating different kinds of machinery, being assigned to specific lines in a call center, or driving predefined routes as a driver.

Prerequisites

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

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 unique tags per period

In the following example, the tagType Tasks includes the tags Task A and Task B:

{
  "tagTypes": [
    {
        "id": "Tasks"
    }
  ],
  "tags": [
    {
        "id": "Task A",
        "tagType": "Tasks"
    },
    {
        "id": "Task B",
        "tagType": "Tasks"
    }
  ]
}

PeriodRules can include tagTypes, effectively filtering out all other tags and tagTypes.

{
  "id": "periodRuleContract",
  "periodRules": [
    {
      "id": "max2TasksRule",
      "period": "WEEK",
      "uniqueTagsLimit": {
        "tagsMax": 2,
        "includeTagTypes": ["Tasks"]
      },
      "satisfiability": "REQUIRED"
    }
  ]
}

PeriodRules must include an ID.

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"
    }
}

uniqueTagsLimit must include tagsMax and includeTagTypes.

tagsMax specifies the maximum number of tags that can be used to assign individual employees to shifts.

includeTagTypes specifies which tagType to include in the rule.

periodRules can include or exclude shifts based on shift tags.

{
  "periodRules": [
    {
      "id": "max2TasksRule",
      "period": "WEEK",
      "uniqueTagsLimit": {
        "tagsMax": 2,
        "includeTagTypes": ["Tasks"]
      },
      "includeShiftTags": ["Part-time"],
      "shiftTagMatches": "ALL",
      "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.

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

2. Required unique tags per period

When the satisfiability of the rule is REQUIRED, the Unique tags per period not in required range for employee hard constraint is invoked, which makes sure the number of tags used to assign shifts to individual employees does not exceed the limit specified in tagsMax.

Shifts will be left unassigned if assigning them would break the Unique tags per period not in required range for employee hard constraint.

In the following example, there are 5 shifts with tags for 3 different tasks. The tagsMax limit is set to 2. Shifts tagged Task A and Task B are assigned. 1 shift tagged Task C is not assigned.

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 unique tags per period example"
    }
  },
  "modelInput": {
    "tagTypes": [
      {
        "id": "Tasks"
      }
    ],
    "tags": [
      {
        "id": "Task A",
        "tagType": "Tasks"
      },
      {
        "id": "Task B",
        "tagType": "Tasks"
      },
      {
        "id": "Task C",
        "tagType": "Tasks"
      }
    ],
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Max2TasksRule",
            "period": "WEEK",
            "uniqueTagsLimit": {
              "tagsMax": 2,
              "includeTagTypes": [
                "Tasks"
              ]
            },
            "satisfiability": "REQUIRED"
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "tags": ["Task A"]
      },
      {
        "id": "Tue",
        "start": "2027-02-02T09:00:00Z",
        "end": "2027-02-02T17:00:00Z",
        "tags": ["Task B"]
      },
      {
        "id": "Wed",
        "start": "2027-02-03T09:00:00Z",
        "end": "2027-02-03T17:00:00Z",
        "tags": ["Task C"]
      },
      {
        "id": "Thu",
        "start": "2027-02-04T09:00:00Z",
        "end": "2027-02-04T17:00:00Z",
        "tags": ["Task A"]
      },
      {
        "id": "Fri",
        "start": "2027-02-05T09:00:00Z",
        "end": "2027-02-05T17:00:00Z",
        "tags": ["Task B"]
      }
    ]
  }
}

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",
    "parentId": null,
    "originId": "ID",
    "name": "Required unique tags per period example",
    "submitDateTime": "2025-06-18T05:37:49.003716694Z",
    "startDateTime": "2025-06-18T05:38:04.237476631Z",
    "activeDateTime": "2025-06-18T05:38:04.477334757Z",
    "completeDateTime": "2025-06-18T05:38:35.601443171Z",
    "shutdownDateTime": "2025-06-18T05:38:35.782618284Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-1medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Ann"
      },
      {
        "id": "Tue",
        "employee": "Ann"
      },
      {
        "id": "Wed"
      },
      {
        "id": "Thu",
        "employee": "Ann"
      },
      {
        "id": "Fri",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 5,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 1,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 4,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann assigned to shifts with 2 different tasks. Shifts with 1 task are left unassigned.

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

KPIs provides the KPIs for the output including:

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

3. Preferred unique tags per period

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

{
  "id": "periodRuleContract",
  "periodRules": [
    {
      "id": "max2TasksRule",
      "period": "WEEK",
      "uniqueTagsLimit": {
        "tagsMax": 2,
        "includeTagTypes": ["Task"]
      },
      "satisfiability": "PREFERRED"
    }
  ]
}

This constraint adds a soft penalty to the dataset score when the number of tags used to assign shifts to an individual employee exceeds the limit set in tagsMax, 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 are 5 shifts with tags for 3 different tasks. The tagsMax limit is set to 2. All shifts are assigned and a soft penalty is added to the dataset score.

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 unique tags per period example"
    }
  },
  "modelInput": {
    "tagTypes": [
      {
        "id": "Tasks"
      }
    ],
    "tags": [
      {
        "id": "Task A",
        "tagType": "Tasks"
      },
      {
        "id": "Task B",
        "tagType": "Tasks"
      },
      {
        "id": "Task C",
        "tagType": "Tasks"
      }
    ],
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Max2TasksRule",
            "period": "WEEK",
            "uniqueTagsLimit": {
              "tagsMax": 2,
              "includeTagTypes": [
                "Tasks"
              ]
            },
            "satisfiability": "PREFERRED"
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "tags": ["Task A"]
      },
      {
        "id": "Tue",
        "start": "2027-02-02T09:00:00Z",
        "end": "2027-02-02T17:00:00Z",
        "tags": ["Task B"]
      },
      {
        "id": "Wed",
        "start": "2027-02-03T09:00:00Z",
        "end": "2027-02-03T17:00:00Z",
        "tags": ["Task C"]
      },
      {
        "id": "Thu",
        "start": "2027-02-04T09:00:00Z",
        "end": "2027-02-04T17:00:00Z",
        "tags": ["Task A"]
      },
      {
        "id": "Fri",
        "start": "2027-02-05T09:00:00Z",
        "end": "2027-02-05T17:00:00Z",
        "tags": ["Task B"]
      }
    ]
  }
}

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",
    "parentId": null,
    "originId": "ID",
    "name": "Preferred unique tags per period example",
    "submitDateTime": "2025-06-18T05:50:40.092236461Z",
    "startDateTime": "2025-06-18T05:50:55.658134091Z",
    "activeDateTime": "2025-06-18T05:50:55.903627022Z",
    "completeDateTime": "2025-06-18T05:51:26.985952291Z",
    "shutdownDateTime": "2025-06-18T05:51:27.355453568Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-1soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Ann"
      },
      {
        "id": "Tue",
        "employee": "Ann"
      },
      {
        "id": "Wed",
        "employee": "Ann"
      },
      {
        "id": "Thu",
        "employee": "Ann"
      },
      {
        "id": "Fri",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 5,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 5,
    "unassignedShifts": 0,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 5,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann assigned to all 5 shifts.

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

KPIs provides the KPIs for the output including:

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

See the full API spec or try the online API.
Learn more about employee shift scheduling from our YouTube playlist.
See other options related to Shift type diversity.

Unique tags per period

Prerequisites

1. Define unique tags per period

2. Required unique tags per period

3. Preferred unique tags per period

Next