Shift Breaks

When creating shifts, there are multiple strategies for dividing them.

Such as:

  • Creating shifts that mirror the exact amount of time worked (no breaks).

  • Creating shifts that span multiple days, but include breaks whenever the employee shouldn’t be working.

  • Creating shifts with intermediate durations, but include breaks for lunch or travel.

1. Defining breaks

Breaks are defined in shifts.

{
  "shifts": [
    {
      "id": "shiftWithBreaks",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z",
      "breaks": [
        {
          "start": "2027-02-01T10:00:00Z",
          "end": "2027-02-01T10:15:00Z"
        },
        {
          "start": "2027-02-01T12:00:00Z",
          "end": "2027-02-01T13:00:00Z"
        }
      ]
    }
  ]
}

Breaks have two required fields, start and end.

Validation rules for breaks:

  1. The break’s start must be before its end.

  2. The total duration of breaks during a shift must not surpass the shift’s total duration.

  3. The breaks in a shift must be ordered from first to last.

  4. The breaks defined on a shift must not overlap.

2. Using breaks

As mentioned before, there are multiple ways to use breaks. They come in very handy if you define long shifts but expect employees to take a certain number of breaks. The parts of the shift that are covered by breaks are not counted towards time worked.

For example, when an employee must work at most eight hours a day, and works the shifts in the code example below, then:

  • shift a is too long. It spans nine hours.

  • shift b is perfect. It spans nine hours, but has a one-hour break.

  • shift c is perfect. It spans nine hours, but has a 15-minute break and a one-hour break.

{
  "shifts": [
    {
      "id": "shift a",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T18:00:00Z",
      "breaks": []
    },
    {
      "id": "shift b",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T18:00:00Z",
      "breaks": [
        {
          "start": "2027-02-01T12:00:00Z",
          "end": "2027-02-01T13:00:00Z"
        }
      ]
    },
    {
      "id": "shift c",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T18:00:00Z",
      "breaks": [
        {
          "start": "2027-02-01T10:00:00Z",
          "end": "2027-02-01T10:15:00Z"
        },
        {
          "start": "2027-02-01T12:00:00Z",
          "end": "2027-02-01T13:00:00Z"
        }
      ]
    }
  ]
}

2.1. Specify which breaks do and do not count as time worked

By default, breaks are not counted towards time worked. However, in scenarios where some breaks do count towards time worked and other breaks which do not count toward time worked, you can specify tags for breaks. The tags are used to determine which breaks count towards the time worked for specific rules, and which do not. Breaks which match the tags specified in the rule will not count towards working time. All other breaks will count towards working time.

In this example, an employee must work no more than eight hours per day. Lunch breaks do not count as working time, but tea breaks do. Their contract rule would specify that we do not count lunch breaks towards working time as follows:

      {
        "id": "8hrsPerDayContract",
        "periodRules": [
          {
            "id": "Max8HoursPerDay",
            "period": "DAY",
            "minutesWorkedLimit": {
              "minutesWorkedMax": 480,
              "unloggedBreakTags": ["lunchBreak"],
              "breakTagMatches": "ALL"
            }
          }
        ]
      }

This employee gets one long lunch break which does not count towards hours worked, and two short tea breaks which do count towards the hours worked. The shift looks as follows:

{
  "shifts": [
    {
      "id": "shift 1",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T18:00:00Z",
      "breaks": [
        {
          "start": "2027-02-01T10:30:00Z",
          "end": "2027-02-01T10:45:00Z",
          "tags": ["teaBreak"]
        },
        {
          "start": "2027-02-01T12:00:00Z",
          "end": "2027-02-01T13:00:00Z",
          "tags": ["lunchBreak"]
        },
        {
          "start": "2027-02-01T16:30:00Z",
          "end": "2027-02-01T16:45:00Z",
          "tags": ["teaBreak"]
        }
      ]
    }
  ]
}

In this example, this shift would be allowed because the employee can work eight hours per day, and the shift’s working time which counts for the rule is eight hours. If the employee’s limit was seven and a half hours, they would exceed the limit, because the tea breaks count towards working time.

If other breaks are added to the shift, they must be tagged to match unloggedBreakTags. Otherwise, they will be counted as working time for the purposes the period rule in the example above.

The following rules accept unloggedBreakTags and breakTagMatches:

Assigning multi-day shifts to a single employee

Another use case for breaks is assigning set of shifts to the same employee. For example, when the servicing of a machine requires multiple days of work, but the same employee must work on the machine and the employee may not work at night. You could define a shift spanning multiple days and include breaks for the night hours. The code example below defines a shift that spans three days, but includes two breaks for the night hours.

{
    "shifts": [
        {
            "id": "multi-day shift with night break",
            "start": "2027-02-01T09:00:00Z",
            "end": "2027-02-03T17:00:00Z",
            "breaks": [
                {
                    "start": "2027-02-01T17:00:00Z",
                    "end": "2027-02-02T09:00:00Z"
                },
                {
                    "start": "2027-02-02T17:00:00Z",
                    "end": "2027-02-03T09:00:00Z"
                }
            ]
        }
    ]
}

Keep in mind that the breaks only work with 'minutes worked' constraints and are not supported by other constraints, e.g. days or weekends worked constraints.

Next