Statutory & Payroll Flags Documentation

This document provides a detailed technical explanation of the various statutory and payroll calculation flags present in the system, organized by the modules where they appear.

1. Flags by Module

A. Employee Master

The Employee Master contains flags that apply specifically to an individual employee. These settings typically override unit-level or designation-level defaults.

PFApplicable (Provident Fund Applicable)
- Purpose: Determines whether Employee Provident Fund (EPF) deductions should be processed for this specific employee.
- When to Select: Check this if the employee is eligible and has opted for PF. Uncheck for trainees, interns, or employees who have formally opted out (and are legally allowed to).
- Impact: If true, the engine calculates PF deductions based on their attendance and gross salary.
PFBasedOn (PF Calculation Rules)
- Purpose: Defines the specific rule/cap applied to calculate the PF Gross amount.
- Available Rules:
  - Basic:
    - Meaning: Caps the PF Gross at the statutory limit (e.g., ₹15,000).
    - When to Select: Standard selection for most compliant organizations.
    - Impact: Even if basic salary is ₹50,000, PF is only deducted on ₹15,000.
  - Actual:
    - Meaning: Calculates PF on the actual earned basic without applying the statutory limit.
    - When to Select: For senior employees who opt to contribute PF on their full basic salary.
    - Impact: Higher PF deduction for both employee and employer.
  - SpecialBasicCondition:
    - Meaning: If the base exceeds ₹15,000, it hardcaps it to ₹15,000. Otherwise, it uses the dynamically calculated final base salary.
    - When to Select: When you have complex conditional basic formulas that need strict statutory capping.
    - Impact: Safeguards against over-deduction while respecting custom basic setups.
  - Manual21kLimit / Manual17_5kLimit:
    - Meaning: Hardcaps the PF gross at ₹21,000 or ₹17,500 respectively.
    - When to Select: When specific company policies or custom trust setups mandate these higher limits instead of ₹15,000.
  - ShreeRam / Manual:
    - Meaning: Custom client-specific override rules that generally default back to the Basic logic (capped at maximum limit).
employeeStateInsuranceApplicable (ESI Applicable)
- Purpose: Determines whether ESI deductions should be processed for this employee.
- When to Select: Check if the employee's gross salary is within the ESI threshold (currently ₹21,000) or if they are in an active ESI contribution cycle.
- Impact: If true, calculates 0.75% employee contribution and 3.25% employer contribution.
esiBasedOn (ESI Calculation Rules)
- Purpose: Defines how the ESI Gross is determined and capped.
- Available Rules:
  - Asper Rule:
    - Meaning: Standard statutory compliance. ESI limit is prorated based on attendance days and capped at ₹21,000 dynamically.
    - When to Select: Default choice for all ESI eligible employees.
    - Impact: Adjusts ESI automatically if an employee takes LWP, ensuring compliance.
  - Gross:
    - Meaning: ESI is computed on the total Gross Pay, ignoring specific individual component flags.
    - When to Select: If your company structure requires ESI on all earnings regardless of custom allowances.
  - AsPerRuleWithLimit:
    - Meaning: Strict cumulative capping. Tracks ESI previously deducted and dynamically limits the max employee contribution (e.g., to ₹158) if cumulative gross crosses limits.
    - When to Select: Useful for complex overtime setups where you need to guarantee the employee is never over-deducted.
  - Derived / Conditional:
    - Meaning: Zeroes out ESI if the base gross crosses ₹21,000 strictly before OT is applied.
    - When to Select: When ESI applicability depends purely on the base gross regardless of performance bonuses.
professionalTaxApplicable (PT Applicable)
- Purpose: Enables State Professional Tax deductions for the employee.
voluntaryProvidentFundApplicable (VPF Applicable)
- Purpose: Allows an employee to contribute additional PF beyond the statutory 12%.

B. Designation Master

The Designation Master acts as a default template. When a new employee is assigned a designation, they inherit these default flags unless overridden in the Employee Master.

providentFundApplicable (PF Applicable)
- Purpose: Default PF applicability for anyone holding this designation.
PFBasedOn
- Purpose: Default PF calculation rule for this role.
esiApplicable (ESI Applicable)
- Purpose: Default ESI applicability for this role.
esiBasedOn
- Purpose: Default ESI calculation rule for this role.

C. Unit Master

The Unit Master contains flags that affect specific geographical locations or branches.

ESIonOT (ESI on OT)
- Purpose: Determines if Overtime (OT) earnings should be subjected to ESI deductions.
- When to Select: Enable if local compliance or company policy dictates that OT is part of ESI Gross.
- Impact: OT earnings are added to the ESI Gross pool during calculations.
PFonOT (PF on OT)
- Purpose: Determines if OT earnings should be subjected to PF deductions.
- Impact: Adds OT earnings to the PF Taxable Gross base.
aggregatePF / aggregateESI
- Purpose: Used for reporting purposes to aggregate challans across the unit.

D. Unit Configuration

Unit Configuration holds the absolute global toggles and limits for a branch.

providentFundApplicable (PF Applicable)
- Purpose: Master switch for the entire unit.
- When to Select: Enable if the branch is registered for EPF. Disable if the branch has less than 20 employees and is not registered.
- Impact: If disabled here, NO employee in this unit will have PF deducted, regardless of their individual Employee Master settings.
esiApplicable (ESI Applicable)
- Purpose: Master switch for ESI in the unit.
- When to Select: Enable if the branch is in an ESI-implemented area. Disable if the branch is in a non-implemented area.
- Impact: If disabled here, NO employee will have ESI deducted.
providentFundMaximumLimit / esiMaximumLimit
- Purpose: Sets the statutory ceilings (e.g., ₹15,000 for PF, ₹21,000 for ESI).

E. Salary Head / Company Head Master

These flags determine how individual salary components (e.g., Basic, HRA, Conveyance) behave.

presenceDependent (Presence Dependence)
- Purpose: Determines if the earning component is prorated based on attendance.
- When to Select: Enable for Basic, DA. Disable for Fixed Allowances (like Internet or Car Allowance) that are paid flat regardless of days worked.
- Impact: If true: (Amount / Month Days) * Attendance Days. If false: Flat Amount.
otGross (OT Gross)
- Purpose: Marks whether an earning head is included when calculating the Overtime rate.
- When to Select: Enable for Basic and DA. Disable for HRA or Special Allowances.
providentFundGrossPart (PF Gross Part)
- Purpose: Indicates if this earning component is legally part of PF Taxable Wages.
- When to Select: Enable for Basic and DA.
employeeStateInsuranceGrossPart (ESI Gross Part)
- Purpose: Indicates if this earning component is legally part of the ESI Gross.
- When to Select: Enable for most earnings (Basic, HRA, Allowances) as per ESI rules.
pfOnNFH / esionnh
- Purpose: Determines if statutory deductions apply to separate National/Festival Holiday (NFH) payouts.

2. Dependency & Hierarchy Flow

To resolve the confusion around flags existing in multiple places, here is the absolute evaluation order the payroll engine follows (Top = Highest Authority):

Statutory Deduction Evaluation Flow (PF & ESI)

Unit Configuration (providentFundApplicable / esiApplicable)
- Is the branch registered?
- If FALSE: Process stops. No deduction for anyone.
- If TRUE: Move to Step 2.
Employee Master (PFApplicable / esiApplicable)
- Is this specific employee eligible?
- If FALSE: Process stops. No deduction for this employee.
- If TRUE: Move to Step 3.
Employee Master / Designation Master (PFBasedOn / esiBasedOn)
- What rule applies to them?
- The engine checks the Employee Master for a custom rule. If it is set to default/empty, it inherits the rule from the employee's Designation Master.
Salary Head Master (pfGrossPart / esiGrossPart)
- Which salary components make up the gross?
- The engine sums up only the heads marked true for these flags to compute the final gross amount.

3. Troubleshooting & Validation Points

Scenario 1: ESI is not deducting for an employee.

Checklist:

Unit Configuration: Is ESI Applicable checked for the employee's unit?
Employee Master: Is ESI Applicable checked in the employee's profile?
Gross Limit: Did the employee's ESI Gross cross the statutory limit (₹21,000) prior to the current contribution cycle?
Salary Head Master: Are the employee's earning heads (e.g., Basic, HRA) marked with ESI Gross Part = true? If none are marked, the ESI Gross will be 0.

Scenario 2: Employee is getting Overtime (OT), but OT amount is too low.

Checklist:

Salary Head Master: Check which heads have OT Gross = true. If only Basic is marked, the hourly rate is derived solely from Basic. If HRA should be included, mark it as OT Gross = true.
Unit Master: Check the OT Multiple field (e.g., is it set to 1.0 or 2.0?).

Scenario 3: An allowance is being reduced when the employee takes leave, but it should be a fixed monthly payout.

Checklist:

Salary Head Master: Find the specific allowance head for that employee/designation.
Uncheck the Presence Dependence flag. This ensures the full amount is paid regardless of attendance days.

Scenario 4: PF is deducting on ₹20,000 instead of being capped at ₹15,000.

Checklist:

Employee Master: Check the PF Based On rule.
If it is set to Actual, it will not cap at ₹15,000. Change it to Basic to enforce the statutory ceiling.

Sub Department Employee Master