Formula Master
Navigation Path
Company → Masters → Formula Master
1. Formula List Page
URL
/masters/formula-master
Page Description
- Displays a list of all formulas configured in the system
- Allows admins to manage calculation formulas used across payroll and statutory modules
- Displays associated salary heads for reference
- Provides actions to add, edit, and delete formulas
List Table Columns
| Column Name | Description |
|---|---|
| S No | Serial number |
| Description | Formula description |
| Formula | Calculation formula |
| Limit | Maximum applicable limit |
| Actions | Edit and Delete options |
Row Actions
| Action | Description |
|---|---|
| Edit | Opens Edit Formula page with pre-filled data |
| Delete | Opens delete confirmation alert |
2. Add Formula Page
Triggered From
Formula List Page → Add Formula button
Page Description
- Allows admins to create a new calculation formula
- Formula can reference predefined heads from the Head List
Add Formula – Fields
| Field Name | Type | Mandatory | Description |
|---|---|---|---|
| Description | Text Input | Yes | Enter formula description |
| Formula | Text Input | Yes | Enter calculation formula |
| Limit | Number Input | No | Define maximum limit for the formula |
Actions
| Action | Behavior |
|---|---|
| Save | Validates and saves the formula |
| Reset | Clears all entered values |
| Cancel | Returns to Formula List page |
Validation Rules
- Description is mandatory
- Formula is mandatory
- Formula syntax must be valid
- Duplicate formula descriptions are not allowed
3. Head List Reference Table
Description
- Displays available heads that can be used while defining formulas
- Used as a reference for building formula expressions
Head List Table Columns
| Column Name | Description |
|---|---|
| H ID | Head identifier |
| Description | Head description |
| Type | Head type (Earning / Deduction) |
4. Edit Formula Page
Triggered From
Formula List Page → Edit icon
Page Description
- Allows updating existing formula details
- All fields are pre-filled with saved data
Editable Fields
| Field Name | Editable |
|---|---|
| Description | Yes |
| Formula | Yes |
| Limit | Yes |
Actions
| Action | Behavior |
|---|---|
| Update | Saves changes |
| Cancel | Discards changes and navigates back |
5. Delete Formula Confirmation Alert
Triggered From
Formula List Page → Delete icon
Alert Content
- Confirmation message before deletion
Actions:
- Confirm / Yes → Deletes the formula
- Cancel → Closes the alert without action
Delete Behavior
- Formula is removed permanently after confirmation
- Deletion may be restricted if the formula is already in use
Field Definitions, Usage, and Calculation Logic
This section provides a technical analysis of the Formula Master's data structure and its role as the payroll calculation engine.
1. Field Definitions
| Field Name | Data Type | Description | Example Value |
|---|---|---|---|
formulaDescription | String | User-facing name of the formula. | HRA @ 50% of Basic |
formula | String | The mathematical expression (Regex Validated). | ("BASIC" * 50) / 100 |
limit | Number | Maximum allowable value for the result. | 15000 |
companyId | ObjectId | Reference to the parent Company. | 60a8b... |
2. Field Usage & System Impact
| Category | Validation / Rule | System Behavior |
|---|---|---|
| Syntax | allowedPattern | Regex: /^[\d\s+\-*\/()"]+$/. Only numbers, operators, and double quotes are allowed. |
| Variables | "HEAD_NAME" | Strings in double quotes are anchors for other salary head values. |
| Capping | limit | If the calculated value exceeds this number, the system truncates it to the limit. |
3. Business & Calculation Logic
The Formula Master is the "Logic Hub" for the payroll module:
A. Formula Validation Engine
The backend enforces strict schema-level validation to prevent code injection via formulas. The validate hook in the model ensures that no alphabetical characters outside of double-quoted head references are saved.
B. Execution Flow (Runtime)
When the payroll engine processes a salary slip:
- Head Retrieval: It fetches the list of all earnings and deductions for the employee.
- Anchor Replacement: It replaces tokens like
"BASIC"or"DA"in the formula string with their evaluated numeric values. - Math Evaluation: The resulting string (e.g.,
(15000 * 50) / 100) is safe-evaluated to derive the component value. - Limit Check: If a
limitis defined (e.g.,PFlimit of1800), the engine appliesMath.min(calculatedValue, limit).
C. Relational Dependencies
Formulas are multi-tenant. A formula created by Company A is not visible to Company B. If a salary head is deleted, any formulas referencing that head name (in quotes) will fail during payroll execution, necessitating a manual update to the formula master.
The Formula Master module interacts with the following API endpoints:
Base URL
export const FORMULAMASTER_URL = '/api/salaryFormulaMaster'
Endpoints
| Endpoint | Method | Description | Parameters/Body |
|---|---|---|---|
${FORMULAMASTER_URL} | POST | Create a new formula | Body: data |
${FORMULAMASTER_URL} | GET | Get all formulas | Query: page, limit |
${FORMULAMASTER_URL}/:formulaId | GET | Get formula by ID | Path: formulaId |
${FORMULAMASTER_URL}/:formulaId | PATCH | Update an existing formula | Path: formulaId, Body: body |
${FORMULAMASTER_URL}/delete/:formulaId | PATCH | Delete a formula | Path: formulaId |
RTK Query Hooks
The following hooks are available for frontend integration:
useCreateFormulaMutationuseGetAllFormulasQueryuseGetFormulaByIdQueryuseUpdateFormulaMutationuseDeleteFormulaMutation
End of Documentation