Payroll Processing

Overview

The Payroll Processing page provides an end-to-end workflow for running fortnightly payroll. It connects three systems -- Deputy (timesheets), RABS (classification and allowances), and Xero (pay runs and payslips) -- into a single guided interface.

The page is located at Admin > Payroll and is designed to be worked through top-to-bottom, with each row of buttons representing a phase of the payroll cycle.

Page Layout

The page is organised into three horizontal zones:

1. Period & Status Bar (Top)

Pay Period selector with date pickers and forward/back arrows. The system auto-selects the current fortnight aligned to the Xero pay calendar.
Status indicators for Xero connection, Deputy connection, timesheet status, and countdown to next pay date.
Period stats showing active staff count, Deputy hours, last pay wages, sync issues, unapproved timesheets, and imported count.

2. Action Buttons (Two Rows)

Row 1 -- Timesheet Preparation:

Button	Purpose
Run Health Check	Compares staff records across RABS, Deputy, and Xero. Identifies mismatches (missing in Xero, missing Deputy ID, name discrepancies). Run this first if payroll looks wrong.
Preview Sync	Shows which staff need to be created in Xero or pulled into RABS. Click "Execute Sync" to action.
Pull Timesheets	Fetches approved timesheets from Deputy for the selected period. Shows a preview table with employee names, shifts, hours. Click "Import to RABS" to save, then "Push to Xero" to send as draft timesheets.
Clear Xero Drafts / Reset Local	Emergency tools. "Clear Xero Drafts" deletes all draft timesheets in Xero for the period (and auto-resets local status). "Reset Local to Draft" resets pushed timesheets in the RABS database back to draft so they can be re-pushed.

Row 2 -- Pay Run & Allowances:

Button	Purpose
Create Pay Run	Creates a draft pay run in Xero for the current period. Xero auto-populates payslips for every employee on the payroll calendar. The pay run summary panel opens automatically showing all employees.
Auto-Detect	Scans imported shift data for overnight shifts (10+ hours crossing midnight, or "overnight/sleepover" in shift comments) and counts shifts per employee for first aid allowance. Populates the editable allowances grid.
Import CSV	Upload a CSV file containing allowance data. Merges into the allowances grid. See CSV Format below.
Push Allowances	Saves the allowances grid to the database, then pushes each employee's allowances to their Xero payslip as EarningsLines (km, overnight, first aid) or DeductionLines (salary sacrifice).

3. Results & Detail Panels (Below Buttons)

These panels appear contextually when actions are taken:

Allowances Grid -- Editable spreadsheet showing every employee with columns for KMs, Overnights, First Aid, and Salary Sacrifice. Totals update live as you type. Click "Save" to persist without pushing.
Pay Run Summary -- Shows the pay run status, totals (gross/tax/super/net), and a table of all employees with their financial breakdown and hours summary. Click the eye icon to view a detailed payslip modal.
Log panels -- Detailed operation logs showing per-employee results for pushes, imports, and deletions.

Standard Payroll Workflow

Follow these steps in order for each pay period:

Step 1: Pull & Import Timesheets

Confirm the pay period dates are correct (should auto-select current fortnight)
Click Pull Timesheets -- review the preview table
Click Import to RABS -- saves shift data to the database
Click Push to Xero -- sends classified timesheets as draft

The system automatically classifies each shift into the correct earnings rate:

Weekday base (06:00--16:30 permanent / 06:00--20:00 casual & PPT)
Weekday evening (16:30--06:00 permanent / 20:00--06:00 casual & PPT)
Saturday, Sunday, and Public Holiday rates
Shifts that span the base/evening boundary are automatically split

Public Holidays

The system checks lunch.nsw_holidays for public holiday dates. If a shift falls on a public holiday, it receives the PH earnings rate regardless of the day of week. Ensure the holidays table is kept current.

Step 2: Approve Timesheets in Xero

Open Xero > Payroll > Timesheets
Review the draft timesheets
Approve all timesheets

This is a manual step -- the Xero API does not support programmatic timesheet approval.

Step 3: Create Pay Run

Return to RABS Payroll page
Click Create Pay Run
The pay run summary panel opens showing all employees, their wages, tax, super, and net pay
The W/AL/LSL/SL/CL column shows hours at a glance:
- W = Worked hours (from timesheets)
- AL = Annual Leave
- LSL = Long Service Leave
- SL = Sick/Personal/Carer's Leave
- CL = Compassionate/Other Leave

Step 4: Enter Allowances & Deductions

Click Auto-Detect to scan for overnights and first aid shifts
Review the allowances grid -- remove first aid for staff who don't hold a current certificate
Enter KMs manually or via CSV import
Enter Salary Sacrifice amounts manually or via CSV
Click Save to persist the data (you can come back later)
Click Push Allowances to send to Xero payslips

Step 5: Review & Generate Report

Click Refresh on the pay run summary to see updated figures (including allowances)
Click any employee's eye icon to view their full payslip breakdown
Click Generate Report to download the payroll report PDF and auto-save to Admin Drive > Documents > Reports

Step 6: Post Pay Run in Xero

Open Xero > Payroll > Pay Runs
Review the draft pay run
Post the pay run to finalise

This is a manual step -- posting a pay run is irreversible and should be verified by a human.

CSV Import Format

The CSV importer accepts flexible column names and allowance type aliases.

Required Columns

Column	Aliases Accepted
Employee name	`name`, `employee`, `staff`
Allowance type	`type`, `allowance`
Quantity	`units`, `quantity`, `kms`, `count`
Dollar amount	`amount`, `total`, `value`

Allowance Type Aliases

Type	Aliases
Kilometre reimbursement	`km`, `kms`, `kilometres`
Overnight allowance	`overnight`, `overnights`, `sleepover`
First aid allowance	`first_aid`, `firstaid`
Salary sacrifice	`salary_sacrifice`, `sacrifice`

Example CSV

name,type,units,amount
Jane Smith,km,45,
John Brown,overnight,3,
Jane Smith,first_aid,10,
John Brown,salary_sacrifice,,150.00

If units is provided without amount, the system calculates: units x rate
If amount is provided without units, the system back-calculates units
Employee matching is by full name or last name (case-insensitive)

Allowance Rates

These rates are configured in Xero and referenced by the system:

Allowance	Xero Earnings Rate	Rate	Xero Line Type
KM Reimbursement	KM Reimbursment	$0.99 per km	EarningsLine (RATEPERUNIT)
First Aid	First Aid	$0.54 per shift	EarningsLine (RATEPERUNIT)
Overnight	Overnight Allowance	$60.02 per night	EarningsLine (RATEPERUNIT)
Salary Sacrifice	FBT - Salary Sacrifice	Fixed amount	DeductionLine (FIXEDAMOUNT)

Payroll Report PDF

The Generate Report button produces a comprehensive PDF document containing:

Summary page -- Company header, period dates, four summary boxes (Gross Wages, Tax, Super, Net Pay), and a full employee table with W/AL/LSL/SL/CL hours and financial columns
Individual payslip pages -- One page per employee with earnings breakdown, tax, deductions, superannuation, leave accrued, and a Gross/Tax/Net Pay summary box

The report is:

Downloaded to the browser immediately
Saved to Admin Drive > Documents > Reports using the naming convention: YYYY-MM-DD Payroll Report start_end.pdf

Error Recovery

Situation	Solution
Timesheets pushed with wrong rates	Click Clear Xero Drafts (deletes from Xero, auto-resets local DB), fix the issue, re-push
Some employees failed to push (rate limit)	Just click Push to Xero again -- only unpushed employees will be sent
Timesheets show as "pushed" locally but were deleted in Xero	Click Reset Local to Draft, then re-push
Timesheets were approved in Xero and need correction	Revert to Draft in Xero UI, then use Clear Xero Drafts in RABS, then re-push
Allowances pushed to wrong payslips	Delete the pay run in Xero, re-create via RABS
Public holiday not detected	Check `lunch.nsw_holidays` table has the correct dates

Classification Rules

The system uses payroll.classification_rules to map shifts to Xero earnings rates. Rules are matched by employment category and day type:

Category	Source	Day Types Covered
`permanent`	Full-time permanent staff	weekday (base + evening), saturday, sunday, public_holiday
`casual`	Staff with "casual" in employment type	weekday (base + evening), saturday, sunday, public_holiday
`ppt`	Part-time permanent staff	weekday (base + evening), saturday, sunday, public_holiday

For weekday shifts, if two rules exist for the same category (base and evening), the system splits hours at the evening threshold time (e.g., 16:30 for permanent, 20:00 for casual/PPT).

Technical Details

Data Flow

Deputy API ──→ payroll.timesheet_entries ──→ classifyShift() ──→ Xero Timesheets (Draft)
                                                                         │
                                                                    [Human approves]
                                                                         │
                                                    RABS creates Pay Run ←┘
                                                         │
payroll.timesheet_allowances ──→ Push to Xero Payslips ──┘
                                                         │
                                                    [Human posts]
                                                         │
                                              Pay Run Summary + PDF Report

Database Tables

Table	Purpose
`payroll.timesheets`	Parent record per staff per period
`payroll.timesheet_entries`	Individual shifts with start/end times
`payroll.timesheet_allowances`	KM, overnight, first aid, salary sacrifice per timesheet
`payroll.classification_rules`	Rate lookup rules by employment category + day type
`payroll.pay_runs`	Local pay run records (mirrors Xero)
`payroll.pay_run_payslips`	Individual payslip records per pay run
`payroll.xero_pay_items`	Cached Xero earnings rates and deduction types
`lunch.nsw_holidays`	Public holiday dates for shift classification

API Endpoints

Method	Endpoint	Purpose
GET	`/payroll/health`	Sync health check
POST	`/payroll/staff-sync`	Force staff sync
GET	`/payroll/deputy/timesheets`	Pull Deputy timesheets
POST	`/payroll/deputy/import`	Import to database
POST	`/payroll/xero/push-timesheets`	Push to Xero
POST	`/payroll/xero/create-payrun`	Create draft pay run
GET	`/payroll/payrun/summary`	Full pay run summary with payslip details
POST	`/payroll/payrun/auto-detect`	Auto-detect overnights and first aid
POST	`/payroll/payrun/allowances`	Save allowances
POST	`/payroll/payrun/push-allowances`	Push allowances to Xero payslips
POST	`/payroll/payrun/import-csv`	Import allowances from CSV
POST	`/payroll/payrun/generate-report`	Generate and save payroll report PDF
DELETE	`/payroll/xero/timesheets`	Delete Xero draft timesheets
POST	`/payroll/timesheets/reset-to-draft`	Reset local pushed status

Overview​

Page Layout​

1. Period & Status Bar (Top)​

2. Action Buttons (Two Rows)​

3. Results & Detail Panels (Below Buttons)​

Standard Payroll Workflow​

Step 1: Pull & Import Timesheets​

Step 2: Approve Timesheets in Xero​

Step 3: Create Pay Run​

Step 4: Enter Allowances & Deductions​

Step 5: Review & Generate Report​

Step 6: Post Pay Run in Xero​

CSV Import Format​

Required Columns​

Allowance Type Aliases​

Example CSV​

Allowance Rates​

Payroll Report PDF​

Error Recovery​

Classification Rules​

Technical Details​

Data Flow​

Database Tables​

API Endpoints​