HRM — Attendance & Shifts

When people work, and the schedule that says when they should

These two modules are documented together because they are tightly linked: a shift says when an employee is supposed to work, and attendance records when they actually did — the gap between the two is what tells the system if someone was late, absent, or eligible for overtime.

Part 1 — Attendance

What it does

Attendance records every clock event — check-in, check-out, break start, break end — as a permanent, immutable entry. From those raw events the system derives a daily status (present, late, absent, on leave, half-day) that payroll later reads. Employees who forget to punch can file a correction (regularization) request, which a manager approves or rejects.

Capture methods

A punch can be captured several ways. The server validates the method on every punch — it never trusts what the client claims.

The punch lifecycle

Every event is stored with no updatedAt and no delete — attendance is a truthful event log. If something is wrong, you don't edit it; you add a correction that creates a new event.

Clocking in (API)

Dev Only Self: ess.attendance.check-in · For others: hr.attendance.check-in.manual

Omit employeeId to punch yourself. Supplying an employeeId forces method: MANUAL and requires the manual permission. The same shape applies to check-out, break-start, and break-end.

Derived daily status

The system computes each day's status on read (and caches it). The logic, in plain terms:

Derived statuses are: PRESENT, LATE, ABSENT, HALF_DAY, WEEKEND, HOLIDAY, ON_LEAVE, with extra flags like MISSING_CHECKOUT.

Corrections (regularization)

In the app

Attendance permissions

Part 2 — Shifts & Scheduling

What it does

Shifts manage work schedules (this is unrelated to v1 cash-drawer sessions). You build reusable shift templates, publish a roster (assign templates to employees on dates), and let employees swap shifts with a colleague — subject to manager approval.

Template vs instance — the key idea

A WorkShift whose endTime is earlier than its startTime is a crosses-midnight shift (e.g. 22:00 → 06:00) and is handled correctly.

Shift statuses

Publishing a roster (bulk)

Dev Only POST /api/v2/hr/shifts/schedule · permission hr.shifts.schedule.create

Send 1–500 entries. Each row is checked independently; the response separates what was created from any conflicts (e.g. a day that's already completed, or an inactive employee). When isOffDay is true, workShiftId is optional.

Shift swaps — a three-step approval

Setting counterpartScheduleId: null makes it a give-away (the counterpart takes the shift; the requester is unrostered that day). Swaps expire after a configurable window (default ~48 hours). Each transition notifies the relevant people.

In the app

Shift permissions

How They Connect

When someone clocks in, attendance asks the shifts module "what was this person scheduled to work today?" and uses that window to judge lateness and overtime. If the shifts module isn't in use, attendance falls back to the tenant's default work-week settings — everything keeps working, just without per-day rosters.