Skip to content

Morning Check Schedules Developer Guide

Ed Mozley edited this page Nov 20, 2026 · 1 revision

Morning check schedules - Developer Guide

GH #383, asked for by @nebev Β· 5.8.0 Β· user guide: Morning Checks β†’ Schedules

In plain words

A morning check used to be due every day. Now each check has a Repeats setting: every day, every weekday, weekly on chosen days, or monthly (on a date, the first or last weekday, or the last day). One small PHP class, MorningCheckSchedule, answers "is this check due on this day?". The round, Watchtower and the REST API all ask it, so they cannot disagree. A check that is not due is never hidden: it is greyed out on the round, still recordable, and says when it is next due, when it was last done, or that its last due day was missed.

Decided on the issue (Ed): dropdowns and ticks, no typed cron or Quartz expression; backwards compatible, with no schedule meaning every day; checks not due today greyed out rather than hidden.

The files

File What
🟣 includes/morning_check_schedule.php The schedule logic: columns(), isDue(), nextDue(), previousDue(), toArray(). Pure - no database
🟣 includes/services/morning_checks.php saveCheck() takes schedule; scheduleColumns() turns a bad one into a ServiceError
🟣 api/morning-checks/get_todays_checks.php The round: Due, NextDue, LastDone, MissedOn per check (mcScheduleState())
🟣 api/morning-checks/add_check.php / update_check.php / get_all_checks.php Forward and return schedule
🟣 includes/watchtower_queries.php Counts only the checks due today
🟣 api/v1/resources/morning_checks.php + api/v1/spec.json schedule on every check; due on the board
🟑 morning-checks/schedule.js MCSchedule: the wording (summary, dateText) and the Settings form (init, sync, fill, read)
🟑 morning-checks/index.php The greyed row, the line under the buttons, Not due in the PDF
🟑 morning-checks/settings/index.php mcScheduleFields($p) prints Repeats in both the Add and Edit windows
πŸ”΅ morning-checks/style.css (v=7) tr.mc-not-due, .mc-due-note, .mc-missed
πŸ—„οΈ morningChecks_Checks Four new columns, below
πŸ§ͺ tests/morning-check-schedule.php 32 date cases; runs in CI (Web exposure job)

The data

-- database/freeitsm.sql and includes/db_verify_schema.php (Database Verification adds them)
`ScheduleType`      VARCHAR(12) NULL,   -- NULL = every day | weekdays | weekly | monthly
`ScheduleDays`      VARCHAR(20) NULL,   -- weekly: ISO days, "1,4" = Monday and Thursday
`ScheduleMonthWhen` VARCHAR(16) NULL,   -- monthly: day | first_weekday | last_weekday | last_day
`ScheduleMonthDay`  TINYINT NULL,       -- monthly 'day': 1-31

Every existing check has ScheduleType NULL, so it stays every day - no migration, no data change. Every day is stored as NULL rather than 'daily', so there is one way to say it. Results are untouched: morningChecks_Results still holds one row per check per day, and a weekly check simply has fewer of them.

Plain columns rather than a rule row like task_recurrences: a task repeat answers "when is the next copy made?" and keeps a lot of state; a check only needs "is it due on this day?", which four columns answer with no state at all.

Deciding "due"

// includes/morning_check_schedule.php
public static function isDue(array $row, string $ymd): bool
{
    $type = $row['ScheduleType'] ?? null;
    $d = DateTimeImmutable::createFromFormat('!Y-m-d', $ymd);
    if (!$d) return true;
    $dow = (int)$d->format('N');                       // 1 = Monday
    switch ($type) {
        case 'weekdays': return $dow <= 5;
        case 'weekly':   $days = self::days($row); return !$days || in_array($dow, $days, true);
        case 'monthly':  $on = self::monthDate($row, $d); return $on === null || $on === $d->format('Y-m-d');
        default:         return true;
    }
}
  • A schedule can never hide a check by accident. An unknown type, a weekly row with no days, a monthly row with no day, or a bad date are all due. columns() refuses those on the way in (with a message for the person), and isDue() forgives them on the way out.
  • The 29th-31st in a shorter month is the month's last day: min($n, days in month). A check set to the 31st runs on 30 Nov, 31 Dec and 28 Feb.
  • First / last weekday walks from the 1st forwards, or from the last day backwards, past Saturday and Sunday. Bank holidays are not known; that is said in the help.
  • nextDue() / previousDue() step a day at a time for up to 62 days - enough for any monthly schedule.

Saving

// MorningChecksService::saveCheck() - absent = keep what is stored, null = every day
...array_values(array_key_exists('schedule', $in) ? self::scheduleColumns($in['schedule']) : [
    $current['ScheduleType'] ?? null, $current['ScheduleDays'] ?? null,
    $current['ScheduleMonthWhen'] ?? null, $current['ScheduleMonthDay'] ?? null,
]),

Absent means unchanged, as for every other field here: update_check.php is also used by reordering, which sends no schedule, and an older REST client that knows nothing of schedules must not wipe one. columns() tidies weekly days ([4, 1, 1] β†’ "1,4") and throws InvalidArgumentException, which scheduleColumns() turns into a ServiceError('validation', ...) - so the settings page and the API show the same message, e.g. A weekly check needs at least one day.

The round

get_todays_checks.php adds, per check:

Field
Schedule { type, days, month_when, month_day }
Due is it due on the day being viewed?
NextDue not due: the next day it is
LastDone the latest result on or before the day viewed (scheduled checks)
MissedOn not due, and its previous due day went by with nothing recorded on or after it

One extra query, only for checks that have a schedule: their results over the 62 days before the day viewed.

$prev   = MorningCheckSchedule::previousDue($r, $date);
$missed = ($prev !== null && !(isset($lastDone[$id]) && $lastDone[$id] >= $prev)) ? $prev : null;

On or after, not on: a weekly Monday check done on Tuesday is not "missed" on Wednesday - it was done, a day late. That is the point of letting a not-due check be recorded.

The row (morning-checks/index.php):

const schedText = MCSchedule.summary(check.Schedule);
if (check.Due === false) {
    // "Not due Β· Weekly: Mon, Thu Β· next due Thu 19 Nov Β· Missed Mon 16 Nov"   (or "Β· last done Mon 16 Nov")
} else if (schedText) {
    // "Weekly: Mon, Thu"   - a due check on a schedule still says what its schedule is
}
<tr class="status-${slug}${check.Due === false ? ' mc-not-due' : ''}">

The line sits under the status buttons, not under the name, because the PDF reads the name from the first cell's text; the PDF prints Not due instead of Not set for a not-due row with nothing recorded. The chart is unchanged - it only ever counted results that exist.

Watchtower

// includes/watchtower_queries.php - the headline counted every active check
foreach ($mcTotalStmt->fetchAll(PDO::FETCH_ASSOC) as $mcRow) {
    if (MorningCheckSchedule::isDue($mcRow, $today)) $mcDueIds[] = (int)$mcRow['CheckID'];
}
$mcTotal  = count($mcDueIds);
$mcDueSql = $mcDueIds ? ' AND c.CheckID IN (' . implode(',', $mcDueIds) . ')' : ' AND 1 = 0';   // ints only

$mcDueSql goes into the done count and the per-status breakdown too, so a not-due check recorded today cannot make done exceed total. Without this a weekly check reads as outstanding six days in seven - the exact complaint on the issue ("oh - I thought it was already done for the week").

The REST API

  • Every check carries "schedule": { "type": "weekly", "days": [1, 4], "month_when": null, "month_day": null }.
  • POST / PATCH /morning-checks/checks accept schedule; absent = unchanged (PATCH) or every day (POST); null = every day. A bad one is a 422 with the same message as the screen.
  • GET /morning-checks/board adds due to each check. Not-due checks are still listed - a probe may still record one.

Settings

mcScheduleFields('add' | 'edit') prints Repeats (a dropdown), the day ticks (built by MCSchedule.init() with fmtNaiveWeekday, so in the person's language), and for monthly a second dropdown plus the day 1-31. MCSchedule.read() returns null - and the save stops - when a weekly check has no day ticked; the server says the same if anything else gets through.

⚠️ Traps

  • TRAP: display: flex beats the hidden attribute. .mc-sched-days / .mc-sched-month are flex, so hidden did nothing and the month dropdown showed on a weekly check. Fixed with .mc-sched [hidden] { display: none; }. The first headless test read the hidden property, which was right, and missed it - the screenshot caught it. Test what is on screen.
  • TRAP: Morning Checks' style.css styles every <nav> on its pages (nav:not(.app-sidebar):not(.header-nav) { display: flex }). It made the Settings-on-one-page index (#399) show in Tabs view here. The index is now a <div role="navigation">, and the One page layout targets a class the script adds (sv-host) instead of assuming .container - Morning Checks uses .settings-container. All 22 settings pages with the switch were re-checked in both views.
  • TRAP: never decide "due" anywhere else. A second copy of the rule in SQL or JavaScript is how the round and Watchtower would start to disagree.

Checked

On the test install, through the real endpoints: a weekly Monday check is due Monday and not Tuesday, next due the following Monday, missed on Tuesday until Monday is recorded, then last done Monday; a monthly last-weekday check is due on Mon 30 Nov and not the 19th; a weekly check with no day is refused with its reason; an update that does not mention the schedule keeps it; an existing check is every day; Watchtower's total on a Friday leaves out checks not due. On screen: Repeats in Add and Edit, the list's Weekly: Mon, Thu, the round greyed with Not due Β· Weekly: Mon, Thu Β· next due Thu 19 Nov Β· Missed Mon 16 Nov. Temporary ZZ checks removed.

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally