A practical guide to every option on the Auto-Generate screen, what the scheduler does with them, and how to fix papers that could not be placed.
The engine only ever considers unscheduled offered courses for the chosen semester + exam type. Courses that already have a datesheet row are left untouched.
| Field | What it does |
|---|---|
| Semester | Scopes everything: offered courses, student registrations, existing datesheet rows, saved merged groups (which are stored per semester + exam type), and the lock state. |
| Exam Type | Mid Term uses 60-minute papers; Final Term uses 120-minute papers. The daily start-time list changes with the exam type, and the Day off field is only available for Final Term. |
Configured slots — Mid Term: 9:45 AM, 11:00 AM, 12:15 PM, 1:45 PM, 3:00 PM; Final Term: 9:45 AM, 12:15 PM, 2:45 PM. These come from EXAM_SLOTS in config.php.
| Filter | Effect |
|---|---|
| Departments (multi-select) | Only offered courses whose program belongs to one of the selected departments. Leave blank for all departments. Changing this refreshes the Program list. |
| Program (multi-select) | Only the selected programs. The list is refreshed automatically and shows only programs that have live courses offered in the current semester for the chosen exam type (and belong to the chosen departments). Programs whose only rows are old/orphaned, or that have no paper for this exam type, are skipped. Leave blank for all programs. Selecting several programs is allowed. |
| Exclude Evaluation Categories (multi-select) | Courses using any selected evaluation category are skipped completely (for example thesis / non-credit categories). Separately, a course whose category carries 0% weight for the chosen exam type (e.g. 0% mid-term) is always skipped — there is no paper to create for it. |
| Already-scheduled courses | Automatically ignored by Preview, because only unscheduled offered courses are considered. Use View / Manage Datesheet to change or delete existing rows. |
The Date range start and Date range end fields (both must be filled) override the semester's own exam window. If left blank, the configured fallback window is used; if that is not set either, the semester's mid-term or final-term dates are used. Weekend days (Sunday) are skipped.
config.php provides a window, extra look-ahead days (up to SCHEDULER_MAX_EXTRA_DAYS = 10) are used only after the official exam dates are exhausted.
A single date that the scheduler should try to keep free. It is not banned: it is simply sorted after every other date and slot. It is used only when a paper genuinely cannot be placed anywhere else without a clash, so choosing a day off never introduces a clash. Mid Term ignores this field.
Day off report: after a preview, the page shows a Day off report card listing every paper that had to be placed on the day off, together with the exact reasons all other date/slots were blocked. The same explanation is saved with the entry (visible as a red day off used badge and in the Day off report card on the datesheet view page), so you can trace and then fix the room, faculty, student or start-time constraint that is forcing the paper onto the day off.
Tick the daily slot(s) that may be used. Nothing ticked = all configured slots. The optional “Schedule at/after this time only” box removes any slot that starts earlier than the time you type (for example 13:45). These two settings only restrict the candidate start times — they never override a conflict rule.
The card below the main form stores permanent per-program (and optionally per-session and per-exam) rules such as “this cohort may only start at 09:45 or 11:00” or “not before 12:15”. Its Program dropdown lists only programs with live courses offered in the selected semester for the chosen exam type. They live in the database and apply automatically to every run — nothing to re-enter.
| Filter | Effect |
|---|---|
| Room Blocks (multi-select) | Restrict the rooms considered to the selected block(s)/building(s). Leave blank for any block. |
| Room Type (multi-select) | Restrict to the selected room type(s), e.g. classroom, lab, auditorium. Combined with blocks, a room must match both filters. |
| Matching rooms | Specific room checkboxes for the chosen blocks/types. All unchecked = every room matching the block/type filters. Tick individual rooms to allow only those. |
Rooms are not filled to their registered capacity. Only 60% of each room's room_capacity is treated as usable exam seating (desks spaced for invigilation). A 60-seat room therefore seats 36 candidates by default. ROOM_CAPACITY_BUFFER adds extra spare seats on top of the headcount.
Every room shown anywhere in the app uses the room's room_number (e.g. B2-202), which normally already identifies its building.
A merged group makes two or more offered courses sit at the same date, time and room as one combined paper. Use it for shared electives, specialization courses, or cohorts that must be examined together.
[Offer #…] number shown in every course label). Example:
101,104
220,221,225
Lines with fewer than two valid IDs are ignored.Saved groups apply in addition to any groups typed in the textarea. Identical memberships are de-duplicated automatically.
Use this when certain papers must be examined as early as the calendar allows, in a deliberate order.
Runs the schedule in two passes:
kiusc_results.repeat_cf_id is one of -2 / -4.An actual overlapping time, a normal student's clash, and every faculty/room/program rule still block in both passes. Rows placed this way show a “Repeat/improvement override applied” note. Unticked = fully strict.
Similar two-pass idea, but the split is by cohort type rather than by failure:
repeat_cf_id = -1) run, with full rules.This guarantees a repeat/improvement course can never displace a regular course's slot. It replaces the normal mixed single-list run; leave unticked to keep the default.
Within the normal (non-early) list, merged groups run before single courses, then units are ordered by size:
The Suggest best order (compare strategies, dry-run) button runs all three strategies without saving anything and compares the number of failures and the day/slot load. If one clearly wins, its card offers Preview with this order. If none beats the default, the page says so — the remaining failures are then capacity/room/faculty-bound rather than ordering-bound.
The proposal is grouped like a printed datesheet: Department → Program — Session (Section X). Within each program, rows are numbered 1, 2, 3… and show:
| Column / note | Meaning |
|---|---|
| Course(s) & Strength | Every course in the unit with its registered student count. A merged group lists all members together. |
| Faculty | The teaching faculty of each course (one line per course). |
| Date / Time | The proposed exam date and start–end time. |
| Room(s) (exam capacity) | The primary room with its usable exam capacity, then any extra rooms. When more than one room is used, a Building line shows whether they all sit in one building; multiple buildings appear only when no single building could cover the paper. |
| Fixed room for this merged group | The saved group's pinned room was honoured for this row. |
| Earliest-date priority N | The row is on the priority list and was placed chronologically at that priority. |
| Repeat/improvement override applied | A same-day, different-time clash was deliberately allowed for a flagged repeat/improvement student. |
| Start-time rule violated | The chosen slot breaks a stored program/session start-time rule (usually because a merged group's rules could not all be satisfied). The row is still scheduled, so you can decide whether to move it. |
Courses that could not be placed appear in the same program table in red, with the exact reason (which student/course/faculty/room/date blocked the attempts and how many slots were blocked). A separate “Could not schedule — summary” card repeats them with program/session/section/strength for a quick scan.
Select all / Select none and the per-row checkboxes decide what gets saved. Nothing in the preview has been written to the database.
kiusc_datesheet. Failed rows are never saved.There is no bulk “undo”. Remove individual rows from View / Manage Datesheet if you need to remove something.
At the bottom of the “Could not schedule” card, this re-runs the scheduler for exactly the failed offered-course IDs and leaves every already-scheduled row untouched. You can widen the date range first.
Each failed row has a Force Insert button. It does not ask you to guess a slot: it searches the current datesheet for a genuinely free date / time / room / teacher combination for that row's course(s).
Results are ranked best-first:
An “Advanced: type an exact date/time/room instead of searching” link reveals a manual date/time/room form that skips the search but still runs the same server-side checks and override rule.
Faculty conflicts, room conflicts, capacity and the one-paper-per-program-per-day rule are never bypassed by the search. The only thing the override intentionally relaxes is a same-day / different-time clash for a repeat/improvement student; a real time overlap is always refused. Duration is fixed by the exam type. The datesheet lock is always enforced.
For each scheduling unit (a single course, or a merged group treated as one paper), it builds the candidate date Ă— slot list and tries them in this order:
Only candidates that pass every conflict rule and have enough room capacity are used.
ROOM_CAPACITY_BUFFER (0).ROOM_ALLOCATION_STRATEGY — currently Largest room that fits (largest_first).All capacity numbers shown in the UI are effective exam capacity (60% of registered capacity), not the room's raw seat count.
| Rule | Behaviour |
|---|---|
| Faculty | The same teacher cannot be in two overlapping exams on the same date. (Softly spread across days when possible, but never double-booked.) |
| Room | A room (primary or overflow) cannot be used by two overlapping exams. Members of the same merged group may share their room intentionally. |
| Student per day | Controlled by ONE_EXAM_PER_STUDENT_PER_DAY (currently ON). When on, a student cannot have two papers on the same calendar date even at different times, unless the repeat/improvement override is explicitly enabled for that case. |
| Program per day | Controlled by ONE_EXAM_PER_PROGRAM_PER_DAY (currently ON). A program cannot have two different papers on the same date. Members of the same merged group are exempt. |
| Credit-hours warning | When a student clash is reported, the message includes that student's total registered credit hours for the semester and flags it when it exceeds 21. This is diagnostic information — it explains why a roster looks overloaded. |
| Exam duration | Fixed per exam type (60 min Mid Term / 120 min Final Term). Overlap checks use the real start–end range. |
| Locked datesheet | Once published/locked, Preview can still run but saving is refused, and Manual Entry / Swap / Delete are blocked. |
| Reason shown | What it means / what to try |
|---|---|
| “No room (or combination of rooms) with enough capacity — needed N seat(s)” | Every allowed room is too small, already busy, or filtered out. Allow more blocks/types/rooms, widen the date range, or check the room capacities and the 60% factor. |
| “Required room X is not free at this slot (or cannot be topped up to N seat(s))” | The saved merge group's fixed room is occupied at every usable slot, or its building cannot supply enough extra seats. Choose another fixed room, clear the fixed room, or widen the date range. |
| Faculty conflict (names the teacher, course and date/time) | The teacher already has another paper at an overlapping time. Widen the window, change the allowed slots, or move the existing row on View / Manage Datesheet or Swap. |
| Student conflict (names the student, registration no., clashing course; may include “Total registered credit hours: N > 21”) | A registered student is already sitting another paper that day/time (depending on the per-day rule). The credit-hour note explains an overloaded registration. Only the repeat/improvement override can relax a same-day / different-time case for a flagged student. |
| Program-per-day conflict | That program already has a different paper the same day. Widen the window or allow more daily slots; keep ONE_EXAM_PER_PROGRAM_PER_DAY in mind. |
| “These merge partners are already scheduled in different slots (…)” | Re-unification is impossible while partners sit in different date/times. Move them to one slot first, then re-run. |
| “A student is registered in more than one of the selected courses” | Those courses cannot be merged. Remove one from the group or split the group. |
| Blank / no courses at all | Usually filters: wrong department/program, the category is excluded, the course carries 0% weight for this exam type, or every matching course already has a datesheet row. |
| Save skipped a row (“a conflict appeared since the preview”) | Someone changed the datesheet between preview and save. Re-run Preview for the skipped courses, or place them with Manual Entry. |
| Save refused / locked | The semester + exam is published. Unlock it on View / Manage Datesheet first. |
These come from config.php. Change them there once and every run follows them.
| Setting | Current value / effect |
|---|---|
EXAM_DURATIONS | Mid Term 60 min; Final Term 120 min |
EXAM_SLOTS | Mid Term: 9:45 AM, 11:00 AM, 12:15 PM, 1:45 PM, 3:00 PM Final Term: 9:45 AM, 12:15 PM, 2:45 PM |
WEEKEND_DAYS | Sunday |
SCHEDULER_DATE_FROM / _TO | 2026-12-07 to 2026-12-18 |
FINAL_TERM_DAY_OFF | Not set (the form field can still choose one) |
ONE_EXAM_PER_STUDENT_PER_DAY | On — one paper per student per day |
ONE_EXAM_PER_PROGRAM_PER_DAY | On — one paper per program per day |
EXAM_ROOM_CAPACITY_FACTOR | 60% of registered room capacity is usable for exam seating |
ROOM_CAPACITY_BUFFER | 0 extra seat(s) added to the headcount when choosing a room |
ROOM_ALLOCATION_STRATEGY | Largest room that fits (largest_first) |
SCHEDULER_MAX_EXTRA_DAYS | 10 look-ahead day(s) after the official window |
FORCE_INSERT_OVERRIDABLE_REPEAT_CF_IDS | -2 / -4 |