Badges, Warnings, and Validation Reference
Reference for scheduler badges, validation warnings, deployment rules, and operational metadata display.
Before you start
- You understand the scheduler layout and job card structure from the views guide.
Expected outcome
You can identify every badge, understand every warning type, and know the validation rules that govern deployment readiness.
Job card badges
Badges appear on job cards (board, timeline), in the planner list, and in the Quick View dialog. They are rendered by schedulingBadges.jsx.
Deployment badges
Deployment badges show the current deployment state and, for deployed jobs, whether the engineer has acknowledged receipt.
| Badge | CSS class | Condition | Source fields |
|---|---|---|---|
| Draft | badge-default | deploymentState === "draft" and not deploy-ready | job.deploymentState |
| Ready | badge-success | deployReady === true | job.deployReady |
| Deployed ✓ | badge-accent | Deployed and engineer has acknowledged | job.deploymentState, job.engineerAcknowledgedAt |
| Deployed ○ | badge-accent-muted | Deployed but awaiting engineer acknowledgement | job.deploymentState, job.engineerAcknowledgedAt |
The shared deploymentBadge() function in schedulingBadges.jsx renders these badges consistently across all surfaces.
Operational badges
| Badge | Appearance | Condition | Source field |
|---|---|---|---|
| 👥 N | Default badge with emoji + count | crewSizeRequired > 1 | job.crewSizeRequired |
| OOH | Accent badge | outOfHours === true | job.outOfHours |
| MEWP | Default badge | "mewp" in accessEquipment | job.accessEquipment |
| Scaffold | Default badge | "scaffold" in accessEquipment | job.accessEquipment |
| Tower scaffold | Default badge | "tower_scaffold" in accessEquipment | job.accessEquipment |
| Ladder | Default badge | "ladder" in accessEquipment | job.accessEquipment |
| Cherry picker | Default badge | "cherry_picker" in accessEquipment | job.accessEquipment |
| Rope access | Default badge | "rope_access" in accessEquipment | job.accessEquipment |
| Harness | Default badge | "harness" in accessEquipment | job.accessEquipment |
| Access | Info badge with icon | siteAccessNotes is non-empty | job.siteAccessNotes |
Equipment label mapping
The canonical lowercase equipment values map to display labels:
| Stored value | Display label |
|---|---|
mewp | MEWP |
scaffold | Scaffold |
tower_scaffold | Tower scaffold |
ladder | Ladder |
cherry_picker | Cherry picker |
rope_access | Rope access |
harness | Harness |
Badge rendering locations
| Location | Component | Notes |
|---|---|---|
| Board cards | workspacePrimitives.jsx | Compact size |
| Timeline cards | workspacePrimitives.jsx | Compact size |
| Planner list | SchedulingPlannerList.jsx | Inline in equipment/crew/OOH columns |
| Quick View | SchedulingJobQuickViewDialog.jsx | Full size in hero section |
Accessibility
- The crew badge uses
aria-label="N crew members required"witharia-hidden="true"on the emoji - Equipment and OOH badges use their text content as the accessible name
Validation warnings
The scheduler validates every job against a set of rules. Warnings appear on job cards, in the planner list, and in the Quick View dialog.
Warning severity levels
| Level | Meaning | Deployment effect |
|---|---|---|
| Blocking | Prevents deployment | Job cannot be deployed until resolved |
| Warning | Needs attention | Job can be deployed but should be reviewed |
| Info | Informational | No action required |
Warning types
| Warning | Severity | Condition | Resolution |
|---|---|---|---|
| No engineer assigned | Blocking | engineerIds is empty | Assign an engineer |
| No scheduled date | Blocking | scheduledDate and targetMonth are both null | Set a date or target month |
| Site access rules violated | Blocking or Warning | Job conflicts with site scheduling constraints | Review site rules and adjust schedule |
| Engineer availability conflict | Warning | Engineer is double-booked or outside working hours | Reschedule or reassign |
| Competency mismatch | Warning | Engineer lacks required competencies for the system type | Assign a qualified engineer |
| Scheduling window exceeded | Warning | scheduledDate falls outside scheduleWindowStart/End | Reschedule within the window |
| Overdue | Warning | scheduledDate has passed | Reschedule or complete |
| High crew requirement | Info | crewSizeRequired > 2 | Ensure enough engineers available |
Warning display
- Job cards: Warning icon with count; red icon for blocking, amber for warning
- Planner list: Warning column with count and severity indicator
- Quick View: Full warning list with descriptions and resolution guidance
- Focus tabs: Blocked and Flagged tabs filter to warned jobs
Deployment validation
A job is deploy-ready when all of these conditions are met:
| Condition | Check |
|---|---|
| Engineer assigned | engineerIds.length > 0 |
| Date or month set | scheduledDate !== null OR targetMonth !== null |
| Status is active | Status is not completed, cancelled, or on_hold |
| No blocking warnings | validationWarnings.filter(w => w.severity === "blocking").length === 0 |
Deployment state transitions
Draft ──(deploy)──▶ Deployed (awaiting ○) ──(engineer opens day run)──▶ Deployed (acknowledged ✓)
▲ │ │
└──(scheduling change)──┴───────────────────────────────────────────────────────┘Any change to scheduledDate, engineerId, or estimatedDurationMinutes resets deploymentState to draft.
Redeploying a job (e.g. after a schedule change) clears engineerAcknowledgedAt back to null, so the job returns to the awaiting state until the engineer opens their day run again.
Deployment acknowledgement
When an engineer opens their day run (GET /my-day-run), all deployed stops in the response are silently marked as acknowledged. This is a fire-and-forget side effect — it does not delay the response to the engineer.
How acknowledgement works:
| Step | What happens |
|---|---|
| Engineer opens My Day Run | The API returns the day-run plan, then asynchronously writes engineerAcknowledgedAt for all deployed stops that haven't been acknowledged yet |
| Implicit acknowledgement | If an inspection or work order has startedAt set, or a task has completedAt set, the system treats this as implicit acknowledgement even without an explicit timestamp |
| Preference order | Explicit engineerAcknowledgedAt is always preferred over implicit startedAt / completedAt |
| Redeployment | Clears engineerAcknowledgedAt back to null so the engineer must re-acknowledge |
| Idempotency | The DB-level IS NULL guard prevents double-writes; reloading the day run does not create unnecessary transactions |
Deployment side effects
| Side effect | Detail |
|---|---|
deployedAt timestamp | ISO datetime of deployment |
engineerAcknowledgedAt cleared | Reset to null on every (re)deployment |
deploymentBatchId | Groups jobs deployed together |
| Email notifications | Sent to assigned engineers (fire-and-forget) |
| History entry | Logged with before/after snapshot for audit and undo |
Scheduling constraints
| Rule | Constraint |
|---|---|
| Date vs month | scheduledDate and targetMonth are mutually exclusive |
| Target month format | Must match YYYY-MM |
| Window ordering | scheduleWindowEnd must be after scheduleWindowStart |
| Duration range | 15-1440 minutes (15 minutes to 24 hours) |
| Flex range | 0-120 days |
| Crew size range | 1-50 |
Equipment validation
| Rule | Detail |
|---|---|
| Canonical set | mewp, scaffold, tower_scaffold, ladder, cherry_picker, rope_access, harness |
| Normalisation | Values lowercased and trimmed on input |
| Deduplication | Duplicate values removed automatically |
| Unknown values | Rejected by the server (Zod enum validation) |
Assignment validation
| Rule | Detail |
|---|---|
| Organisation membership | Assigned engineer must belong to the user's organisation |
| Field eligibility | Engineer must have canBeScheduled: true |
| Inspection assignment | Cannot clear engineer assignment on inspections |
Bulk update validation
| Rule | Detail |
|---|---|
| Job count | 1-100 jobs per bulk update |
| Required fields | Each job must include entityType and id |
| Per-job overrides | Take precedence over base-level values |
| Inspection status | Cannot be changed via bulk update |
| Work order status | Cannot be changed via bulk update |
| Warning check | Rejected if update would introduce new blocking warnings |
Dialogs and Workflows Reference
Reference for every scheduler dialog — Quick View, Bulk Update, Task, Day Run, Batch Inspections, Recurring Import, Deploy, Warnings, and Engineer Rules.
API and Data Types Reference
Technical reference for the scheduler API endpoints, response shapes, core data types, and Zod validation schemas.