Managing Employees

Complete guide to viewing, searching, and managing employee records in HCMatrix

Overview

The employee management module is the heart of HCMatrix. This guide covers how to view, search, filter, and navigate employee records efficiently.

Viewing Employees

1. Access Employee Directory

   Navigate to the Employees page from the sidebar. The system automatically fetches your employee list:

   // From: ~/workspace/source/app/employees/page.tsx:25-30
   const fetchEmployees = async (page: number = 1, query: string = '') => {
     const token = auth.getToken()
     if (!token) {
       router.push('/auth/login')
       return
     }
   
2. View Employee List

   Employees are displayed in a paginated table with key information:

   • Name & Email - Employee identification
   • Job Title - Current position
   • Department - Organizational unit
   • Location - Work location
   • Status - Employment status (Active, Onboarding, On Leave, etc.)
3. Understand Status Badges

   Employee status is color-coded for quick identification:

   // From: ~/workspace/source/app/employees/page.tsx:99-115
   const statusMap: Record<string, { bg: string; text: string }> = {
     active: { bg: 'bg-green-100', text: 'text-green-700' },
     onboarding: { bg: 'bg-yellow-100', text: 'text-yellow-700' },
     'on leave': { bg: 'bg-orange-100', text: 'text-orange-700' },
     inactive: { bg: 'bg-gray-100', text: 'text-gray-700' },
     terminated: { bg: 'bg-red-100', text: 'text-red-700' },
   }
   

   • 🟢 Green - Active employees
   • 🟡 Yellow - Onboarding in progress
   • 🟠 Orange - On leave
   • ⚪ Gray - Inactive
   • 🔴 Red - Terminated

Searching Employees

HCMatrix provides powerful search functionality with real-time results:

1. Use Search Bar

   Enter any search term in the search field at the top of the employee list. You can search by:

   • Employee name
   • Email address
   • Job title
2. Debounced Search

   The search automatically triggers 500ms after you stop typing to reduce server load:

   // From: ~/workspace/source/app/employees/page.tsx:69-81
   const handleSearch = (e: React.ChangeEvent<HTMLInputElement>) => {
     const value = e.target.value
     setSearchQuery(value)
     setCurrentPage(1)
   
     if (debounceTimer.current) {
       clearTimeout(debounceTimer.current)
     }
   
     debounceTimer.current = setTimeout(() => {
       fetchEmployees(1, value)
     }, 500)
   }
   
3. API Search Request

   Search queries are sent to the API with the name parameter:

   // From: ~/workspace/source/lib/api.ts:246-260
   async searchEmployees(
     token: string,
     query: Record<string, string>,
     page: number = 1
   ): Promise<EmployeesResponse> {
     const params = { ...query, page: page.toString() }
     const queryString = new URLSearchParams(params).toString()
     const response = await apiCall<any>(
       `/api/v1/employee?${queryString}`,
       'GET',
       undefined,
       token
     )
     return normalizeEmployeesResponse(response, page)
   }
   

Search is case-insensitive and supports partial matches. Type “john” to find “John Smith”, “Johnny Doe”, etc.

Pagination

Employee lists are paginated for performance:

Navigating Pages

// From: ~/workspace/source/app/employees/page.tsx:83-97
const handleNextPage = () => {
  if (pagination?.hasNext) {
    const next = currentPage + 1
    setCurrentPage(next)
    fetchEmployees(next, searchQuery)
  }
}

const handlePrevPage = () => {
  if (pagination?.hasPrev) {
    const prev = currentPage - 1
    setCurrentPage(prev)
    fetchEmployees(prev, searchQuery)
  }
}

Pagination Controls

The bottom of the employee table shows:

• Current page number
• Total number of pages
• Previous/Next navigation buttons
• Buttons are automatically disabled when at first/last page

Fetching Employee Data

Get Paginated Employees

// From: ~/workspace/source/lib/api.ts:214-230
async getEmployees(
  token: string,
  page: number = 1,
  params?: Record<string, string>
): Promise<EmployeesResponse> {
  const queryString = new URLSearchParams({
    page: page.toString(),
    ...params,
  }).toString()
  const response = await apiCall<any>(
    `/api/v1/employee?${queryString}`,
    'GET',
    undefined,
    token
  )
  return normalizeEmployeesResponse(response, page)
}

Get Single Employee Details

// From: ~/workspace/source/lib/api.ts:233-243
async getEmployee(token: string, id: number): Promise<EmployeeDetail> {
  const response = await apiCall<any>(
    `/api/v1/employee/${id}`,
    'GET',
    undefined,
    token
  )
  const raw = response.data || response
  return mapEmployeeDetail(raw)
}

Employee Data Structure

Basic Employee Interface

// From: ~/workspace/source/lib/api.ts:26-38
export interface Employee {
  id: number
  name: string
  email: string
  job_title: string
  department: string
  location: string
  employment_type: string
  status: string
  start_date: string
  avatar?: string
  [key: string]: any
}

Detailed Employee Interface

// From: ~/workspace/source/lib/api.ts:49-62
export interface EmployeeDetail extends Employee {
  phone: string
  date_of_birth: string
  address: string
  salary: number
  manager: string
  manager_id: number
  next_of_kin_name: string
  next_of_kin_relationship: string
  next_of_kin_phone: string
  tenure_years: number
  tenure_months: number
  spouse: string | null
}

Viewing Employee Details

Click on any employee name in the table to view their full profile:

// From: ~/workspace/source/app/employees/page.tsx:199-202
<Link href={`/employees/${employee.id}`} className="block">
  <p className="font-bold text-blue-600 group-hover:text-blue-700 transition-colors">
    {employee.name || 'N/A'}
  </p>
</Link>

The detail view shows:

• Contact information (phone, email, address)
• Employment details (job title, department, manager)
• Compensation information
• Emergency contact (next of kin)
• Tenure information

Exporting Employee Data

The “Export to CSV” button allows you to download employee data for external analysis:

// From: ~/workspace/source/app/employees/page.tsx:151-154
<Button variant="outline">
  <Download className="w-4 h-4" />
  Export to CSV
</Button>

Export functionality respects current search filters - only visible employees are exported.

Error Handling

The system handles various error scenarios:

// From: ~/workspace/source/app/employees/page.tsx:56-62
catch (err) {
  const errorMsg = err instanceof Error ? err.message : 'Failed to load employees'
  setError(errorMsg)
  setEmployees([])
} finally {
  setIsLoading(false)
}

Errors are displayed prominently at the top of the page with clear messaging.

Loading States

While fetching data, the system shows a loading spinner:

// From: ~/workspace/source/app/employees/page.tsx:165-171
{isLoading ? (
  <div className="flex items-center justify-center p-20">
    <div className="text-center">
      <div className="inline-block animate-spin rounded-full h-10 w-10 border-b-2 border-blue-600"></div>
      <p className="mt-4 text-gray-500 font-medium">Loading employees...</p>
    </div>
  </div>
) : ...}

Empty States

When no employees match your search, a helpful empty state is displayed:

// From: ~/workspace/source/app/employees/page.tsx:172-181
{employees.length === 0 ? (
  <div className="flex items-center justify-center p-20">
    <div className="text-center">
      <div className="bg-gray-50 w-16 h-16 rounded-full flex items-center justify-center mx-auto mb-4">
        <Users className="w-8 h-8 text-gray-300" />
      </div>
      <p className="text-gray-900 font-bold mb-1">No employees found</p>
      <p className="text-sm text-gray-500">Try adjusting your search criteria</p>
    </div>
  </div>
) : ...}

Next Steps

• Tracking Attendance - Monitor employee time
• Processing Payroll - Manage compensation
• Recruiting Workflow - Hire new talent
• Generating Reports - Analyze employee data