Rota data & automation

JQL namespaces

Use /reference/rota for curated fields, intents, and examples. Primary models live in src/rota/models.py.

Namespace	Use it for
`rota.RotaSettings`	Tenant policy: week start, swaps, claims, rest limits, publish mail, attendance sync.
`rota.Rota`	Planning boards and the groups that supply staff rows.
`rota.ShiftTemplate`	Reusable windows, colours, headcount, optional `attendance.Shift`.
`rota.RotaShift`	Dated shift instances on a board.
`rota.RotaAssignment`	Person on a shift; cancel unassigns and may reopen the pool.
`rota.RotaPattern`, `rota.RotaPatternSlot`	Repeating week designs and their slots.
`rota.RotaComplianceRule`	Configurable rest, hour, and booking rules.
`rota.EmployeeAvailability`	Cannot-work windows.
`rota.ShiftSwapRequest`	Swap lifecycle and approval.
`rota.OpenShiftClaim`	Claims on unfilled published slots.

Controller namespace: rota.Rota with schema: "controller". The intent is the method name.

Controller intents

rota.Rota.getDashboard
rota.Rota.getBoard
rota.Rota.getMySchedule
rota.Rota.getEmployeeSchedule
rota.Rota.getConflicts
rota.Rota.getCoverageReport
rota.Rota.getMyBadgeCount
rota.Rota.publish
rota.Rota.copyWeek
rota.Rota.applyPattern
rota.Rota.bulkCreateShifts
rota.Rota.autoFill
rota.Rota.exportRota

getBoard and getMySchedule include presence on assignments when Attendance records exist for that duty window. Coverage actual counts punched, non-shadow assignees.

Useful workflow events

Prefer the dispatch intents the models already emit rather than inventing parallel names.

rota.RotaAssignment:create — someone was rostered.
rota.RotaAssignment:confirm / rota.RotaAssignment:decline — acknowledgement when required.
rota.RotaAssignment:cancel — unassign; the shift may reopen if empty.
rota.Rota:archive / rota.Rota:duplicate
rota.RotaShift:cancel
rota.ShiftSwapRequest:create / rota.ShiftSwapRequest:approve
rota.OpenShiftClaim:create / rota.OpenShiftClaim:approve

There is no dedicated “published” event class. After publish, react to shift status updates or send mail from RotaSettings.notify_on_publish (already handled in PublishService). Add a workflow only when you need extra tasks, tickets, or a downstream system.

Create and update patterns

Create assignments through the Scheduler or bulkCreateShifts / autoFill, not by writing orphan rows that skip compliance.
Publish through rota.Rota.publish so statuses, timestamps, and notifications stay consistent.
Cancel an assignment rather than deleting history when the week is already published.
Keep foreign keys as scalar ids in JQL payloads (rota, employee, template).
Filter automations by status, rota, and date range so routine draft edits stay quiet.

Reports and dashboards

Unfilled published slots and shortfall by day.
Coverage: required versus assigned versus punched.
Conflicts: double-booking (both dates), rest, weekly hours, consecutive days.
Swap and claim queues and cycle time.
Presence: due versus live versus done for the current window.

Attendance reports remain the place for lateness, absence, and overtime. Rota reports should not recompute punches.

Integration notes

Tenant isolation is mandatory on every query.
Board staff is Rota.groups → group members → HCM employees.
Presence is derived: never persist a parallel “clocked in” flag on RotaAssignment.
When sync_attendance_expectations is true, Attendance unions office workdays with published rota assignees.