Attendance Module — User Guide
All guides

Attendance Module — User Guide

Time tracking, shifts, and devices.

ProductVertex ERP
ModuleAttendance (`modules/attendance`)
AudienceAttendance officers/supervisors, biometric administrators, and employees viewing own attendance in the portal
FormatHTML + Mermaid diagrams

1. Overview

The Attendance module captures biometric punches, maps them to employees, compares them to work schedules, and produces attendance sessions plus exception records (late, early departure, absence, overtime) for review and reporting.

Layer What users work with
Schedules Templates and per-employee work schedules
Devices Biometric devices and employee enroll-number mappings
Raw punches Biometric records
Sessions Attendance records
Exceptions Late, early departure, absence, overtime
Insights Period reports, monthly work days, monthly overtime
flowchart LR Dev[Biometric device] --> Punch[Biometric record] Map[Employee mapping] --> Punch Punch --> Sess[Attendance record] Sched[Work schedule] --> Sess Sess --> Exc[Late / Early / Absence / OT] Exc --> Rep[Reports]

Employees and leave data come from HR. Payroll may later consume work-day and overtime outputs; automatic payslip fill from Attendance is not fully wired yet.

2. Getting started

2.1 Recommended setup order

flowchart TD A[HR employees exist] --> B[Work schedule templates or schedules] B --> C[Biometric devices] C --> D[Employee biometric mappings] D --> E[Test connection] E --> F[Sync punches] F --> G[Auto process to attendance] G --> H[Review and approve exceptions] H --> I[Run reports]
  1. Ensure HR employees exist.
  2. Create work schedule templates and apply them, or create work schedules / recurring schedules.
  3. Register biometric devices (IP and port for ZKT).
  4. Create employee biometric mappings (EnrollNumber to employee).
  5. Test connection, then Sync punches.
  6. Sync typically processes pending punches into attendance and exceptions.
  7. Review/approve overtime, late, early departure, and absence.
  8. Run reports.

2.2 Main navigation

Default entry redirects to Work Schedules.

Menu Path Purpose
Work Schedules /attendance/work-schedules Per-employee day schedules
Work Schedule Templates /attendance/work-schedule-templates Reusable schedule patterns
Biometric Devices /attendance/biometric-devices Devices, test, sync
Employee Biometric Mappings /attendance/employee-biometric-mappings EnrollNumber links
Attendance Records /attendance/attendance-records Check-in/out sessions
Overtime Records /attendance/overtime-records Overtime
Absence Records /attendance/absence-records Absences
Late Records /attendance/late-records Lateness
Early Departure Records /attendance/early-departure-records Early leave
Biometric Records /attendance/biometric-records Raw punches
Reports and Statistics /attendance/reports Period and daily comparison
Monthly Work Days Report /attendance/monthly-work-days-report Actual vs scheduled days
Monthly Overtime Report /attendance/monthly-overtime-report Monthly OT summary

3. Work schedule templates and work schedules

Schedules define when an employee is expected to work. Days without a schedule are not treated as scheduled work days in monthly calculations.

3.1 Templates

A template holds a named pattern:

Field Meaning
Name / description Label
Active Available to apply
Recurrence pattern Daily, Weekly, Monthly, or none
Template days Day of week, start/end time, break minutes, flexible flag

Day of week numbering: 1 = Sunday … 7 = Saturday.

Apply template to employees: choose template, employees, effective from/to, and whether to replace existing schedules. Creates one work schedule row per active template day per employee.

3.2 Work schedules

Per employee and weekday:

Field Meaning
Employee Who the schedule belongs to
Day of week 1–7 as above
Start / end time Expected shift
Break duration Minutes
Flexible Flexible schedule flag
Effective from / to Validity window

Create recurring builds the same times for selected weekdays over a date range.

flowchart TD A[Create template with days] --> B[Apply to employees] B --> C[Work schedule rows created] D[Or create schedules / recurring directly] --> C C --> E[Used when processing punches]

4. Biometric devices

Devices are the source of fingerprint/face/card punches.

Field Meaning
Device code / name Identity
Device type Fingerprint, Face, Card, RFID, Other
Location Optional location id
IP address / port Required for ZKT network connect
Serial number Optional
Active Soft enable
Last sync / sync status Online, Offline, Error
Real-time capture Live capture toggle
Notes Free text

Device actions

Action Purpose
Test connection Verify ZKT reachability
Sync Pull attendance and optionally fingerprints
Get users / get records Inspect device contents
Enable / disable real-time capture Live punch capture

Sync options typically include: date/time range, optional employee filter, include unmapped records, sync fingerprints, sync attendance records.

5. Employee biometric mappings

Mappings link an HR employee to the device enroll number so punches can be matched.

Field Meaning
Employee Person linked to the mapping
Device Specific device, or empty for all devices
Biometric id Device EnrollNumber
Fingerprint / face / card Optional templates or card number
Active / enrolled / last used Lifecycle metadata

Tips:

  • Prefer matching the enroll number to the employee number used on the device.
  • Device-specific mappings take precedence over all-device mappings.
  • Leading zeros on enroll numbers are normalized during sync matching.
  • Unmapped punches remain unmatched until a mapping exists.

6. Biometric records

Biometric records are raw punches before or after processing.

Field Meaning
Device / employee / biometric id Source and match
Record type CheckIn, CheckOut, BreakStart, BreakEnd, Other
Date / time Punch moment
Processed Whether turned into attendance
Matched / confidence Employee match result
Notes / raw data Extra device metadata

How punches arrive

  1. ZKT sync — inserts pending punches, then processes them.
  2. Real-time capture — when enabled on the device.
  3. Manual create — admin entry.
  4. Generic sync data — import path with JSON payload.

Processing actions

Action Effect
Process one Map if needed, create/update attendance session
Process all pending Chronological batch for a period
Reprocess Recalculate CheckIn/CheckOut alternation for processed rows
flowchart TD A[Punch arrives] --> B{Mapped to employee} B -->|Yes| C[Matched] B -->|No| D[Unmatched until mapping] C --> E[Process] E --> F[Toggle CheckIn or CheckOut] F --> G[Create or close Attendance session] G --> H[Calculate hours and issues]

ZKT-imported punches often start as CheckIn and become CheckIn/CheckOut alternating as they are processed for the day.

7. Attendance records

An attendance record is a work session for an employee on a date.

Field Meaning
Employee Who attended
Check-in date/time Session start
Check-out date/time Session end
Work hours / overtime hours Calculated
Late / late minutes Session late flags
Absent Absence flag on the session
Notes Free text

Build rules from punches

  1. Employee must be identified.
  2. Same-day punches alternate CheckIn / CheckOut.
  3. CheckIn opens a new session.
  4. CheckOut closes the latest open session and recalculates.
  5. Multiple sessions per day are supported.
  6. Calculate recalculates hours/late on a session.

Present typically means not absent and has check-in. Open session means check-in without check-out.

8. Exception records

When a schedule exists and the employee is not on an overlapping HR leave, processing can create exception records.

8.1 Late records

If check-in is after schedule start, late minutes are rounded to the nearest half hour.

Outcome Rule
Late record Rounded late under 3 hours
Absence record Rounded late 3 hours or more

Fields: late date/time, minutes, reason, excused flag. Approve sets excused.

8.2 Early departure records

Created when early leave patterns are detected inside the schedule window. Minutes rounded to half hours; combined with late thresholds can escalate to a full-day absence when the total is large enough.

Approve sets excused.

8.3 Absence records

Field Meaning
Absence date Day
Absence type Sick, Personal, Emergency, Other
Reason / excused Explanation and excuse
Leave id Optional link to HR leave

Approve sets excused. Auto-created absences from severe lateness may use a localized personal-leave label.

8.4 Overtime records

If check-out is after schedule end, overtime duration is greater than 0.5 hour, and there is no absence that day:

Field Meaning
Overtime date / start / end Window
Hours / rate / amount Quantities
Approved / approved by / date Approval

New auto OT starts not approved. Approve sets approved with timestamp.

8.5 Leave and excuse behavior

flowchart TD A[Attendance session processed] --> B{On HR leave that day} B -->|Yes| C[Skip late / OT / early processing] B -->|No| D[Compare to work schedule] D --> E[Create Late / Early / Absence / OT as needed] E --> F{Has remaining leave balance} F -->|Yes| G[Auto set IsExcused] F -->|No| H[Needs supervisor Approve]

If the employee has remaining leave balance of any type, new late/early/absence rows may be auto-marked excused. Supervisors still use Approve for explicit clearance and for overtime.

All exception types also support manual create/edit/delete within permissions.

9. Matching settings

Attendance matching settings are named configuration keys (host-level), for example:

Setting Intended meaning
auto_match_enabled Auto-match punches to employees
match_tolerance_minutes Matching window
auto_create_attendance Auto-create sessions
check-in / check-out time windows Expected punch windows
late_tolerance_minutes Grace before late
overtime_threshold_hours Hours before overtime

CRUD APIs and permissions exist. There is no dedicated frontend menu page. Live processing currently follows hardcoded operational rules described in this guide (half-hour rounding, 3-hour severe late threshold, overtime over 0.5 hour). Treat the settings store as configuration inventory unless your deployment wires them into SQL helpers.

10. Reports

Report What it shows
Reports and Statistics Period totals and daily attendance comparison; Excel export
Attendance report Work hours, OT, late, absent, present totals
Employee statistics Per-employee stats
Daily attendance comparison Schedule vs actual vs punches
Monthly work days Scheduled days minus unexcused absences/late/early converted to days
Monthly overtime Hours, days, counts; approved vs not

Monthly work days outline

flowchart TD A[Count scheduled days in month] --> B[Subtract unexcused absence days] B --> C[Subtract unexcused late and early as day fractions] C --> D[Actual work days]

Late/early minutes are converted using an 8-hour day. Excused breakdowns are returned separately. HR also has a separate Monthly attendance report under HR reports.

11. ZKT device integration

Topic User guidance
Platform Windows host with zkemkeeper COM registered
Connect Device IP and port via Connect_Net
Identity Device EnrollNumber stored as BiometricId
Sync Dedupes by device + biometric + datetime
After sync Pending punches processed automatically
Fingerprints Can update mapping templates; does not invent employee mappings alone
Sync status Success sets Online + last sync; failure sets Error
Real-time Toggle on the device record

Ensure network reachability and that mappings exist before expecting matched attendance.

12. Employee portal

Under HR employee portal (/hr/employee/...), employees with view-own rights can open:

Portal area Content
Attendance records Own sessions
Work schedules Own schedules

When the user only has own-view HR rights, lists lock to the current employee and hide the employee picker. Biometric records may be routed but not always shown in portal navigation.

13. Permissions summary

Permission group: Attendance.

Area Key abilities
Attendance records CRUD, View, Calculate, Statistics, Export
Work schedules CRUD, View, Create recurring
Work schedule templates CRUD, View, Apply template
Biometric devices CRUD, View, Test, Sync, Get users/records, Real-time capture
Employee biometric mappings CRUD, View
Biometric records CRUD, View, Process, Process all, Reprocess, Sync
Overtime / Absence / Late / Early departure CRUD, View, Approve
Matching settings CRUD, View
Reports Monthly work days, monthly OT, attendance report, stats, daily comparison
Employee lookup Dropdowns without full HR permission

Typical seeded roles:

Role Focus
Attendance Manager Full access
Attendance Supervisor View, Approve, Reports
Attendance Officer Operational manage without Approve
Employee Limited view/create; portal uses HR view-own

14. Integration with HR and Payroll

flowchart TB subgraph HR Emp[Employees / Persons] Leave[Leaves] end subgraph Attendance Sched[Schedules] Sess[Attendance sessions] Exc[Exceptions] Rep[Work days / OT reports] end subgraph Payroll PS[Payslips] end Emp --> Sched Emp --> Sess Leave --> Exc Sess --> Exc Exc --> Rep Rep -.->|Not auto-filled yet| PS
Module Relationship
HR Employees are attendance subjects. Overlapping leave skips late/OT/early auto-processing. Leave balance can auto-excuse some exceptions. Official holidays / weekend tables in HR are not the Attendance engine; non-scheduled weekdays simply have no work schedule.
Payroll Formula variables may include Attendance category. Payslip actual work days / hours are intended consumers of attendance outputs but are not automatically filled from this module today — use monthly work-days report operationally.

Appendix A — Quick procedures

A.1 Onboard attendance for an employee

  1. Create or apply a work schedule.
  2. Ensure a biometric mapping with the correct EnrollNumber.
  3. Test device connection.
  4. Sync a short date range and confirm matched biometric records.
  5. Verify attendance sessions and any exceptions.

A.2 Daily / period operations

  1. Sync devices.
  2. Process any remaining pending punches.
  3. Review open sessions.
  4. Approve overtime and excused late/early/absence as needed.
  5. Run monthly work days and overtime reports at period close.

A.3 Approve overtime

  1. Open Overtime Records.
  2. Filter unapproved.
  3. Approve valid rows.
  4. Include them in the monthly overtime report.

Appendix B — Operating notes

Topic Guidance
Day of week 1 = Sunday … 7 = Saturday
Severe late About 3 hours rounded late becomes absence
Overtime minimum More than 0.5 hour past schedule end
Rounding Late/early minutes round to nearest half hour
Unmapped punches Stay unmatched until mapping exists
Matching settings UI API only; processing uses documented hardcoded thresholds
Payroll link Export/report driven until auto fill is enabled

Appendix C — Document control

Item Value
Title Attendance Module User Guide
Source of truth modules/attendance and frontend/src/app/modules/attendance
Format Markdown + Mermaid (PDF edition embeds rendered figures)
Screenshots Not included (by design)

This guide describes functional capabilities of the Attendance module as implemented in the Vertex ERP codebase. UI labels may appear in English or Arabic depending on language settings.

Vertex ERP documentation. Generated from Markdown sources in docs/.