Skip to content

Timesheet Management Business Logic

The timesheet management system is the core of the Stratpoint Timesheet Application. Employees log their work time, managers approve it, and the system tracks everything for payroll and project management.

How It Works

For Employees: 1. Log in and select dates to enter time 2. Choose which project you worked on 3. Select what type of work you did (development, testing, etc.) 4. Enter your start/stop times and describe the work 5. Submit for approval

For Managers: 1. Review submitted time entries from your team 2. Approve or reject entries (with reasons) 3. Can approve multiple entries at once for efficiency

What the System Does: - Calculates hours automatically - Prevents overlapping time entries - Tracks leave balances when people take time off - Manages "comp time" (CTO) for overtime work - Generates reports for missing timesheets

Time Entry Details

Simple Workflow

flowchart TD
    A[Employee Logs Time] --> B[Choose Project & Task]
    B --> C[Enter Times & Description]
    C --> D[System Validates]
    D --> E[Submit for Approval]
    E --> F[Manager Reviews]
    F --> G[Approved/Rejected]

Basic Rules

  • Start/Stop Times: Must be valid timestamps, stop time after start time
  • Description: Required, minimum 10 characters
  • Project Assignment: Must be assigned to the project you're logging time for
  • No Overlap: Can't log overlapping time periods
  • Task Types: Must select a valid task type (Development, Testing, etc.)

What Gets Tracked

  • Which employee logged the time
  • Which project the work was for
  • What type of work was done
  • When the work started and stopped
  • How many hours (calculated automatically)
  • Description of the work
  • Whether it's billable to the client
  • Current approval status

Approval Process

How Approvals Work

flowchart LR
    A[Employee Submits] --> B[Goes to Manager]
    B --> C{Manager Decision}
    C -->|✅ Approve| D[Time Approved]
    C -->|❌ Reject| E[Back to Employee]
    C -->|📝 Needs Changes| E

Who Can Approve

  • Your direct manager (defined in the system)
  • Project managers for specific projects
  • Must have "timelog approval" permission in the system

Manager Actions

  • Approve: Time entry is accepted and counts toward project hours
  • Reject: Send back with a reason (common reasons below)
  • Bulk Actions: Can approve/reject multiple entries at once

Common Rejection Reasons

  1. Employee on Leave - You were on vacation/sick leave that day
  2. Wrong Project - Time should be charged to a different project
  3. Other Issues - Various business reasons with explanation

What Happens After

  • Approved: Counts toward your hours, project billing, and payroll
  • Rejected: You need to fix and resubmit
  • System tracks everything for audit purposes

Special Features

Leave Time Integration

When you take vacation, sick leave, or other time off: - Select the appropriate leave type instead of a project - System automatically deducts from your leave balance - Still goes through the same approval process - Manager can see if you have enough leave balance available

Compensatory Time Off (CTO)

For overtime or holiday work: - System tracks extra hours you work - You can use these "comp time" hours later - CTO expires after 6 months if not used - Can offset future time entries automatically

Time Calculations

  • Hours calculated automatically from start/stop times
  • Rounded to nearest hundredth (0.01 hours)
  • Supports multi-day entries for long tasks
  • Prevents time overlap conflicts

Deficiency Tracking

What Are Deficiencies?

The system automatically tracks when employees: - Miss logging time for working days - Log insufficient hours (below required daily hours) - Have pending approvals past deadlines - Have rejected entries that need fixing

How It Works

  • Daily Check: System calculates expected vs. actual hours
  • Weekly Reports: Managers get summaries of team deficiencies
  • Escalation: Multiple levels of notifications for missing time
  • Compliance: Required for payroll processing and project tracking

Technical Implementation Details

For developers and system administrators

Core API Endpoints

Timelog Management: 

// Get individual timelog data
POST /api/v2/timelogs/{userId}/{startDate}/{endDate}

// Bulk approval/rejection
POST /api/v2/timelogs/changeStatus
{
  "id": "12345,12346,12347",  // Comma-separated timelog IDs
  "status": "Approved"
}

// Rejection with business reasons
{
  "id": "12345,12346",
  "status": "Rejected",
  "rejectReasonType": "Re-classify to Other Charge Code",
  "note": {
    "note": "Please reclassify this work as internal training",
    "rejectReasonType": "Re-classify to Other Charge Code"
  }
}

Reporting Endpoints: 

// Deficiency tracking
POST /api/v2/users/timelogDeficiencyReport
POST /api/v2/users/getDeficiencySnapshotReportByApprover

// Approver reports
POST /api/v2/timelogs/approverDetailedTaskReport

// Offset hour reports
POST /api/v2/timelogs/reportOffsetReferences

Database Schema

Timelog Model Structure: 

// Core fields from actual Timelog model
'user_id' => 'Employee ID (required)',
'projectUser_id' => 'Project assignment ID (nullable)',
'tasktype_id' => 'Task type classification (required)',
'startTime' => 'Start timestamp (required)',
'stopTime' => 'End timestamp (required)',
'spentHours' => 'Calculated duration (auto-calculated)',
'description' => 'Work description (required)',
'status' => 'Approval status (For_Approval, Approved, Rejected)',
'approverUserId' => 'Assigned approver ID',
'isProcessable' => 'Business flag for processing eligibility',
'subtasktype_id' => 'Sub-task categorization (nullable)',
'isNightDiff' => 'Night differential flag',
'billable' => 'Billing classification',
'location' => 'Work location tracking',
'offsetHours' => 'CTO offset hours (nullable)'

Related Models: - OffsetHour: CTO tracking with source timelog linkage - ProjectUser: Project assignment relationships - TaskType: Work categorization (including leave types with isLeaveType = 1) - User: Employee data with approver hierarchy via approverUser_id

Validation Rules Implementation

Business Rules (from TimelogController): 

// Actual validation rules from the codebase
'startTime' => 'required|date_format:Y-m-d H:i:s',
'stopTime' => 'required|date_format:Y-m-d H:i:s|after:startTime',
'description' => 'required|min:10',
'tasktype_id' => 'required|integer|exists:tasktypes,id',
'projectUser_id' => 'nullable|integer|exists:project_users,id',

Time Calculation Logic: 

// Actual calculation from Timelog model
public function calculateSpentHours($startTime, $stopTime)
{
    $start = new DateTime($startTime);
    $stop = new DateTime($stopTime);
    $diff = $stop->diff($start);

    $hours = $diff->h + ($diff->i / 60) + ($diff->s / 3600);
    if ($diff->days > 0) {
        $hours += $diff->days * 24;
    }

    return round($hours, 2);
}

Permission System

Key Permissions: - Permission 1: Basic user access to own timelog data - Permission 103: Timelog approval authority (required for managers) - Permission 72: Admin access to all user data (super user) - Permission 67: Access to deficiency reports

Access Validation Pattern: 

// Standard permission check across all timelog operations
if (!hasPermission($this->authUser, 1) ||
    ($userId != $this->authUser['id'] && !hasPermission($this->authUser, 72))) {
    return respondAccessNotAllowed('Timelog');
}

Approval Workflow Implementation

Approval Hierarchy: - Based on approverUser_id field in users table - Career mentors defined in user relationships - Project-specific approvers through ProjectUser assignments - Permission ID 103 required for approval operations

Status Management: - For_Approval: Default status for new entries - Approved: Approved by authorized approver - Rejected: Rejected with reason code - Only approved timelogs count toward project hours and billing

Rejection Reason Types: - Employee on Leave: Employee was on leave during logged time - Re-classify to Other Charge Code: Work should be charged to different project/task - Others: Other business-specific rejection reasons

CTO (Compensatory Time Off) Integration

OffsetHour Model Structure: 

// From OffsetHour model
'sourceTimelogId' => 'Source timelog that generated CTO',
'userId' => 'Employee ID',
'hours' => 'CTO hours available',
'earnedDate' => 'Date CTO was earned',
'expiryDate' => 'CTO expiration date (typically 6 months)',
'isUsed' => 'Usage status flag',
'usedDate' => 'Date CTO was consumed'

CTO Business Rules: - Earned from overtime hours beyond standard work schedule - Holiday work compensation - FIFO consumption (oldest first) - Automatic offset against future work hours - Approval required for CTO usage

Deficiency Tracking Implementation

Deficiency Types: 1. Missing Timelogs: No entries for working days 2. Insufficient Hours: Below required daily/weekly hours 3. Unapproved Entries: Pending approval beyond deadlines 4. Rejected Entries: Requiring resubmission

Escalation Process: 1. Level 1: Direct supervisor notification 2. Level 2: Department head escalation 3. Level 3: HR intervention 4. Level 4: Management action

Leave Management Integration

Leave as Task Types: - Leave types are task types with isLeaveType = 1 - Leave requests create timelog entries with special status - Leave balance tracking via LeaveAdjustment model - Accrual calculations based on accrualType and accrualValue - Same approval workflow as regular timelogs

Performance Considerations

Bulk Operations: - Bulk approval endpoints reduce database load - Comma-separated ID handling for efficiency - Optimized queries for large approval volumes

Caching Strategy: - User hierarchy cached for performance - Permission checks cached per session - Project assignment data cached with refresh intervals

Integration Architecture

External System Integration: - NetSuite: Approved timelogs flow for billing and financial reporting - Payroll Systems: Time data feeds payroll processing - Project Management: Resource utilization tracking - HR Systems: Leave balance and deficiency reporting

Data Flow and Audit Trail

Complete Audit Tracking: - All timelog changes logged with timestamps - Approver identification recorded for each action - Status change history maintained - Reason codes for all rejections tracked - Integration with notification system for workflow alerts

Business Compliance: - Comprehensive tracking for regulatory requirements - Export capabilities for external audits - Data retention policies enforced - Integration with external compliance systems

This timesheet management system is designed for enterprise-level time tracking with complex business rules, comprehensive approval workflows, and extensive integration requirements specific to Stratpoint's operational needs.