Attendance Management

Overview

OptiCRM provides a complete attendance management system covering students, teaching staff, and operational staff. It includes daily/period-wise marking, automated shortage alerts, holiday management, staff self-service, and regularisation workflows.

Student Attendance

Daily Marking

1. Navigate to Attendance from the sidebar
2. Select the class/section and date
3. System loads all enrolled students
4. Mark each student: Present, Absent, Late, Half Day, Excused, Leave
5. Click Save -records saved to database
6. Students marked Absent automatically trigger SMS/Email notification to their primary guardian

Period-Wise Attendance

For subject-level tracking, teachers can mark attendance per period:

• Select the period number in addition to class and date
• System uses the timetable to identify which subject/teacher is scheduled
• Allows tracking: "Present for Maths (Period 1) but absent for Science (Period 3)"

Attendance Statuses

Attendance Corrections

HOD or Principal can correct wrongly-marked records:

• Navigate to the student's attendance record
• Change the status with a mandatory reason
• Reason is appended to the record's notes for audit trail

Staff Attendance

Admin Marking

1. Navigate to HR & Staff →Staff Attendance (admin view)
2. Select department and date
3. Mark each staff member: Present, Absent, Half Day, On Leave, Work From Home, On Duty
4. Optionally enter check-in/check-out times
5. Overtime auto-calculated if working hours exceed 8

Self-Service View

Staff members can view their own attendance at Self Service →My Attendance:

• Monthly calendar grid with color-coded status badges
• Summary cards: Present, Absent, Leave, Half Day, Holidays, Overtime hours, Attendance %
• Navigate between months

Staff Attendance Statuses

Attendance Regularisation

When a staff member notices an incorrect attendance record:

1. Go to Self Service →My Attendance
2. Click the day with wrong status
3. Submit a regularisation request with:
   • Current (wrong) status
   • Requested (correct) status
   • Reason for correction
4. HOD or Admin reviews the request
5. On approval: attendance record is automatically corrected

API: POST /api/staff-attendance/regularisation (submit), PATCH (approve/reject)

Holiday Management

Setting Up Holidays

Navigate to Administration →Holiday Calendar:

1. Click Add Holiday
2. Enter: name, date, type, and options
3. Holidays automatically affect:
   • Student attendance (students auto-marked as HOLIDAY)
   • Staff attendance (excluded from working day count)
   • Working days calculation
   • Calendar display

Holiday Types

Options

• Applies to Staff -Include in staff working days calculation
• Applies to Students -Include in student attendance calculation
• Recurring -Repeats every year (e.g., Republic Day)

Attendance Reports

Daily Register

API: GET /api/attendance/report?type=daily&sectionId=xxx&date=2026-04-13

Shows all students in a section for one date with:

• Student name, code, status, notes
• Summary: total present/absent/late/half-day/excused
• Who marked the attendance and when

Monthly Summary

API: GET /api/attendance/report?type=monthly&sectionId=xxx&month=4&year=2026

Full month grid showing:

• One row per student, one column per day (1-31)
• Status codes: P (Present), A (Absent), L (Late), HD (Half Day), E (Excused), LV (Leave), H (Holiday), W (Weekend)
• Right column: attendance percentage per student
• Color coding: Green (above 90%), Amber (75-90%), Red (below 75%)
• Working days count (excludes holidays and weekends)

Shortage Report

API: GET /api/attendance/report?type=shortage&sectionId=xxx

Lists students below 75% attendance:

• Student name, code, class/section
• Present days / working days, percentage
• Guardian name and phone number
• Sorted by percentage (lowest first)

Automated Shortage Alerts

A daily cron job (POST /api/cron/attendance-shortage) runs automatically:

1. For each institution, calculates every student's attendance percentage
2. Students below 75% trigger an email to their primary guardian
3. Email includes: student name, attendance percentage, present/working days
4. Deduplication: Each student is notified at most once per week (Redis-based)
5. Requires: CRON_SECRET env variable for security

Sample notification:

"Alert: Your child Aarav Sharma (STU-2026-0042, Grade 8-A) has 68% attendance this term, which is below the required 75%. Please ensure regular attendance."

Role-Based Access

API Reference

Technical Architecture (Developer Reference)

Storage Model

Attendance uses dedicated Prisma tables (not JSONB DynamicRecord) for performance reasons. With millions of rows (every student x every day), dedicated tables with proper indexes are essential for aggregations, date-range queries, and cross-entity joins.

However, all attendance entities are fully integrated into the entity system:

• Object Manager - Visible as standard objects (StaffAttendance, Holiday, Attendance)
• Report Builder - Custom reports with filters, grouping, computed columns
• Cross-Object Reports - Student+Attendance join for combined student-attendance analysis
• Entity List - CRUD views at /o/StaffAttendance, /o/Holiday
• Dashboard KPIs - todayAttendanceRate, attendanceBySection
• Export - CSV, Excel, PDF via the report builder

Database Models

Attendance (student) - prisma/schema.prisma

• Unique: [studentId, date, period]
• Indexes: [sectionId, date], [studentId, date]
• 7 statuses: PRESENT, ABSENT, LATE, HALF_DAY, EXCUSED, HOLIDAY, LEAVE
• Source tracking: MANUAL, BIOMETRIC, IMPORTED

StaffAttendance - prisma/schema.prisma

• Unique: [staffId, date]
• 7 statuses: STAFF_PRESENT, STAFF_ABSENT, STAFF_HALF_DAY, STAFF_ON_LEAVE, STAFF_HOLIDAY, WORK_FROM_HOME, ON_DUTY
• Check-in/out with overtime auto-calculation

Holiday - prisma/schema.prisma

• Unique: [institutionId, date]
• Types: GAZETTED, RESTRICTED, VACATION, CUSTOM
• Affects: attendance calculations, calendar, working days

AttendanceRegularisation - prisma/schema.prisma

• Status: REG_PENDING, REG_APPROVED, REG_REJECTED
• On approval: auto-updates StaffAttendance record

PersonalEvent - prisma/schema.prisma

• User-scoped calendar events
• Indexed: [userId, startDate]

Key Implementation Files

Integration Points

Report Builder - An admin can create custom reports like:

• "Staff Attendance by Department" - source: StaffAttendance, group by: department
• "Student Shortage List" - source: Attendance, filter: percentage below 75
• "Holiday Summary by Type" - source: Holiday, group by: type

Cross-Object Reports - Student+Attendance join enabled in cross-object.ts:

• Shows student details alongside their attendance summary
• Columns: studentName, className, presentDays, absentDays, percentage

Dashboard KPIs - Real-time metrics from kpi/engine.ts:

• todayAttendanceRate(institutionId) - today's present percentage
• attendanceByClass(institutionId) - per-section rates for chart

Calendar - Holiday model feeds into the unified calendar API:

• Red blocks for holidays
• Working days excluded from attendance calculations