Administrator Shift Management Documentation

Table of Contents

1. Overview

The Shift Management module lets administrators define, schedule and maintain employee shifts. It ensures accurate timekeeping, enforces rest rules, supports recurring schedules and integrates with the DTR and payroll modules.

Implemented admin views:

  • resources/views/users/admin/shift/index.blade.php
  • resources/views/users/admin/shift/create.blade.php

2. Purpose & Scope

Purpose:

  • Create and maintain shift templates and scheduled shifts for employees and teams.
  • Ensure schedule compliance with labor rules and internal policies.
  • Provide tools for coverage planning, shift swapping and exceptions.

Scope:

  • Admin-level shift creation/editing and mass scheduling.
  • Template creation and recurring shifts.
  • Integration hooks for DTR, payroll and absence/leave systems.

Excluded:

  • Employee self-scheduling UX (documented separately).
  • Shift bidding algorithms (not in scope).

3. Access & Permissions

Roles & permissions recommended:

  • Admin — full CRUD on shift templates and schedules, overrides, publish/unpublish.
  • Scheduler / Team Lead — create/edit shifts for own teams, request publish.
  • HR — view schedules, approve exceptions, audit.
  • Employee — view assigned shifts, request swap (non-admin flow).

Minimum permission flags:

  • view_shifts
  • manage_shifts
  • publish_shifts
  • override_shift_rules

4. Admin UI Pages

Files:

  • index.blade.php — list of shift templates and scheduled shifts
  • create.blade.php — create/edit shift template or schedule

4.1 Index View — features

Purpose: list templates and upcoming schedules, enable bulk actions.

Key UI items:

  • Table rows: Shift ID, Name, Department/Team, Start / End, Duration, Break, Recurrence, Active/Published, Assigned Employees, Status, Actions.
  • Filters: date range, department, shift type, template vs scheduled shifts, active/archived.
  • Bulk actions: publish/unpublish, assign to employees, export, delete (audit logged).
  • Quick actions: duplicate template, quick-edit time, view schedule coverage heatmap.

Behavior:

  • Toggle between "Templates" and "Scheduled Shifts" tab.
  • Row-level badges indicate violations (insufficient coverage, missing breaks, overtime risk).
  • Pagination and server-side filtering for large orgs.

4.2 Create / Edit View — features

Purpose: create or update shift templates / scheduled shifts.

Form fields:

  • Shift name (required)
  • Code (unique short code)
  • Department / location / team
  • Start time, End time (time pickers; support cross-midnight)
  • Duration (auto-calculated)
  • Break windows (start/end, minutes)
  • Shift type (regular, night, split, flex)
  • Recurrence settings (none / daily / weekly / custom)
  • Effective date range (start & optional end)
  • Max concurrent assignments (coverage)
  • Required roles / positions
  • Publish flag (active / draft)
  • Notes and policy tags
  • Auto-assign settings (by role, by headcount)
  • Attachments / documentation

Validation UX:

  • Show computed working hours, shift crossing midnight warning, suggested compliance notes.
  • Save as Template or Save & Schedule.

Actions:

  • Preview schedule (calendar snapshot)
  • Assign employees (single or bulk)
  • Save draft / Publish

5. Shift Types & Metadata

Common shift types:

  • Regular — standard daytime shift.
  • Night — premium pay rules, different rest rules.
  • Split — two non-contiguous segments.
  • Flex — variable start/end within bounds.
  • On-call / Standby — not full shift; used for callbacks.
  • Shift Template — reusable configuration for scheduling.

Metadata and flags:

  • Shift code, color (calendar), pay code, meal/break enforcement, overtime eligibility, required certifications, blackout tagging.

6. Scheduling Rules & Business Logic

Business rules to enforce at create and assign time:

  • start_time < end_time; allow cross-midnight (end next-day).
  • Enforce minimum rest period between end of previous shift and start of next shift.
  • Enforce minimum break duration for shifts longer than threshold (e.g., >=30 minutes after 5 hours).
  • Limit maximum contiguous working hours and overtime eligibility.
  • Prevent double-assignment for a single employee at overlapping times.
  • Respect location/timezone differences; store UTC timestamps with user timezone for display.

Examples:

  • Night shift 22:00–06:00 crosses midnight; stored as start=22:00 day X, end=06:00 day X+1.
  • Split shift: Segment A 08:00–12:00, Segment B 14:00–18:00; total hours = 8, breaks applied accordingly.

7. Recurring Shifts & Templates

Recurrence options:

  • Daily, Weekly (multiselect days), Biweekly, Monthly (date or pattern), Custom cron-like schedule.
  • Set occurrence range: start_date & end_date or indefinite until manually stopped.
  • Exceptions: holidays, blackout dates, manual overrides per occurrence.

Template usage:

  • Create template → preview occurrences → adjust occurrences individually if exceptions required.
  • Versioning for templates (so changes can be applied to future occurrences only).

8. Shift Swaps, Coverage & Overrides

Swap flow (admin perspective):

  • Employees request swap via employee UI; team lead or admin approves.
  • Admins can force-swap and must record reason and audit metadata.

Coverage management:

  • Dashboard shows staffing counts per shift and highlights under-staffed shifts.
  • Auto-assign suggestions: fill required headcount from eligible pool (role, availability).
  • Alerts for shifts with insufficient coverage during publish.

Overrides:

  • Admins can override rule failures (e.g., short rest) but must provide comment and designate additional approver (HR).

9. Validation & Conflicts

Validation checks:

  • Overlap detection for assigned employees.
  • Late assignment beyond publish cutoff.
  • Conflicts with approved leaves / DTR entries.
  • Compliance flags (short rest, max weekly hours exceeded).

UI should:

  • Surface conflict details and options: auto-resolve, reject assignment, require override.
  • Provide a "conflict report" for batch assignments.

10. DTR & Payroll Integration

Integration goals:

  • Translate published scheduled shift into DTR expectations.
  • Feed shift time windows to employee DTR for accurate time-in/out validation.
  • Mark premium pay codes for night/holiday shifts to payroll.

Sync behavior:

  • Publish => create DTR schedule entries (async job).
  • Update => propagate changes to DTR if within allowed window; otherwise create change record for payroll.
  • Cancellation after payroll lock requires manual adjustment and audit entry.

Reconciliation:

  • DTR vs scheduled shift mismatch reports.
  • Payroll adjustments: negative entries or corrections for already-processed payroll.

11. Notifications & SLA

Notifications:

  • Assigned employee: shift assigned or changed.
  • Manager / Team lead: under-coverage or approval needed.
  • Admin: publish confirmation, errors during DTR sync, override requests.

SLA:

  • Shift publish should be completed within defined lead time (e.g., 72 hours before shift start).
  • Notifications for missing assignments / coverage should be sent daily for upcoming 7-day window.

Templates:

  • Subject: "New Shift Assigned — {shift_name} {date}"
  • Subject: "Shift Coverage Alert — {team} {date range}"

12. Reporting & Analytics

Useful reports:

  • Schedule roster by period (team/employee).
  • Coverage heatmap (by date/time).
  • Compliance report: short-rest events, maximum weekly hours breaches.
  • Assignment utilization: unassigned shift hours and overtime risk.
  • Change log: published changes after payroll lock.

Export formats: CSV, Excel, JSON. Allow scheduled report delivery.

13. API Endpoints & Data Model

Suggested endpoints:

  • GET /api/admin/shifts (filters: date, team, status)
  • GET /api/admin/shifts/{id}
  • POST /api/admin/shifts (create template or schedule)
  • PUT /api/admin/shifts/{id}
  • POST /api/admin/shifts/{id}/assign (assign employees)
  • POST /api/admin/shifts/bulk (bulk create/assign)
  • POST /api/admin/shifts/{id}/publish
  • POST /api/admin/shifts/{id}/override (with reason)
  • POST /api/admin/shifts/{id}/sync-dtr

Suggested model fields:

  • id, code, name, department_id, start_time, end_time, duration_hours, break_minutes, shift_type, recurrence_rule (json), effective_from, effective_to, max_assignments, paycode, published (bool), created_by, updated_by, meta (json), audit_trail (json)

Example JSON create payload: { "code": "SFT-NIGHT-01", "name": "Night Shift - Ops", "department_id": 9, "start_time": "22:00:00", "end_time": "06:00:00", "break_minutes": 60, "shift_type": "night", "recurrence_rule": { "freq": "weekly", "byweekday": ["mon","tue","wed","thu","fri"] }, "effective_from": "2025-01-01", "max_assignments": 5, "paycode": "NIGHTPREM", "published": false }

14. Testing & QA Checklist

Unit tests:

  • Time calculations including cross-midnight & DST.
  • Recurrence expansion & exceptions.
  • Overlap detection and conflict validation.

Integration tests:

  • Publish -> DTR creation -> payroll sync (simulate payroll lock).
  • Assignments vs approved leaves -> ensure conflict flagged.

End-to-end:

  • Create template -> schedule range -> assign employees -> publish -> DTR receives schedule.

Performance:

  • Ensure bulk schedule creation is batched and returns a validation summary.
  • Index queries must handle tens of thousands of schedules.

15. Troubleshooting & Known Issues

Common problems:

  • Duplicate assignments → run overlap query to locate conflicts.
  • DTR mismatch → verify timezone storage, sync logs and correlation ids.
  • Publish failures → check async job queue and retry with logs.

Tips:

  • Use preview calendar before publishing to detect coverage gaps.
  • Use effective_to to prevent accidental indefinite schedules.

Appendix — Examples & SQL snippets

  1. Detect overlapping shifts for an employee: SELECT s1.* FROM shifts s1 JOIN shifts s2 ON s1.employee_id = s2.employee_id AND s1.id <> s2.id WHERE s1.start_time < s2.end_time AND s1.end_time > s2.start_time AND s1.employee_id = {employee_id};

  2. Expand recurrence example (pseudo-query) — ensure recurrence expansion service logs all exceptions.

Document version: 1.0
Maintainers: Product / Scheduling / HR / Engineering
Last updated: December 5, 2025