docs/security/EMPLOYEE_SYSTEM_USER_INTEGRATION.md

Employee System User Integration

Overview

This document describes the implementation of automatic system user creation when an employee is created with the is_system_user flag set to true.

Implementation Details

1. Schema Changes

Employee Create Schema (EmployeeCreate)

• Added is_system_user: bool field with default value False
• When set to True, triggers system user creation after employee creation

Employee Update Schema (EmployeeUpdate)

• Added is_system_user: Optional[bool] field for updates

Employee Response Schema (EmployeeResponse)

• Added is_system_user: bool field to include in responses

Employee Model (EmployeeModel)

• Added is_system_user: bool field for database storage

2. Service Layer Changes

Employee Service (EmployeeService)

Modified create_employee method:

• After successful employee creation, checks if is_system_user is True
• If true, calls _create_employee_system_user method
• System user creation failure doesn't fail employee creation (logged as error)

Added _create_employee_system_user method:

• Creates a system user in the SCM_SYSTEM_USERS collection
• Generates username from employee code (lowercase, hyphens → underscores)
• Creates temporary password with format Temp@{random_token}
• Maps employee designation to role_id
• Stores employee metadata in system user record

3. System User Creation Logic

When is_system_user=True, the following system user is created:

{
    "username": "emp_test_001",  # from employee_code
    "email": "employee@company.com",  # same as employee
    "password": "Temp@{random}",  # temporary password
    "full_name": "First Last",  # from employee name
    "role_id": "role_asm",  # from designation
    "merchant_id": "created_by_value",  # from created_by
    "metadata": {
        "employee_user_id": "usr_xxx",
        "employee_code": "EMP-TEST-001",
        "designation": "ASM",
        "created_from": "employee_creation"
    }
}

4. Role Mapping

Employee designations are mapped to system user roles:

• ASM → role_asm
• SALES_EXECUTIVE → role_sales_executive
• etc.

5. Error Handling

• System user creation errors are logged but don't fail employee creation
• Employee record is always created successfully
• System user creation can be retried separately if needed

Usage Examples

Creating Employee with System User

employee_data = EmployeeCreate(
    employee_code="EMP-MUM-001",
    first_name="John",
    last_name="Doe",
    email="john.doe@company.com",
    phone="+919876543210",
    designation=Designation.ASM,
    base_city="Mumbai",
    base_state="Maharashtra",
    doj=date.today(),
    emergency_contact={
        "name": "Jane Doe",
        "relation": "Spouse",
        "phone": "+919876543211"
    },
    is_system_user=True,  # This triggers system user creation
    created_by="admin_001"
)

employee = await EmployeeService.create_employee(employee_data)

Creating Employee without System User

employee_data = EmployeeCreate(
    # ... same fields ...
    is_system_user=False,  # No system user created
    created_by="admin_001"
)

employee = await EmployeeService.create_employee(employee_data)

API Response

The employee response now includes the is_system_user field:

{
    "user_id": "usr_01HZQX5K3N2P8R6T4V9W",
    "employee_code": "EMP-MUM-001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@company.com",
    "designation": "ASM",
    "is_system_user": true,
    "status": "onboarding",
    "created_by": "admin_001",
    "created_at": "2023-01-10T08:00:00Z"
}

Testing

Use the provided test script to verify the functionality:

cd cuatrolabs-scm-ms
python test_employee_system_user_creation.py

Security Considerations

1. Temporary Passwords: System users are created with temporary passwords that should be changed on first login
2. Role Mapping: Ensure proper role mapping for security permissions
3. Metadata Tracking: Employee-system user relationship is tracked via metadata
4. Error Isolation: System user creation failures don't affect employee creation

Future Enhancements

1. Email Notifications: Send temporary password via secure email
2. Role Customization: Allow custom role assignment during employee creation
3. Bulk Operations: Support bulk employee creation with system users
4. Audit Trail: Enhanced logging for system user creation events