# Phase 4 – Employee Master Upload

The Employee Master Upload is the fourth and final phase of the CMS Data Loader workflow.\
This phase enables administrators to bulk-create employees, assign roles, map departments and designations, and configure jurisdiction boundaries for a given tenant.

The upload process follows the same structured validation model as previous phases:

1. HRMS API-Level Validation (Backend Service)

This ensures that only accurate, complete, and compliant employee data is inserted into the system.

## 1. Employee Master Template Overview

The Employee Master Template consists of a single worksheet containing the employee profile, role assignments, and jurisdiction configuration.\
All mandatory fields must be completed before upload. Optional fields are assigned system defaults if left empty.

#### Employee Master Template – Column Definitions

| Column Name                    | Description                               | Mandatory | Example          | Data Type           |
| ------------------------------ | ----------------------------------------- | --------- | ---------------- | ------------------- |
| User Name\*                    | Full name of the employee                 | Yes       | John Doe         | Text (A–Z, spaces)  |
| Mobile Number\*                | Unique 10-digit mobile number             | Yes       | 9876543210       | Numeric (10 digits) |
| Password                       | Login password (default applied if empty) | No        | MyPass\@123      | Text (≥8 chars)     |
| Department Name\*              | Must match Department from Phase-3        | Yes       | WATER DEPARTMENT | Text (Dropdown)     |
| Designation Name\*             | Must belong to Department                 | Yes       | engineer         | Text (Dropdown)     |
| Role Names (comma-separated)\* | Valid system role codes                   | Yes       | GRO,EMPLOYEE     | Text (multi-select) |
| Gender                         | Male/Female/Other                         | No        | Male             | Dropdown            |
| Employee Status                | Employment status                         | No        | EMPLOYED         | Dropdown            |
| Employee Type                  | Type of employee                          | No        | PERMANENT        | Dropdown            |
| Assignment From Date\*         | Start date of assignment                  | Yes       | 05-09-2024       | Date (DD-MM-YYYY)   |
| Date of Appointment\*          | Joining date                              | Yes       | 20-06-2024       | Date (DD-MM-YYYY)   |
| Hierarchy Type                 | Admin hierarchy type                      | No        | ADMIN            | Text                |
| Boundary Type                  | Boundary type for jurisdiction            | No        | City             | Text                |
| Boundary Code                  | Boundary code assigned                    | No        | PG.CITYA         | Text                |

#### System-Generated Fields (Not Present in Excel)

The loader automatically generates:

<table><thead><tr><th width="176.6953125">Attribute</th><th width="366.08984375">Logic</th><th>Example</th></tr></thead><tbody><tr><td>Employee Code</td><td>Name converted to uppercase, spaces → underscores</td><td>JOHN_DOE</td></tr><tr><td>Tenant ID</td><td>Taken from upload session</td><td>pg.citya</td></tr><tr><td>User UUID</td><td>Generated by HRMS</td><td>1fda5623-448a-...</td></tr><tr><td>User Type</td><td>Always "EMPLOYEE"</td><td>EMPLOYEE</td></tr><tr><td>Active Flag</td><td>Always true</td><td>true</td></tr><tr><td>OTP Reference</td><td>System default</td><td>12345</td></tr></tbody></table>

***

## 2. Dynamic Template Generation (Jupyter Notebook)

The Data Loader provides a dynamic template generator to eliminate manual errors.

#### Steps in the Notebook

1. The Administrator enters the Target Tenant ID (e.g., pg.citya).
2. Notebook fetches:
   1. Departments from MDMS
   2. Designations from MDMS
   3. Roles from MDMS
   4. Boundary hierarchy from Boundary Service
3. The system generates a pre-validated Excel with dropdowns.

Template is saved as: `templates/Employee_Master_Dynamic_<tenant>.xlsx`

4. This ensures the template always aligns with the latest MDMS configuration.

***

## 3. Filling the Employee Master Template

#### Mandatory Fields – Validation Rules

<table><thead><tr><th width="285.703125">Field</th><th>Validation</th></tr></thead><tbody><tr><td>User Name</td><td>Text only; no symbols except spaces</td></tr><tr><td>Mobile Number</td><td>10 digits; must be unique</td></tr><tr><td>Department Name</td><td>Must match Phase 3 (case-sensitive)</td></tr><tr><td>Designation Name</td><td>Must belong to selected department</td></tr><tr><td>Role Names</td><td>Comma-separated; valid codes only</td></tr><tr><td>Dates</td><td>Format: DD-MM-YYYY</td></tr></tbody></table>

#### Optional Fields – Default Values

<table><thead><tr><th width="300.76171875">Field</th><th>Default</th></tr></thead><tbody><tr><td>Password</td><td>eGov@123</td></tr><tr><td>Employee Status</td><td>EMPLOYED</td></tr><tr><td>Employee Type</td><td>PERMANENT</td></tr><tr><td>Hierarchy Type</td><td>ADMIN</td></tr><tr><td>Boundary Type</td><td>City</td></tr><tr><td>Boundary Code</td><td>Tenant code</td></tr></tbody></table>

***

## 4. Validation Layers

#### 4.1 HRMS API-Level Validation

API endpoint: `POST /egov-hrms/employees/_create`

Validations include:

* Mobile number uniqueness (DB-level)
* Duplicate employee code
* Invalid jurisdiction boundary
* Invalid role assignment
* Missing or outdated MDMS references

## 5. Processing Employee Upload in Jupyter Notebook

#### Workflow Execution

Upload the filled Excel File.\
The file is saved under: `upload/Employee_Master.xlsx`

1. Notebook Processes Each Row
2. Converts department/designation names → codes
3. Converts roles → role objects
4. Generates employee code
5. Converts dates → Unix timestamps
6. Builds HRMS payload
7. Data Submission to HRMS
8. Sends a structured payload to `/employees/_create`
9. Captures row-wise success/failure
10. Status Update in Excel File

New columns are appended:

<table><thead><tr><th width="283.015625">Column</th><th>Description</th></tr></thead><tbody><tr><td>_STATUS</td><td>SUCCESS / FAILED / EXISTS</td></tr><tr><td>_STATUS_CODE</td><td>201 / 400 / 409 / 500</td></tr><tr><td>_ERROR_MESSAGE</td><td>Detailed message</td></tr></tbody></table>

***

## 6. Employee Upload Error Handling

<table><thead><tr><th width="318.2421875">Error Message</th><th>Reason</th></tr></thead><tbody><tr><td>Department not found</td><td>Incorrect spelling or missing from Phase 3</td></tr><tr><td>Mobile number already exists</td><td>Duplicate in system</td></tr><tr><td>Role not found</td><td>Invalid role code</td></tr><tr><td>Invalid date format</td><td>Not in DD-MM-YYYY format</td></tr><tr><td>Boundary code invalid</td><td>Not matching Phase 2 hierarchy</td></tr></tbody></table>

#### Common Errors & MeaningError File Workflow

1. Download processed file
2. Review FAILED rows
3. Correct only failed records
4. Remove status columns
5. Re-upload the corrected file

The loader automatically skips successful rows.

## 7. Password Management Guidelines

* Default password applied if empty: `eGov@123`
* Custom password must meet security criteria:
* Min 8 characters
* 1 uppercase, 1 lowercase, 1 number, 1 special character

Password update limitations:\
After employee creation, updating the password via Excel is not supported.\
Use HRMS UI for password reset.

## 8. Role & Jurisdiction Assignment

#### Role Assignment

Roles define employee privileges.

Common roles include:

<table><thead><tr><th width="230.8046875">Code</th><th>Description</th></tr></thead><tbody><tr><td>GRO</td><td>Grievance Routing Officer</td></tr><tr><td>CSR</td><td>Customer Service Representative</td></tr><tr><td>EMPLOYEE</td><td>Field/department staff</td></tr></tbody></table>

Multiple roles can be assigned using comma separation.

#### Jurisdiction Assignment

A jurisdiction maps a user to a boundary (city/ward/zone).

If no boundary is entered, the employee is assigned to the entire tenant boundary.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digit.org/complaints-management/complaints-resolution-v2.10/deploy/setup/production-setup/deploy-complaints-management/data-validation-layers/phase-4-employee-master-upload.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.