HR and leave troubleshooting

Fix leave approvals blocked on balance, substitutes that never reach the timetable, staff skipped by a payroll run, and appraisals a teacher cannot see.

Getting started guide for day and boarding schools.

Last updated August 29, 2026

The HR side of Schoolyi is four loosely coupled workflows — leave, substitute cover, payroll, and appraisals — and each has one gate that quietly stops the rest. Leave stops on entitlement, cover stops on timetable publish state, payroll stops on an approved salary assignment, and appraisals stop on record status. Identify the gate first; the fix is usually one field.

Leave requests and approval

Staff apply at /leave and see their own requests; Platform Admin, Principal, Vice Principal, and the office Admin role see everything and are the only roles that can approve or reject. Leave types are a fixed list — CL, EL, SL, ML, SCL, CPL, PL, CCL, HPL, EOL, DL, LWP, and OTHER — so you cannot invent a new type, only decide which ones you use and what each teacher is entitled to.

Symptom	Cause	Fix
Approval refused with "Insufficient leave balance"	Entitlement for that teacher, year, and type is lower than the working days requested	Raise the entitlement for that leave type and academic year, or approve with the override, which records the leave as exceeding balance.
Balance never decreases after approval	The dates contain no working days, or the request has no academic year	Entitlement is only deducted when the range covers at least one working day inside a resolved academic year. Check the calendar for that week at /academic-calendar.
Second request rejected as overlapping	Another pending or approved leave covers the same dates	Cancel or shorten the existing request first; the overlap guard looks at both PENDING and APPROVED rows for that teacher.
Teacher cannot edit their own request	Editing is limited to pending rows	Once a request is approved or rejected only an approver can change it. Ask the approver to revert or raise a fresh request.

Substitute cover

Choosing a substitute while approving leave creates one confirmed arrangement per published timetable slot for each working day in the range. That is the whole mechanism, and it explains most of the surprises: a draft grid produces no cover, a teacher with no published slots produces no cover, and a range that lands entirely on holidays produces no cover. The substitute must be a staff member and cannot be the teacher on leave. Teachers find their cover under /timetable on the My substitutes tab; leadership and the office Admin role also see the Tools tab for manual arrangements.

Payroll runs

Symptom	Cause	Fix
Staff member missing from generated payslips	No approved salary assignment covering the period end	Create or approve the assignment at /payroll/salary-assignments. Only APPROVED and active assignments are picked up.
Cannot import a salary from the HR record	No official CTC on the staff profile	Record the CTC under /employment/finances first; the import reads that figure and then still needs a separate approver.
Regenerate button does nothing on an old run	The run is finalized or paid	A finalized run refuses regeneration by design. Create a fresh run for the correction rather than editing history.
Finance staff cannot open payroll settings	Two different gates	Runs, structures, and statutory processing need Platform Admin, Principal, Vice Principal, or Admin. Finance roles get read access to totals, finalize with budget, and statutory export only.

New staff accounts

A Platform Admin creates the login at /users. Nobody else can create users.
The role name decides the account type: Teacher, Principal, Vice Principal, and any Support Staff role become staff; Student becomes a student; Platform Admin becomes an admin account. A role outside that list leaves the account with no type, which is why a new hire can sign in but sees almost no navigation and never appears in teacher pickers.
Creation generates a temporary password, forces a password change at first sign-in, and emails the invite. If SMTP fails the account still exists — resend the invite, which rotates the password.
Add the employment record at /school-staff and set staffType. PRT, TGT, and PGT drive homeroom eligibility and the weekly teaching-load cap, so an empty staffType blocks class-teacher assignment later.

Appraisals

Appraisal cycles carry a status of DRAFT, ACTIVE, or CLOSED and a set of weighted criteria; a closed cycle refuses new appraisals. Individual appraisals are the thing that gets published, and publishing notifies the teacher and lets them acknowledge with a comment. Creating and editing cycles and appraisals is limited to Platform Admin, Admin, Principal, and Vice Principal; teachers get read access to their own published records only.

Symptom	Cause	Fix
Teacher sees nothing at /teachers/appraisals	The appraisal is still a draft	Publish the record. Teachers are scoped to their own appraisals with status PUBLISHED or ACKNOWLEDGED.
Cannot add an appraisal to a cycle	Cycle is CLOSED, or the academic year does not match the cycle	Reopen the cycle or pick the matching academic year; both are validated on save.
Score does not match what was typed	Weighted criteria override the manual figure	When criterion scores exist the overall score is recalculated from them on a 0-10 scale. Edit the criterion scores, not the total.

Common questions

Quick answers in plain language.

Leave was approved with a substitute but no cover appears on the timetable. Why?+

Cover rows are generated from PUBLISHED timetable entries belonging to the teacher on leave. If the grid for that year is still a draft, or the teacher holds no published slots, approval creates zero arrangements and reports nothing wrong. Publish the timetable, then re-approve or add the cover by hand under Tools.

Why does approving leave fail with "Insufficient leave balance"?+

Approval checks entitlement minus leave already taken for that teacher, academic year, and leave type. Either raise the entitlement for that type and year, or resubmit the approval with the override so the leave is recorded as exceeding balance. Entitlement is set per teacher per type — there is no school-wide default applied automatically.

A payroll run generated payslips for fewer staff than expected. Which record is missing?+

Generation walks active staff and skips anyone without an approved salary assignment covering the period end date. A draft or rejected assignment counts as missing. Check /payroll/salary-assignments, get the assignment approved by a second Principal, Vice Principal, or Platform Admin, then regenerate.

Where do teachers see their appraisal, and why is it blank?+

Appraisals live at /teachers/appraisals — there is no /hr/appraisals screen. A teacher only sees their own appraisals once the record status is PUBLISHED or ACKNOWLEDGED. A draft is invisible to them no matter how complete it looks to HR.