TaskRox Help & User Manual

The Roster module manages rotation patterns and crew swings for projects that run shift work — typical for construction, civil, and mining sites with FIFO, DIDO, or local-rotation crews.

It answers:

• Who is on site today? — the Today view at /project/[id]/roster.
• What does the next 14 / 28 / 60 days look like? — the calendar grid.
• Who is across multiple projects? — the workspace overview at /roster.

The module does not calculate pay, certify fatigue compliance, or replace the Workforce master record. It produces *expected* attendance; Daily Reports remain the source of truth for *actual* attendance.

Rotation patterns are reusable on/off day strings — for example WWWWWWWOOOOOOO (7/7 even time), WWWWWWWWOOOOOO (8/6 FIFO), or WWWWWOO (5/2 standard). Patterns can be workspace-scoped (reusable across every project) or project-scoped (specific to one site).

A crew combines a rotation pattern, a pattern start date, a colour, and a target strength. Crew phase offsets are how you achieve alternating coverage — Crew A with pattern start 2026-06-01 and Crew B with pattern start 2026-06-08 give continuous 7-on cover.

An assignment links a workforce person to a crew for a date range. One worker can only hold one active assignment per project at a time; overlapping windows are rejected.

Use the override editor to mark an individual day as leave, training, induction, travel, absent, RDO, or a custom status. Overrides override the baseline pattern for that one day; they keep the audit trail and capture an optional note.

Note visibility — override notes may carry context like a leave reason. Anyone who can open the roster (roster.view and above) sees the full note; access is controlled by the module permission, not a separate note-level gate.

Bulk overrides — the override dialog accepts a date range so you can mark a worker as on leave for a week without clicking each day.

Each project has an advisory fatigue configuration: max consecutive working days, min off days, max shift hours, and min break hours. Cells past the configured consecutive-days threshold receive a warning ring in the grid and contribute to the Reports "Fatigue flags" metric.

This is advisory only. TaskRox does not certify fatigue compliance. Australian fatigue management remains the operator's responsibility per the relevant work-health-and-safety regime.

On the Daily Reports labour section, the Roster action pre-fills labour rows from the rostered-on workers for the report date. Duplicates are skipped by worker reference (workforce_person_id) or name.

The Roster Reconciliation panel on each report compares rostered-on workers against captured labour rows and surfaces:

• Rostered, not reported — workers expected on shift with no labour row.
• Reported, not rostered — labour rows for workers not on the roster (visitors, casual hires).
• Matched — workers in both lists, with expected vs reported hour delta.

Use this to find missing labour rows before approval or to spot late roster updates that need to be applied.

When a Daily Report is approved and a timesheet handoff batch is created, the roster crew name, rotation pattern code, designation, and shift mode are attached to each handed-off labour row as read-only context fields — they appear in the batch detail API and as additional columns at the end of the payroll handoff CSV export.

The CSV also carries work placement columns (project_name and site_name) at the end of each row: every row names its project, and site_name carries the project's Site when it is placed at one (empty for standalone projects). Workspace-period batches can span multiple projects, so downstream payroll uses these to attribute hours per project and site.

This is context only. The handoff does not calculate pay, apply award rates, or assume any payroll system schema beyond the existing 16-column labour mapping — all context columns are appended after it, so existing column positions never move.

/roster (workspace-scoped) shows every active assignment in the workspace alongside:

• Bench — active workforce people with no current roster assignment.
• Demand vs availability — per project, the active assignment count, unique workers, sum of crew target strength, and shortfall.
• Cross-project conflicts — workers actively assigned to overlapping date windows on more than one project. Resolve by demobilising or narrowing one assignment.

The page reads existing roster data only; create patterns, crew, and assignments at the project level (/project/[id]/roster).

GET /api/roster/availability?startDate=&endDate=&position=&role=&projectId=&crewId= returns a workspace-scoped availability list for use by Resources or Gantt planning. Per worker, the response reports working days, leave days, and travel days within the requested window (max 90 days).

The endpoint is read-only and consumes existing roster data — it does not mutate assignments or overrides.

The project Reports register surfaces a 14-day roster outlook above the register tabs:

• workers, assignments, expected and worked shifts;
• attendance rate, leave utilisation, and fatigue flagged worker count;
• per-crew assigned count, target strength, on-today / leave / training / travel counts.

These metrics use the same roster engine as the project page so what you see on the calendar matches what Reports rolls up.

The workspace roster (/roster) offers four ways to read the same scoped data:

• Rotation Timeline — crew swimlanes grouped Project ▸ Crew ▸ Worker. Bar colour = roster status (emerald on swing, cyan travel, amber leave, pale dashed off/RDO), labelled in-block where width permits; crew identity is the left colour accent on each row, not the bar fill. Each worker row also carries a compact current-status + next-movement summary (and a readiness/conflict warning flag) in the left column, and every block has a hover/focus card with worker, crew, project, status, dates, duration, rotation pattern, and any override/conflict. ▸ mobilise / ◂ demobilise edge markers flag swing edges. An Off / RDO toggle hides or shows the pale off-swing bands. The scale view for "who moves when".
• Person/Pair Calendar — pick 1–4 people (or a position's back-to-back set) and read their movements on a month grid, with handover (⇄) and gap/overlap rings.
• Position Coverage — one lane per (project, position); red = gap, emerald = covered, amber = overlap. The continuity checker for a seat.
• Mobilisation Board — a date-ordered worklist of upcoming movements (swing edges), each with its booking coverage. The logistics action list (see below).

Movements are computed on read from assignment dates + swing pattern — there is no separate movement table.

A travel booking captures one leg of a movement: a flight, accommodation, vehicle hire, transfer, or other. Each booking has its own status — draft → requested → booked → confirmed → changed / cancelled — provider (a Business Register company or free-text), reference, optional cost, and optional booking evidence (ticket / itinerary / confirmation / invoice) uploaded against it.

Bundle several bookings under one movement by giving them the same person + date + direction — a flight and a hire car for the same mobilisation are separate lines.

Required coverage is not guessed from bookings alone. You define requirements (e.g. "every crew mobilisation needs a flight + accommodation") and a movement is unbooked until it has a non-cancelled confirmed booking for each required type. If a swing date shifts after a booking is made, the booking is flagged out of step so you can re-book.

The Mobilisation Board lists every upcoming movement with its coverage state (unbooked / partial / covered), missing booking types, provider, and an out-of-step badge. Search, multi-select Project / Direction / Coverage filters, sort, density, and a column picker work as on any TaskRox register. Select rows to bulk-confirm or bulk-cancel (bulk cancel needs roster_travel admin).

Use Export (top-right) to download the board as CSV, XLSX, or PDF for the current window.

Movements and bookings also appear in the Calendar, drive Notifications (unbooked movement, booking confirmed / changed / cancelled, movement moved), feed a Reports → Logistics Outlook section, and surface provider booking counts on the Business Register company profile — all only to users who hold roster_travel view.

The roster module follows the standard none / view / edit / admin permission model:

Workspace owners and admins receive admin access automatically.

Travel & Logistics is gated by a separate roster_travel sub-permission (none / view / edit / admin) because booking existence and cost are more sensitive than roster status. view reads bookings, movements, and the board; edit creates/updates bookings and links expense claims; admin manages requirements and cancellations. Booking cost and reference are hidden below roster_travel.view, and booking existence never leaks into the Calendar, Global Search, Business Register, or Reports for users without it.