EMS

Technical Reference: Guard Duty Schedule Board

Overview

Every teacher’s own weekly working schedule can already carry a “Guard” slot — one configurable ems.non_teaching_type reason among others (see Non-teaching types), assigned to a period the same way as a break or a coordination meeting (see Teacher working schedules & schedule frameworks). What was missing was a way to consult that information across teachers: for a given weekday, who is teaching where, and who is on guard duty, in each time block. This board is a read-only, centre-wide aggregation answering exactly that — no new data is captured, it only re-reads what already lives on every teacher’s own resource.calendar.attendance rows.

flowchart LR
    NT["ems.non_teaching_type.is_guard"] -->|related, store=True| ATT["resource.calendar.attendance.non_teaching_is_guard"]
    T1["Teacher A: resource.calendar.attendance (teaching)"] --> AGG["ems.course._get_guard_duty_board_attendance_ids()"]
    T2["Teacher B: resource.calendar.attendance (guard)"] --> AGG
    AGG --> LINES["ems.course.get_guard_duty_board_lines(weekday, shift, area_ids, day) -- lines = time periods, columns = groups by area, + guards; laid out on a real time axis (BoardTimeGrid)"]
    ABS["hr.leave (approved or pending, covering 'day')"] --> LINES
    PTR["ems.absence_pending (state pending, covering 'day')"] --> LINES
    LINES --> DATA["ems.course.get_guard_duty_board_data(weekday, shift, area_ids, day) -- same, JSON-safe, @api.model"]
    LINES --> PDF["QWeb PDF: ems.report_guard_duty_board (model = ems.course)"]
    DATA --> W["ir.actions.client 'ems_guard_duty_board' -- week picker + weekday tabs (Mon-Fri) x shift dropdown x area filter x two views (timetable / absences table)"]

No dedicated model. An earlier version introduced a ems.guard_duty_board TransientModel wizard, opened via a dynamic ir.actions.server. That was replaced (2026-08-31) once it caused a real, user-visible problem: the URL bar showed a raw ems.guard_duty_board/<id> instead of a stable action-<xmlid> like every other EMS screen, because Odoo can only put a real xmlid in the URL for a statically declared action — a server action that returns a dynamically-built act_window dict has no xmlid of its own to show. The board’s methods now live directly on ems.course instead (a real, always-existing model every teacher already has read access to — see “Access control” below), and the screen itself is a plain ir.actions.client, both addressable by a real, stable URL.

Model changes

ems.non_teaching_type (models/employees/non_teaching_type.py):

resource.calendar.attendance (ems_working_schedule_assignation, models/employees/working_schedule.py):

ems.course (extended, models/attendance/guard_duty_board.py, _inherit = ['ems.course', 'ems.schedule_report_mixin'] — same “extend in place” pattern as ems_working_schedule/resource.calendar and ems_group_schedule/ems.group):

Absences on the board

The problem this solves. A guard-duty period is only worth planning if you know which classes are actually going to be left without a teacher. That information lives in hr.leave (see Staff absences) and nothing joined the two: the board answered “who is on guard on a Tuesday”, never “who is missing on Tuesday the 15th”.

Weekday vs date — why the screen needed a week picker first. The timetable repeats by weekday; an absence happens on a real date. There is no way to resolve one from the other, so get_guard_duty_board_lines()/get_guard_duty_board_data() take an optional day, and the client action grew a date input and week navigation to supply it. Without a date the board behaves exactly as it did before — every absence structure comes back empty — which is what keeps every weekday-only caller working unchanged.

flowchart TD
    D["day (a real date)"] --> Q["hr.leave.search: employee in this shift's teachers,<br/>state in confirm/validate1/validate,<br/>request_date_from &lt;= day &lt;= request_date_to"]
    Q --> I["_get_guard_duty_absence_intervals()<br/>{employee.id: [(hour_from, hour_to, state)]}"]
    I --> S["_guard_duty_absence_state(intervals, employees, hour_from, hour_to)<br/>overlap test per board period"]
    S --> C["cell['absences'] -- who is away in this group's cell"]
    S --> G["line['guard_absences'] -- who is away in the guard column"]
    C --> R["line['absences'] -- one row per uncovered class (teacher + group/subject/room)"]

Two states, never one. ABSENCE_STATES maps hr_holidays’ states onto the only two distinctions that matter to whoever assigns guards: validate → 'approved' (a fact to plan around), confirm/validate1 → 'pending' (a request nobody has decided on yet). The two pre-approval states are collapsed deliberately — “waiting for the first approver” vs “the second” changes nothing here. Refused and cancelled requests are not in the mapping at all, which is what keeps them off the board entirely. (A third state, 'unchecked', is not an absence at all: a teacher who has not checked in today, see “Teachers who have not checked in” below.) When the same teacher has both an approved and a pending absence overlapping one period, approved wins: the period needs covering either way, and reporting it as merely requested would understate it.

Co-taught classes: listed, but marked as covered. Every row of line['absences'] carries covered, from _guard_duty_is_co_taught(cell_entries, teacher, absences): true when another teacher of the same cell (same group, same period) is not away and teaches in the same room as the absent one. The row is still there, so the board says who is missing, but it is struck through (.o_guard_board_absence_covered on screen, .gdb-absence-covered in the PDF) because nobody needs to cover it. On screen every struck-through line, whatever the reason (co-taught, a guard sent, a timetable change communicated), carries an info icon on its left, and the whole line answers like it: its reason (struckReason()) shows as a tooltip on hover and in a popover on click - a plain title was only found by whoever happened to hover, which most teachers never do. A line struck out because a guard was sent stays editable by whoever organises the absence: its popover also offers “Change or remove the guard”, which opens the assignment dialog. The room check is what keeps a group split across two rooms (each teacher with half of it) from being marked covered: the absent teacher’s half has nobody. On this centre’s data every shared slot is same room and same subject, i.e. genuine co-teaching. A co-teacher away for any part of the period does not cover, the same overlap test _guard_duty_absence_state uses.

Detected absences are pending absences too. An ems.absence_pending entry, entered by the teacher’s chief, the Head of Studies or their Deputy on the teacher’s behalf or found from a missing check-in once the day was over (see Detected absences), is added as a 'pending' interval while its own state is pending, clipped to the requested day in the company’s timezone by _get_local_hours(). Once the teacher files the real absence the entry is linked to it and ignored here for good: only the teacher’s own request counts, with its own range and state, whatever becomes of it.

Whole day vs part of one. The interval is read from request_unit_hours rather than ems_full_day: it is the field that actually decides whether request_hour_from/_to carry anything (see hr.leave._compute_request_unit_hours and EMS’s override of it), and a multi-day request is a whole day on each of its days however it was filled in. A whole day becomes (0.0, 24.0) so it compares against a board period exactly like a partial one does — no special case anywhere downstream. Arriving an hour late therefore marks the 9-10 lesson and leaves the 11-12 one alone.

An absent regular guard is a subtraction, not an addition. A teacher who is away during a period they were on a regular guard duty for has no class of their own for anybody to cover — they are simply one fewer person available to cover somebody else’s. That is why guard_absences is reported separately from absences: the guard column marks them, and no row appears in the “what needs covering” list. A guard duty that is not regular (WC, break…) is the exception, see “Guard duties that are not regular” below.

Confidentiality. The absence search runs sudo() — same justification ems.attendance_session_header.get_guard_sessions() already carries for reading schedules that are not the reader’s own: whoever reads this board legitimately needs to know a colleague is not coming. Only the fact and the interval are ever exposed. The absence type, its reason and its attachments never leave the model, so the confidentiality rule described in Staff absences is not weakened by this screen.

Access control

Action ems.group_teacher (every teacher) ems.group_department_chief and above
Open the board Yes Yes
Call get_guard_duty_board_lines() / get_guard_duty_board_data() Yes Yes
Export the board to PDF Yes Yes

No new ir.model.access.csv rows at all. ems.access_ems_course_teacher already grants ems.group_teacher read access to ems.course — since the board’s methods live there now (rather than on a dedicated model that would have needed its own ACL), every teacher can already call them. No sudo() is used anywhere in _get_guard_duty_board_attendance_ids() either, and none is needed: base Odoo’s own resource module already grants base.group_user (every internal user, so every teacher) plain read access to resource.calendar/resource.calendar.attendance, with no ir.rule narrowing it further — see Group Schedule’s own “Access control” section, which documents this same fact for its identical aggregation. Colleagues’ schedules were never actually access-restricted at the model level; only the “Working Schedules” menu (admin configuration screen, resource.calendar records with is_framework=False, write access still ems.group_department_chief-only) was.

views/attendance/guard_duty_board/menu.xml — action_guard_duty_board is a plain ir.actions.client (tag="ems_guard_duty_board"), not bound to any model or record — see the class docstring in models/attendance/guard_duty_board.py for why this replaced an earlier TransientModel + dynamic server-action design. <menuitem> sits directly under hr_attendance.menu_hr_attendance_root (“Employee Attendances”, already visible to ems.group_teacher, see views/attendance/menu.xml), a sibling of the “Attendance” submenu (which itself groups Overview/Correction Requests/Management) and “Time off” — deliberately not under “Working Schedules” (menu_work_locations), which only Head of Studies/Direction can see.

The menu item is limited to ems.group_teacher and ems.group_secretary (groups= on menu_guard_duty_board). Every role that organises or looks up guards implies one of the two (Tutor, Department/Seminar Chief, Head of Studies/Deputy, Director, the academic administrator, Coexistence, TAC and Orientation all imply group_teacher). Quality and Settings (and their administrators) imply neither: they don’t organise guards and have no read access to ems.group, which the board needs, so the menu is hidden from them rather than widening their access for this screen alone (issue #680). Covered per role by test_menu_visible_only_to_the_roles_that_can_open_the_board.

Client action

static/src/js/backend/guard_duty_board.js (GuardDutyBoard, registered as registry.category("actions").add("ems_guard_duty_board", GuardDutyBoard), static props = ["*"] — the standard shape for a top-level ir.actions.client component, same convention as attendance_session_view.js’s AttendanceSessionView) + matching .xml template (static/src/xml/backend/guard_duty_board.xml) and CSS (static/src/css/backend/guard_duty_board.css, o_guard_board_* classes). onWillStart first calls get_current_course_data() (to label the page and remember the course id for the PDF button), then loads the initially-active day/shift. useState({ activeDay, activeShift, board, loading, courseId, courseName }) drives the weekday tabs (Mon-Fri) plus a shift <select> (Morning/Afternoon) — a dropdown, not a second row of tabs, and not both shifts stacked on one page: morning and afternoon are different shifts (see ems.group.shift) and a school’s real bell schedule made the two stacked together too dense to read at a glance (developer feedback, 2026-08-31). Only one <table> (the active day + active shift) is ever rendered from state.board.

The <h1> title is a get title() getter, not a literal string in the template (issue #442, fixed 2026-09-11). The template used to build it inline (t-esc="state.courseName ? 'Guard duty schedule (' + state.courseName + ')' : 'Guard duty schedule'") — a plain JS string concatenation the i18n extractor never sees, so it always rendered in English regardless of the viewer’s own language, unlike every other label on this screen. get title() calls _t() instead (_t("Guard duty schedule (%s)", this.state.courseName) / _t("Guard duty schedule")), and the template just does t-esc="title".

A week, not just a weekday. state.weekStart holds the Monday of the shown week, and the weekday tabs render their own day of the month alongside their name, so the tab strip doubles as that week’s calendar. The toolbar carries ‹ › week navigation plus a native <input type="date">; picking any date moves the whole week and lands on that date’s own weekday tab. Four helpers at the top of the file keep this honest: toIsoDate() formats from the browser’s local calendar fields, deliberately not toISOString() (which converts to UTC first and so returns the previous day for anyone east of Greenwich during the evening — the board’s date is a calendar day, never an instant); fromIsoDate() parses one back; mondayOf() maps any date onto its week’s Monday, with a weekend belonging to the week it closes, which is also what makes picking a Saturday in the date input land on a real, showable weekday; and addDays() moves by calendar days (new Date(year, month, day + n)), never by adding milliseconds: the day the clocks go back has 25 hours, so a week of 7 x 24h from a Monday landed on Sunday 23:00 and Monday and Tuesday both showed as the 25th (issue #678, October 2026; the 23-hour day in March did the same going back). ems_guard_duty_board_clock_change checks both, with the test browser put in the centre’s timezone (Emulation.setTimezoneOverride): it runs in UTC otherwise, which has no clock changes.

Two views of the same payload, no extra round trip. state.activeView switches between the absences table (table, first and the default since 2026-10-07: it is the one the centre works from day to day) and the timetable (schedule). The absences table (table, labelled “Absences table” on screen - renamed from “Guard duty table” per issue #442, since the tab is about who’s missing, not the board as a whole), rendered as nav-pills in the toolbar rather than a second row of nav-tabs, so they never compete visually with the weekday tabs above them. Both come in the same already-fetched payload — the server sends cells, guards and absences on every line (see “Absences on the board” above) and both views already laid out on its real time axis (schedule_grid/absence_grid, see “A real time axis” below), so switching view is a pure re-render. Every teacher arrives as {name, absence} rather than a bare name, which is what lets both views mark absences the same way without matching names back against a separate list; absenceClass() maps that to o_guard_board_absent (bold red, an absence that is going to happen) or o_guard_board_absent_pending (lighter italic, still awaiting its approver). That red is the only colour left anywhere on the board — everything else was deliberately stripped back to plain text and thin borders (developer feedback, 2026-09-01), so nothing competes with it.

The absences table is not stretched across the window. Bootstrap’s own .table { width: 100% } spread its few columns over the full width of a wide screen and left the content adrift in empty cell (developer feedback, 2026-09-08: “queda demasiado disperso en la pantalla”). .o_guard_board_duty_table overrides width to auto, so table-layout: fixed sizes the table to the literal sum of its <col> widths (100px of time, 400px per area, 170px per guard lane), and margin: 0 auto centres it when there is room to spare. The wrapper keeps its own overflow-x: auto, so a narrow window, or a centre with many areas, scrolls rather than squeezing the columns. Each absence stays on one line — teacher and the class to cover side by side, never wrapped (developer feedback, 2026-09-08: “elimina el salto de línea aunque quede una columna un poco más ancha”); the text-overflow: ellipsis alongside white-space: nowrap is there so a longer name degrades by being clipped rather than by spilling over the next column. Both are regression-tested in guard_duty_board_tour.js: the table is centred whenever it is narrower than its wrapper, and no absence row wraps onto a second line (measured against its own computed line-height, not a hardcoded pixel height).

Where the planner was survives leaving the board (2026-10-07). navigationState (date, shift, view, areas) is published with props.updateActionState(), so the router keeps it in the URL’s query string (?date=...&shift=...&view=...&areas=...), and handed back through useSetupAction({ getLocalState }). restoreNavigation() applies, over the defaults below, either props.state (coming back through the breadcrumbs) or action.context.params (the URL: browser back button, reload, a shared link), ignoring anything invalid. Opening the board from the menu carries neither, so it still starts at “now”. absence_coverage_tour.js checks both ways back from a notice (and fails without the restore).

Opens on today’s own day/shift, not always Monday/Morning. getDefaultDayAndShift() (top of the file) reads the browser’s own Date() — “now” here means the viewer’s wall-clock time, not the server’s — and maps Date.getDay() (0=Sunday..6=Saturday) onto the board’s own weekday index (0=Monday..4=Friday); a weekend defaults to Monday (the board has no weekend concept at all, every table is keyed to a Mon-Fri dayofweek). The shift threshold (>=15:00 → afternoon) is a hand-kept copy of SHIFT_HOURS’s own boundary in models/attendance/guard_duty_board.py — added per developer feedback (2026-09-01): “cuando entro en la sección… por defecto tendría que estar viendo el que toca”. Regression-tested in guard_duty_board_tour.js by computing the same expected day/shift independently in the test itself (against the real clock the test happens to run at) and asserting the board’s initial state matches — not a fixed “Monday” assumption, which the rest of that same tour still relies on for its own (date-independent) fixture-data assertions, reached by explicitly switching back to Monday/Morning right after this check.

The data is fetched via RPC (ems.course.get_guard_duty_board_data()), one weekday/shift at a time. An early version instead read a form field’s own prefetched sub-records client-side (the same approach schedule_grid_readonly_field.js uses for its own, much smaller, per-group/ per-student aggregation) — this broke in practice: the web client silently caps how many sub-records a relational field fetches for rendering, and a centre-wide aggregation easily exceeds that cap (several hundred rows for a real school), so only whichever weekday happened to load first (in practice, Monday) ever showed real data — every other tab rendered empty, even though the server-side PDF (which reads the same recordset directly over the ORM, no such cap) always showed the full week. setActiveDay()/onShiftChange() both call the same loadBoard(), which re-fetches exactly the currently active day+shift pair.

No cell colouring. An earlier version painted each occupied cell’s background with the same per-subject colour the teacher/group schedule PDFs use (ems.schedule_report_mixin.REPORT_COLOR_PALETTE), with white text on top (.o_guard_board_cell_occupied). Removed per developer feedback (2026-09-01): “quita los colores de background de la tabla… a ver como queda” — with every group already its own column and the subject spelled out as a short acronym, the colour wash was noise, not signal. The Guard duty column’s own light background tint went too, for the same “no background colour anywhere in the table” reading of that request. First pass deliberately kept one exception — the guard-duty badge itself (.o_guard_board_guard_badge, a fixed orange fill) — reasoning that it was the actual “who is on duty” signal the column exists to surface, not a whole-cell/ whole-column wash. The developer asked for that gone too on a second pass, same day: “quitar el color de fondo de los nombres de las personas que están de guardia” — so .o_guard_board_guard_badge now has no background-color/color overrides at all, just a thin 1px solid #ccc border (purely to keep several names in the same cell visually separated from each other, not a colour). Applied identically to the PDF (see “PDF report” below) — same reasoning throughout, verified against a real generated PDF at each pass.

One deliberate, narrower exception (developer request, 2026-09-11, and issue #637): a break block - a group’s or an area’s own break, or a break-time guard - carries a 4px border-left (#8a6240, the exact same brown schedule_grid.css’s .o_schedule_grid_entry_break already uses for a break block on the teacher’s own Schedule tab, so the same colour reads as “patio” on both screens). This does not reopen the decision above: it is a border, not a background fill, and it marks a kind of block (break time), never a person’s name or a subject the way the removed washes did. It is a real border-left, not an inset box-shadow: Bootstrap paints its own cell box-shadow over an inset one, which is why an earlier attempt never showed.

Why a table, not the existing absolute-positioned grid: schedule_grid_field.js/ schedule_grid_readonly_field.js position entries by pixel offset within one weekday column, at most a handful of genuinely overlapping blocks side by side (see the read-only widget’s own layoutOverlappingBlocks column-split, added for a student’s own schedule — a single teacher still can’t be in two places at once, but a group or a student can have a handful of concurrent entries). A centre-wide board is a different scale of the same problem — many dozens of groups run in parallel at any given hour, not a handful — so instead of a 5-day-column grid, this renders weekday tabs (one day visible at a time) and, within a day, a genuine <table> whose columns are the groups taught in that shift and whose rows are stretches of time - see “A real time axis” below.

Column widths are fixed, not content-driven — deliberately. Each group column shares one identical CSS width (.o_guard_board_col_group) via an explicit <colgroup> combined with table-layout: fixed on the <table>; the Time block (first) column and each guard lane get their own fixed widths (.o_guard_board_col_time, .o_guard_board_col_lane). Two things this fixes, both found during manual review (2026-08-31):

  1. A first attempt used table-layout: auto with min-width/max-width hints instead — this let each shift’s table auto-size its own columns from its own content, so Morning and Afternoon (or one weekday vs. another) never lined up the same way, and one abnormally long cell (e.g. an unlinked “Pending teacher (email@…)” placeholder) could still noticeably skew a single column’s width relative to the rest.
  2. Auto-layout sizing also under-reported the table’s true rendered width to the wrapping <div>’s own scrollWidth calculation in practice, so the scrollbar existed but couldn’t actually be dragged all the way to reveal the last column. table-layout: fixed with <col>-defined widths removes that ambiguity — the table’s total width is the literal sum of the declared column widths, so overflow-x: auto always has an exact width to scroll against. Regression-tested in guard_duty_board_tour.js (scrolls the wrapper to its reported max and asserts the last header cell is then fully within the wrapper’s visible bounds).

Per-day toolbar (shift <select> + PDF button) sits right under the weekday tabs, so switching days always shows that day’s own controls — matches “one PDF per day” (below), not a single page-wide PDF button for the whole week.

Page layout: the root needs an explicit height, or neither scroll axis works at all. This is a plain ir.actions.client page (no <sheet>/form chrome to inherit sizing from), and Odoo’s own action container clips whatever the mounted component doesn’t explicitly claim — an early version’s bare, height-less root div meant a table taller (or wider) than the viewport was just cut off with no scrollbar on either axis (developer feedback, 2026-08-31), not a squeezed-but-scrollable one. Fixed the same way attendance_session_view.css’s .ems-av-root already does it: .o_guard_board gets height: 100%; display: flex; flex-direction: column, the title/tabs/toolbar sit in a fixed-height .o_guard_board_header, and only .o_guard_board_content (flex: 1 1 auto; overflow-y: auto) scrolls vertically — with .o_guard_board_table_wrap’s own overflow-x: auto still handling horizontal scroll inside that, so a vertical drag can never also scroll sideways. Both axes are regression-tested in guard_duty_board_tour.js the same way: scroll to the reported max, assert the true end (rightmost column / bottom row) is then actually visible.

PDF report (ems.report_guard_duty_board)

reports/attendance/report_guard_duty_board.xml — a qweb-pdf ir.actions.report on ems.course (not the removed ems.guard_duty_board). Not bound to the generic Print menu (no binding_type/binding_model_id) — triggered only from the client action’s own PDF button, same as ems.report_working_schedule/ems.report_group_schedule.

Landscape A3, not the site default (portrait A4). paperformat_id points at a new, reusable ems.paperformat_a3_landscape (report.paperformat, same file) — same margins/dpi/ css_margins as base Odoo’s own default paperformat_euro, only format/orientation differ. Needed because this board is wide (one column per group, easily a dozen or more): under the site-default portrait A4, every group column was cramped even after the fixed-width pass below. Landscape A4 alone (the first attempt, 2026-09-01) still felt too tight in practice per developer feedback after seeing it rendered — moved to A3 (420×297mm usable vs. A4’s 297×210mm) for real breathing room. Not named guard-duty-specific, since any future EMS report facing the same “wide grid” shape (a school-wide timetable, say) can reference this same paperformat record instead of each defining its own — verified by generating a real PDF against this dev DB’s own data at each step, same way the column-width bug below was originally caught.

One PDF per day AND per shift — not the whole week, not both shifts. onPdfClick() calls actionService.doAction("ems.action_report_guard_duty_board", { additionalContext: { active_ids: [this.state.courseId], guard_duty_weekday: String(this.state.activeDay), guard_duty_shift: this.state.activeShift } }) — the extra guard_duty_weekday/guard_duty_shift context keys are what scope the report down to whichever day tab and shift dropdown value were active. The template reads both via course.env.context.get(...) (there is no bare context name bound inside a QWeb report template — additionalContext merges into the calling env’s own context, which every record obtained from docs already carries) and loops just that one day/shift; if a key is absent (defensive fallback only — no other caller omits either) it falls back to all 5 weekdays and/or both shifts, one <div class="page"> per weekday (standard QWeb pagination). For whichever day(s)/shift(s) it renders, the template calls course.get_guard_duty_board_lines(weekday, shift, ...) directly (Python-side, unlike the client action’s own JSON RPC) and renders the very same grid the screen does (schedule_grid/ absence_grid, see “A real time axis” below: same stretches, rowspans, lanes and break blocks), with the subject acronym and every co-teacher. No colour anywhere, same as the live screen — see the “No cell colouring” note above for the full history (including the guard-duty badge itself losing its fill on a second developer pass the same day).

Column widths are fixed here too — <colgroup> + table-layout: fixed, mirroring the live screen (.gdb-col-time/.gdb-col-group/.gdb-col-guard: 85/115/160px, the last one per guard lane, and the absences table’s area columns width: auto, sized for A3 landscape’s own usable width — see the class comment in the template for the exact figure — not simply carried over from the live screen’s 90/130/190px, nor from the original A4-sized 60/75/110px attempt). A bigger page alone does not widen a table-layout: fixed table — found switching this report from A4 to A3 (2026-09-01, developer feedback: “sigue saliendo todo muy apretado” even after landscape A4): the paperformat change alone did nothing visible, because the <col> widths are absolute pixel values independent of the page they’re printed on — a bigger page just adds blank margin around the same-sized table unless the column widths are also widened to use the extra room. One thing the live screen didn’t need but the PDF did: overflow-wrap/word-break: break-word on every cell’s text spans (.gdb-cell-subject/.gdb-cell-teacher/.gdb-cell-room/.gdb-guard-badge). Confirmed by generating a real PDF against this dev DB’s own data (2026-08-31): without it, one long unbroken string (an unlinked “Pending teacher (email@…)” placeholder — no spaces to wrap at) still forced that one column — and, via border-collapse, every row sharing it — visibly wider than the rest, even under table-layout: fixed. With word-breaking allowed, the same content wraps onto multiple lines within its declared column width instead.

The PDF prints what the screen shows, absences included. The board’s PDF button passes guard_duty_date alongside the guard_duty_weekday/guard_duty_shift context keys it already sent, and the template forwards it to get_guard_duty_board_lines(..., day=...) and marks absent teachers with .gdb-absent/.gdb-absent-pending — the same two-state distinction, and the same single accent colour, as the live screen. A cuadrante handed out on paper to assign the day’s guards is no use without them. Omitting the key (any other caller) still prints the plain timetable.

The PDF prints whichever of the two tabs is on screen (issue #442). onPdfClick() also forwards guard_duty_view: this.state.activeView ('schedule' or 'table'), and the template reads it as requested_view (falsy/absent = 'schedule', same fallback convention as every other guard_duty_* context key here) to render schedule_grid or absence_grid. The absence line and the guard badges are sub-templates of their own (ems.report_guard_duty_board_absence, ems.report_guard_duty_board_guards, plus ems.report_guard_duty_board_break for a break block), shared by both views. The page’s own <h1> title also switches between “Guard Duty Schedule -“ and “Absences Table -“ so the printed heading never contradicts what’s actually below it.

A real time axis (issue #637)

The problem. Each area keeps its own time framework: on this centre’s data ESO/BTX have their break at 10:00-10:25 and 12:25-12:40, vocational training at 11:00-11:25 and 18:00-18:20, and their lessons start and end at different times. One row per period, with a shorter period folded into whichever longer one contained it (#410), mixed them up: the ESO break (10:00-10:25) folded into a VET lesson (10:00-11:00) and its break guards were listed against that lesson, as if they could cover it, while no break showed as such. The developer asked for a board “understandable without the level filters” (issue #637).

Framework periods never fold. _merge_absorbed_periods(periods, fixed=...) takes every period of every schedule framework of the shift (_get_guard_duty_board_framework_periods(): lessons and breaks) and never absorbs one of them: a level’s break is a block of its own. Only a teacher’s own shortened period (the #410 case, e.g. 13:25-14:00 inside 13:25-14:25) still folds. This is what fixes the guards: a break guard has its own line, so it is never offered against a lesson that merely spans its break.

flowchart TB
    LINES["lines (one per period, framework periods never folded)"] --> AXIS["BoardTimeGrid: rows = stretches between every start and end"]
    AXIS --> SCH["schedule(): one column per group (lesson blocks, one lane), its level's breaks as blocks"]
    AXIS --> ABSG["absences(): one column per area (absence blocks, lanes when they overlap), the area's breaks as blocks"]
    AXIS --> GL["guard lanes: one block per line with guards, side by side when they overlap; absences(): + fixed guard posts left without teacher"]
    SCH --> R["screen (guard_duty_board.xml) and PDF (report_guard_duty_board.xml) render the same grid"]
    ABSG --> R
    GL --> R

BoardTimeGrid (module-level class, models/attendance/guard_duty_board.py) lays both views out once, from the board’s lines, and get_guard_duty_board_lines() returns them as schedule_grid/absence_grid (passed through as-is to the JSON payload: only ints, strings and booleans). The screen and the PDF only render them - no layout logic on either side, so they can never disagree.

Columns grouped by area. get_guard_duty_board_lines() sorts groups by area name, then group name (groups with no area last), and returns areas ({group id: area}, _guard_duty_group_areas(): the top-level department above the department that manages the group’s study, or its main groups’ studies for a reinforcement group - the same ems.group.managing_department_ids that decides who organises its absences). The timetable heads each area’s groups with a band (grid['areas'], with its colspan) and draws a thicker rule between areas; the absences table has one column per area. A group whose study has no managing department falls under “Other groups”.

Why the layout lives on the server. The screen built it in JS at first; the PDF needed the same layout, and a second copy in QWeb/Python would have been the same logic twice (CLAUDE.md’s DRY rule). The client only resolves a slot’s line index against state.board.lines to reach the cell, guard or absence data it already renders (slotAbsences()), and keeps every interaction (clicks, popovers, dialogs) exactly as before.

Performance (issue #637). On this centre’s real timetable (~75 groups in the morning) the RPC took 1.6s in odoo shell (14-17s on the dev service, which runs under debugpy). Now ~0.15-0.2s cold, thanks to three rules applied throughout the file:

Area filter (issue #637)

Replaces the level filter (issue #390), which the timetable on a real time axis made unnecessary to read the board, but which planners still want to narrow it down to their own area. An area is a top-level department (hr.department.is_top_level) that manages some study, itself or through one of its departments (_get_guard_duty_board_area_records(); ASP manages none, so it is never offered). Areas map onto time frameworks on this centre’s data: ESO/BTX share one, every VET level another.

Client: state.activeAreaIds (empty = “All areas”) + state.areas (get_guard_duty_board_areas(), fetched once onWillStart), a Bootstrap dropdown with one checkbox per area (o_guard_board_area_dropdown/o_guard_board_area_menu; a native multi-<select> would need ctrl/cmd-click, which is not discoverable). Toggling a checkbox re-runs loadBoard(). The URL keeps the selection (?areas=...), and the PDF button forwards it as guard_duty_area_ids, which the report passes to get_guard_duty_board_lines(..., area_ids=...).

Area names: data/custom/hr.department.csv seeds the three areas in English only (a CSV row carries no translations, and data/custom is frozen after its first load). _translate_area_names() (__init__.py, from post_init_hook and migrations/18.0.0.38.0/post-migrate.py) adds Catalan and Spanish (ESO / BTX, FP, PAS) to an area still named as the CSV left it, for a language nobody has filled in yet.

Managing absences from the board (issues #539, #571, #581, #605)

The absences table is also where an absence gets organised, not just read. Three decisions are taken from it, all of them manually (nothing is ever sent or changed on its own):

  1. Send a guard to a class left without its teacher, with a message for them (#571).
  2. Tell the families that the students can come in later, leave earlier or have no classes, when the empty lessons are at the start or the end of the group’s day (#539). Once told, those lessons need no guard and are struck out (#581). A longer break is told to the students only and still needs a guard (#679, see “A longer break” below). Each kind of change can be switched off, and all of them are off by default (#679, see “Which changes the board may propose”).
  3. Apply an internal arrangement instead of a guard (#605, #645): the board detects how the teachers of the group (and of the groups sharing lessons with it) could swap or move their lessons, in chains, so that the students lose as few lessons as possible and nobody has to cover the class; anything else can be recorded by hand.
  4. Undo what an absence that changed afterwards made unnecessary or wrong: release a guard who is no longer needed, or send a correction for a notice that no longer matches (a sent notice can never be taken back).
flowchart TD
    ABS["hr.leave / ems.absence_pending<br/>(same intervals as the board)"] --> BLK["ems.course._get_group_day_blocks(day, groups)<br/>each group's whole day, block by block:<br/>teachers, who is away, covers, empty?"]
    COV["ems.absence_cover (state assigned)"] --> BLK
    CFG["res.company ems_absence_change_*<br/>(_enabled_absence_changes, per group)"] --> EXP
    BLK --> EXP["_allowed_absence_changes(blocks, breaks, enabled)<br/>every enabled late_entry / early_leave / no_classes / long_break option"]
    NOT["ems.notice with absence_changes<br/>(scheduled / sent / failed = communicated)"] --> ST
    EXP --> ST["_get_absence_change_states(day, groups)<br/>per side (entry/leave): expected vs communicated<br/>status: proposal / communicated / rectification"]
    ST --> MGT["_get_board_absence_management()<br/>covers + states + day's pending actions"]
    MGT --> ROWS["each absence row: cover, authorized, break_change, proposed, can_manage"]
    MGT --> ACT["actions: proposal / rectification / obsolete_cover"]
    ROWS --> UI["absences table: colours, strike-through, guard dialog"]
    ACT --> UI
    UI -->|"board_assign / board_release<br/>board_self_assign / board_self_release"| COV
    UI -->|"board_send_absence_change -> notice sent (draft form if it fails)"| NOT

Keyed by teacher, date, period and group - never by the absence record

ems.absence_cover (models/attendance/absence_coverage.py) stores the absent teacher, the date, the period (hour_from/hour_to, the board row’s own bounds), the group, the guard and the message; the timetable change lives on the ems.notice itself (absence_date, absence_group_id, absence_changes, models/communications/notice_absence_change.py). Neither points at an hr.leave or an ems.absence_pending. That is what makes a detected absence and the request the teacher files afterwards (which takes its place, see Detected absences) behave as one absence: whatever was organised on the detected one still matches the same teacher, date, period and group, so nothing is redone, and the days or hours the request adds come up as new, uncovered rows. Whatever the request no longer covers shows up as a pending action instead (below).

Which changes the board may propose (issue #679)

Three company settings (Settings > EMS Management > Guard Duty Board Settings, res.company ems_absence_change_late_entry, ems_absence_change_early_leave, ems_absence_change_long_break, all False by default) decide which kinds of change the board and the arrangement planner propose; no_classes goes with the late entry, being the start of the day stretched over all of it. A fourth one, ems_absence_change_level_ids (issue #718, many2many to ems.level, shown only while coming in later or leaving earlier is on), is an allowlist: late_entry, no_classes and early_leave (SHORTER_DAY_CHANGES) are only allowed for the groups whose level_id is listed, and an empty list allows them for no group. The level is what tells compulsory education (ESO) from the rest, whose students can never be sent home early, and a forgotten level must fail safe. long_break does not depend on it: the students stay in the centre. _enabled_absence_changes(groups) reads all four once per request into {group id: set of change types}, which _allowed_absence_changes(blocks, breaks, enabled[group]) filters _all_absence_changes() (the rules below) with; _arrangement_planner() passes the same dict to ArrangementPlanner. A disabled kind is simply never offered, so its empty lessons only get guards. What was already communicated keeps counting, and its correction (normal_*) is still offered if the absences change, whatever the setting is now: a notice already sent has to be put right.

Late entry, early leave, no classes

_get_group_day_blocks() reads each group’s whole day (both shifts: a group starts its day at its first lesson and ends it at its last), one block per period, merged the same way the board’s rows are. A block is empty when every teacher in it is away and no guard covers it: a co-teacher who is in, the other half of a split group, an optional subject with its own teacher or a guard already sent all mean somebody is with the students. _all_absence_changes() then lists, per side, every change the run of empty blocks allows, from the smallest to the largest: at the start of the day, starting at the hour_from of the 2nd, 3rd… block up to the first non-empty one; at the end, leaving at the hour_to of the block before the last, the one before that… up to the last non-empty one; a day with every block empty also allows no classes. The largest option is 'expected' (the dashed row tag and the default); the smaller ones exist because the planner may tell the families about only part of it and send a guard to the rest. Pending absences count as much as approved ones: the planner sees the state on the row and decides.

A longer break

_all_absence_changes(blocks, breaks) also gets the group’s level’s break periods for that weekday (_get_guard_duty_board_break_periods([level]); none for a group without a level). A break that falls between two of the group’s lessons is its own side (BoardBreakSide.key(), break@<from>-<to>), whose options are every ('long_break', start, end) combination of the break itself extended back over the empty lessons right before it and/or forward over those right after it - as long as a non-empty lesson remains further out on that side. A run of empty lessons that reaches the start or the end of the day is a late entry or an early leave instead, never a longer break, so “coming in after the break” and “going home at the break” stay what they are. A break change carries its span (('long_break', from, to) in the notice’s absence_changes); the correction back is ('normal_break', from, to). A free lesson in the middle of the day that is not next to a break is not proposed (developer decision, 2026-10-07): it is covered with a guard.

A longer break still needs a guard, and only the students are told (issue #679). The students under 18 cannot leave the centre, so during the lessons a longer break takes in they are in the playground and somebody has to watch them. _change_frees_guard() (a change that frees the group from the period and is not a long_break) is what decides “no guard needed”: in _get_needed_absence_block(), in a row’s authorized (which strikes it out) and in _plan_resolves(). A communicated longer break comes on the row as break_change instead: shown as a tag (o_guard_board_break_change_tag), but the row is not struck out and a guard can still be sent. Its notice goes to the students only and reminds those under 18 that they cannot leave the centre (see notice.md); a notice that also changes the entry or the leave goes to the families too, break included. A break proposal carries students_only (_board_action_data()), so the proposals box titles a group’s notice-only section Only tell the students when all of its proposals are breaks.

What was communicated, and the sides of the day

A change belongs to one side of the day: late_entry, no_classes and normal_entry to the start, early_leave and normal_leave to the end (CHANGE_SIDES), long_break and normal_break to the break they overlap (_change_side()).

A notice can tell several changes, at most one per side (#652: an accepted arrangement plan sends one notice per group with every change it brings). They are stored on the notice as a JSON list, absence_changes, each change as the same tuple the options use ([type, hour], or [type, from, to] for a break), in the order of the day (start, breaks, end); _absence_change_tuples() reads them back. A JSON list rather than a child model, like the students’ notice’s arrangement_lessons (#649): the changes are only ever written with their notice and read with it, never searched on their own, and a list needs no access rules of its own to stay in step with the notice’s three levels of access (a child model would need its own copy of every rule_notice_*). The form shows them in one line (absence_change_label, _absence_changes_label()). Notices created before #652 had one change in three columns of their own; migration 18.0.0.38.1 (post-migrate.py) moved each one into a one-item list.

Per side, _get_absence_change_states() reads every change of the day’s notices once, oldest notice first, and compares the allowed options with the change on that side of the latest notice that left the draft state (COMMUNICATED_NOTICE_STATES: a scheduled notice is on its way, a failed one reached at least part of its recipients). The normal_* types are the correction back to the usual timetable, so they communicate “no change”. A correction is always about one side: a rectification of a notice that told several changes is a new notice with one change, the other sides keeping what was told.

Allowed options Communicated Status Options offered
none none - -
some none proposal every allowed option, the largest by default
any one of the allowed options communicated - (its rows struck out); change_options until its time comes (#659, below)
any anything else rectification every allowed option and normal_<side>, the largest allowed (or normal) by default

Communicating a smaller option than the largest is the planner’s decision and is never nagged about: the lessons beyond it simply stay on the table to be covered. Likewise, an absence that grows after the notice keeps the notice valid - the new lesson is one more to cover. Only telling the families more than the absences now allow (they shrank, were refused or cancelled, or the timetable changed) asks for a correction. Telling the families goes through the “Only tell the families” steps (board_apply_plan(), see “Pending actions”), or, for one change chosen in the Change proposal dialog (#659, below), through board_send_absence_change(), which prepares the notice (_board_absence_change_draft()) and sends it at once (#652), with the same fallback as an accepted plan: one that cannot be sent stays a draft and opens with the reason. Both accept any option of the side’s current state (_find_change_state(), over options + change_options) and refuse anything else. A draft notice for one of the options ('draft', the option being 'draft_change') gets an Open draft button on its step; applying the step again replaces it. Rows whose period falls inside the communicated window (_change_window_contains) carry authorized and are struck out; rows inside an expected window nobody has communicated yet carry proposed, shown as a dashed tag.

Only changes still to come are offered (issue #599). On the board’s own day, an option whose time has come (_change_start(): the hour a late entry, early leave or longer break starts; the group’s first lesson for no_classes/normal_entry; its last one for normal_leave) is dropped from options before anything else (_change_deadline(), issue #744: an early leave stays on offer until the class it frees ends, since the teacher of the last class may leave once it has started), so expected, the row tags and the box only ever show what can still reach the families in time; with nothing left, the side has no status. A communicated change whose time has come is settled (communicated, no correction proposed): a correction would arrive too late. _board_day_hour() gives the company-time hour of day (None for a day still to come, so nothing is dropped; past every lesson for a day already over), and since _board_absence_change_draft() validates against the same states, it refuses an option that went past while the board stayed open.

Changing a communicated change (issue #659)

A communicated change still allowed is the planner’s decision, but they may change their mind (a guard turns out to be free, they would rather rearrange the lessons than lengthen the break). Until its time comes, its state carries change_options: every allowed option except the one told, and normal_<side> last. Every row it strikes out carries change_side (the side’s key) when there is something to change it for, and the board shows a Change proposal button on it to whoever can manage the row (also offered from the row’s reason popover). It opens GuardChangeProposalDialog (static/src/js/backend/guard_change_proposal_dialog.js), fed by ems.course.get_change_proposal_options(day, group_id, side) (same manager and past-day checks as every board action), which returns:

“As if nothing had been told” is the ems_reopen_side context key (_reopened_side()): the planner builds that side’s communicated as None, so its lessons are gaps it can fill and its notices can change; _get_needed_absence_block() ignores that side’s window, so a swap can be applied to a lesson the families were told the students skip; board_apply_plan(reopen=...) re-enters itself with the key set. The states themselves are never reopened: what the families were told is still what they were told until the correction goes out.

Corrections are steps of a plan (kind correction, after every other step), built by _arrangement_plan_records() from the planner’s per-group notices (raw['notices'], before they are grouped into one step per change) and the groups’ states, which _arrangement_planner() returns along with the planner:

Deciding this per group, before grouping, is what keeps a notice for several groups intact for the others with no step to split or renumber.

board_apply_plan() gathers notices and corrections per group, looks each change up in the group’s options + change_options (refusing it when it is in neither), and creates one notice per group, a correction when any of its changes is on a side already told.

Guard assignment

board_assign() re-validates everything on the server: the user manages the absent teacher, the day is not over, the class still needs a guard (_get_needed_absence_block(): the teacher is away then, it is not co-taught, and it is outside every communicated window) and the guard is a candidate (_get_guard_candidates(), see below). Assigning someone else releases the previous guard of the part they cover; assigning the same guard again updates the message and re-sends it. One assigned guard per part of a class (_check_one_guard_per_class refuses two overlapping covers), but one guard can cover several classes.

Partial covers (issue #637). With areas on different time frameworks, a guard’s duty may only overlap part of a class (an ESO 10:25-11:25 lesson against a VET 10:00-11:00 guard). _guard_spans() gives each candidate the part they would cover: their regular guard duty (a WC or break guard is needed where they are, see “Guard duties that are not regular”) clipped to the class, consecutive duties joined, the longest piece otherwise, dropping a guard away or with a group through an internal arrangement during it. It runs no query: the board calls it once per line with the shift’s regular guard rows, absence intervals and covers it already holds (line['guard_spans']), and _get_guard_candidates() wraps it for the board actions with its own SQL-filtered search. board_assign() creates the cover for that part only (the server recomputes it, never trusting the client) and only withdraws the covers overlapping it, so several guards can each cover part of one class. A row carries covers (sorted) and missing (_uncovered_periods(), empty without any cover); it is resolved, struck out, only once nothing is missing, and arrangement options are only offered while no guard covers any of it. The dialog lists the whole-class candidates first, then the partial ones with their part, and every current cover with its own “Remove assignment”.

The guard is told through message_notify() on the cover (Odoo inbox or email, per their own notification preference), in their own language, with the date, time, group, subject, room, absent teacher and the planner’s message. board_release() sends the matching “no longer needed” message.

Covers per guard (issue #600)

So whoever plans the guards can share the covers out fairly, every guard in get_guard_duty_board_data() (lines[].guards) and every candidate (lines[].guard_candidates) carries cover_count: how many times that teacher has been sent to cover during the current course. _guard_cover_counts(guards) counts it in one _read_group over ems.absence_cover, for every guard of the shown day and shift, grouped by guard, day, room and period: covers of one guard in the same room in the same period of the same day count once (issue #629), since two groups put together in one room are a single guard, while two groups in two rooms are two, and so are two periods in a row with the same group. A cover with no room (a guard duty, a class with none on the timetable) always counts by itself. What counts: state = 'assigned' only (a released cover was never done), date within the course’s date_range(), covers already planned for a coming day included (an assignment for tomorrow is work already given to that guard, and assigning one makes the number go up straight away). Every teacher reads the board, and ems.absence_cover is readable to them, so no sudo() is needed. The screen shows it as a small number after the name on both views’ guard badges (.o_guard_board_guard_count, plain like the WC tag) and in the guard dialog’s options ("Name (N covered this course)"). The PDF does not print it: it is a planning aid, not part of the timetable posted on the wall.

Guard duties that are not regular (issue #606)

Not every guard duty is the same: a regular guard (G) waits to be sent wherever needed, while a WC or break guard (GWC, GB) is a post that must be manned. ems.non_teaching_type.is_regular_guard (seeded True only on G, data-driven like is_guard) tells them apart, and decides two things:

ems.absence_cover therefore covers either a class (group_id) or a guard duty (duty_id), exactly one of the two (class_or_duty SQL constraint; both ondelete='restrict', as the former required group_id was). Its display_name is the group’s or the duty’s name, which the guard’s notification, the release action’s label and the dialog’s title use. The duty-specific parts:

Self-assignment

A teacher on guard duty may take a class still left without anybody themselves (#601), without being in the absent teacher’s chain of command: board_self_assign() runs the same checks as board_assign() (_check_board_assignable(): day not over, class still needed, the current user’s employee a guard candidate) and also refuses a class whose part the guard would cover already has a guard - changing someone else’s assignment stays with the planner. A guard whose duty only overlaps part of the class takes that part (issue #637). Nobody is notified: the board shows it. The cover’s assigned_by_id is the guard’s own user, which is what is_self_assigned (non-stored) reads. board_self_release() lets that same user leave it again, silently, and only a cover they took themselves: one a planner sent them to is the planner’s to release. The planner can still change or release a self-assigned guard as any other. The board sends can_self_assign (the user is a candidate in the row and their part is free and editable), self_label (that part) and self_cover_id (the cover they took themselves, to leave it) per absence row; a manager’s own dialog takes precedence when both apply. A row still to be covered that the user can do nothing about on an editable day (the board’s editable), because they have no guard duty there (self_label empty), answers the pointer too, saying so (notOnGuardReason(), #659): every row of the table reacts the same way.

Sending a guard as support (issue #725)

A guard on duty can also be sent to a class whose teacher is there, to support them (a restless group, a practical that needs two people). Nothing is left to cover: the guard is simply busy with that class, like a teacher an arrangement has with a group.

It is an ems.absence_cover with cover_type = 'support': absent_employee_id is the teacher supported (who is not away), group_id the group, guard_employee_id the guard, hour_from/ hour_to the part of the class the guard’s regular duty overlaps (as for a partial cover, issue #637), subject and room the teacher’s own lesson. Reusing the model gives it the guard’s notification, the release, the live board refresh (#692) and the course’s cover count (#600) for free; every place that matches covers against absences leaves supports out.

flowchart LR
    BADGE["Guard badge, absences table<br/>(can_support)"] --> OPT["ems.absence_cover.get_support_options(day, from, to, guard)<br/>-> ems.course._get_support_options()"]
    OPT --> DLG["GuardSupportDialog<br/>class + message / current support"]
    DLG -->|board_support| COV["ems.absence_cover<br/>cover_type = support"]
    DLG -->|board_release| COV
    COV --> BUSY["_arrangement_busy(): guard busy<br/>(struck out, not a candidate)"]
    COV --> CELL["_board_cell_arrangements(): 'supports'<br/>(timetable + PDF)"]
    COV --> COUNT["_guard_cover_counts()"]

Internal arrangements (#605, #645)

The other way of resolving a class: no guard is sent because the teachers rearrange themselves. The board detects the arrangements the timetable allows and proposes them as plans: short chains of steps that can be applied whole or in part. What it cannot work out is recorded by hand.

Step / arrangement_type What happens Notice to the families
swap Another teacher B of the group, free now, teaches now; the absent teacher A teaches B’s lesson with the group later that day No
move A teacher B, free now, brings one of their lessons with the group into the gap; the lesson they leave is a new gap, which another step can fill Only when the last gap is left free (start or end of the day, or next to a break)
join (#660) A teacher teaching the same subject to the other half of a split group then brings their lesson with this half from another hour: both halves are taught together, in the other half’s room; the lesson left is a new gap, as in a move As in a move
notice The families are told the group comes in later, leaves earlier or has a longer break It is the notice
manual Anything else, described by hand (two groups joined for the same subject, a teacher of another group…), with the teacher involved if any No

An example of a chain: a teacher teaching two groups together is away at the first lesson of their afternoon and at the one before last. Each group’s teacher of the next two hours, on guard during the first one, brings their lessons forward; a teacher on guard right after them brings in the last lesson of the day, which they teach both groups; both groups leave one lesson earlier. No guard, one notice per group.

Co-teaching: a lesson moves with all its teachers (#678)

The teachers who give a lesson together (the same group or groups at the same time, whatever the subject or room) are a pack: a move or a swap takes the lesson with all of them, never with one while the other stays behind teaching a lesson that is no longer there. ems.course._arrangement_sessions(context) builds, once per board load, every lesson of the day with its teachers and those of them away then: (lesson, group ids, teacher ids, away ids).

Finding the plans (ArrangementPlanner, models/attendance/arrangement_planner.py)

Teachers another area organises (fixed, issue #721) are never moved, see “Teachers of another area” below.

A plain Python class, like BoardTimeGrid: no query, so it can try many combinations. ems.course._arrangement_planner(context, groups) feeds it what _arrangement_context() already read once per board load (the weekday’s timetable, indexed by teacher; absences; covers), and returns it with the groups’ timetable-change states it was built from.

Measured on a real centre’s timetable (odoo shell, cold): ~55 ms for the plans of two linked groups, ~0.3 s for both shifts of the whole board.

_arrangement_plan_records() turns a plan into records, its steps ordered by time (never before a step they need), one notice step per change told to every group it applies to, and each teacher’s entry/exit changes on their last step. _arrangement_plan_data() is its JSON: “Proposal N:”, one sentence per step, depends (indexes) and the payload the server needs to apply it, plus schedule_changes (the entry/exit sentences) and schedule_teachers (whose). A move, join or swap reads as one short line, “Ferran: 13:00 lesson → 10:00 (AIX1A and AIX1B)” or “Sergi and Carla swap their 08:00 and 11:00 lessons (AIX1A)” (_arrangement_step_label()), with grey details lines under it saying what kind of move it is for each teacher (#709): _arrangement_step_how() sorts them into a swap with their regular guard or another non-teaching hour, a join, a shifted day (their entry and exit both change) or a free hour, and _arrangement_step_details() words them, naming the teachers only when a co-taught step mixes kinds. A teacher’s timetable cannot be changed without them (#709): when the checked steps carry any entry/exit change, the board’s applyPlan() asks first “Have you talked to …?” (Working day changes), and applies nothing if the planner answers “Not yet” (the dialog the plan came from stays open).

Joining the two halves of a split group (#660)

A join is a move whose target is not a free hour of the teacher but one where they are already teaching the same subject to the other half of a split group: that half is joined to it, and the lesson the teacher had with it at another hour is left free, exactly as a moved lesson leaves it (a notice can then free the group from it: typically both halves leave an hour earlier, each told by its own notice when its own day changes; the half that only receives the other one is told nothing).

The same-hour split (both halves at once with two teachers, one away) is not a join: nothing is left free.

Where they show

Only to whoever may organise the absence (can_manage) and only for a class still left without anybody (_board_row_arrangement_plans()): on every row a plan resolves (_plan_resolves(): a step fills it, or one of its notices frees the group from it) - as a tag and at the top of its dialog - and once per plan in the “Proposals for the absences” box, under its groups’ section (_arrangement_plan_actions(), action type arrangement_plan; see “Pending actions”). Each plan is a block: its title and, indented below it, one line per step with its checkbox on the left (GuardArrangementPlan, static/src/js/backend/guard_arrangement_plan.js), all checked by default. Unchecking a step unchecks those that need it, checking one checks what it needs (toggledPlanSelection()). In the box, a plan’s Apply the checked steps button sits on the right (.o_guard_board_plan_actions), in the same column as the buttons of the proposal rows: every action button of the boxes above the table shares one width (.o_guard_board_action_button, guard_duty_board.css), so they line up whatever their label.

Applying (ems.absence_cover.board_apply_plan(day, steps))

steps are the checked steps’ payloads, in the plan’s order. The server builds the planner again for the day as it is now and checks the subset (ArrangementPlanner.check()): each step still possible with the earlier ones applied, each notice one of the changes the resulting day allows on a side nobody was told about. So a stale screen, or a step kept without one it needs, is refused. It also works out what the checked steps still leave to a guard (ArrangementPlanner.gaps(), #710) and returns it as gaps ({'group_id', 'hour_from', 'hour_to'}): once the board reloads, it opens the guard dialog of each of those classes in turn, offering only “Send a guard teacher” (openGapCovers(), GuardCoverDialog’s guardOnly: no other proposal, which could also open its own gaps’ dialogs on top of the queue), skipping one not on the shift shown or already covered. Not when a notice could not be sent: its draft opens instead. Then:

Telling the students which lessons change time (#649)

A move or a swap changes when the group has a subject, which the families’ notice (only about when the group starts or finishes) never says. So every swap and every move, in effect or still waiting for the families’ notice, is told to the group’s students only, in an ems.notice of its own (models/communications/notice_arrangement.py), separate from the families’ one since its recipients are different:

A lesson moved without a notice is a class to cover

A move whose lesson is not freed by a notice leaves the group without anybody then. _board_cell_arrangements() returns those teachers as freed ({teacher: cover}), and get_guard_duty_board_lines() gives them a row of their own: state = 'moved' (red, not bold: they are not away), the tag “Lesson moved to HH:MM” (moved; the PDF prints it too). The row is managed like any other: a guard, a manual arrangement, or another plan - which is how a planner who kept only part of a plan, or who changes their mind later, carries on. _get_needed_absence_block() already treats a moved teacher as away.

Who manages it (_original_absent()): the teacher whose lesson moved is not the absence; the class really comes from the absent teacher whose gap the move filled (along the whole chain). Row can_manage, pending actions and every board action (board_assign, board_arrange, board_release, board_apply_plan) check the managers of that teacher (_check_cover_manager()).

A shared lesson moved for several groups

One decision, several covers (one per group). _with_siblings() finds the others: same date, same teacher, overlapping lesson left free and overlapping gap. Withdrawing one (_board_withdraw()) withdraws them all, and _is_cover_still_needed() finds the remaining ones no longer valid if one of the lesson’s groups lost its cover (its draft notice was deleted, say). Each group’s cover follows its own notice: the families of each group are told separately.

What the board shows once an arrangement is in effect

Pending actions

_get_board_absence_management() lists the day’s decisions that belong to no single row, shown above the table in two boxes, and only sent to whoever can act on them (can_manage: to any other teacher they are noise, and the struck-out rows already say what was decided):

Nothing is released or sent until the planner presses the button; doing it automatically, behind a setting, is planned in plans/absence_management_automation.md.

Colours

_board_cover_colors(lines, guard_covers) gives colour indexes (COVER_COLOR_COUNT = 8) once for the whole shift, not per line (issue #637): a guard can cover part of a class on another line than their own guard block, and both must match. Each line carries that shift-wide map as line['cover_colors'], read by the absence rows and their guard tags. A guard’s badge in the Guard duty column only takes the colour in the blocks where they cover something (line['guard_colors'], issue #675): on guard 10-12 and sent to a 10-11 class, their 11-12 badge stays plain. _board_guard_covers(lines) (what each guard covers, and whether it is partial) is computed once and feeds both. The colour belongs to the class covered (developer decision): every guard covering one class shares it, and a guard covering several classes joins them under one colour, since their badge can only have one (a union-find over classes and guards). Groups are coloured in time order, greedily: a group never takes the colour of another overlapping it in time - their classes, or the guard blocks their badges show the colour in -, while one overlapping nobody may reuse a colour, so the palette only runs short with more groups at the same time than colours. The screen uses o_guard_board_cover_N, the PDF gdb-cover-N, with the same palette. This is the board’s one deliberate use of background colour (see “No cell colouring” above): it pairs two things the planner must match at a glance, which plain text can’t do.

Whole or partial: the border. On top of the colour, a solid bar means a whole class covered and a thin dotted one a partial cover (o_guard_board_cover_partial/gdb-cover-partial): on the row while a part is still missing, on a guard’s tag when their cover is partial, and on a guard’s badge when any of their covers overlapping that block is (line['partial_guard_ids']). Dotted and 2px rather than dashed: a 4px dashed bar draws as big blocks (developer feedback).

Who can manage

_is_absence_manager(employee, group=None): whoever answers for the students who lose the class, or for the teacher who is away (issue #622). Both sides add up; nothing takes a right away.

flowchart TD
    Q["_is_absence_manager(employee, group)"] --> ADM{"administrator?"}
    ADM -->|yes| YES["can manage"]
    ADM -->|no| SELF{"the absent teacher themselves?"}
    SELF -->|yes| NO["cannot"]
    SELF -->|no| GRP{"user in group._absence_manager_users()?<br/>(chiefs of the departments managing the group's study,<br/>of every department/area above them, and the Director)"}
    GRP -->|yes| YES
    GRP -->|"no, or no group (a guard duty)"| CHAIN{"the teacher's side:<br/>chain of command (tutor_scope_user_ids),<br/>chiefs of their own department (#604),<br/>chiefs of employee.managing_department_ids"}
    CHAIN -->|yes| YES
    CHAIN -->|no| NO

Never every holder of those roles centre-wide, and never the absent teacher. The administrator (base.group_system or ems.group_academic_admin) always can: they sit above Direction although, not being a teacher, they appear nowhere in the hierarchy. A timetable change concerns several teachers at once; any of their managers for that group may act on it. Every teacher still sees who covers what and what was communicated; rows only offer their click to whoever may use them (can_manage, resolved per teacher and group), the action boxes only reach them, and the server checks again. Restricting who may act (e.g. only the Head of Studies in ESO/BTX) is issue #602.

ems.study.managing_department_id is edited on the study’s form (the administrator only, like the rest of the study). Existing installations got it from migration 18.0.0.36.2, new ones from post_init_hook, both through ems.study._backfill_managing_department(): the department whose teachers give more than half of the study’s groups’ classes (ems.teaching), which matches how the vocational families work and leaves ESO/BTX blank.

Action Any teacher Whoever manages the class (above)
See assigned guards, colours, struck rows, pending actions Yes Yes
Assign / change / release a guard (board_assign, board_release) No Yes
Take a free class themselves / leave one they took (board_self_assign, board_self_release) Only a guard on duty then Same
See and apply detected arrangements, record a manual one, remove one (board_arrange, board_release) No Yes
Send a timetable change or correction (board_send_absence_change) No Yes
Send that notice No Yes (own notice)
Check in a teacher who has not (board_mark_present, issue #692) Only a guard on duty then Yes
Send a guard on duty as support to a teacher who is in, remove it (board_support, board_release, issue #725) No Yes (for that teacher’s class, and a guard of their area)

Department and Seminar chiefs use Communications > Notices limited to the groups their department teaches or manages (see the access table in notice.md); a timetable-change notice is one of those. _check_absence_change_recipients keeps it addressed to its own group’s students and families, and the form locks its groups; _check_arrangement_recipients does the same for the notice to the students about moved lessons (#649), which the user who applies the arrangement creates and sends too. Accepting a plan or a swap sends both notices as that user (#652): a department chief sends the notices of the groups they manage, and one they may not send (someone else’s draft reused, say) simply stays a draft. ems.absence_cover is read-only to every teacher (ems.access_ems_absence_cover_teacher): every write goes through the board methods above, which check who manages the class and then write with sudo().

Teachers of another area (issue #721)

Who may organise an absence (above) says nothing about whose day an arrangement may change. Some teachers are shared between areas (an ESO/BTX teacher with lessons in VET groups), and an area that organises its guards outside the board (ESO/BTX) would otherwise lose them without knowing: the board treats a regular guard as free (#709), so a VET chief could take an ESO teacher’s VET lesson to the hour of their ESO guard. ems.course._can_move_teacher(teacher, context=None) decides it from who is deciding, whatever group the class is of, so it works both ways:

flowchart TD
    Q["_can_move_teacher(teacher)"] --> ALL{"Direction or administrator?"}
    ALL -->|yes| YES["may move / send"]
    ALL -->|no| NONE{"teacher has an area?"}
    NONE -->|no| YES
    NONE -->|yes| SHARE{"teacher's areas (own department +<br/>Also managed by) ∩ user's areas<br/>(departments chiefed + own department)"}
    SHARE -->|not empty| YES
    SHARE -->|empty| NO["cannot"]

Where it applies:

Path Effect
Detected swaps (_get_arrangement_options) Not offered if an absent teacher who would teach the other lesson cannot be moved; a co-teacher who cannot be moved stays at the lesson (stays)
Moves and joins (ArrangementPlanner, fixed) busy() is always true for them: no step takes a lesson of theirs anywhere; a co-teacher among them stays on guard, with the reason 'area' (“organised by another area”)
Applying (board_apply_plan, board_arrange) Re-planned on the server as the user, so a stale screen cannot apply it
Manual arrangement (get_arrangement_candidates, board_arrange) Not listed; naming them raises a UserError
Sending a guard (guard_candidates of each line, board_assign) Not listed; sending them raises a UserError (_check_board_assignable)
Self-assignment (board_self_assign) Unaffected: the guard decides for themselves, and their own area is theirs

The answers are cached per board load in the arrangement context (or a plain dict for the guard candidates), so the check costs a few queries per load (measured on this box’s data: at most 15 ms of a 0.43 s afternoon load).

Dates

The day comes from the board (a calendar date); the server refuses to manage a day before ems.datetime_utils.get_local_today() - what is over is over.

Teachers who have not checked in (issue #692)

A guard on regular duty who has not checked in is checked in the same way from their badge in the guard column (issue #725): board_mark_present() with neither a group nor a duty means their regular guard duty in the period, with the same checks (_can_mark_present(), today, in progress, still not checked in). The badge carries can_mark_present for the user (on guard in that line, or managing the guard, never the guard themselves); the dialog is the same GuardUncheckedDialog, worded for a guard (“They are in the centre”).

A class whose teacher has not checked in is left without anybody as surely as an absent teacher’s, so from the moment it starts it is on the absences table, to be covered with a guard. Whoever is on guard then, or manages the absence, can also say the teacher is in the classroom after all, which checks them in.

flowchart TD
    ATT["hr.attendance._ems_first_check_in_hours(day, employees)<br/>first real check_in of today, per employee (one _read_group)"] --> UI["_get_unchecked_intervals(day, employees)<br/>{employee: (now, arrival, 'unchecked')}"]
    UI -->|"unchecked=True only"| INT["_get_guard_duty_absence_intervals"]
    INT --> ST["_guard_duty_absence_state<br/>approved > pending > unchecked"]
    ST --> ROWS["board rows, guard column, guard candidates,<br/>_get_group_day_blocks (assign / obsolete cover)"]
    ROWS -->|"row in progress, can_mark_present"| MP["ems.absence_cover.board_mark_present<br/>hr.attendance sudo create, ems_checked_in_by_id"]
    MP --> MSG["_notify_checked_in_by(): message to the teacher"]

The rule. _get_unchecked_intervals() only answers for today (get_local_today()), with one query: the first check-in of each employee that company day (hr.attendance._ems_first_check_in_hours(), shared with the detected absences, which turn what is still missing into an absence once the day is over; technical attendances are no presence). Its interval is not an overlap like an absence’s but (now, arrival): a period counts as unchecked when it has started (hour_from <= now) and the teacher had not arrived before it ended (hour_to <= arrival, arrival = 24.0 without a check-in). Checking in at 10:05 clears the 10-11 class and the next ones, while the 8-9 one stays: a guard sent to it was the right decision and must not turn into a “no longer needed” action. _guard_duty_absence_state() applies that test to 'unchecked' intervals and ranks it below an absence: an approved or pending one on the same period wins.

Who sees it, who doesn’t. _get_guard_duty_absence_intervals(..., unchecked=True) is passed only by the guard side of the board: its own lines (classes and the guard column), _get_group_day_blocks (so board_assign, _get_needed_absence_block and the obsolete-cover action treat it like an absence), _get_needed_duty_entry (a WC or break guard not checked in is a post to cover, issue #606) and _get_guard_candidates (a guard not checked in cannot be sent). A teacher who has not checked in may still be in the building, so nothing else reacts to it:

“The teacher is in the classroom”. board_mark_present(day, hour_from, hour_to, absent, group_id | duty_id) checks that the current user may (_can_mark_present: _is_absence_manager(), which already covers the chain of command, Direction and the administrator, or a guard duty of their own overlapping the period, _is_on_guard), then that the class is going on now and the teacher is still unchecked (_is_unchecked_in_progress). A class already over is refused: checking the teacher in at this hour would not take it off the table. The check-in is created with sudo(), check_in = fields.Datetime.now() (naive UTC without microseconds, as _auto_checkin_teacher does, for last_attendance_id), in_mode='manual' and ems_checked_in_by_id = the user, its own field since create_uid would be the superuser. The attendance form shows it when set (the list does not), and hr.attendance._notify_checked_in_by() tells the teacher in their language, with the time in the company’s timezone. The board sends can_mark_present per row: the row is 'unchecked', its line is in progress (_in_progress) and the user manages it or is among the line’s guards.

On screen the row shows the name in red with a dotted underline and the tag “Not checked in” (the PDF prints the tag too). Clicking a row with can_mark_present opens GuardUncheckedDialog (guard_unchecked_dialog.js): “They are in the classroom” and, when the user can, the usual next step (send a guard, cover it themselves, stop covering it). Both “They are in the classroom” and “Cover it myself” act straight away: choosing them in the dialog is the confirmation, so “Cover it myself” calls selfAssign() directly instead of confirmSelfAssign(), the confirmation a plain click on a free line still asks for (there the click is the only step).

Live updates, only when something changes. The board never polls. It reloads in two cases:

Client side (guard_duty_board.js): onBoardChanged only reacts to the day on screen, and requestRefresh groups a burst of messages (applying a plan writes several covers) into one reload after 500 ms. The reload has no spinner, keeps the planner’s checked steps and only replaces state.board when the JSON differs. It waits (stays pending) while a load is running, the tab is hidden, or a dialog or a popover (not a tooltip) is open, and runs as soon as that ends: every dialog and popover the board opens goes through addDialog/addPopover, whose onClose flushes it, and so does visibilitychange. A result for another day, shift or area than the one now on screen is dropped. The current-time line keeps its own once-a-minute timer, independent of all this.

Cost: nothing while nothing changes. Each reload costs the same as opening the board, measured on the dev database (2026-10-22, odoo shell, cold) at 0.15-0.24 s, the extra check-in query included (0.06 s for every employee of the centre).

Public holidays (issue #740)

On a public holiday (a resource.calendar.leaves with no resource_id, entered under Absences > Configuration > Public Holidays) nobody is expected, so nobody is missing and there is nothing to organise. resource.calendar.leaves._ems_public_holiday_on(day) (models/employees/public_holiday.py) returns the holiday touching that company day, or an empty recordset: one sudo() search with limit=1, the day’s bounds computed in the company’s timezone. It is shared with the detected absences (ems.absence_pending._ems_detect_missing_check_ins), which create nothing on such a day.

flowchart TD
    H["_ems_public_holiday_on(day)"] -->|holiday| L["get_guard_duty_board_lines(): day = None<br/>(the plain timetable: no absences, no 'unchecked',<br/>no absences-table rows, no actions); 'holiday' = its name"]
    L --> D["get_guard_duty_board_data(): editable = False,<br/>no 'now' line; 'holiday' to the client"]
    D --> UI["guard_duty_board.js/xml: .o_guard_board_holiday notice,<br/>absences table hidden, timetable kept"]
    L --> PDF["report_guard_duty_board: .gdb-holiday notice,<br/>absences table not printed"]
    H -->|holiday| CHK["_check_board_day_open(day): UserError<br/>(every board action goes through it)"]
    H -->|holiday| DET["_ems_detect_missing_check_ins(day): nothing detected"]