City Master

Navigation Path

Company → Masters → City Master

1. City List Page

URL

/masters/city-master

Page Description

Displays a list of all cities configured in the system
Shows statutory applicability details per city
Provides actions to add, edit, and delete city records

List Table Columns

Column Name	Description
S No	Serial number
State	State associated with the city
City Name	Name of the city
Central / State	Indicates whether Central or State
Central Type	Central classification type
PF No	PF number mapped to the city
ESI No	ESI number mapped to the city
Is Metro	Indicates whether the city is metro
PT Applicable	Professional Tax applicability
LWF Applicable	Labour Welfare Fund applicability
Actions	Edit and Delete options

Row Actions

Action	Description
Edit	Opens Edit City page with pre-filled data
Delete	Opens delete confirmation alert

2. Add City Page

Triggered From

City List Page → Add City button

Page Description

Allows admins to add a new city under a selected state
Enables statutory and tax-related configuration at city level

Add City – Fields

Field Name	Type	Mandatory	Description
State	Dropdown	Yes	Select or create a state
City Name	Text Input	Yes	Enter the city name
Central / State	Dropdown	Yes	Select Central or State
Central Type	Dropdown	Conditional	Enabled when Central is selected
PF No	Text Input	No	Enter PF number
ESI No	Text Input	No	Enter ESI number
Is Metro	Checkbox	No	Indicates metro city
PT Applicable	Checkbox	No	Enables Professional Tax
LWF Applicable	Checkbox	No	Enables Labour Welfare Fund

Actions

Action	Behavior
Save	Validates and saves the city
Reset	Clears all entered values
Cancel	Returns to City List page

Validation Rules

State selection is mandatory
City Name cannot be empty
Central Type is mandatory if Central is selected
Duplicate city names are not allowed within the same state

3. Edit City Page

/masters/city-master/edit/:id

Triggered From

City List Page → Edit icon

Page Description

Allows updating existing city details
All fields are pre-filled with saved data

Editable Fields

Field Name	Editable
State	Yes
City Name	Yes
Central / State	Yes
Central Type	Yes
PF No	Yes
ESI No	Yes
Is Metro	Yes
PT Applicable	Yes
LWF Applicable	Yes

Actions

Action	Behavior
Update	Saves changes
Cancel	Discards changes and navigates back

4. Delete City Confirmation Alert

Triggered From

City List Page → Delete icon

Alert Content

Confirmation message before deletion

Actions:

Confirm / Yes → Deletes the city
Cancel → Closes the alert without action

Delete Behavior

City is removed permanently after confirmation
If the city is mapped to other records, deletion may be restricted

Field Definitions, Usage, and Calculation Logic

This section provides a technical analysis of the City Master's data structure and its impact on payroll and statutory compliance.

1. Field Definitions

Field Name	Data Type	Description	Example Value
`cityName`	String	Official city name (Required).	`Pune`
`state`	ObjectId	Reference to the parent State Master.	`60d8a...`
`cityCategoryId`	ObjectId	Reference to City Category (A, B, C).	`60d8c...`
`isMetro`	Boolean	Flag for Metro/Non-Metro designation.	`true`
`PTApplicable`	Boolean	If Professional Tax should be deducted.	`true`
`LWFApplicable`	Boolean	If Labour Welfare Fund should be deducted.	`true`
`PFNo`	String	PF number for the city location.	`PN-00123`
`ESINo`	String	ESI number for the city location.	`ESI-45678`

2. Field Usage & System Impact

Category	Validation / Rule	System Behavior
Taxation	`PTApplicable`	Triggers the calculation of Professional Tax based on the state's slab rules.
Welfare	`LWFApplicable`	Includes the employee in LWF contribution cycles (Employer/Employee).
HRA Relief	`isMetro`	Affects Income Tax calculations (50% HRA for Metro, 40% for Non-Metro).
Unique Key	`state` + `cityName`	Prevents duplicate cities within the same state for a specific company.

3. Business & Calculation Logic

The City Master is the primary configuration point for locale-based salary logic:

A. Professional Tax (PT) & LWF Logic

The system uses the PTApplicable and LWFApplicable flags as master switches. If these are set to false, no deductions will occur for employees assigned to this city, even if they meet the salary thresholds defined in the state slabs.

B. Bulk Import & Data Normalization

The /all-in-one-city-import endpoint automates city-state mapping:

Auto-State Creation: If the provided State in Excel doesn't exist, the system initializes a new State record (Parent Country: INDIA).
Data Casting: Excel values for lwf_applicable and pt_applicable (often 1 or 0) are atomically cast to Boolean true/false.
Defaulting: Imported cities are defaulted to centralOrState: 'State' and isMetro: false unless explicitly updated later.

C. Relational Hierarchy

City records are heavily indexed (state, cityCategoryId) to ensure rapid lookups during employee document creation. Deletion is restricted if active Units or Deployments are currently mapped to the city.

The City Master module interacts with the following API endpoints:

Base URL

export const CITYMASTER_URL = '/api/salaryCityMaster'

Endpoints

Endpoint	Method	Description	Parameters/Body
`${CITYMASTER_URL}`	POST	Create a new city	Body: `data`
`${CITYMASTER_URL}`	GET	Get all cities	Query: `page`, `limit`
`${CITYMASTER_URL}/:cityId`	GET	Get city by ID	Path: `cityId`
`${CITYMASTER_URL}/search`	GET	Search city masters	Query: `cityName`, `page`, `limit`
`${CITYMASTER_URL}/:cityId`	PATCH	Update an existing city	Path: `cityId`, Body: `body`
`${CITYMASTER_URL}/delete/:cityId`	PATCH	Delete a city	Path: `cityId`

RTK Query Hooks

The following hooks are available for frontend integration:

useCreateCityMutation
useGetAllCitiesQuery
useGetCityByIdQuery
useSearchCityMastersQuery
useUpdateCityMutation
useDeleteCityMutation

End of Documentation

District Industry Type