Manual Punch Attendance Documentation

Create professional documentation using Nextra (.mdx) for the Manual Punch Attendance module in the Worksphere application.

Audience: Admin / Super Admin
Style: Atomic CRM–style documentation
Scope: Add, View, Edit, Delete
Exclude: Separate list page, implementation details, code logic, screenshots

MODULE: MANUAL PUNCH ATTENDANCE MANAGEMENT

Navigation Path

Company → Attendance → Manual Punch Attendance

Manual Punch Attendance Page

URL

/attendance/manual-punch-attendance

Page Description

• Used to add manual attendance records for employees
• Works as a single-page module
• Attendance records are retrieved by searching Employee Code
• Existing records are displayed in a table below the form
• Records can be edited or deleted from the same page

1. Attendance Entry Form

Form Fields

2. Search Employee Attendance

Search Flow

1. Select Month, Year, and Unit
2. Enter Employee Code
3. Click Search

Search Result

• If attendance exists:
  • Records are displayed in a table below
  • Form fields are populated for edit
• If no record exists:
  • Form remains empty for new entry

3. Attendance Records Table

Table Description

• Displays manual attendance records for the selected employee
• Appears below the form after successful search

Table Columns

4. Row Actions

Edit Attendance

• Triggered by clicking Edit button
• Selected record details are populated into the form
• Admin can modify values and click Update

Delete Attendance

• Triggered by clicking Delete button
• Opens a confirmation alert

5. Delete Confirmation Alert

Alert Content

• Confirmation message before deletion

Actions:

• Confirm / Yes → Deletes the attendance record
• Cancel → Closes the alert without action

6. Actions

Validation Rules

• Month and Year must be selected
• Employee Code is mandatory
• Attendance Days cannot exceed Month Days
• Numeric fields accept only valid numbers

Field Definitions, Usage, and Calculation Logic

This section provides a deep dive into the technical properties, business validation, and logic governing the Manual Punch Attendance module.

1. Field Definitions

2. Field Usage & Validation

3. Relationships & Dependencies

• Employee Master Dependency: empCode and employeeName are read-only in this module and are automatically synchronized from the Salary Employee Master based on the employeeId.
• Unit Dependency: unitCode, unitName, and branch are synchronized from the Unit Master. If the Unit's monthDays is set, it defaults as the Division Factor.
• Salary Process Dependency: If an attendance record is linked to a locked Salary Process, it cannot be edited or deleted until the process is unlocked.
• Joining Date Restriction: Attendance cannot be recorded for any month prior to the employee's Date of Joining.

4. Calculation Logic

A. Leave Without Pay (LWP)

LWP is automatically calculated to ensure data integrity during payroll generation.

Formula: LWP = Month Days (Division Factor) - Attendance Days

B. Overtime (OT) Conversion

If a user enters attendance days that exceed the actual calendar days of the month (e.g., 32 days in January), the system may trigger a validation error or (in bulk imports) attempt to adjust excess days into the OT category depending on configuration.

C. Division Factor (Month Days)

1. System checks for a predefined monthDays value in the Unit Master.
2. If null, it defaults to the actual number of days in the calendar month for that specific year.

5. Business Purpose

• LWP Accuracy: Automating LWP calculation prevents manual entry errors that could lead to overpayment or underpayment.
• Audit Compliance: Auto-assigning Unit and Employee details from Masters ensures that attendance is always mapped to the correct cost center and legal identity.
• Financial Controls: The 50-day cumulative limit (Attendance + OT) acts as a safety barrier against extreme data entry errors.

6. Data Flow & System Integration

7. Integration with Payroll Processing

The Manual Punch Attendance module is the primary data feeder for the Payroll Engine.

• Salary Auto Process: When an administrator initiates the salary generation process, the system queries the SalaryAttendanceDetails collection for the specified month and year.
• Financial Calculations:
  • Gross Pay: Calculated by multiplying the effective attendance days by the employee's daily rate.
  • Overtime: OT days and hours are multiplied by the OTMultiple (e.g., 1.5x or 2.0x) defined in the Unit Config.
  • Deductions: LWP days are used to reduce the total earnings before PF and ESI calculations.
• Record Locking: Once a salary process is "Locked" or "Verified," the corresponding attendance record's isProcessed flag is set to true, and further modifications are restricted through API-level validation.

8. Versioning & Audit Trail

To maintain high financial integrity, the system tracks every change made to processed data.

• Salary Versioning: When a salary record needs to be updated (e.g., due to an attendance correction), the existing processed record is archived in the Salary Versioning collection before a new one is created.
• Traceability: Each version is linked to the original attendanceId. This allows auditors to see the full "paper trail" of how an employee's pay changed as a result of attendance adjustments.
• Revert Logic: Administrators can "Revert" a process, which resets the isProcessed flag on the attendance record, allowing for corrections before the next processing run.

API Endpoints

The Salary Attendance Details module interacts with the following API endpoints:

Base URL

export const SALARYATTENDENCEDETAILS_URL = '/api/salaryAttendanceDetails'

Endpoints

RTK Query Hooks

The following hooks are available for frontend integration:

• useCreateSalaryAttendenceMutation
• useGetAllSalaryAttendencesQuery
• useGetSalaryAttendenceByIdQuery
• useUpdateSalaryAttendenceMutation
• useDeleteSalaryAttendenceMutation
• useExportToExcelQuery
• useExportSchemaToExcelQuery
• useImportAttendenceMutation
• useSearchSalaryAttendenceDetailsMutation
• useSearchAndExportToExcelAttendenceMutation
• useImportAttendanceFromExportedSheetMutation
• useBulkattendenceDeleteMutation

End of Documentation