Auto-Generate Datesheet — Help

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.

Open Auto-Generate
Nothing is saved until you confirm. Preview builds the whole schedule in memory only. Review it, untick any rows you do not want, then click Confirm & Save Selected. A published/locked semester + exam cannot be changed from this screen.
On this page

Quick start

  1. Pick the Semester and Exam Type (Mid Term = 1 hour, Final Term = 2 hours).
  2. Optionally narrow the run: departments, programs, evaluation categories to exclude, room blocks/types/rooms, and a date range.
  3. Optionally add merged groups (papers that must share one date/time/room) and earliest-date priorities (papers that must be placed as early as possible).
  4. Click Preview Datesheet. Nothing is written yet.
  5. Check the proposed schedule. Use the per-row checkboxes / Select none to leave rows out.
  6. Click Confirm & Save Selected to write the ticked rows to the datesheet.
  7. For anything still unscheduled, use Retry Failed Only, Force Insert, or the Manual Entry screen.

The engine only ever considers unscheduled offered courses for the chosen semester + exam type. Courses that already have a datesheet row are left untouched.

Semester & exam type

FieldWhat 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.

What to schedule — filters

FilterEffect
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.

When — dates, day off and daily time slots

Date range

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.

Current configured date window: 2026-12-07 to 2026-12-18. When neither the form nor 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.
Day off (Final Term only)

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.

Exam start-time slots

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.

Program / session start-time preferences

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.

Where — rooms and buildings

FilterEffect
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.
Exam capacity

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.

One room or several

Every room shown anywhere in the app uses the room's room_number (e.g. B2-202), which normally already identifies its building.

Merged groups — one combined paper on one slot

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.

Two ways to create a group
  1. Quick textarea: one group per line, comma-separated offered-course IDs (the [Offer #…] number shown in every course label). Example:
    101,104
    220,221,225
    Lines with fewer than two valid IDs are ignored.
  2. Create Merged Group card: search the offered-course list (by course name, faculty name or course ID), select 2+ courses, give the group a label, optionally choose a fixed exam room, and click Save Merge Group. This stores it for the current semester + exam type so it can be reused.
Saved merged groups
Fixed room behaviour
Merge validation and partial groups

Saved groups apply in addition to any groups typed in the textarea. Identical memberships are de-duplicated automatically.

Earliest-date priority list

Use this when certain papers must be examined as early as the calendar allows, in a deliberate order.

Adding courses
  1. Search the offered-course list by course name, faculty name or course ID (the same search/add picker as merged groups).
  2. Select one or more courses.
  3. Choose a Priority:
    • Automatic — assigns the next free number within that course's program / session / section, so a cohort's papers come out as 1, 2, 3… in the order you add them.
    • Priority 1…9 — forces that number on every course selected in this step.
  4. Click Add to priority list.
The list
How priority affects scheduling
Priority cannot beat a hard rule. If the earliest slot is blocked by a faculty/room/student/program conflict, the paper moves to the next free date/slot — the priority decides who gets to claim first, not which conflicts are ignored.

Scheduling options

For anything that can't otherwise be scheduled, automatically retry allowing repeat/improvement students to sit two papers the same day

Runs the schedule in two passes:

  1. Pass 1 — strict: every course is placed with full rules. Regular students always get first claim.
  2. Pass 2 — override: only the courses that failed pass 1 are retried once, allowing a same-day / different-time clash for a student whose 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.

Schedule regular courses first, then fit repeat/improvement & failure courses in a second run

Similar two-pass idea, but the split is by cohort type rather than by failure:

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.

Unit order and “Suggest best order”

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.

Reading the preview

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 / noteMeaning
Course(s) & StrengthEvery course in the unit with its registered student count. A merged group lists all members together.
FacultyThe teaching faculty of each course (one line per course).
Date / TimeThe 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 groupThe saved group's pinned room was honoured for this row.
Earliest-date priority NThe row is on the priority list and was placed chronologically at that priority.
Repeat/improvement override appliedA same-day, different-time clash was deliberately allowed for a flagged repeat/improvement student.
Start-time rule violatedThe 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.

Confirm & Save Selected

There is no bulk “undo”. Remove individual rows from View / Manage Datesheet if you need to remove something.

Retry Failed Only

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.

Force Insert (for what still cannot be scheduled)

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).

  1. Optionally set a specific date, or a From/To range (blank = the whole exam window).
  2. Optionally limit the search to specific blocks and/or room types.
  3. Optionally tick “Allow repeat/improvement students to sit two papers this day” before searching — it changes which slots come back.
  4. Click Find Available Slots.

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.

How the scheduler chooses a date and time

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:

  1. Unit order: earliest-date priority units first (1, 2, 3…), then merged groups, then single courses, then by size (biggest or smallest per the chosen order; regular units before repeat/improvement units when that option is on).
  2. Window rank: official/selected dates first, extra look-ahead dates later, the configured day off last.
  3. Least-loaded day: the date with the fewest exams already on it (live rows + earlier placements in this same preview) comes first. This spreads papers across the whole window instead of piling them onto day one.
  4. Least-loaded slot: within that day, the daily slot with the fewest exams comes first, so one slot does not collect every paper.
  5. Specialization clustering: for a single course whose students all share one specialization, dates already used by that specialization are preferred (a soft preference only).
  6. Faculty day-spread: among otherwise tied dates, days where the unit's faculty have no other exam are preferred (again soft).
  7. Earliest-date units skip steps 3–6: they simply walk the calendar chronologically (day off/look-ahead still last).
  8. Pinned merge partners skip the search entirely: the unit is forced onto the existing partner's date/slot.

Only candidates that pass every conflict rule and have enough room capacity are used.

How the scheduler chooses rooms

  1. Calculate the needed seats: combined registered strength + ROOM_CAPACITY_BUFFER (0).
  2. Consider only rooms allowed by the block / type / specific-room filters that are free for the whole date + time range (including rooms already claimed earlier in this preview).
  3. If one room fits, pick per ROOM_ALLOCATION_STRATEGY — currently Largest room that fits (largest_first).
  4. If not, combine rooms from a single building (fewest rooms, then least waste). Use the fixed room's / existing partner's building first when there is one.
  5. If no single building can cover it, combine across buildings as a last resort.
  6. For a saved merged group with a fixed room: the fixed room is mandatory. It must be free at the slot and is topped up from its own building when the group is too large.

All capacity numbers shown in the UI are effective exam capacity (60% of registered capacity), not the room's raw seat count.

Conflict rules the engine enforces

RuleBehaviour
FacultyThe same teacher cannot be in two overlapping exams on the same date. (Softly spread across days when possible, but never double-booked.)
RoomA room (primary or overflow) cannot be used by two overlapping exams. Members of the same merged group may share their room intentionally.
Student per dayControlled 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 dayControlled 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 warningWhen 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 durationFixed per exam type (60 min Mid Term / 120 min Final Term). Overlap checks use the real start–end range.
Locked datesheetOnce published/locked, Preview can still run but saving is refused, and Manual Entry / Swap / Delete are blocked.

Troubleshooting: why a paper failed and what to try

Reason shownWhat 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.

Current settings that affect Auto-Generate

These come from config.php. Change them there once and every run follows them.

SettingCurrent value / effect
EXAM_DURATIONSMid Term 60 min; Final Term 120 min
EXAM_SLOTSMid 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_DAYSSunday
SCHEDULER_DATE_FROM / _TO2026-12-07 to 2026-12-18
FINAL_TERM_DAY_OFFNot set (the form field can still choose one)
ONE_EXAM_PER_STUDENT_PER_DAYOn — one paper per student per day
ONE_EXAM_PER_PROGRAM_PER_DAYOn — one paper per program per day
EXAM_ROOM_CAPACITY_FACTOR60% of registered room capacity is usable for exam seating
ROOM_CAPACITY_BUFFER0 extra seat(s) added to the headcount when choosing a room
ROOM_ALLOCATION_STRATEGYLargest room that fits (largest_first)
SCHEDULER_MAX_EXTRA_DAYS10 look-ahead day(s) after the official window
FORCE_INSERT_OVERRIDABLE_REPEAT_CF_IDS-2 / -4

FAQ

Priority decides who is placed first, not which rules are ignored. If the first date/slot is blocked by a faculty, room, student or program conflict, the paper moves to the next free date/slot. The configured day off and look-ahead dates are also always tried last. Check the row's notes and the failure reasons for the blocking rule.

The scheduler balances across the whole window: it prefers the least-loaded day and slot instead of filling day one. Specialization clustering and faculty day-spread can also move a paper later. If you need a specific paper early, add it to the Earliest-date priority list; it will then walk the calendar chronologically.

The group's strength is bigger than the fixed room's exam capacity, so extra rooms are added. They come from the fixed room's own building whenever it has enough free capacity. Only when no single building can cover the paper are rooms mixed across buildings — the preview says which building(s) are used.

It stays saved in the database (with its label and fixed room) but is skipped for that run. Tick it again on a later run to apply it. Deleting removes it permanently.

No. A student cannot sit two papers at the same time, so the merge is rejected and the message names the student and both courses. Remove one of the courses from the group.

No. It only inserts rows for the ticked proposed exams, and only for courses that are currently unscheduled. Existing rows are never overwritten by Auto-Generate. Delete or move individual rows from View / Manage Datesheet.

No. The teaching faculty on each course is not an invigilator. Assign invigilation duty separately on Assign Invigilators, which also checks that one person is not assigned to two rooms at once.

When no fully clean slot exists in the searched window, the search still shows the closest options. Green “best option” rows only have a same-day / different-time clash for repeat/improvement students. Yellow “force insert” rows have harder conflicts. Choosing one is a deliberate override; the listed conflicts are shown first and the result page warns that they were bypassed.

Read the exact reason on the red row. Widen the date range or allow more blocks/rooms/slots, then use Retry Failed Only. If it still cannot fit, use Force Insert to search for a free slot, or place it by hand on Manual Entry.
Back to Auto-Generate Manual Entry View / Manage Datesheet Validate Datesheet