Product Documentation
Complete reference for every feature and setting in Schedaddle.
Overview
Schedaddle is a staff scheduling tool for shift-based businesses. It replaces Sunday-night spreadsheet sessions with a structured weekly planner, visual day-level role assignment, automated draft generation, and one-click publishing that notifies your team by email.
Core workflow: Set up your team → Configure availability → Generate a draft → Review and adjust → Publish.
Weekly Schedule
Assign shifts across a 7-day grid with live labor budget tracking and violation alerts.
Day View
Paint role assignments across 30-minute blocks. Drag to assign, click to erase.
Auto-Generate Draft
The Smart Shift Builder (8-step engine) builds a full week from your rules, availability, and peak targets.
Available to Add
Bench panel shows unscheduled employees with their availability and weekly hours — right in the day view.
Coverage Report
Generation flags surface unfillable slots with human-readable reasons before you publish.
Publish & Notify
Email personalised schedules + PDFs + .ics calendar files to your whole team in one click.
Managing Your Team
Adding employees
Go to Team in the top nav. Click Add Employee. Fill in name, role, employment type, and email. Email is required to receive published schedules — employees without one are scheduled but not notified.
Roles
GM and ASM are manager-level. The algorithm guarantees manager coverage — at least one manager must be scheduled during operating hours. Part-Time staff fill coverage and budget gaps.
Employment type
Full-time employees are subject to ft_max_hours per week (typically 40h). Part-time employees are subject to pt_min_hours and pt_max_hours. Employment type is important — setting an ASM as part-time will cap their hours at the PT limit and cause coverage gaps.
Availability
Click Set Availability on any employee to define recurring weekly windows. Days with no windows = unavailable that day. The algorithm treats unconfigured employees as available all day. Use Temporary Unavailability for date-range blocks without changing permanent availability.
Qualifications
Employees can hold qualifications (e.g. HubMaster / Team Lead) that unlock restricted roles. Without the qualification, that role cannot be painted in the Day View and the draft generator won't assign it.
New hire flag
Mark employees as new hires to track training hours. When a new hire accumulates enough Training-role hours across published weeks (configurable threshold), they are automatically graduated on the next publish.
Exclude from auto-schedule
Toggle this for employees who should never be auto-scheduled — on-call staff, contractors, etc. They remain visible and can be added manually.
Weekly Schedule
The weekly grid shows one week (Mon–Sun), one row per employee. The sticky left column shows name, role, and weekly hours. Click any cell to assign or change a shift.
Week navigation
Use ← / → to move between weeks. Click Today to jump to the current week. Click any date column header to open the Day View for that day.
Sidebar panels (top to bottom)
Auto-Generate Draft — Generates a full week in one step. The ▾ dropdown also offers Training Only mode (see below). Locked days are skipped; a coverage report appears after generation.
Holidays This Week — Lists any public holidays in the current week. Shown immediately below the generate button for decision context.
Labor Budget — Enter your weekly forecast; budget bars show scheduled vs. target hours from the labor matrix. Amber/red bars signal over-schedule.
Violations — Hard (red) and soft (amber) violations update in real-time as you edit shifts.
Availability Conflicts — Employees scheduled outside their availability window.
Manager Coverage — Gap indicators per day — green = covered, red = gap.
Shift Templates — Quick-assign templates. Hover to edit. All templates are also available in each cell's dropdown.
Day column headers
Holidays show a 🌟 icon with the holiday name on hover. Today's column is highlighted in arctic blue. Long-weekend weekdays (where elevated staffing applies) show a small arctic dot. Approved days show 🔒.
Row hover
Hovering any cell in a row highlights the employee name column with an arctic tint — making it easy to track which row you're in across wide grids.
Day View
A 15-hour grid (08:00–23:00) in 30-minute blocks for every scheduled employee. Click or drag across blocks to paint role assignments.
Role palette
Select a role on the left, then click or drag across any block within an employee's shift. Blocks outside the shift window are a darker gray (not in shift). Use Erase mode to clear assignments. ↩ Undo reverses the last gesture. Drag roles in Edit mode to reorder the palette.
Available to Add (bench panel)
Directly below the scheduled employee rows, the bench panel shows every unscheduled employee with: today's availability window, their current weekly hours vs. cap, and how many hours they need to reach minimum. Click + Add to pre-fill the Add Employee modal.
Auto-fill
Click Auto-fill to paint roles for all employees using your configurable role rules (see Role Assignment Rules). The algorithm assigns roles in priority order, respecting min/max slot counts and managers-only restrictions.
Approve day
Click Approve to lock the day. Approved days are excluded from the next draft run. If shifts change after approval, the day is flagged for re-approval. Use Unlock to make changes.
Auto-Generate Draft
Click Auto-Generate Draft in the sidebar to build a full week from your rules. The algorithm runs 8 phases in sequence. Locked (approved) days are skipped — their hours are pre-seeded into the algorithm so budget and equity calculations remain accurate for the whole week.
Manager assignment — 3 rounds
Round 1: assigns one opener manager per day (equity-rotated — managers with fewer recent early shifts go first). Round 2: assigns one closer manager per day. Between Rounds 2 and 3, peak coverage runs (see Phase 2). Round 3: fills remaining roster days for under-capacity managers, hardest-day-first.
Peak coverage (runs between manager Rounds 2 and 3)
Fills peak windows (e.g. Friday 17:00–21:00 min 5 staff) using available PT staff. Days sorted hardest-first: highest min_staff first, fewest available staff as tiebreaker. This runs before manager Round 3 so peak windows get priority over opportunistic manager roster fills.
Opener slots
Fills the configured minimum number of openers per day using PT staff. Sorted by opener equity — fewest recent early shifts first.
Closer slots
Fills the configured minimum number of closers per day. Sorted by closer equity.
Labor budget fill (staff hours)
Pass 1: maximises ASM (full-time) hours toward ft_max_hours before adding PT shifts. Pass 2: fills remaining budget gap with PT, sorted by least-loaded day first to prevent weekday bias.
PT minimum hours
Ensures every PT employee reaches pt_min_hours. Assigns mid → opener → closer templates in preference order. Also uses least-loaded-day ordering.
Manager hours budget
If the labor matrix specifies a manager hours target, adds additional shifts to managers until the target is reached. Days sorted hardest-first.
New hire training shifts
Schedules new hires who have not yet reached the graduation threshold. Shifts are anchored to a GM's shift window (minimum overlap configurable). If no GM overlap is possible and training_require_gm is off, falls back to a standard template.
Coverage report
After generation, a banner appears showing whether all coverage requirements were met. If gaps exist, click View details to see per-day shortfalls with human-readable reasons and a Go to Day link for each gap.
Holiday awareness
When a weekday is a public holiday (or part of a long weekend above your configured threshold), the algorithm uses Saturday peak rules instead of the weekday rules — without any manual adjustment. See Holiday-Aware Scheduling below.
Training-Only Mode
Click the ▾ dropdown next to Auto-Generate Draft and select Training Only. This mode re-generates only new hire training shifts — anchored to the current manager schedule — without touching any other shifts.
Use this after manually adjusting the manager schedule: run Training Only to re-anchor new hire shifts to the updated GM windows.
Training-only mode always requires GM anchor — the fallback template is never used, regardless of the training_require_gm setting. If a new hire's availability doesn't overlap with any GM shift by the required minimum, no shift is placed for that day.
After running, a result message appears below the button: green for success (lists names and count), red with a specific reason if nothing was generated.
Coverage Report
After every auto-draft run, a coverage banner appears in the sidebar:
- Green — All coverage requirements met. Shows staff/manager hours vs. targets.
- Amber — N coverage gaps detected. Click View details → to see a modal with per-day shortfalls.
Each shortfall entry shows: the day, the shortfall type (peak window / openers / closers / manager budget), how many were assigned vs. required, and a human-readable reason explaining why the gap couldn't be filled (e.g. "No PT staff with opener availability on Monday — 2 at hour cap").
Day column headers show a small ● dot for any day with active coverage gaps. These update live as you manually add shifts — the indicator disappears when the gap is resolved.
Publishing & Notifications
Click Publish in the weekly schedule header. Use the ▾ dropdown to choose a mode:
- Email & App — Emails every employee + sends a push notification to the mobile app.
- App only — Push notification only, no email.
- Silent — Marks as published with no notifications (useful for draft-testing).
What each email contains
- Personalised HTML showing only that employee's shifts
- Weekly Schedule PDF (all employees, all days) — versioned v1, v2, etc.
- Daily Deployment PDF (7 pages, one per day, with role block grid) — for ASM-led deployment without the GM present
- .ics calendar file with their individual shifts (imports into Google Calendar, Outlook, Apple Calendar)
Versioning
Every post-publish edit increments the week's version number. PDFs are stamped v1, v2, etc. so staff can confirm they're looking at the latest version. The version badge appears in the header once the week has been modified and republished.
Unpublish
Use Unpublish (in the ▾ dropdown) to return a week to draft state. Emails already sent cannot be recalled, but the week becomes editable again and re-publishable.
Re-publishing
Publishing an already-published week re-sends emails and re-syncs the calendar. Days flagged with ⚠ (changed after approval) must be re-approved before republishing.
Holiday-Aware Scheduling
Schedaddle automatically adjusts peak coverage requirements on public holidays and long weekends.
Holiday data — three-tier union
Holiday data is fetched from three sources, merged by date, with manual overrides always winning:
- date-holidays npm — computed from astronomical algorithms; covers 180+ countries including Malaysia federal + state holidays
- Nager.Date API — REST API that adds replacement/substitute holidays
- Google Calendar API — supplementary coverage for SEA markets
Click ↻ Refresh in Settings → Draft Rules → Public Holidays to fetch the current year + January–February of next year (so December scheduling has January holiday context).
Traffic profiles per holiday
Each holiday can be tagged with a traffic profile: Weekend staffing (default), Normal weekday, Low traffic, or Closed. When set to Weekend staffing, the algorithm applies Saturday peak rules to that day. Set profiles in Settings → Draft Rules → Public Holidays.
Long weekend detection
When consecutive non-working days (weekends + holidays) form a stretch at or above your configured threshold (default: 3 days), all weekdays in that stretch automatically receive elevated staffing — even if they aren't individually listed as holidays. This catches replacement holidays that might not yet be in the database.
Apply rules for
Configures which day's peak rules to apply on holiday weekdays. Default: Saturday. Change this in Settings → Draft Rules → Public Holidays → Apply rules for.
Long weekend trigger
The minimum number of consecutive non-working days that activates long weekend mode. Default: 3. A single Monday holiday (3-day weekend: Sat + Sun + Mon) triggers elevated staffing on the Monday. Increase to 4 if you only want the upgrade for 4-day+ stretches.
Shift Templates
Named start/end time pairs shown in the shift cell dropdown. Making common shifts one-click.
Manager only
When checked, only SMs and ASMs see this template in their dropdowns. Also used by the algorithm for MOD (Manager on Duty) shift detection — ASMs on a manager-only shift are automatically assigned the Flex role in auto-fill.
Applicable days
Restrict a template to specific days of the week. A "Close F,S,Su" template stays hidden on weekday dropdowns.
Role Assignment Rules
Replaces the old fixed slot-limit system. Each non-system role can be configured with priority, minimum, and maximum. Drag the ⠿ handle to set priority order (top = highest priority). Save after reordering.
Priority order
The algorithm assigns roles in this order. Higher priority roles are filled first. If the top role is at its maximum, the algorithm moves to the next eligible role.
Min
The minimum number of employees who should have this as their primary role. During post-break rotation, the algorithm won't rotate employees away from a role if doing so would drop it below its minimum.
Max
The maximum number of employees in this role simultaneously. Once the maximum is reached, additional employees fall through to the next priority role. Click ∞ to set unlimited (recommended for the last/fallback role).
Managers only
When enabled, part-time staff skip this role entirely during auto-fill. Only GMs and ASMs are assigned it. Use this for Flex / management roles. GMs still consume a Flex slot — if your max is 2, two overlapping managers can both be in Flex simultaneously.
Draft Rules
Openers required
Minimum openers the generator must assign per day. If it can't be met, a coverage gap is reported.
Closers required
Minimum closers per day.
Full-time max hours
Weekly hour cap for FT employees. The generator stops adding shifts once an FT employee would exceed this. If a FT employee already has hours on locked days, those count toward the cap.
Part-time min hours
The generator tries to reach this total for each PT employee in Phase 6.
Part-time min hours — soft
When on, Phase 6 stops topping up part-time minimums once the labor-budget target is reached, so hitting minimums doesn't blow the budget. When off, minimums are always filled.
Part-time max hours
Weekly hour cap for PT employees.
MOD shift role
The role assigned to Manager-on-Duty shifts in day-view auto-fill. "Auto" uses the top-priority role from Role Assignment Rules.
ASM hours count toward
Which labor-budget bar an Assistant Manager's hours count against — Staff hours (treated like staff) or Manager hours (treated like a GM, out of the Staff bar). This drives both the budget bars and how ASMs are scheduled (staff fill in Phase 5 vs the manager budget in Phase 7).
ASM scheduling priority
Whether all ASMs get full manager priority (roster days + manager budget), or only full-time ASMs do. With "full-time only," part-time ASMs compete for shifts like staff and are used for manager coverage only as a fallback when no full-time manager is available.
New hire graduation threshold
Training-role hours across all published weeks at which a new hire is auto-graduated. Graduation happens on the next publish after the threshold is crossed.
Clopen Prevention
A "clopen" is closing late and opening early the next day with little rest in between. When enabled, the generator de-prioritises (does not hard-block) these assignments and flags any that are forced.
Prevent clopens
When on, the draft pushes clopen-risky candidates to the back of the list, and surfaces any forced clopen as a warning after generation.
Minimum rest period
The minimum hours between a closing shift and the next opening shift before the pairing counts as a clopen.
Exclude managers
When on, GMs and ASMs are exempt from the clopen rule (managers often need to clopen by necessity).
Training Settings
Training shift duration
Length of each training block the generator assigns to new hires (default: 6 hours).
Min. manager overlap required
Minimum hours a new hire's shift must overlap with a GM shift for the training anchor to be valid (default: 3 hours). If no GM shift overlaps by this amount, the day is skipped in training-only mode.
Manager supervision
When on, training shifts in the full auto-draft also only place if a GM is present (same as training-only mode). When off (default), the full draft falls back to a standard template if no GM overlap is found.
Peak Coverage Rules
Enforce minimum staffing during high-traffic periods. Peak rules run in Phase 2 of the draft — before openers, closers, and budget fill — so they get first pick of available PT staff.
Days
Days of the week this rule applies (multi-select). 0 = Sunday.
Peak window
Start and end time of the high-traffic period.
Minimum staff
Total employees (any role) required to be scheduled during this window. If the draft falls short, a coverage gap is reported with a reason.
Days within the week are processed hardest-first (highest min_staff requirement first), so high-demand days are filled before low-demand ones. Within a day, peak rules also inherit the holiday-aware DOW substitution — a Monday holiday with Saturday peak rules will apply Saturday's peak windows.
Labor Matrix
Maps your weekly forecast metric to target staffing hours. The matching tier's hours become the budget bar targets on the schedule page. Add tiers to cover your full forecast range. Leave the last tier's max blank for an open-ended cap.
Break & Hours Settings
Min break duration
Consecutive Break blocks required to satisfy the break rule (in minutes). If a shift exceeds the trigger but has fewer break blocks than this threshold, a violation is flagged.
Break trigger hours
Shift length above which a break is mandatory. Shifts below this length don't require break blocks.
Break time & worked hours
Whether break time counts as worked hours is controlled by the Paid breaks toggle in Time Clock & Attendance — when off (the default), break minutes are subtracted from worked hours in reports and exports; when on, breaks count as paid time.
Roster days / week
Standard working days per week for a full-time employee. The draft generator uses it as the default cap — a full-time employee is scheduled up to this many days per week (5 by default) before the generator stops adding their shifts.
Normal shift hours
Standard shift length. Reference value for configuring the labor matrix.
Weekly OT threshold
Hours per week beyond which overtime applies. Hard violation flagged when exceeded.
Daily OT threshold
Hours in a single day beyond which overtime applies. The Hours report and payroll exports use the more protective (lower) of this and your market's statutory daily threshold, and the schedule flags any day scheduled over it.
Time Clock & Attendance
Controls how staff clock in/out from the mobile app and how attendance is enforced. (Kiosk PIN, sessions, and attendance-rule notifications live under Settings → Web Kiosk.)
Geofence mode
How the geofence is applied when an employee taps clock in: Hybrid (geofence verified at punch-in, allowed if location is unavailable), Manual (employee taps clock-in, no location check), or Geofence required (block clock-in outside the store radius). GPS is sampled only at the moment of clock-in, not continuously. Full Sprint.
Geofence radius
Distance from the store, in metres, within which clock-in is allowed. Below 50m is not recommended — phone GPS accuracy is ±10–50m, so a tight radius causes missed check-ins.
No-show threshold
Minutes after shift start with no clock-in before the employee is marked as a no-show and the GM is notified.
Paid breaks
When on, breaks count as worked hours (not deducted) and employees aren't required to clock out for breaks. When off (the default), break time is subtracted from worked hours.
Roles
Each store has 8 role codes. Labels and colours are customisable in Settings → Roles. Internal codes never change (role block data stays valid). System roles (Opening, Closing, Break, Training) are assigned automatically and cannot be reordered in role rules.
Opening
Auto-assigned to blocks before the opening boundary time. System role.
Closing
Auto-assigned to blocks from the closing boundary time onward. System role.
Flex
Management/supervisory. Typically managers-only. Slot-limited.
HubMaster / Team Lead
Requires qualification. Slot-limited. Only qualified employees can be assigned.
Lobby / Floor
Primary customer-facing role. Slot-limited. Alternates with Hub after break.
Hub / Counter
Secondary service role. Default unlimited. Alternates with Lobby after break.
Training
New hire training shifts. Hours count toward graduation threshold. System role.
Break
Break period. Two consecutive blocks visualise as a 45-minute diagonal. System role.
Violations
The Violations panel updates in real-time as you edit the schedule.
Hard violations (red — must resolve before publish)
- Weekly overtime — Scheduled hours exceed the weekly OT threshold.
- 7+ consecutive days — Employee is scheduled without a rest day.
Soft violations (amber — warnings)
- Missing break — Shift exceeds the break trigger threshold with no valid Break blocks.
- Availability conflict — Employee scheduled outside their stated availability window or temp restriction.
Coverage gaps (amber dot on day header)
Coverage gaps from the draft generator appear in the Coverage Report panel (not the Violations panel). They update live as you add shifts manually — the dot disappears when the gap is resolved.
Integrations
Connect Schedaddle to payroll, HRIS, POS/booking, accounting, and automation tools. Manage everything in Settings → Integrations; export hours from Reports → Hours Worked.
Payroll & HRIS exports
Export each employee's hours for a pay period as a provider-shaped CSV. Totals use the same engine as Reports → Hours, so the file always matches what managers see. Set your pay period in Settings → Payroll Setup, then use Export to payroll on the Hours Worked report — pick the provider, Actual or Scheduled hours, and a date range.
Ready: Gusto, Generic CSV, Kakitangan (Malaysia — its Monthly Payroll Import layout). Beta (verify the column mapping on first run): ADP RUN, Paychex Flex, BambooHR; the Malaysian systems Talenox, PayrollPanda, HReasily (overtime by Employment-Act category); and ADP Workforce Now, Paylocity, Paycor, Justworks, Roll by ADP, SurePayroll, Wave, Toast, Xero. Employees export by payroll ID where set, otherwise by name (a warning lists who's missing one). Scheduled-hours export needs The Schedaddle; actual (clocked) hours need The Full Sprint.
Not available as CSV: Square Payroll and QuickBooks Online (use their native connections, below); SQL Payroll and AutoCount (Malaysian desktop systems — send us a sample export to add them).
Webhooks
Outbound, HMAC-signed events to your endpoint (Schedaddle+). Events: schedule_published, clock_in, clock_out, shift_called_out, shift_swap_approved. Verify the X-Schedaddle-Signature header (SHA-256 HMAC of the raw body, keyed by the secret shown once on creation). Failed deliveries retry with backoff (1m → 24h, abandoned after 6); an endpoint that fails 3 times in a row is paused.
Calendar feed (iCal)
Each employee can subscribe to a personal calendar feed of their shifts (past 30 days + upcoming) from the mobile app. The feed URL is token-secured and refreshes every few minutes — works with Google Calendar, Apple Calendar, and Outlook.
Roller (booking & POS)
For entertainment venues. Connect with the Data API Client ID + Secret from your ROLLER Venue Manager (Full Sprint). Schedaddle pulls bookings and revenue hourly to drive labor suggestions and the day-view demand overlay. Read-only today; pushing staff/sessions back to Roller is planned.
QuickBooks, Square, Clover & Lightspeed
Native connections via secure OAuth (Schedaddle+) — click Connect and authorize; tokens are stored encrypted. QuickBooks Online and Square handle payroll/time data directly (no file upload); Square, Clover, and Lightspeed also feed POS sales into the labor-cost overlay.
Public API & Zapier
A versioned REST API (/api/v1, Full Sprint) for employees, schedules, attendance, and hours — authenticated with a store API key from Settings → Integrations. Use it directly or through Zapier to connect Schedaddle to thousands of apps.
Google Calendar
Connect in Settings → Integrations. Once connected, publishing creates or updates events in a dedicated store calendar. Employees receive invite emails. Disconnect removes the refresh token but does not delete existing events.
Google Calendar API (holiday data)
A separate Google Calendar API key (set via GOOGLE_CALENDAR_API_KEY) is used for the three-tier holiday data refresh. This is a server-side API call — it does not require user consent or OAuth.
Email notifications (Resend)
Configure RESEND_API_KEY and RESEND_FROM. The FROM address appears as Store Name <schedule@schedaddle.co> in employee inboxes. The integration status badge in Settings confirms whether Resend is active.
Push notifications (mobile app)
When the Schedaddle mobile app is connected, publishing sends a push notification to all employees with the app installed. Push is included in Email & App mode and App Only mode.
Web Kiosk (Time Clock)
The Web Kiosk is a browser-based time clock that runs on a dedicated store computer. Employees tap their name, enter their personal kiosk PIN, and clock in or out — no app or phone required. It is completely isolated from the manager's scheduling session: the kiosk authenticates with its own signed cookie and employees cannot navigate to the schedule or any other manager screen.
Requires: The Full Sprint subscription, a KIOSK_SECRET environment variable, and three Supabase tables (store_kiosk_config, employee_kiosk_pin, kiosk_pin_setup_token).
Two PINs
Store Kiosk PIN
SM/ASM only. Unlocks the kiosk session on the store computer. Set in Settings → Web Kiosk. Minimum 6 digits.
Employee PIN
Each employee sets their own. Used to identify themselves when clocking in. Minimum 4 digits. Never seen by managers.
Manager setup (one time)
1. Go to Settings → Web Kiosk → set a Store Kiosk PIN and session duration.
2. Open the Kiosk Link on the store computer and bookmark it. (Or click Kiosk in the Schedule nav.)
3. Enter the store PIN — the kiosk session starts. Close the main Schedaddle tab safely.
Employee PIN setup
Employees set their own PIN via a secure email link (48-hour, single-use). There are three ways to send the link:
The employee opens the link, enters a PIN twice to confirm, and they're done. PIN is verified server-side — the hash never reaches the browser.
Employee clock-in/out flow
Roster status badges
Expected (gray)
Shift has not started yet
Late (orange)
Past scheduled start time, not yet clocked in
On Shift (green)
Currently clocked in
On Break (amber)
Break in progress
Done (blue)
Clocked out — shift complete
No Show (red)
Shift ended with no clock-in ever recorded
Done and No Show rows are dimmed and non-tappable. "Late" is computed in real-time using the store's timezone. No Show is only set after the shift's end time has passed — a late clock-in before shift end is always valid.
Resetting an employee's PIN
Go to Team → [employee name] → Availability. The Kiosk PIN section shows the current status and a Send Reset Link button. Clicking it emails the employee a fresh 48-hour setup link. The old PIN stays active until they complete the reset.
Session management
End session from the kiosk
Tap "End Session" (top-right corner of the roster). Clears the cookie and redirects to the login page.
End all sessions remotely
Settings → Web Kiosk → End All Kiosk Sessions. Instantly invalidates all active sessions on all devices. The store PIN is unchanged — re-enter it to resume.
Session duration
8h, 12h, 18h, 24h, 48h, or "Keep open" (never auto-expires). For 24/7 stores use Keep open.
Attendance data
All events are stored in shift_attendance and break_record. Feeds into Reports → Hours Worked and Reports → Hours Breakdown. Whether breaks are paid is configured in Settings → Mobile App Settings → Breaks are paid.