EMS

Technical Reference: ems.attendance_correction

Overview

ems.attendance_correction lets an employee request a correction of the check-in and/or check-out time on one of their own hr.attendance records (the native Odoo employee attendance model). The request is routed automatically to the nearest ancestor in the employee’s manager chain who holds the Head of Studies (or Deputy Head of Studies) security group, and stays pending until that approver accepts (patching the attendance) or rejects it (leaving the attendance untouched). The requester is notified either way.

Module file: models/attendance/attendance_correction.py


Data Model

Fields

Field Type Required Stored Description
attendance_id Many2one → hr.attendance Yes, unless absence_pending_id Yes The attendance record being corrected. Empty for a teacher’s request about a detected absence’s day with no attendance: accepting it creates one and sets it here
absence_pending_id Many2one → ems.absence_pending No Yes The detected absence the teacher answers with this request (issue #735, see absence.md)
employee_id Many2one → hr.employee (computed) — Yes attendance_id.employee_id, or the detected absence’s teacher
original_check_in Datetime (snapshotted at create()) — Yes attendance_id.check_in at the time the request was made — not related, so it survives action_accept() overwriting the attendance
original_check_out Datetime (snapshotted at create()) — Yes attendance_id.check_out at the time the request was made, same reasoning
requested_check_in Float (ems_time_of_day widget) No Yes Desired new check-in time of day (optional) — the date is not editable, see below
requested_check_out Float (ems_time_of_day widget) No Yes Desired new check-out time of day (optional) — the date is not editable, see below
reason Text Yes Yes Why the correction is needed
state Selection Yes Yes pending / accepted / rejected
approver_id Many2one → res.users No Yes Stamped on decision
decision_date Datetime No Yes Stamped on decision
decision_note Text No Yes Optional note left by the approver
is_check_out_requestable Boolean (computed) — No False while the attendance is still open (no check_out yet) and the employee is still within their expected working hours for that day; drives whether requested_check_out is shown in the form

At least one of requested_check_in / requested_check_out is enforced both at the Python level (@api.constrains) and at the DB level (_sql_constraints), and both must be times of the day (0-24). ems_time_of_day reads 9.15, 9,15, 9h15 and 915 as 9:15, where float_time would read decimal hours (issue #735). A request about a detected absence’s day without attendance, or about the technical attendance Odoo leaves on a day without check-in (original_technical), needs both times, in order (_check_attendance_or_absence). Every request about a day with an unresolved detected absence answers it (absence_pending_id, also when asked for from the attendance itself): rejecting the request, or rejecting it after accepting it (_undo(): the attendance restored, or deleted if the request recorded it), sends that detected absence back to the review (see absence.md). A pending request is withdrawn on its own (_withdraw()) when the teacher files the absence of that day instead.

Time-only correction: a teacher can only request a different time of day, not a different date — the date is always taken from the original hr.attendance record. _combine_date_and_time() converts the original check_in/check_out (UTC) to the company’s local timezone via ems.datetime_utils.utc_datetime_to_local(), keeps its .date(), and combines it with the requested float time via time_float_to_utc_datetime() (same mixin, reused rather than re-implemented — see the ems.attendance_template/attendance_schedule cron code for the other consumer of this helper). If check_out isn’t set yet (still clocked in) and a check-out time is requested, check_in’s date is used instead since there is no original check-out to anchor to.

Check-out hidden while still clocked in and still on schedule: is_check_out_requestable (_is_check_out_requestable_for()) hides requested_check_out from the form (invisible="not is_check_out_requestable") whenever the attendance has a check_in but no check_out yet and “now” is still before the end of the employee’s last expected working interval for that day, resolved via hr.attendance._get_last_working_hour() (models/employees/employee_autocheckout.py — the same helper the auto-checkout cron uses, which already subtracts approved absences and handles split shifts). A day nothing was expected of the employee (a schedule with no slots yet, a non-working weekday, an absence covering the whole day) ends where that weekday ends in their framework (see auto check-out), so the check-out becomes requestable at the same hour the auto check-out would close it. With no framework period that weekday either (e.g. a weekend), it is treated the same as “the day has already ended” — the check-out becomes requestable again, since there’s nothing left to be “still within”. _default_requested_time() never pre-fills a value for a hidden field, and create() strips a requested_check_out sent anyway by a stale/tampered client once the same check says it isn’t requestable — defense-in-depth on top of the view hiding it.

State Machine

The approver isn’t locked into their first decision — action_accept()/action_reject() can be called again at any time (not just while pending) to revise a mistaken decision. Both methods always work off the snapshotted original_check_in/original_check_out, never off whatever hr.attendance currently holds, which is what makes switching back and forth safe/idempotent.

stateDiagram-v2
    [*] --> pending: create()
    pending --> accepted: action_accept() [approver only]
    pending --> rejected: action_reject() [approver only]
    accepted --> rejected: action_reject() [revise a mistake]
    rejected --> accepted: action_accept() [revise a mistake]
    accepted --> accepted: action_accept() [re-apply, no-op]
    rejected --> rejected: action_reject() [re-apply, no-op]
    accepted --> [*]: hr.attendance check_in/out patched
    rejected --> [*]: hr.attendance restored to original_check_in/out

Approver Resolution

There is no per-teacher “reports to a specific Head of Studies” field in EMS: role_hos and role_dhos are both mapped to the same global ems.group_head_of_studies security group (see data/main/ems.role_group_relationship.xml). The approver is instead resolved by walking the native hr.employee.parent_id (manager) chain, implemented as hr.employee.find_head_of_studies():

flowchart TD
    A[Requesting employee] --> B{Employee's user in group_head_of_studies?}
    B -- yes --> C[Self-approval: employee is their own approver]
    B -- no --> D[current = employee.parent_id]
    D --> E{current empty?}
    E -- yes --> F[No approver found: notify ems.group_academic_admin]
    E -- no --> G{current's user in group_head_of_studies?}
    G -- yes --> H[approver = current]
    G -- no --> I[current = current.parent_id]
    I --> E

That resolves who the request is routed to (the task). When nobody above the employee is a Head of Studies, _find_approver() falls back to whoever manages their area’s attendance (hr.employee.attendance_manager_id) and only then to the administrators. The whole resolution lives in hr.employee._find_attendance_approvers(). The auto check-out’s fallback notice deliberately does not use it: it goes to the employee alone, who requests the correction that then reaches these approvers.

Who may decide (_check_is_approver(), issue #543) is wider than the one person it is routed to, but scoped to the employee’s own branch, never to every holder of the role centre-wide:

User Decides
Head / Deputy Head of Studies The requests of the employees below them in the chain of command (hr.employee.tutor_scope_user_ids) and of the area whose attendance they manage (attendance_manager_id) - the “double flow”: hierarchy and area manager. Their own too, as before: nobody below the Director is above them.
Director (ems.group_director) Every request
Administrator (ems.group_academic_admin) Every request: above the whole hierarchy, although they appear nowhere in it

The record rules below show them exactly those requests, so another branch’s Head of Studies does not even see the request. The centre-wide “Heads of Studies see everybody’s attendance” setting (see Employee attendance) only widens what they can read of hr.attendance; it never widens who decides.


CRUD Operations

Create

A teacher opens one of their own hr.attendance records and clicks Request Correction in the header, which opens ems.attendance_correction in a dialog with attendance_id pre-filled. requested_check_in/requested_check_out default (_default_requested_time()) to the original time of that attendance, so the requester only has to tweak the value that’s wrong. If the original check_out isn’t set yet (employee still clocked in) and the check-out is requestable (see below), _schedule_time_for() falls back to the requester’s resource.calendar (working schedule) for that weekday — earliest hour_from for check-in, latest hour_to for check-out — instead of leaving the field blank. On create(), the resolved approver(s) get a mail.activity to-do (activity type ems.mail_activity_attendance_correction) and the record’s chatter logs the request. The activity is scheduled with mail_activity_quick_update, so Odoo’s “X has assigned you an activity” email is not sent: a correction is not urgent, and the approver is reminded of it by the daily summary instead.

A Head of Studies, Deputy Head of Studies, Director or Academic Admin can do the exact same thing on behalf of any employee (issue #480): the “Request Correction” button is on the native hr.attendance form itself, so opening any employee’s attendance record (already possible for these roles, see the read access note below) and clicking it works identically, create() included, regardless of whose attendance it is.

Read

Teachers see their own requests (views/attendance/attendance_correction/list.xml); Head of Studies/Director/Academic Admin see all pending and historic requests, under the native “Attendances” menu. The list defaults to the Pending filter (action_attendance_correction_tree’s context: {'search_default_pending': 1}), matching the same pattern already used by ems.student.document — an approver isn’t forced to wade through already-decided requests by default. The search view also exposes standalone Accepted/Rejected filters, so switching to (or combining) any other state, or removing the default filter to see all requests, is a single click. action_view_corrections() (the “Corrections” smart button on hr.attendance) explicitly resets the context to {} when drilling into one specific attendance’s requests, so that view is never filtered.

Update / Decide

Only the resolved approver (or an Academic Admin) may call action_accept() / action_reject() — this permission check (_check_approver()) is the only gate; there is no state == 'pending' restriction, so a decision can be revised later:

reason (set by the requester) is readonly="id" in the form — editable only in the creation dialog, never afterward, including by the approver or an admin. decision_note has no such restriction, since it’s expected to be updated across multiple decision revisions.

Delete

Only Academic Admin can delete correction requests (audit trail is otherwise kept).


Access Control

Role Create Read Write Delete Group XML ID
Administrator ✓ (any employee) ✓ ✓ ✓ ems.group_academic_admin
Head of Studies / Deputy ✓ (own branch) ✓ (own branch) ✓ (own branch) — ems.group_head_of_studies
Director ✓ (any employee) ✓ ✓ — ems.group_director
Any employee (teachers and non-teaching staff) ✓ (own only) ✓ (own only) — — hr_attendance.group_hr_attendance_own_reader (implied by base.group_user)

Record rules (security/rules/attendance.xml): Admin and Director unrestricted (rule_attendance_correction_admin, rule_attendance_correction_director); Head of Studies restricted to their own branch, including on create (rule_attendance_correction_hos: employee_id.tutor_scope_user_ids contains the user, or employee_id.attendance_manager_id is the user); every other employee restricted to employee_id.user_id = user.id, including on create (rule_attendance_correction_teacher_own) — a plain teacher or a member of the non-teaching staff cannot request a correction on another employee’s behalf. That ACL and rule belong to hr_attendance.group_hr_attendance_own_reader (whoever reads their own attendance), not only to teachers, since issue #734: the non-teaching staff clock in too, and the auto check-out asks them to correct a check-out it had to guess. Their requests are routed like a teacher’s (_find_attendance_approvers()). The ids keep “teacher” in their name.


Integration Map

Model Field Relation Description
hr.attendance attendance_id Many2one (required) The attendance record being corrected; header button added via inherited view
hr.attendance correction_ids / correction_count One2many (inverse of attendance_id) / computed Lets the attendance form show a “Corrections” smart button with a count, opening action_view_corrections() (domain-filtered reuse of action_attendance_correction_tree)
hr.employee find_head_of_studies() method Resolves the approver by walking parent_id
hr.employee _find_attendance_approvers() method Who corrects the employee’s attendance (res.users): nearest Head of Studies, else attendance_manager_id, else the administrators; used by _find_approver() and the review of detected absences (ems.absence_pending)
mail.activity.type ems.mail_activity_attendance_correction data record Dedicated activity type for the approval to-do

Views

View File Notes
List views/attendance/attendance_correction/list.xml Employee, attendance, requested times, state; create="false" — records can only be created from the “Request Correction” button, never from this list
Form views/attendance/attendance_correction/form.xml Statusbar + Accept/Reject buttons (visible to the resolved approver only)
Search views/attendance/attendance_correction/search.xml Pending/Accepted/Rejected filters + group by status/employee; action_attendance_correction_tree defaults to search_default_pending: 1
Menu views/attendance/attendance_correction/menu.xml Under the native “Attendances” root menu, sibling to Overview/Management
hr.attendance header button + smart button views/attendance/attendance_correction/hr_attendance_form.xml Inherits hr_attendance.hr_attendance_view_form: adds “Request Correction” to //header, and a “Corrections” stat button (count) before the first <group> that opens the same list/form (domain-filtered to that attendance) via action_view_corrections()

Data Files

File Purpose
data/main/ems.mail_activity_type.xml Adds the mail_activity_attendance_correction activity type

Note: a dedicated mail.template for the decision email was considered and dropped — message_post(partner_ids=...) already emails the requester as a mail notification (visible in the chatter added to the form), which covers the “notify by email” requirement without extra plumbing.