Leave Management Business Logic¶

The leave management system handles employee vacation, sick leave, and other time off within the Stratpoint Timesheet Application. It tracks leave balances, processes requests, and integrates with the timesheet system.

How Leave Management Works¶

For Employees: 1. Check your available leave balances 2. Submit leave requests for approval 3. Leave gets automatically deducted when approved 4. Track your leave usage throughout the year

For Managers: 1. Review leave requests from your team 2. Check if employees have sufficient leave balance 3. Approve or reject requests with reasons 4. Monitor team leave usage and planning

System Features: - Automatic leave accrual based on employment terms - Integration with regular timesheet approval process - Multiple leave types with different rules - Balance tracking and compliance monitoring - Integration with compensatory time off (CTO) system

Leave Types and Accrual¶

How Leave Works in the System¶

Unlike separate leave systems, Stratpoint integrates leave as special task types within the timesheet system.

graph LR
    A[Regular Work] --> B[Time Entry]
    C[Leave Request] --> B
    B --> D[Same Approval Process]
    D --> E[Balance Adjustment]

Common Leave Types¶

Annual Leave: Vacation time, usually 15 days per year
Sick Leave: Medical time off, usually 5 days per year
Emergency Leave: Urgent personal matters, usually 3 days per year
Personal Leave: Other personal time off
Holiday Leave: Company holidays and special occasions

How Leave Accrues¶

Monthly Accrual: Most leave types accrue monthly (e.g., 1.25 days per month)
Annual Accrual: Some leave types are granted annually
Pro-rated: New employees get pro-rated leave based on start date
Eligibility: Usually begins after regularization period
Working Days: Accrual based on business days, not calendar days

Leave Request Process¶

Simple Leave Request Flow¶

flowchart TD
    A[Employee Requests Leave] --> B[System Checks Balance]
    B --> C{Enough Leave?}
    C -->|Yes| D[Goes to Manager]
    C -->|No| E[Balance Error]
    D --> F[Manager Approves/Rejects]
    F --> G[Balance Updated]

How to Request Leave¶

Select Leave Type: Choose vacation, sick leave, etc.
Pick Dates: Select the dates you want to take off
System Check: Automatically verifies you have enough leave balance
Submit Request: Goes to your manager for approval
Get Approved: Manager approves and your balance is updated

Balance Validation¶

Real-time Check: System immediately tells you if you have enough leave
Hour Calculation: Automatically calculates hours based on your work schedule
Buffer Protection: Prevents requesting more leave than you have
Future Balance: Considers already approved future leave requests

Leave Balance Management¶

How Balances Are Tracked¶

Automatic Accrual: Leave automatically added monthly/annually
Usage Tracking: Leave deducted when approved requests are taken
Manual Adjustments: HR can add or remove leave for special circumstances
Year-End Processing: Unused leave may carry over or expire based on policy

Types of Adjustments¶

Earned: Regular accrual based on employment terms
Used: Leave taken through approved requests
Bonus: Extra leave granted for special circumstances
Correction: Adjustments to fix errors or policy changes
Carryover: Moving unused leave to the next year

Administrative Features¶

Mass Adjustments: HR can update multiple employees at once
Audit Trail: All adjustments tracked with reasons and dates
Approval Required: Manual adjustments require proper authorization
Effective Dating: Adjustments can be backdated when necessary

Leave Policies¶

Annual Leave (Vacation)¶

Accrual: 1.25 days per month (15 days per year)
Usage: Can be planned in advance for vacations
Carryover: May be carried to next year (policy dependent)
CTO Integration: Can use comp time to offset vacation if needed
Planning: Advance notice recommended for team planning

Sick Leave¶

Accrual: 0.417 days per month (5 days per year)
Usage: For medical appointments and illness
Documentation: May require medical certificate for extended periods
Non-transferable: Usually doesn't carry over to next year
Immediate Use: Can be used as soon as needed

Emergency Leave¶

Allocation: 3 days per year (annual grant)
Usage: For urgent personal emergencies
Immediate: Can be used without advance notice
Non-transferable: Doesn't carry over between years
Approval: Still requires manager approval after use

Special Leave Types¶

Personal Leave: Other personal time off needs
Holiday Leave: Company holidays and special occasions
Bereavement: Family emergency situations
Jury Duty: Legal obligations

Leave Reporting¶

Individual Leave Summary¶

Each employee can view their leave summary showing: - Earned: Total leave accrued for the year - Used: Leave already taken - Balance: Remaining leave available - Scheduled: Future approved leave requests - History: Past leave usage patterns

Manager Reports¶

Team Leave Balances: Overview of team's leave status
Pending Requests: Leave requests awaiting approval
Leave Calendar: Visual calendar of team leave schedules
Usage Patterns: Analysis of leave usage trends
Compliance: Ensuring minimum leave usage requirements

HR Analytics¶

Company-wide Leave Trends: Organization-level leave patterns
Department Comparisons: Leave usage across business units
Policy Compliance: Monitoring leave policy adherence
Cost Analysis: Financial impact of leave policies
Forecasting: Predicting future leave usage and costs

Leave Eligibility¶

Who Can Take Leave¶

Regularized Employees: Must complete probationary period first
Pro-rated: New employees get partial leave based on start date
Employment Type: Different rules for regular, contract, and part-time staff
Service Length: Some leave types require minimum service period

Eligibility Rules¶

Regularization Required: Must be a confirmed employee
Start Date Impact: Leave accrual begins from employment start
Pro-rating Calculation: First year leave calculated proportionally
Contract vs Regular: Different accrual rates and policies
Minimum Service: Some leave types need minimum employment period

Special Considerations¶

New Hires: Limited leave until regularization
Contract Workers: May have different leave entitlements
Part-time Staff: Pro-rated leave based on work schedule
Temporary Employees: Limited or no leave benefits

Compensatory Time Off (CTO) Integration¶

How CTO Works with Leave¶

CTO as Offset: Can use earned comp time instead of leave hours
Automatic Application: System uses CTO first when configured
Leave Preservation: Saves your actual leave balance for later
Configurable: Different leave types may or may not allow CTO offset

CTO Usage Rules¶

FIFO Consumption: Oldest comp time used first
Expiration Tracking: CTO expires if not used within time limits
Automatic Offset: System automatically applies when leave is approved
Leave Type Specific: Only certain leave types can be offset with CTO

Benefits of CTO Integration¶

Preserve Leave: Save actual vacation days for longer trips
Use Overtime: Convert overtime work into time off
Flexibility: More options for taking time off
Automatic: System handles the calculations automatically

Technical Implementation Details¶

For developers and system administrators

Leave as Task Types Architecture¶

Core Concept: Unlike traditional separate leave systems, Stratpoint implements leave management as special task types integrated with the timelog system.

TaskType Model (Leave Configuration):

// Leave types are task types with special flags
'id' => 'Task type ID (used as leave type ID)',
'name' => 'Leave type name (e.g., "Annual Leave")',
'isLeaveType' => '1 for leave types, 0 for regular tasks',
'accrualType' => 'monthly or annual',
'accrualValue' => 'Decimal accrual rate (e.g., 1.25 for monthly)',
'offsetable' => 'Whether this leave type can offset CTO',
'hexcolor_id' => 'Color coding for UI display'

Accrual Calculation System¶

Business Rules Implementation:

public {

href="#__codelineno-1-1">// Actual accrual logic from Leave model static function getSummaryPerLeaveType($viewYear, $user, $dailyRequiredHours, $leaveAccrualDay, $taskType, $leaveAdjustments, $authUser) pan> // Calculate earned days based on accrual type if ($taskType->accrualType === 'monthly') { $monthlyAccrual = $taskType->accrualValue; $earnedDays = calculateMonthlyAccrual($user, $viewYear, $monthlyAccrual); } else { $annualAccrual = $taskType->accrualValue; $earnedDays = calculateAnnualAccrual($user, $viewYear, $annualAccrual); } return [ 'earned' => $earnedDays, 'used' => $usedDays, 'balance' => $earnedDays - $usedDays, 'adjustments' => $leaveAdjustments ]; }

Employment-Based Accrual Factors: 1. Employment Start Date: Affects pro-rating for partial years 2. Regularization Date: Leave eligibility begins after regularization 3. Employment Type: Different accrual rates for different employment types 4. Business Days: Accrual calculated based on working days, not calendar days

Accrual Configuration:

// From configuration
$leaveAccrualDay = config('timesheet.leaveAccrualDay'); // Usually 15th of month
$dailyRequiredHours = config('timesheet.dailyRequiredHours'); // Usually 8 hours

API Endpoints¶

Individual Leave Reports:

POST /api/v2/leaves/individual_report/{userId}
{
  "year": "2024",
  "userId": 123,
  "filtersToGet": true
}

Mass Adjustments:

POST /api/v2/leaves/saveMassAdjustments
{
  "adjustments": [
    {
      "userId": 123,
      "taskTypeId": 1,
      "hours": "8.00",
      "reason": "Bonus leave credit for exceptional performance",
      "type": "manual_adjustment"
    }
  ]
}

Comprehensive Reporting:

POST /api/v2/leaves/getAllUserReport
{
  "year": "2024",
  "selectLeaveType": "1,2,3",
  "selectBusinessUnit": "1,2",
  "selectEmploymentType": "1,2"
}

Leave Balance Validation¶

Pre-Request Validation:

// Actual validation from codebase
public function validateLeaveBalance($userId, $taskTypeId, $requestedHours, $leaveDate)
{
    $availableBalance = LeaveAdjustment::getAvailableBalance($userId, $taskTypeId, $leaveDate);

    if ($requestedHours > $availableBalance) {
        throw new ValidationException("Insufficient leave balance. Available: {$availableBalance} hours");
    }

    return true;
}

LeaveAdjustment Model¶

Leave Adjustment Tracking:

// Actual leave adjustment tracking
'user_id' => 'Employee ID',
'tasktype_id' => 'Leave type (task type) ID',
'year' => 'Leave year',
'hours' => 'Adjustment hours (positive for addition, negative for usage)',
'type' => 'adjustment_type (earned, used, manual_adjustment)',
'reason' => 'Adjustment reason',
'effectiveDate' => 'Date adjustment takes effect',
'createdByUser_id' => 'User who created the adjustment',
'isProcessable' => 'Whether adjustment affects balance calculations'

Standard Leave Type Configuration¶

Typical Setup:

-- Annual Leave (Monthly Accrual)
INSERT INTO tasktypes (name, isLeaveType, accrualType, accrualValue)
VALUES ('Annual Leave', 1, 'monthly', 1.25);

-- Sick Leave (Monthly Accrual)
INSERT INTO tasktypes (name, isLeaveType, accrualType, accrualValue)
VALUES ('Sick Leave', 1, 'monthly', 0.417);

-- Emergency Leave (Annual Accrual)
INSERT INTO tasktypes (name, isLeaveType, accrualType, accrualValue)
VALUES ('Emergency Leave', 1, 'annual', 3.0);

CTO Integration Implementation¶

CTO Offset Process:

// When leave is approved, check for available CTO
if ($taskType->offsetable && $user->hasAvailableCTO()) {
    $availableCTO = OffsetHour::getAvailableHours($userId);
    $offsetHours = min($requestedLeaveHours, $availableCTO);

    // Reduce leave usage by CTO offset
    $actualLeaveUsage = $requestedLeaveHours - $offsetHours;

    // Record CTO usage
    OffsetHour::consumeHours($userId, $offsetHours, $leaveTimelogId);
}

Eligibility System¶

Eligibility Validation:

// Actual eligibility check
public static function isEligibleForLeaveType($userId, $taskTypeId, $leaveDate)
{
    $user = User::find($userId);
    $taskType = Tasktype::find($taskTypeId);

    // Check if user is regularized
    if (!$user->regularizationDate || $leaveDate < $user->regularizationDate) {
        return false;
    }

    // Check service length requirements
    $serviceLength = getDaysBetween($user->startDate, $leaveDate);
    if ($serviceLength < $taskType->minimumServiceDays) {
        return false;
    }

    return true;
}

Permission System¶

Leave Management Permissions: - Permission 125: Can view own leave data - Permission 126: Can view and manage leave for others - Permission 127: Can make leave adjustments - Permission 128: Can approve leave requests

Access Validation:

// Actual permission check from LeaveController
if (!hasPermission($this->authUser, 125) ||
    ($userId != $this->authUser['id'] && !hasPermission($this->authUser, 126))) {
    return respondAccessNotAllowed($this->title);
}

Year-End Processing¶

Annual Leave Processing:

// Year-end leave processing
public function processYearEndLeave($year)
{
    // Calculate carry-forward balances
    // Process leave forfeitures
    // Generate year-end reports
    // Initialize next year balances
}

Compliance and Monitoring¶

Automated Monitoring: - Leave balance calculations verified daily - Negative balance alerts generated - Unused leave expiry tracking - Mandatory leave compliance (minimum usage requirements)

Audit Trail: - All leave adjustments logged with reasons - Approval history maintained - Balance calculation audit logs - Integration with external HR systems

Integration Architecture¶

Payroll Integration: - Approved leave affects payroll calculations - Integration with NetSuite for financial impact - Leave deductions calculated automatically - Special handling for unpaid leave

Calendar Integration: - Leave requests appear in team calendars - Resource availability updated automatically - Project planning impact notifications - Conflict detection with project deadlines

This leave management system is designed for enterprise HR management with complex accrual calculations, comprehensive audit trails, and tight integration with the timesheet and project management systems specific to Stratpoint's operational requirements.