Employee Master

Navigation Path

Company → Employee → Employee Master

Employee Master Page

URL

/employee/employee-master

Page Description

Used to add new employees and edit existing employee details
Editing is performed by searching using an existing Employee Code
Employee records cannot be deleted from the system

1. Add New Employee

Description

Allows administrators to create a new employee record
Employee Code acts as a unique identifier

Add Employee – Fields

Basic Information

Field Name	Description
Employee Code	Unique employee identifier
Name	Employee full name
Father Name	Father’s name
Mother Name	Mother’s name
Gender	Select gender
Category	Select or create category
Religion	Select or create religion
Marital Status	Select marital status
Spouse Name	Enter spouse name (if applicable)
Date of Birth	Select birth date

Posting & Organization Details

Field Name	Description
Posting State	Select or create state
Posting City	Select or create city
Department	Select department
Sub Department	Enter sub department
Unit	Select or create unit
Designation	Select designation
Nature Type	Select nature type
Stationed At	Select stationed location
Role	Enter role
Qualification	Enter qualification
Grade	Select or create grade

Contact & Identity Details

Field Name	Description
PAN Number	Enter PAN number
Aadhaar Card No	Enter Aadhaar number
Email ID	Enter email
Mobile Number	Enter mobile number

Bank & Payment Details

Field Name	Description
Payment Mode	Bank Transfer
Bank	Select or create bank
Account Number	Enter account number
IFSC Code	Enter IFSC code
Bank Reference No	Enter bank reference number

Employment Dates

Field Name	Description
Date of Joining	Select joining date
Date of Confirmation	Select confirmation date
SAF Start Date	Select SAF start date
Contract End Date	Select contract end date
Resign Date	Select resignation date
Leaving Date	Select leaving date
Leaving Reason	Enter leaving reason
Reason for Leave	Enter leave reason

Statutory & Salary Configuration

Field Name	Description
PF Applicable	Enable/Disable PF
PF Based On	Basic
PF No	Enter PF number
UAN No	Enter UAN number
ESI Applicable	Enable/Disable ESI
ESI Type	Select ESI type
ESI No	Enter ESI number
Bonus Applicable	Enable/Disable bonus
Bonus Based On	Select bonus rule
Professional Tax	Enable/Disable
Pension PF Applicable	Enable/Disable
Voluntary PF Applicable	Enable/Disable
Voluntary PF Type	Percent / Amount
VOL PF Percent / Amt	Enter value
LWF Applicable	Enable/Disable
AC10 Not Applicable	Enable/Disable
ESIONNH	Enable/Disable

Additional Payroll Settings

Field Name	Description
Site Allowance	Amount per month
Fooding Deduction	Percentage or amount
OT As Per	Select OT type
Site Increment Applicable	Enable/Disable
Appraisal Applicable	Enable/Disable
Approve Appraisal Through Reporting Manager	Yes/No
Approve Appraisal Through Site Manager	Yes/No
CTC Structure as per HO	Yes/No
Make Salary Site Based	Yes/No
GPA Amount	Enter GPA amount
Trust Deduction Amount	Enter amount
CTC / BASIC	Enter amount
Stop Salary	Yes/No
Head Mapping	Using unit heads
Total Earnings	Auto-calculated
Total Deductions	Auto-calculated

Actions

Action	Behavior
Save	Validates and saves employee record
Reset	Clears all entered values
Cancel	Navigates away from the page

2. Edit Existing Employee

Description

Editing is done within the same Employee Master page
Admin enters an existing Employee Code and performs search
All employee details are auto-filled for update

Edit Flow

Enter existing Employee Code
Click Search
Employee details are populated
Update required fields
Click Save

Edit Rules

Employee Code cannot be changed
All other fields are editable
Deletion of employee records is not allowed

API Endpoints

The Employee Master module interacts with the following API endpoints:

Base URL

export const EMPLOYEEMASTER_URL = '/api/salaryEmployeeMaster'

Endpoints

Endpoint	Method	Description	Parameters/Body
`EMPLOYEEMASTER_URL`	POST	Create a new salary employee	Body: `data`
`EMPLOYEEMASTER_URL`	GET	Get all salary employees with pagination	Query: `page`, `limit`
`EMPLOYEEMASTER_URL/:salaryEmployeeId`	GET	Get salary employee by ID	Path: `salaryEmployeeId`
`EMPLOYEEMASTER_URL/:salaryEmployeeId`	PATCH	Update an existing salary employee	Path: `salaryEmployeeId`, Body: `body`
`EMPLOYEEMASTER_URL/delete/:salaryEmployeeId`	PATCH	Delete a salary employee (soft delete)	Path: `salaryEmployeeId`
`EMPLOYEEMASTER_URL/managers`	GET	Get manager employees	Query: `managerType`, `page`, `limit`
`EMPLOYEEMASTER_URL/search/employee`	POST	Search employees	Body: `data` (search criteria)
`EMPLOYEEMASTER_URL/export/employee`	GET	Export all employees to Excel	Returns: Excel file (blob)
`EMPLOYEEMASTER_URL/search/export/configurations`	POST	Search and export employees to Excel	Body: `data` (search criteria), Returns: Excel file (blob)
`EMPLOYEEMASTER_URL/import/employee/configurations`	POST	Import employee configurations	Body: `data` (file/data)
`EMPLOYEEMASTER_URL/import/employee/heads`	POST	Import employee heads	Body: `data` (file/data)
`EMPLOYEEMASTER_URL/export/employee/heads`	POST	Export employee heads	Body: `data`, Returns: Excel file (blob)
`EMPLOYEEMASTER_URL/import/new-joining-employees`	POST	Import new joining employees	Body: `data` (file/data)
`EMPLOYEEMASTER_URL/import/from-exported-sheet/employee`	POST	Import employees from exported sheet	Body: `data` (file/data)
`EMPLOYEEMASTER_URL/import/from-exported-sheet/employee-heads`	POST	Import employee heads from exported sheet	Body: `data` (file/data)
`EMPLOYEEMASTER_URL/bulk-update/left-status`	POST	Bulk update employee left status	Body: `data` (array of employee IDs and status)

RTK Query Hooks

The following hooks are available for frontend integration:

useCreateSalaryEmployeeMutation
useGetAllSalaryEmployeesQuery
useGetSalaryEmployeeByIdQuery
useUpdateSalaryEmployeeMutation
useDeleteSalaryEmployeeMutation
useSearchEmployeeMutation
useImportDataEmployeeMutation
useExportToExcelEmployeeQuery
useSerachAndExporToExcelEmployeeMutation
useImportEmployeeHeadsMutation
useSearchAndExportEmployeeHeadsMutation
useGetManagerEmployeesQuery
useImportNewJoiningEmployeesMutation
useImportEmployeesFromExportedSheetMutation
useImportEmployeeHeadsFromExportedSheetMutation
useBulkUpdateEmployeeLeftStatusMutation

Field Definitions, Usage, and Calculation Logic

This section provides a technical deep-dive into the Employee Master's data structure, validation ecosystem, and business logic governing payroll and statutory compliance.

1. Field Definitions

The Employee Master is the primary entity for personnel management, partitioned by companyId and unitId.

A. Basic & Identity Information

Field Name	Technical Name	Data Type	Description	Example Value
Employee Code	`empCode`	String	Unique system identifier.	`WS00123`
Manual Code	`manualEmpCode`	String	Legacy identifier from previous systems.	`E-554`
Aadhaar Card	`adhaarCardNumber`	String	12-digit UID (Unique for active employees).	`123456789012`
PAN Number	`panNumber`	String	10-char alphanumeric (Unique for active).	`ABCDE1234F`
Gender	`gender`	String	Male, Female, Other.	`Male`

B. Organizational Mapping

Field Name	Technical Name	Data Type	Description
Unit	`unitId`	ObjectId	Reference to the operational Unit (Mandatory).
Designation	`designationId`	ObjectId	Reference to `SalaryDesignationMaster`.
Department	`departmentId`	ObjectId	Reference to `departmentMaster`.
Stationed At	`stationedAt`	ObjectId	Geographical reporting location.

C. Statutory & Salary Configuration

Field Name	Technical Name	Data Type	Description
Basic Salary	`basicSalary`	Number	Fixed monthly basic pay amount.
CTC / Total Comp	`currentTotalCompensation`	Number	Total Cost to Company (if based on CTC).
PF Applicable	`providentFundApplicable`	Boolean	Enables PF calculation for this employee.
PF Based On	`PFBasedOn`	Enum	`Basic`, `Actual`, `Manual`, `Conditional`.
AC10 N/A	`ac10NotApplicable`	Boolean	Skips Pension (Account 10) contribution.
ESI Based On	`esiBasedOn`	Enum	`Asper Rule`, `Manual`, `Gross`, `Derived`.

2. Field Usage & Validation Rules

Category	Validation / Rule	System Behavior
Uniqueness	Partial Indexing	`panNumber`, `adhaarCardNumber`, and `bankAccountNumber` are strictly unique among Active employees within a company to prevent ghost payroll.
Banking	IFSC Regex	Must match `^[A-Za-z]\{4\}0[A-Za-z0-9]\{6\}$` (Standard RBI format).
RBAC	Unit Access Control	Users can only view/edit employees within Units authorized via `unitAccessPlugin`.
Integrity	Soft-Delete	Deletion sets `isDeleted.status` to `true`. Permanent deletion is blocked if the employee has historical salary records.

3. Relationships & Dependencies

Aadhaar Linking: The system uses Aadhaar as a bridge to legacy records. If a "new" employee is created with an existing Aadhaar, the system automatically attempts to transfer unpaid loans from the old record.
Head Mapping: The isHeadMapping flag determines whether the employee uses the Unit-level default salary distribution or has custom head overrides unique to their profile.

4. Calculation Logic

A. Statutory PF (Provident Fund)

The logic follows the PFBasedOn selection:

Basic: Calculated as 12% of the Basic Salary.
Actual: Calculated after daily-rate normalization: (FullAmount / MonthDays) * AttendanceDays.
Contribution Capping:
- If pfGross > providentFundMaximumLimit (typically ₹15,000), the taxable wages are capped.
- Pension (AC10): Calculated only if employeeAge < 58 and ac10NotApplicable is false.

B. Total Summarization

Total compensation is dynamically calculated across the system:

Total Earnings = Σ (Active Earnings Heads)
Total Deductions = Σ (Active Deduction Heads) + Statutory PF/ESI/PT
Net Pay = Total Earnings - Total Deductions

C. Loan-to-Employee Transfers

Enabled via a post('save') Mongoose hook:

Trigger: New employee creation.
Scan: Find non-deleted employees with the same adhaarCardNumber.
Migration: Any pending LoanMaster records (status != 'COMPLETED') are updated with the new employeeId and marked as isTransferred: true.

5. Data Flow (Lifecycle)

From UI/Excel to Database

Ingress: User submits form or uploads Excel.
Normalization:
- Dates (e.g., Joining Date) are normalized to DD/MM/YYYY.
- Shorthand Codes (e.g., 'Y' for PF Applicable) are cast to Booleans.
Pre-Save Middleware: Checks for record uniqueness and branch permissions.
Persist: Saves the primary record in SalaryEmployeeMaster.
Head Cloning: The system searches CompanyHeadMaster and creates a mirrored set in EmployeeHead (linked to the New Employee ID).
Audit: Changes are logged in the logger system with "Old" and "New" value diffs.

End of Technical Documentation

Sub Department Application Approve