Salary Head Master

The Salary Head Master is the core configuration layer where generic company-wide heads (defined in CompanyHeadMaster) are instantiated and customized for specific Units and Designations. It defines exactly how much an employee earns or is deducted, and how those amounts interact with statutory rules (PF/ESI/OT).

Navigation Path

Company → Masters → Head Master

1. Salary Head List Page

URL

/masters/head-master

Page Description

Displays a consolidated view of Earnings and Deductions scoped to specific Units and Designations.
Supports Inline Editing for quick amount adjustments.
Features Statutory Flag Toggles (PF, ESI, etc.) directly within the table rows for rapid configuration.
Implements a Virtual Row Engine to suggest missing heads based on company templates.

Filter & Search Section

Field Name	Type	Description
Unit	Searchable Dropdown	Filters heads by a specific business unit. Supports infinite scrolling.
Designation	Creatable Dropdown	Filters by role. Allows creating new designations on-the-fly if not found.
Head Type	Dropdown	Filters by category: Earnings, Deduction, Over Time, Bonus, Reimbursement, etc.
Description	Text Input	Search for a specific head by its name or description.

Actions:

Clear → Resets all filters and reloads the default list.
Search → Automatically triggers as values are selected/typed (Debounced).

List Table Columns

Column Name	Description
S No	Serial number.
Description	Name of the salary component (e.g., Basic, HRA, PF).
Amount	The monetary value. Editable Inline for established records.
Actions	Includes the Edit icon and several Statutory Flag Toggles.

Row Actions & Status Toggles

These buttons allow instant updates to the calculation behavior of a specific head:

Toggle	Name	Purpose
PF	Provident Fund	Toggles `providentFundGrossPart`. If green, the head contributes to PF gross.
ESI	ESI	Toggles `esiGrossPart`. If green, the head contributes to ESI gross.
PD	Presence Dependent	If active, the amount is pro-rated based on attendance (Worked Days).
OT	Overtime	If active, the head is included in the base for Overtime calculations.
NFH	National Holiday	Inclusion in base for National Festival Holiday pay.

2. Head Master Configuration (Add/Edit)

Triggered From

Virtual Row → Create Button: To instantiate a template head for a specific destination.
Table Row → Edit Icon: To open the detailed configuration form.

Page Description

Provides granular control over how a head is calculated (Fixed Amount vs. Formula).
Allows mapping to statutory sections and setting display priorities.

Key Configuration Fields

Field Name	Type	Mandatory	Description
Description	Text Input	Yes	Full name of the salary component.
Amount	Number	Yes*	Fixed value. (*Mutually exclusive with Formula).
Formula	Dropdown	No	Reference to a `Formula Master` definition.
Display Order	Number	No	Sorting sequence in UI and Salary Register.
Active	Checkbox	Yes	Enables/Disables the head from payroll processing.
Mapping	Checkbox	Yes	Controls ledger mapping for accounting integration.

Validation Rules

Mutual Exclusivity: A head cannot have both a fixed Amount and a Formula assigned.
Uniqueness: The system prevents creating duplicate heads for the same { Unit, Designation, Template } combination.
Unit Constraints: Heads defined at the Unit level (null designation) often enforce Amount: 0 via backend defaults, requiring formula-based calculations.

Field Definitions, Usage, and Calculation Logic

1. Technical Field Definitions

Field Name	Data Type	Description
`companyHeadId`	ObjectId	Reference to the template head definition (`CompanyHeadMaster`).
`unitId`	ObjectId	Scopes the head to a specific physical unit/location.
`designationId`	ObjectId	Scopes the head to a specific role. Records with `null` designation are "Unit-level" constants.
`salaryRegisterShowFlag`	Boolean	Determines if this head appears as a separate column in the final Salary Register.
`blockSummation`	Boolean	If `true`, the head is informational and does not add to the "Gross Salary" total.

2. Business Logic & System Behavior

A. The "Virtual Row" Engine

To prevent redundant data entry, the frontend (HeadMasterTable.jsx) uses a merging logic:

Missing Heads: The UI compares the list of templates in CompanyHeadMaster against existing SalaryHeadMaster records for the selected Unit and Designation.
Dynamic Display: Template-only items are shown as "Virtual Rows" (highlighted in yellow).
Auto-Initialization: Entering an amount or clicking "Create" on a Virtual Row triggers a POST request that instantiates the database record.

B. Bulk Operation Logic

Excel Import: Supports broad mappings. The import engine can auto-create State and Category if they are missing in the referenced sheet.
Bulk Creation: When a new Designation is saved, the system can automatically seed all active template heads into the SalaryHeadMaster for that designation using the useCreateHeadsUsingUnitsAndDesignationMutation.

API Endpoints

Base URL

export const SALARYHEADMASTER_URL = '/api/salaryHeadMaster'

Endpoints

Endpoint	Method	Description	Parameters/Body
`${SALARYHEADMASTER_URL}`	POST	Create a new Salary Head	Body: `data`
`${SALARYHEADMASTER_URL}`	GET	Get all active heads	Query: `page`, `limit`
`${SALARYHEADMASTER_URL}/search`	POST	Multi-criteria search	Body: `{ unitId, designationName, exportType }`
`${SALARYHEADMASTER_URL}/:id`	PATCH	Update amount or flags	Path: `id`, Body: `data`
`${SALARYHEADMASTER_URL}/delete/:id`	PATCH	Soft delete a head	Path: `id`
`${SALARYHEADMASTER_URL}/import/heads`	POST	Bulk Excel Import	Multipart: `file`

RTK Query Hooks

The following hooks are available for frontend integration (from salaryHeadMasterApiSlice.js):

useCreateSalaryHeadMasterMutation
useUpdateSalaryHeadMasterMutation
useSearchSalaryHeadMasterMutation
useImportSalaryHeadsMutation
useCreateHeadsUsingUnitsAndDesignationMutation

End of Documentation

Bank Master LWF Slab Master