Auto Salary Process

Navigation Path

Salary → Auto Salary Process

Auto Salary Process Page

URL

/salary/auto-salary-process

Page Description

The Auto Salary Process is the core transactional module in the HRMS. It retrieves attendance-based employee records and processes their monthly salaries. The system separates records into Unprocessed and Processed tabs, tracks multi-stage workflow verification statuses, and executes complex calculations conforming to Indian statutory regulations (PF, ESI, PT, LWF).

Architectural Overview

• Branch-Based Unit Access: Before any processing, the API filters requested units to enforce accessible units assigned to the user, preventing unauthorized salary calculations.
• Dynamic Batch Sizing: For high-performance operations, batch sizes are dynamically scaled based on the total employee count:
  • Small batches (< 100): 100
  • Medium batches (100 - 1000): 500
  • Large batches (1000 - 5000): 1000
  • Very large batches (5000+): 2000

1. Salary Search Section

Search & Filter Parameters

The user can filter attendance and salary records using the following fields:

2. Unprocessed Salary Records

Description

• Displays attendance records that have not yet been processed for the selected cycle.
• Eligible records must have a valid monthDays (greater than 0) and at least one non-zero attendance-related field (attendanceDays, nationalHoliday, otdays, or othrs).
• Salary cannot be processed for periods prior to the employee's dateOfJoining.

Unprocessed Records Table

3. Processed Salary Records

Description

• Displays monthly salary processes that are calculated and saved in the database.
• Follows a structured multi-level approval and verification workflow.
• Locked records are fully finalized and cannot be modified or reprocessed unless special unlocking mechanisms are invoked.

Processed Records Table

4. Multi-Stage Verification Workflow

Salary records follow a strict validation lifecycle to ensure multi-departmental audit compliance.

Verification States and Technical Keys

[!WARNING] Reprocessing an existing salary process will automatically revert any outstanding Loan Installment balances and Recovery records associated with the attendance record to prevent double-deductions.

5. Calculations, Formulas, and Core Rules

The payroll system automatically maps Designation or Employee-specific heads to compute earnings, deductions, employer contributions, and overall CTC.

A. PF (Provident Fund) Calculation

PF calculation follows statutory capping guidelines:

• PF Taxable Wages = (Basic + PF-Gross-Part-Heads) derived from actual attendance-based earnings.
• Employee PF = TaxableWages * 12%.
• Voluntary PF = Configured as an additional voluntary percentage/amount deduction.
• Employer EPF Share (AC01) = TaxableWages * 3.67%.
• Employer Pension Share (AC10) = TaxableWages * 8.33% (subject to ₹15,000 ceiling, where max pension wages = ₹1,250).
• Admin Charges (AC02, AC21, AC22) = Calculated based on statutory slab configurations.

B. ESI (Employee State Insurance) Calculation

ESI calculations are performed on both regular earnings and overtime components:

• ESI Gross = Sum of ESI-eligible earning heads actually paid.
• Employee ESI = ESI Gross * 0.75%.
• Employer ESI = ESI Gross * 3.25%.
• Statutory Cap: Employee ESI contribution is capped at ₹158 for regular employees if previous months exceed the statutory limit.

C. Overtime (OT) Calculation

Overtime is calculated on hours (othrs) and days (otdays):

• OT Days Pay = (OT Days * perDayGross * OT Multiple).
• OT Hours Pay = (OT Hours * perHourGross).
• OT Multiple: Defined at the Unit level (e.g., 1.5 or 2.0 for double rates).
• Statutory Inclusions: If ESIonOT or PFonOT is enabled at the unit config level, OT earnings are added to the statutory ESI/PF gross calculations.

D. National Holiday (NH) / Paid Holiday Logic

• Paid holidays and National Holidays are evaluated separately.
• Pays a daily rate for holiday attendance based on nh / nationalHoliday count.
• Eligible to receive ESI and PF contributions if flagged on the respective salary head rules (esionnh, nfhgross).

E. Labour Welfare Fund (LWF) & Professional Tax (PT)

• LWF: Slab-based state welfare fund deduction.
  • Haryana LWF Special Rule: Aggregates LWF deductions across multiple attendances under a monthly ceiling (default ceiling of ₹34) to avoid over-deducting.
• Professional Tax: Slab-based state tax evaluated on gross monthly earnings, including OT and NFH.

F. Employer Benefits & Contributions (CTC)

The total Cost to Company (CTC) aggregates:

• Final Net Pay + Total Deductions + Employer PF + Employer ESI + Employer LWF + GPA (Group Personal Accident) + GTLI (Group Term Life Insurance) + Trust Fund Contributions.

G. Loans, Arrears, and Recovery

• Loans: Integrates with LoanMaster and SpecialLoanMaster (special designation/unit configurations). Deducts monthly installments and automatically decrements balances. Reprocessing auto-reverts the balances.
• Arrears: Processed on the first attendance of the month. Includes Basic Arrear, PF/ESI/PT Arrears, and LWF Arrears, updating the salary totals dynamically.
• Negative Pay & Recoveries: If deductions exceed earnings resulting in a negative pay balance, the net pay is set to 0, and a SalaryRecoveryModel record is created for the negative amount. In subsequent payrolls, this amount is treated as an outstanding recovery and is automatically deducted from positive net pay.

6. System Flags and Configuration Controls

The salary processing engine utilizes multiple layers of system flags at the Employee, Unit, Salary Head, and Transaction levels to orchestrate calculations and status transitions.

A. Lifecycle & Workflow Approval Flags (Transaction Level)

• processedVerified (Boolean): Set to true when salary calculations are executed for an employee. It transitions the record from the Unprocessed list to the Processed list.
• branchVerified (Boolean): Indicates the Unit/Branch Manager has audited and confirmed attendance days.
• billingVerified (Boolean): Confirms that the processed records align with the client billing invoicing rules.
• accountVerified (Boolean): Set by the Accounts department. Triggers bank details and mandatory checks. Validation Rules:
  • Requires valid Bank Account Number and IFSC Code.
  • If PF is applicable, requires UAN. If ESI is applicable, requires ESI number.
  • Note: Statutory UAN/ESI checks are ignored if isVoucher is true.
• isLocked (Boolean): Frozen state flag. Once flipped to true (typically when bank mandates are processed), the salary record becomes immutable. Any edits, deletes, or recalculations are blocked until a mandate reset is performed.

B. Architectural & Control Toggles

• isHeadMapping (Boolean):
  • Employee Wise (true): The engine loads custom heads, specific rates, and statutory rules directly from the Employee's Profile.
  • Site Wise (false): The engine falls back to standard templates defined in the Designation Master and Unit defaults.
• isVoucher (Boolean): Flags the process as a voucher (e.g. vendor payment). It bypasses statutory validations (like UAN/ESI requirements) and standard rollback rules during reprocessing.
• isDummyRecord (Boolean): Marks mock or placeholder salary processes. Bypasses the background auto-left cron check so dummy processes do not block inactivity evaluation.

C. Statutory & Calculation Rule Flags

• providentFundApplicable (Boolean): Evaluated on the Employee (isHeadMapping = true) or Designation (isHeadMapping = false). Triggers standard EPF/EPS deductions.
• employeeStateInsuranceApplicable / esiApplicable (Boolean): Evaluated on the Employee/Designation. Triggers employee (0.75%) and employer (3.25%) ESI contributions.
• professionalTaxApplicable (Boolean): Enables state slab-based Professional Tax deductions.
• lwfApplicable (Boolean): Enables slab-based State Labour Welfare Fund deductions.

D. Overtime (OT) & National Holiday (NH) Flag Rules

• ESIonOT (Boolean): Configured at the Unit level. If true, OT payouts are added to the ESI Gross pool.
• PFonOT (Boolean): Configured at the Unit level. If true, OT payouts are added to the PF Taxable Gross base.
• esiOnOThours (Boolean/String): Controls whether hourly overtime specifically attracts ESI deductions (as opposed to only daily overtime).
• esionnh (Boolean): Configured on individual salary heads. If true, ESI contributions are computed on National Holiday / Paid Holiday earnings.
• pfOnNFH (Boolean): Configured on individual salary heads. If true, PF contributions are computed on National Holiday / Paid Holiday earnings.

E. Salary Head Master Rules

• presenceDependent (Boolean): Configured on individual deduction heads. If true, the deduction amount scales down for days the employee was absent. If false, a flat deduction is applied.
• employeeStateInsuranceGrossPart (Boolean): Dictates whether this earning head is included in calculating the ESI Gross amount.
• providentFundGrossPart (Boolean): Dictates whether this earning head is included in calculating the PF Taxable wages.

7. API Endpoints

Base URL

export const AUTOSALARYPROCESS_URL = '/api/salarySalaryAutoProccess'

REST & Action Endpoints

8. RTK Query Hooks

The following hooks are available in autoSalarySlice.js for React frontend integration:

• useCreateAutoSalaryProcessMutation
• useGetAllAutoSalaryProcessQuery
• useGetAutoSalaryProcessByIdQuery
• useUpdateAutoSalaryProcessMutation
• useDeleteAutoSalaryProcessMutation
• useSearchAutoSalaryProcessMutation
• useMakeSalaryProcessMutation
• useMakeSalaryUnProcessMutation
• useExportToExcelSalaryMutation
• useUpdateVerificationFlagsMutation
• useExportSalaryMandateToExcelMutation
• useSendSalaryMandateEmailControllerMutation
• useExportBankWiseSalaryMandatePDFMutation
• useExportBankWiseEmployeeSalaryPDFMutation
• useExportSalaryMandateSummaryToExcelMutation
• useRevertSalaryProcessFlagsMutation

9. Background Automation: Auto-Mark Left

The system supports automated employee lifecycle cleanup:

• Eligibility & Evaluation Rules:
  1. Skips employees who joined less than 4 months ago.
  2. Evaluates the remaining employees against consecutive monthly records.
  3. If no active salary record (excluding dummy processes) is processed in the last 4 consecutive months, they are automatically marked as inactive.
• Workflow Impact:
  • Sets employeeLeftStatus to 'Y'.
  • Sets leftDate to the current system date.
  • Adds leftRemarks in the format: "Auto-marked as left: No salary calculated for last 4 consecutive months. Missing months: [Month/Year List]"

10. Complete Salary Process Workflow Diagram

Below is a comprehensive flow diagram illustrating how the system processes salaries, from fetching attendance to the final payout generation.

End of Technical Documentation