Timesheets App Overview
Turn attendance data into accurate, audit-ready paychecks with the Timesheets App—auto-generated timesheets from clock-in records, multi-level approval workflows, per-week overtime calculations, and payroll-ready exports that feed Payroll Connect or in-house Payroll Processing.
Feature Evidence Table
Every claim in this overview is grounded in the codebase. The table below maps each feature to the file that implements it.
| Feature | Evidence (Source File) |
|---|---|
| Auto-generation on first page load | src/app/controllers/timesheets_controller.rb (TimesheetGenerationService auto-call in #index) |
| Proactive daily creation for all employees | src/app/jobs/proactive_timesheet_creation_job.rb, src/app/services/proactive_timesheet_service.rb |
| Real-time sync from attendance clock in/out | src/app/services/real_time_timesheet_service.rb |
| Manual entry edits with required reason | src/app/controllers/timesheets_controller.rb (update_entry enforces edit_reason) |
Per-entry audit trail (TimesheetEdit) |
src/app/models/timesheet_entry.rb#record_edit, TimesheetEdit model |
| Break duration tracking (cap 480 min) | src/app/models/timesheet_entry.rb (validates break_duration_minutes ≤ 480) |
| Overnight shift support | src/app/models/timesheet_entry.rb#calculate_duration_with_date_fix |
| Future entry lockout | src/app/models/timesheet_entry.rb#future_entry?, #user_editable? |
| Missing-punch detection (past entries only) | src/app/models/timesheet_entry.rb#missing_punch?, TimesheetEntry.with_missing_punch scope |
| Absence tracking (excused/unexcused) | src/app/models/timesheet_entry.rb#excuse_absence!, #mark_unexcused! |
| Employee submission service | src/app/services/timekeeping/timesheet_submission_service.rb |
| Manager approve / reject / edit | src/app/controllers/timesheet_approvals_controller.rb |
| Regional (second-level) approval | src/app/models/timesheet.rb#regional_approve!, #regional_approvable? |
| Bulk regional approval | src/app/controllers/timesheet_approvals_controller.rb#bulk_regional_approve |
| PTO-aware skip-level routing | src/app/models/timesheet.rb#effective_approver, #can_be_approved_by? (via ApprovalRoutingHelper) |
| Auto-approval scoring | src/app/services/timesheet_scoring_service.rb#check_for_auto_approval |
| Per-week 40-hour overtime threshold | src/app/models/timesheet.rb#overtime_hours, src/app/controllers/timesheets_controller.rb#calculate_overtime_from_entries |
| Pay period types (weekly/biweekly/semi-monthly/monthly) | src/app/services/real_time_timesheet_service.rb#determine_pay_period_for_date, BusinessPayPeriodSetting |
| Submission & approval deadline enforcement | src/app/models/timesheet.rb#calculate_submission_due_date, #calculate_approval_due_date |
| Daily deadline + recurring reminders | src/app/jobs/timesheet_deadline_check_job.rb, src/app/services/timesheet_deadline_service.rb |
| End-of-pay-period reminders | src/app/jobs/timesheet_end_of_week_reminder_job.rb |
| Premium pay auto-apply on submission | src/app/jobs/premium_auto_apply_job.rb, Timesheet#enqueue_premium_calculation |
| Seniority hours cache update on approval | src/app/models/timesheet.rb#update_user_seniority_cache (RecalculateSeniorityHoursJob) |
| Payroll report generation | src/app/controllers/admin/payroll_controller.rb, src/app/services/payroll_report_service.rb |
| CSV / PDF / JSON export | src/app/services/payroll_export_service.rb, PayrollReport::FORMATS |
| Location + department + user filtering | src/app/controllers/admin/payroll_controller.rb#create (filters_hash) |
| Rest-violation flag on report rows | src/app/services/payroll_export_service.rb (has_rest_period_violations column) |
| Leave balance/used columns | src/app/services/payroll_export_service.rb (leave_balance, leave_used columns) |
| Location-scoped permission filtering | src/app/controllers/admin/payroll_controller.rb#authorize_report_access! |
| SFTP export (scheduled push) | src/app/jobs/timesheet_export_job.rb, src/app/services/timesheet_sftp_export_service.rb |
| SFTP import (pull) | src/app/jobs/timesheet_import_job.rb, src/app/services/timesheet_sftp_import_service.rb |
| CSV import (admin upload) | src/app/controllers/timesheet_approvals_controller.rb#process_import, TimesheetImportService |
| Bulk timesheet approval job | src/app/jobs/bulk_approve_timesheets_job.rb |
| Team management dashboard | src/app/controllers/team_timesheet_management_controller.rb |
| Missing timesheet tracking (team dashboard) | src/app/controllers/team_timesheet_management_controller.rb#calculate_missing_timesheets |
| REST API v1 | src/app/controllers/api/v1/timesheets_controller.rb |
| Timekeeping AI Agent | src/app/services/agents/timekeeping_agent.rb |
| Payroll Connect: ADP / Workday / Gusto / Paychex / BambooHR | src/app/services/payroll_connect/{adp,workday,gusto,paychex,bamboohr}/connector_service.rb |
| Directory metadata (capabilities, FAQs, use cases) | src/lib/marketplace_app_definitions/directory/timesheets.rb |
~40 features verified against source code.
What is the Timesheets App?
The Timesheets App is MangoApps Workforce’s core timesheet and payroll-prep system. It is auto-enabled for every business (tier: core, category: scheduling) and is the hub that turns raw attendance punches into approved, export-ready pay data.
Rather than ask employees to type hours into a blank form, Timesheets auto-generates a timesheet for each pay period and live-syncs clock-in/clock-out data from the Attendance app the moment a punch happens. Employees review; managers approve; admins export.
Core Value Proposition:
- Auto-populated — timesheets build themselves from attendance, no manual entry required
- Audit-ready — every edit captures who changed what, when, and why
- Overtime-correct — per-week 40-hour rolling calculation, not per-pay-period
- Payroll-native — exports feed Payroll Connect (ADP, Workday, Gusto, Paychex, BambooHR) or in-house Payroll Processing
- Approval-aware — manager sign-off, optional regional sign-off, PTO-aware skip-level routing
How it fits the stack: Timesheets consumes attendance data from the Attendance app and outputs approved hours to one of two sinks:
- Payroll Connect — push to an external payroll provider
- Payroll Processing — run payroll in-house inside MangoApps (coming soon)
At a Glance
| App slug | timesheets |
| Tier | Core (auto-enabled for every business) |
| Category | Scheduling |
| Default pay period | Biweekly (admin-configurable) |
| Supported pay periods | Weekly, Biweekly, Semi-monthly, Monthly |
| Overtime rule | >40 hours per 7-day week within the pay period |
| Export formats | CSV, PDF, JSON |
| Payroll Connect providers | ADP Workforce Now, Workday HCM, Gusto, Paychex, BambooHR, MangoPay, Custom |
| Break duration cap | 480 minutes (8 hours) per entry |
| Edit audit trail | Required reason on every edit (TimesheetEdit record) |
| Pricing | Included with MangoApps Workforce |
How It Works
Timesheet Lifecycle
┌───────────────────────────────────────────────────────────────────────────────┐
│ TIMESHEET LIFECYCLE │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ ATTENDANCE TIMESHEETS PAYROLL │
│ ========== ========== ======= │
│ │
│ ┌──────────┐ real-time ┌──────────┐ │
│ │ Clock In │───────────────▶│ PENDING │ │
│ └──────────┘ sync │ (editable)│ │
│ │ └────┬─────┘ │
│ ▼ │ employee submits │
│ ┌──────────┐ ▼ │
│ │ Break │─────────────▶┌──────────┐ │
│ └──────────┘ │ SUBMITTED│ │
│ │ └────┬─────┘ │
│ ▼ │ manager reviews │
│ ┌──────────┐ │ │
│ │Clock Out │───────┐ ┌────────┴────────┐ │
│ └──────────┘ │ ▼ ▼ │
│ │ APPROVED REJECTED ──► back to PENDING │
│ │ │ (w/ reason) (resubmit) │
│ │ │ │
│ │ │ │
│ │ │ (if regional approval required) │
│ │ ▼ │
│ │ REGIONAL_PENDING ──► APPROVED │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ PAYROLL │── CSV/PDF/JSON ─► download │
│ │ REPORT │── SFTP push ────► external system │
│ └──────┬───────┘── Payroll Connect ─► ADP/Workday/Gusto/… │
│ └────────── Payroll Processing (in-house, coming soon) │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Auto-Generation & Real-Time Sync
Timesheets never require a blank form. Three mechanisms keep them populated:
- On first view — When an employee opens
/timesheets,TimesheetsController#indexcallsTimesheetGenerationServiceto create the current pay period’s timesheet if it doesn’t exist (source:timesheets_controller.rb). - Daily proactive creation —
ProactiveTimesheetCreationJob(cron:1 0 * * *) loops through every business with the Timesheets app enabled and creates timesheets for all active employees at the start of each pay period. - Real-time attendance sync —
RealTimeTimesheetServiceruns on every clock-in, clock-out, and break event. It finds or creates the containing timesheet, finds or creates the correct entry, and updatesstart_time,end_time, andhoursusing the attendance record’spayable_hoursmethod (which accounts for unpaid breaks). ActionCable broadcasts the update live to the employee’s browser.
Integration Ecosystem
┌──────────────────┐
│ TIMESHEETS │
│ APP │
└────────┬─────────┘
│
┌──────────────┬─────────────┼─────────────┬──────────────┐
▼ ▼ ▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌────────────┐
│ATTENDANCE │ │ SCHEDULING│ │ LEAVE │ │ PREMIUMS │ │ ASK AI │
│ │ │ (Shifts) │ │ MANAGEMENT│ │ (Shift │ │(Timekeeping│
│ │ │ │ │ │ │ Premiums)│ │ Agent) │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬──────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
Clock in/out Shift-based Leave balance Auto-apply 13 tools:
populates entries; + used shown premiums on view, submit,
entries in overnight on payroll submission overtime,
real time shift support report (PremiumAuto missing
ApplyJob) checkouts
│
┌────────────┼────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────┐ ┌──────────────┐
│ PAYROLL │ │ PAYROLL │ │ MEAL │
│ CONNECT │ │PROCESSING│ │ COMPLIANCE │
│ │ │ │ │ │
│ ADP/Workday/│ │ In-house │ │ Reads break │
│ Gusto/ │ │ engine │ │ patterns │
│ Paychex/ │ │ (coming │ │ for waiver │
│ BambooHR │ │ soon) │ │ enforcement │
└─────────────┘ └─────────┘ └──────────────┘
Key Features
Auto-Generated Timesheets from Attendance
Timesheets materialize themselves — employees never face a blank form.
| Feature | Description |
|---|---|
| Auto-create on view | Opening /timesheets generates the current pay period timesheet if missing (TimesheetGenerationService) |
| Daily proactive creation | ProactiveTimesheetCreationJob runs daily at 12:01 AM UTC to pre-create timesheets for new pay periods across all employees |
| Real-time attendance sync | RealTimeTimesheetService syncs clock-in, clock-out, and break events into the timesheet as they happen |
| Ad-hoc shift entries | Unplanned shifts sync into the timesheet on every page load via update_timesheet_with_ad_hoc_entries |
| Pay period auto-detection | New attendance records automatically route to the correct pay period (weekly, biweekly, monthly) |
| Per-entry live broadcast | ActionCable broadcasts entry updates to the user’s browser during a shift |
Use case: An employee clocks in at 9 AM. By the time they look at /timesheets that afternoon, the entry for today already shows Start: 9:00 AM, break deducted, hours still accumulating as they work.
Manual Entry & Edit Controls
Employees can edit their entries — with guardrails.
| Rule | Behavior |
|---|---|
| Editable only when pending or rejected | Timesheet#editable? gates all edit actions |
| Future entries are read-only | TimesheetEntry#future_entry? blocks editing entries before their shift date |
| Reason required on every edit | update_entry returns an error if edit_reason is blank |
| Per-field audit trail | Every changed field creates a TimesheetEdit record with original value, new value, reason, and editor |
| Break duration cap | Hard maximum of 480 minutes per entry (enforced at model-level validation) |
| Break auto-shrinks to shift length | If the edited shift is shorter than the break, break auto-adjusts (adjust_break_duration_to_shift_length) |
| Overnight shift detection | Auto-detects when end_time < start_time and bumps end date by 1 day |
| Date-misalignment repair | calculate_duration_with_date_fix detects and corrects dates that drift during edits |
| End time cannot be in the future | 5-minute buffer allowed for clock drift |
| Edit marker on entry | edited: true flag displayed in approval UI so managers know what was touched |
Use case: An employee forgot to clock out at 5 PM and clocked out at 11 PM the next morning. They open the entry, fix the end time to 5 PM, and must provide a reason (“forgot to clock out after leaving for the day”). The system writes a TimesheetEdit row capturing the change.
Absence Tracking
Missed shifts don’t disappear — they’re flagged and categorized.
| Feature | Description |
|---|---|
| Absent detection | Entry with no start_time, no end_time, no hours, for a past date = absent |
| Excuse an absence | excuse_absence! marks the entry excused with an optional reason and tracks who excused it |
| Mark unexcused | mark_unexcused! for documentation of unplanned no-shows |
| Exclusion of future entries | Future-dated entries are never treated as absences |
Multi-Level Approval Workflow
┌──────────────────────────────────────────────────────────────────────┐
│ TIMESHEET APPROVAL WORKFLOW │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ submit ┌──────────┐ manager ┌─────────────┐ │
│ │ EMPLOYEE │────────────▶│ SUBMITTED│─────────────▶│ DECIDE │ │
│ │ edits │ │ │ reviews │ │ │
│ └──────────┘ └──────────┘ └──────┬──────┘ │
│ │ │
│ ┌───────────────┬───────────────────┤ │
│ ▼ ▼ ▼ │
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │APPROVED│ │REJECTED│ │EDITED │ │
│ │ │ │+ reason│ │by mgr │ │
│ └────┬───┘ └───┬────┘ └────────┘ │
│ │ │ │
│ (if regional │required) ▼ │
│ ▼ ┌────────┐ │
│ ┌──────────────┐ │PENDING │ │
│ │ REGIONAL_ │ │(resub- │ │
│ │ PENDING │ │ mit) │ │
│ └──────┬───────┘ └────────┘ │
│ │ │
│ bulk or │ │
│ per-item ▼ │
│ ┌──────────────┐ │
│ │ APPROVED │─► Payroll export │
│ │ (final) │─► Seniority hours cache │
│ └──────────────┘─► Premium auto-calc │
│ │
│ PTO-aware: if approving manager is on leave, skip-level manager │
│ (via can_approve_as_skip_level?) can approve. │
│ │
└───────────────────────────────────────────────────────────────────────┘
Approval capabilities:
| Feature | Description |
|---|---|
| Employee submit | Timekeeping::TimesheetSubmissionService enforces submittable? (has entries, pending or rejected state) |
| Manager approve | Moves timesheet to approved or regional_pending based on business settings |
| Manager reject | Requires rejection_reason; returns timesheet to rejected (editable) state |
| Manager edit on approval | Managers can edit employee entries during review — edits are audit-tagged with manager: prefix |
| Regional approval | Second-level approval by a regional manager (regional_approve!); gated by business.timesheet_setting.regional_approval_required |
| Bulk regional approval | Approve many timesheets in one action (bulk_regional_approve) |
| Bulk approval background job | BulkApproveTimesheetsJob processes large batches asynchronously with progress tracking |
| Auto-approval scoring | TimesheetScoringService auto-approves when accuracy score meets threshold (default 95) |
| PTO-aware routing | Skip-level managers can approve when the direct manager is on leave (via ApprovalRoutingHelper) |
| In-app notifications | Notification records created on submit, approve, reject, and regional-approval events |
| Permission-scoped access | Managers see only timesheets for users they have approve/timesheets authority over (via IntegratedPermissionService) |
Pay Periods & Overtime
| Feature | Evidence |
|---|---|
| Weekly pay period | RealTimeTimesheetService#determine_pay_period_for_date |
| Biweekly pay period | RealTimeTimesheetService — epoch-based alternating-week calculation |
| Semi-monthly pay period | TeamTimesheetManagementController#get_previous_pay_period (1st–15th / 16th–end) |
| Monthly pay period | Beginning-of-month to end-of-month |
| 40-hour per-week overtime | Timesheet#overtime_hours iterates week by week; any hours over 40 in a 7-day slice become overtime |
| Overtime correct across pay period length | A biweekly period of 45+45 hours = 10 overtime hours (not 10 — overtime is calculated per week, not per pay period) |
| Regular vs. overtime split on every timesheet | regular_hours, overtime_hours computed on every view |
| Submission deadline | Default 1 day after period end (admin-configurable via business.timesheet_submission_deadline) |
| Approval deadline | Default 2 days after submission (admin-configurable via business.timesheet_approval_deadline) |
| Timesheet lockout | Timesheet becomes non-editable N days after period end (admin-configurable) |
| Overdue tracking | Timesheet#overdue?, #days_until_due, #due_soon? |
Reminders & Automation
| Job | Schedule | Purpose |
|---|---|---|
ProactiveTimesheetCreationJob |
Daily 12:01 AM UTC | Create empty timesheets for new pay periods |
TimesheetDeadlineCheckJob |
Daily 8:02 AM UTC | Check approaching deadlines + send recurring reminders |
TimesheetEndOfWeekReminderJob |
Daily 2:00 PM UTC | Send end-of-period submission reminders based on business pay period |
PremiumAutoApplyJob |
On timesheet submission | Auto-calculate shift premiums for all entries |
RecalculateSeniorityHoursJob |
On timesheet approval | Update user seniority hours cache for tenure-based calculations |
BulkApproveTimesheetsJob |
On-demand | Process large bulk approvals without UI blocking |
PayrollConnectSyncJob |
On-demand or scheduled | Sync employees/paychecks to external payroll providers |
Reminder types surfaced via TimesheetDeadlineService:
- Recurring daily reminders for pending/rejected timesheets
- Approaching submission deadline warnings (admin-configurable lead days)
- Approval-needed reminders to managers
- Escalation when deadlines are missed
Team Management Dashboard
For managers overseeing direct reports.
TeamTimesheetManagementController#dashboard surfaces:
- Pending approvals — Timesheets in
submittedstatus awaiting manager action (top 10) - Recent decisions — Last 10 approved/rejected timesheets for context
- Current period timesheets — All direct-report timesheets for the active pay period (top 50)
- Missing timesheets — Employees who haven’t submitted for the previous pay period (flagged so you can nudge them)
- Regional-pending queue — If the user has regional approval authority
- Stats tiles — Pending count, approved-this-period count, missing count, team size
All counts are scoped via IntegratedPermissionService#authorized_users_for('approve', 'timesheets') so managers only see their authorized team.
Payroll Reporting
┌─────────────────────────────────────────────────────────────────────┐
│ PAYROLL REPORT GENERATION │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ filter by ┌──────────────┐ │
│ │ Admin │───Location───────│ PayrollReport│ │
│ │selects │ Department │ created │ │
│ │date range│ Date range │ (synchronous)│ │
│ │& format │ Include leave └──────┬───────┘ │
│ └──────────┘ Include rest │ │
│ violations │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ PayrollReportService │ │
│ │ builds report items │ │
│ │ (one per employee) │ │
│ └──────────┬────────────┘ │
│ │ │
│ ┌─────────────────────────┼────────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────┐ │
│ │ CSV │ │ PDF │ │ JSON │ │
│ │ (full │ │(landscape│ │(ISO │ │
│ │ fields) │ │ Prawn) │ │ 8601)│ │
│ └──────────┘ └──────────┘ └──────┘ │
│ │ │ │ │
│ └───────────────────────┼────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ Download / SFTP push / │ │
│ │ Payroll Connect sync │ │
│ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
Per-employee report item includes (from PayrollExportService CSV columns):
- Employee ID, first/last name, email
- Hourly rate
- Regular hours, overtime hours, premium hours, total hours
- Regular pay, overtime pay, premium pay, total pay
- Premium breakdown (code → hours/amount)
- Shifts count
- Leave balance, leave used
- Has rest-period violations flag
Filters:
- Location (multi-select, permission-scoped)
- Department (multi-select)
- User (multi-select)
- Include inactive employees (toggle)
- Include leave balances (toggle)
- Include rest violations (toggle)
Permission-scoped output: Non-admins only see report items for users they have view/payroll authority over. Location access is enforced at download time — if a user tries to download a report with locations they don’t have access to, they’re blocked (authorize_report_access!).
Regeneration: Completed or failed reports can be regenerated synchronously (POST /payroll/reports/:id/regenerate), and the report file is auto-recreated on download if missing.
Exports & Integrations
| Mechanism | Direction | Source |
|---|---|---|
| CSV download | Pull (admin/manager) | PayrollExportService#generate_csv_file |
| PDF download | Pull (admin/manager) | PayrollExportService#generate_pdf_file (Prawn, landscape) |
| JSON download | Pull (admin/manager) | PayrollExportService#generate_json_file |
| CSV import | Pull into MangoApps | TimesheetImportService via /timesheet_approvals/import |
| SFTP push | Push to external system | TimesheetExportJob + TimesheetSftpExportService (approved timesheets only, incremental by updated_at) |
| SFTP pull | Pull from external system | TimesheetImportJob + TimesheetSftpImportService |
| Payroll Connect: ADP Workforce Now | Bidirectional | src/app/services/payroll_connect/adp/connector_service.rb |
| Payroll Connect: Workday HCM | Bidirectional | src/app/services/payroll_connect/workday/connector_service.rb |
| Payroll Connect: Gusto | Bidirectional | src/app/services/payroll_connect/gusto/connector_service.rb |
| Payroll Connect: Paychex | Bidirectional | src/app/services/payroll_connect/paychex/connector_service.rb |
| Payroll Connect: BambooHR | Bidirectional | src/app/services/payroll_connect/bamboohr/connector_service.rb |
| REST API v1 | Bidirectional | src/app/controllers/api/v1/timesheets_controller.rb (scopes: read:timesheets, write:timesheets) |
Payroll Connect syncs employee records, pushes approved timesheets for payroll processing, and pulls paychecks back for employee self-service. Compensation change events are tracked, and sync logs capture success/failure with retry on error.
Timekeeping AI Agent
The Ask AI sidebar can act on the Timesheets app through the Timekeeping Agent (src/app/services/agents/timekeeping_agent.rb).
Tools available to the agent (13 total):
| Tool | Purpose |
|---|---|
view_timesheet |
Show timesheet details for a period with daily breakdown |
view_timesheet_status |
Show status + due date + overdue flag for timesheets |
view_overtime_summary |
Report overtime across a time range |
submit_timesheet |
Submit the current timesheet for approval (risky-action confirmation) |
submit_time |
Directs user to the timesheet page to submit a specific entry |
clock_in / clock_out |
Direct user to the time clock (location verification required) |
start_break / end_break |
Direct user to the break controls |
view_attendance |
View recent attendance records |
view_attendance_history |
View detailed clock history over a date range |
adjust_time_entry |
File an adjustment request (requires reason, routes to manager) |
view_missing_checkouts |
Find past days with no clock-out |
view_team_timesheet_status |
For managers — see direct reports’ timesheet statuses |
Example queries:
- “How many hours did I work this week?” →
view_timesheetwithperiod: this week - “Do I have overtime this pay period?” →
view_overtime_summary - “Which days did I forget to clock out?” →
view_missing_checkouts - “Submit my timesheet” →
submit_timesheet(risky-action confirmation) - “Who on my team hasn’t submitted?” →
view_team_timesheet_status
The agent is capability-gated — tool availability depends on per-business configuration flags (capability_timesheet_review, capability_overtime_tracking, capability_exception_detection, capability_payroll_reports).
Audit Trail & Data Integrity
| Feature | Description |
|---|---|
| Per-entry edit records | Every field change writes a TimesheetEdit with field_changed, original_value, new_value, reason, user_id |
| Manager vs. employee edit tagging | Manager edits are prefixed with manager: in the reason field |
| Edited flag on entries | edited: true flag prevents real-time attendance sync from overwriting manual corrections |
| Manager notes on timesheet | manager_notes field saved during approval review |
| Seniority hours cache update | On approval, RecalculateSeniorityHoursJob runs to update tenure calculations used by downstream features |
| Rest-violation tracking | Flagged per employee on payroll reports |
| Missing punch flagging | Only past-date entries with null start or end time are flagged (future entries ignored) |
| Date-misalignment auto-repair | calculate_duration_with_date_fix detects bad dates that would yield negative or >24h durations |
User Roles & Permissions
| Role | Capabilities |
|---|---|
| Employee | View/edit own timesheet (pending or rejected only), submit for approval, view own attendance history, use Ask AI for personal timesheet queries |
| Manager | All employee capabilities + team dashboard, approve/reject/edit team timesheets, export CSV, import CSV, bulk approve (background job), view team timesheet status via agent |
| Regional Manager | All manager capabilities + regional-level approval (final sign-off), bulk regional approval |
| Payroll Permission Holder | Generate, view, download, regenerate, delete payroll reports (scoped to their location/user authority) |
| Admin / Super Admin | Everything above + configure pay period settings, timesheet settings, timesheet lockout days, regional approval requirement, submission/approval deadlines |
Permission enforcement runs through IntegratedPermissionService:
can?('approve', 'timesheets')— manager approvalcan?('view', 'payroll')— payroll report accessauthorized_users_for('approve', 'timesheets')— which users I can approve foraccessible_locations_for('view', 'payroll')— which locations I can see payroll for
How We Compare
The Timesheets app is evaluated against the leading Time & Attendance / Timesheet systems. Competitor features listed here were verified via product documentation; features we could not verify are omitted.
Feature Comparison
| Feature | MangoApps Timesheets | ADP Workforce Now | UKG Ready (Kronos) | Deputy | When I Work |
|---|---|---|---|---|---|
| Auto-generated timesheets from attendance | Yes | Yes | Yes | Yes | Yes |
| Manager approve individual timecards | Yes | Yes | Yes | Yes | Yes |
| Bulk approval | Yes | Yes (via timeframe) | Yes (select + approve) | Yes | Yes |
| Overtime auto-calculation | Yes (per-week 40h) | Yes (configurable rules) | Yes (configurable rules) | Yes (by rules) | Yes (weekly/daily thresholds) |
| Regional (second-level) approval | Yes (built-in) | Configurable | Configurable | Not documented | Not documented |
| PTO-aware skip-level routing | Yes | Not documented | Not documented | Not documented | Not documented |
| CSV export | Yes | Yes | Yes | Yes | Yes (Excel) |
| PDF export | Yes | Not documented | Not documented | Not documented | Not documented |
| JSON export | Yes | Not documented | Not documented | Not documented | Not documented |
| SFTP push/pull | Yes | Not documented | Not documented | Not documented | Not documented |
| Direct payroll integrations | Yes (ADP, Workday, Gusto, Paychex, BambooHR, MangoPay) | Native (ADP payroll) | Native (UKG Pro) | Yes (ADP, Gusto, Paycom, Paycor, Xero, etc.) | Yes (integrations + Excel) |
| Per-edit audit trail with reason | Yes (enforced) | Yes (configurable) | Yes | Yes | Yes |
| In-app AI assistant | Yes (Timekeeping Agent, 13 tools) | Not documented | Not documented | Not documented | Not documented |
| Included with core platform | Yes (no extra charge) | Paid module | Paid module | Paid plan | Paid plan |
Sources: ADP Workforce Now documentation, UKG Ready help center, Deputy help center, When I Work help center (see references in Related Resources).
Where We Stand Out
- Included with the platform — Timesheets is a
coreapp (tier:core, auto-enabled). Competitors sell time & attendance as a paid module or standalone subscription. - Built-in regional (two-level) approval — Out of the box. Enterprise competitors often require configuration or higher-tier plans.
- PTO-aware skip-level approval routing — Unique to MangoApps. When an approving manager is on leave, a skip-level manager is automatically eligible to approve.
- Timekeeping AI Agent — 13 tools for time-tracking queries through Ask AI. None of the compared competitors expose a conversational AI agent against their timesheet data.
- Three download formats + SFTP + REST API + Payroll Connect — Every export surface is first-class.
Where Competitors Are Strong
- ADP and UKG have deeper native payroll-engine integration (they are payroll platforms). MangoApps bridges this with Payroll Connect (to ADP, Workday, Gusto, Paychex, BambooHR) and the upcoming in-house Payroll Processing app.
- Deputy and When I Work have stronger retail/hospitality-specific POS integrations (e.g., Square, Clover). MangoApps focuses on the broader workforce platform.
Getting Started
For Employees
- Open Apps → Timesheets (or navigate to
/timesheets) - Your current-period timesheet appears automatically — all clock-in data is already populated
- Review daily entries; click any entry to fix a missing punch or break (reason required)
- Click Submit when the period ends and your hours look right
- Use Ask AI to check status: “Is my timesheet submitted?” or “How many overtime hours this week?”
For Managers
- Navigate to Timesheet Approvals (
/timesheet_approvals) or open the Team Timesheet Dashboard - Review the Pending Approvals queue; click any timesheet to see entries, edits, and audit trail
- Approve with one click, Reject with a required reason, or Edit the entry yourself (edit is audit-tagged)
- Export team timesheets as CSV for offline review
- Use the dashboard’s Missing Timesheets list to nudge non-submitters before the deadline
For Regional Managers
- Navigate to Regional Approvals (
/timesheet_approvals/regional) - Review timesheets that have passed first-level approval and need final sign-off
- Use Bulk Regional Approve for period-close processing
For Administrators
- Go to Admin → General Settings → Pay Period Settings to configure pay period type, start day, and reference date
- Go to Admin → General Settings → Timesheet Settings to configure submission/approval deadlines, lockout days, regional approval requirement, and auto-approval threshold
- Go to Admin → Payroll to generate payroll reports for any date range and location
- (Optional) Configure Payroll Connect to sync with ADP, Workday, Gusto, Paychex, or BambooHR
- Review the Team Timesheet Management Dashboard for organization-wide visibility
Best Practices
For Employees
- Review your timesheet daily — catching a missing punch on Monday is easier than reconstructing it on Friday
- Submit on time — the default submission deadline is 1 day after period end
- Add a clear reason on every edit — the audit trail is permanent and seen by your manager
- Don’t wait for the deadline reminder — proactive submission avoids the reject-resubmit cycle
For Managers
- Check the Team Dashboard once a day during active pay periods
- Use Reject with specific reasons rather than editing yourself — employees learn the right patterns
- For trustworthy employees, consider enabling auto-approval for high-scoring timesheets
- Prioritize the Missing Timesheets list — flagging non-submitters early avoids payroll-day scrambles
- If you’ll be on PTO, confirm your skip-level manager is aware — PTO-aware routing will route to them automatically
For Administrators
- Align Pay Period Settings with your actual payroll schedule before any timesheets exist (changing later can create messy transitions)
- Enable Regional Approval only if you have a legitimate two-level workflow — it doubles the approval effort otherwise
- Set Submission Deadline to match your payroll processing window (give payroll team 2–3 days before run)
- Configure Timesheet Lockout Days to freeze data after payroll closes — prevents retroactive edits that break audit
- Run payroll reports with rest-violation flags enabled if your jurisdiction has meal/rest-break laws (e.g., California)
- Use SFTP exports for scheduled recurring transfers to your payroll processor; use Payroll Connect for real-time bidirectional sync
FAQ
How are timesheets generated?
Timesheets are auto-generated per pay period based on business pay period settings. When an employee first views their timesheet, the system creates it if it does not already exist and syncs in attendance records automatically. Additionally, ProactiveTimesheetCreationJob runs daily to pre-create timesheets for new periods across all active employees.
How is overtime calculated?
Overtime is calculated per week within the pay period using a 40-hour threshold. Hours exceeding 40 in any given 7-day week become overtime, regardless of the pay period length. A biweekly period with 45 hours week 1 and 35 hours week 2 = 5 overtime hours (not 0, even though the 80-hour total is exactly 2×40).
What timesheet statuses exist?
pending → submitted → (regional_pending if regional approval enabled) → approved, with rejected as a branch that returns the timesheet to editable state for resubmission.
Can managers edit employee timesheet entries?
Yes. When a timesheet is in submitted status (or back in pending/rejected), managers can edit entries during their review. All manager edits are recorded in the audit trail with a manager: prefix so the distinction between employee-initiated and manager-initiated edits is preserved.
What happens when my manager is on PTO?
The system’s PTO-aware routing identifies this via effective_approver. A skip-level manager becomes eligible to approve your timesheet without escalation. The routing info is computed by ApprovalRoutingHelper.
What payroll report formats are supported?
CSV, PDF, and JSON. CSV is the richest (full premium breakdowns, all fields). PDF is landscape-formatted for printing. JSON uses ISO 8601 dates for programmatic consumption. All three include regular/overtime/premium pay splits, leave data, and rest-violation flags.
Does the data stay synchronized with attendance in real time?
Yes. RealTimeTimesheetService runs on every attendance event (clock-in, clock-out, break). It finds or creates the correct timesheet and entry, updates the live data, and broadcasts to the employee’s browser via ActionCable. If the employee has manually edited the entry (edited: true), attendance sync respects the edit and won’t overwrite it.
Can employees enter time for a future date?
No. TimesheetEntry#future_entry? blocks any edit where the entry date (or shift start) is after today. Future entries are rendered read-only until the shift occurs.
How do I connect to my existing payroll provider?
Use Payroll Connect. Built-in connectors exist for ADP Workforce Now, Workday HCM, Gusto, Paychex, BambooHR, and MangoPay, plus a custom API connector for other providers. Configuration is under Admin → Payroll Connect, where you enter API credentials and map employee records.
Is there a background job that auto-approves clean timesheets?
Yes, if enabled. TimesheetScoringService computes an accuracy score based on missing punches, edited entries, and business scoring rules. If the score meets the threshold (default 95), the timesheet auto-approves with auto_approval_reason recorded.
Can I use the API to pull timesheet data into an external system?
Yes. Api::V1::TimesheetsController exposes REST endpoints: GET /api/v1/timesheets, GET /api/v1/timesheets/:id, GET /api/v1/timesheets/current, PATCH /api/v1/timesheets/:id, POST /api/v1/timesheets/:id/submit. Token scopes required: read:timesheets for reads, write:timesheets for mutations.
Related Resources
MangoApps Apps
- Apps & Extensions Overview — Full app catalog
- Attendance App Overview — The source of clock-in data that populates timesheets
- Scheduling Teams App Overview — Shift scheduling that seeds timesheet entries
- Meal Compliance App Overview — Uses timesheet break patterns for waiver management
- Payroll Connect — Integrate with ADP, Workday, Gusto, Paychex, and BambooHR
- Payroll Processing — In-house payroll engine (coming soon)
Documentation
/src/docs/testing/TIMESHEETS_TEST_PLAN.md— Full QA test plan
External References (competitor comparison sources)
- ADP Workforce Now Time & Attendance
- UKG Ready Time & Attendance
- Deputy — Exporting Timesheets
- When I Work — Approving Timesheets
The Timesheets App replaces manual time tracking with a system that populates itself, tracks every change, and exports clean data to your payroll engine. Clock in, work, submit, approve — pay accurately.