Employee Management

Timesheet provides comprehensive employee management capabilities designed for Australian businesses. This includes employee profiles, role assignments, location management, and award compliance.

Overview

The employee management system consists of several key components:

• Employee Profiles - Personal details, contact information, and employment data
• Role Assignments - Linking employees to specific roles at specific locations
• Location Management - Assigning employees to work locations with geofencing
• Award Integration - Australian award wages and employment type compliance
• Photo Management - Employee photos for identification and security

Key Features

Multi-Location Support

• Assign employees to multiple locations
• Location-based geofencing for clock-in restrictions
• Role assignments specific to each location
• Location-based reporting and analytics

Role-Based Access Control

• Granular permissions based on employee roles
• Manager roles with limited employee access
• Admin roles with full system access
• Custom role definitions with specific permissions

Australian Compliance

• Modern award integration with penalty rates
• Employment type tracking (casual, part-time, full-time)
• Standard hours per week configuration
• Leave entitlements and TOIL tracking

Advanced Features

• Face detection for secure clock-in/out
• Offline mode support for remote locations
• Bulk employee operations and imports
• Automated email onboarding
• Employee photo synchronisation

Employee Data Structure

Core Employee Fields

Employment Fields

Authentication Fields

Role Assignment System

Employee Role Assignments

Role assignments link employees to specific roles at specific locations:

interface IEmployeeRoleAssignment {
  employeeId: ObjectId      // Reference to Employee
  roleId: ObjectId          // Reference to Category (type=role)
  locationId: ObjectId      // Reference to Category (type=location)
  validFrom: Date           // Assignment start date
  validTo: Date | null      // Assignment end date (null = indefinite)
  isActive: boolean         // Computed: current date within range
  assignedBy: ObjectId      // User who created assignment
  assignedAt: Date          // When assignment was created
  notes?: string            // Optional assignment notes
}

Assignment Rules

• Unique Assignments: No overlapping assignments for same employee/role/location
• Date Validation: validTo must be after validFrom
• Active Calculation: isActive computed based on current date within range
• Audit Trail: Track who assigned roles and when

Multiple Assignments

Employees can have multiple role assignments:

• Different roles at the same location
• Same role at different locations
• Different roles at different locations
• Time-based assignments (temporary roles)

Categories System

Employees are organised using three category types:

Employers

• Business entities or departments
• Used for payroll and reporting separation
• Can have multiple employers per employee
• Examples: "Main Company Pty Ltd", "Subsidiary Co"

Locations

• Physical work locations with geofencing
• GPS coordinates for location verification
• Opening hours and working days
• Geofence radius and enforcement mode

Roles

• Job functions and responsibilities
• Default pay rates and schedules
• Permission levels and access rights
• Examples: "Casual Employee", "Manager", "Supervisor"

Employee Lifecycle

1. Employee Creation

graph TD
    A[Create Employee] --> B[Set Basic Details]
    B --> C[Assign PIN]
    C --> D[Set Employment Type]
    D --> E[Create Role Assignments]
    E --> F[Send Onboarding Email]
    F --> G[Employee Active]

2. Role Assignment Process

graph TD
    A[Select Employee] --> B[Choose Role]
    B --> C[Select Location]
    C --> D[Set Date Range]
    D --> E[Validate Assignment]
    E --> F{Valid?}
    F -->|Yes| G[Create Assignment]
    F -->|No| H[Show Error]
    G --> I[Update Employee Permissions]

3. Employee Onboarding

When creating employees, the system can automatically:

• Generate secure PINs
• Send welcome emails with login details
• Create password setup links
• Assign default roles and locations
• Upload profile photos

Permission System

User Roles

Location-Based Permissions

Users can be restricted to specific locations:

• View only employees at assigned locations
• Create timesheets for assigned locations only
• Generate reports for accessible locations
• Manage roles within permitted locations

Managed Roles

Managers can be assigned specific roles to manage:

• Create/edit employees with managed roles
• View timesheets for managed role employees
• Assign managed roles to employees
• Generate reports for managed roles

API Endpoints

Employee Management

List Employees

GET /api/employees?search=john&limit=50&offset=0&location=office&role=manager

Query Parameters:

• search - Search by name, PIN, email, or phone
• limit - Number of results (default: 50, max: 500)
• offset - Pagination offset (default: 0)
• location - Filter by location name(s) (comma-separated)
• role - Filter by role name(s) (comma-separated)
• employer - Filter by employer name(s) (comma-separated)
• sortBy - Sort field: name, pin, email, createdAt
• order - Sort order: asc, desc

Response:

{
  "employees": [
    {
      "id": "employee_id",
      "name": "John Smith",
      "pin": "1001",
      "roles": [
        {
          "id": "assignment_id",
          "role": {
            "id": "role_id",
            "name": "Manager",
            "color": "#3b82f6"
          },
          "location": {
            "id": "location_id", 
            "name": "Head Office",
            "address": "123 Collins St, Melbourne",
            "geofence": {
              "radius": 100,
              "mode": "soft"
            }
          },
          "validFrom": "2024-01-01T00:00:00Z",
          "validTo": null,
          "isActive": true
        }
      ],
      "employers": [
        {
          "id": "employer_id",
          "name": "Main Company Pty Ltd",
          "color": "#10b981"
        }
      ],
      "email": "john@company.com",
      "phone": "0412 345 678",
      "employmentType": "full-time",
      "standardHoursPerWeek": 38,
      "awardId": "award_id",
      "awardLevel": "Level 3 - Manager"
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

Create Employee

POST /api/employees
Content-Type: application/json

{
  "name": "Jane Smith",
  "pin": "1002", 
  "email": "jane@company.com",
  "phone": "0412 345 679",
  "employer": ["Main Company Pty Ltd"],
  "role": ["Casual Employee"],
  "location": ["Head Office"],
  "employmentType": "casual",
  "standardHoursPerWeek": 20,
  "sendSetupEmail": true
}

Role Assignment Management

Create Role Assignment

POST /api/employees/{employeeId}/roles
Content-Type: application/json

{
  "roleId": "role_category_id",
  "locationId": "location_category_id", 
  "validFrom": "2024-01-01T00:00:00Z",
  "validTo": null,
  "notes": "Promoted to manager role"
}

Update Role Assignment

PATCH /api/employees/{employeeId}/roles/{assignmentId}
Content-Type: application/json

{
  "validTo": "2024-12-31T23:59:59Z",
  "notes": "Assignment ending due to role change"
}

Common Use Cases

Adding New Employee

1. Create Employee Record

   • Set basic details (name, PIN, contact info)
   • Choose employment type and standard hours
   • Assign to employer categories

2. Assign Roles and Locations

   • Select appropriate role for employee
   • Assign to work location(s)
   • Set assignment date range

3. Configure Awards (if applicable)

   • Assign modern award
   • Set award level/classification
   • Configure penalty rates

4. Send Onboarding

   • Generate welcome email
   • Provide login credentials
   • Include system instructions

Managing Role Changes

1. Temporary Role Assignment

   • Create new assignment with end date
   • Keep original role assignment active
   • Document reason in notes

2. Permanent Role Change

   • End current role assignment
   • Create new role assignment
   • Update award level if needed

3. Location Transfer

   • End assignments at old location
   • Create assignments at new location
   • Maintain same roles if applicable

Bulk Employee Operations

1. CSV Import

   • Prepare employee data in CSV format
   • Use bulk import API endpoint
   • Validate and process results

2. Role Assignment Updates

   • Select multiple employees
   • Apply role changes in batch
   • Generate audit trail

3. Award Updates

   • Filter employees by current award
   • Update to new award rates
   • Maintain historical records

Best Practices

PIN Management

• Use 4-digit PINs for easy memorisation
• Ensure PINs are unique across all employees
• Consider sequential numbering (1001, 1002, etc.)
• Avoid obvious patterns (1234, 0000)

Role Assignment Strategy

• Plan role hierarchy before implementation
• Use descriptive role names
• Document role responsibilities
• Regular review of assignments

Location Configuration

• Set appropriate geofence radius (50-200m)
• Use "soft" mode initially, upgrade to "hard" after testing
• Configure accurate GPS coordinates
• Set realistic working hours

Data Quality

• Require email addresses for important notifications
• Keep employee photos up to date
• Regular data validation and cleanup
• Maintain accurate employment types

Troubleshooting

Common Issues

Employee Cannot Clock In

• Verify PIN is correct and unique
• Check role assignments are active
• Ensure location geofencing is configured
• Verify employee has active assignments

Role Assignment Conflicts

• Check for overlapping date ranges
• Verify role and location exist
• Ensure user has permission to assign roles
• Review assignment validation errors

Email Notifications Not Sending

• Verify SMTP configuration
• Check employee email addresses
• Review email template configuration
• Check spam/junk folders

Photo Upload Issues

• Verify Cloudinary configuration
• Check file size and format limits
• Ensure proper permissions
• Review upload error logs

Next Steps

• Creating Employees - Detailed employee creation process
• Role Assignments - Managing roles and locations
• Employee Profiles - Profile management and photos
• Bulk Operations - Mass employee management