Training for Portal Users Developer Guide

Training for Portal Users — Developer Guide

How the LMS stopped assuming every learner is an analyst. Companion to Training for Portal Users.

---

The shape of the change

The LMS was analyst-only all the way down: lms_learning_group_members.analyst_id, lms_progress keyed UNIQUE (analyst_id, course_id), lmsMyCourses($conn, $analystId), and a player reading $_SESSION['analyst_id'].

A self-service portal user is a users row and has no analyst record at all, so the identity had to carry which table it means.

LmsLearner

includes/lms_access.php. A value object of (type, id) where type is analyst or user.

A class rather than (?int $analystId, ?int $userId). That pair carries an unwritten "exactly one of these" rule that nothing enforces — the shape the portal password-reset tables were deliberately split apart to avoid, for the same reason. The day somebody passes both, or neither, the LMS shows one person another person's training record. Here the object cannot be constructed in an invalid state.

---

Schema

lms_course_assignments.target_type

Says what group_id means:

target_type	group_id points at
learning_group	lms_learning_groups.id — the default, so every pre-existing row is unchanged
user_group	knowledge_user_groups.id
all_users	nothing; group_id is 0
analyst	analysts.id — one named person
user	users.id — one named person

group_id would more honestly be target_id now. It was not renamed: that rewrites every existing row's meaning in a migration for a cosmetic gain.

Unique key is (course_id, target_type, group_id). target_type has to be in it — without it, learning group 2 and people group 2 collide on the same course, and the second assignment is refused as a duplicate of something it has nothing to do with.

lms_progress — the learner is (learner_type, learner_id)

analyst_id is kept, in step for analyst rows and NULL for portal learners, purely so this was not a column drop (which would make the release MAJOR — see RELEASING.md). Nothing reads it. It goes at the next major version.

🔴 The unique key had to move with it. Making analyst_id nullable is not enough on its own: MySQL permits any number of NULLs in a unique index, so under the old (analyst_id, course_id) key every portal learner would have been unconstrained — a fresh progress row per visit, each with its own bookmark, and their place in a course appearing to reset at random.

New key: (learner_type, learner_id, course_id).

---

The migration, and three ways it could have failed silently

All three are in api/system/db_verify.php. All three produce a quiet wrong answer, which is why they are written down.

1. Ordering. The generic index backfill adds uq_lp_learner_course. On a grown install every existing row still has learner_id at its column default of 0, so they all collide on ('analyst', 0, course_id) and the key cannot be created. The backfill that sets learner_id = analyst_id therefore runs above the index pass, and says so in a comment. Move it below and the key is reported as un-addable on every installation that has ever recorded a course.

2. A second, hand-maintained index list. db_verify.php also carries a $uniqueIndexes array which still named uq_lp_analyst_course and uq_lca_course_group — it would have put back the two keys the repair exists to remove. Both entries were deleted. If you change an LMS index, check both places.

3. Inner joins to analysts. api/lms/progress.php, assignments.php and learner_data.php each opened with JOIN analysts …. For a portal learner that matches nothing, so a course pushed to 400 people would have rendered as an empty Progress tab, an assignment missing from the manager's own list, and "no progress record found" for a row visibly on screen.

🔑 An inner join to one of several possible tables is a filter, not a lookup.

---

The two queries that answer "who"

Both live in includes/lms_access.php. Everything composes them rather than writing its own joins — the same three-table join used to be spelled out in five files.

• lmsAssignmentReachSql($conn, $learner) → [sql, params], a WHERE fragment against lms_course_assignments ca. Answers "what reaches this person". Used by My Courses, the portal Training page, the access gate and the nav-tab check.
• lmsAssignedLearnersSql($conn) → a parenthesised UNION usable as a derived table. Answers "who does this reach". Used by the Progress tab and the reminder run.

They cannot be one query: one starts from a person, the other from an assignment.

UNION, not UNION ALL — somebody reached by two routes is one person expected to do one course. Callers still reduce by (learner, course) afterwards, because two routes can carry two different deadlines and the earliest wins.

⚠️ A cautionary tale: lmsAssignedLearnersSql() was extracted and progress.php was not switched over to it in the same commit. Individually-assigned learners were then missing from the manager's Progress tab — exactly the failure the extraction existed to prevent, one commit after making it.

The people-group branch applies the membership expiry at read time, exactly as Knowledge does: somebody whose access has lapsed is no longer expected to do the course, and leaving them in would generate chasing emails for training they can no longer open.

---

🔴 Two identities in one session

The analyst app and the self-service portal are the same host and share one PHP session. Anybody signed into both — which is every administrator who has ever looked at the portal — has analyst_id and ss_user_id sitting side by side.

There is then no such thing as "who is signed in". There are two answers, and only the request knows which one is acting.

LmsLearner::fromSession() originally preferred the analyst, with a confident comment explaining why that was safe. It was not. Measured: an administrator opened the portal's own Training page and was shown the administrator's ten courses, with their scores and overdue flags, under a heading reading "Courses you have been asked to complete".

Worse than the wrong list — the progress endpoints resolved identity the same way, so taking one of those courses from the portal would have written the attempt onto the analyst training record, while the page that allowed entry had gated it as the portal user. The gate and the writer disagreeing about who is acting.

The fix

Every LMS call made from the portal carries ?as=portal, and LmsLearner::fromRequest() honours it.

A plain query parameter is safe here precisely because it does not name an identity. It selects between the identities this session has already proven with its own cookies. An analyst-only session passing as=portal gets its own analyst identity back; an anonymous one gets nothing.

Five call sites in the two players carry it, including navigator.sendBeacon() on unload — the last thing the page does, and the one that writes the closing bookmark that decides where somebody resumes.

If you add an LMS endpoint that both front ends call, use fromRequest(), not fromSession().

---

Reminders

includes/lms_reminders.php, cron/lms_reminders.php, api/lms/reminder_settings.php.

lms_reminders_sent is a fire-once guarantee, not a log. Reminders are found by asking "whose deadline is N days away", which is true for the whole of that day and every run inside it — so the send is an INSERT IGNORE against a unique key. Without the key the INSERT IGNORE is meaningless and a nightly reminder becomes an hourly one. Same shape, and the same reason, as workflow_scheduled_emissions.

fingerprint carries the deadline the reminder was about, so moving a deadline legitimately reminds again while re-running today does not. Mirrors the SLA notification fingerprint.

🔑 The row is claimed before the send. A cron tick and somebody opening the LMS in the same second then send one email rather than two. Claiming afterwards leaves exactly that window open.

⚠️ A failed send gives the claim back. A reminder that failed has not been sent, and leaving the row would mean that person is never reminded about that deadline again — permanently, and invisibly.

Two run paths — cron, and opportunistically when a manager opens the LMS (throttled to once an hour) — for the reason includes/search/extract_queue.php gives: a cron-only design does nothing at all on an installation that never set one up. The settings screen is honest that the fallback is not a schedule.

A dry run (lmsRemindersRun($conn, true)) is the same code with a flag, not a separate estimate query that would eventually disagree with it.

---

Gotchas worth not rediscovering

• lmsCanManage() is analyst-only, and the manager bypass with it. It asks an RBAC question about an analysts row; passing a portal user's id would ask whether analyst #12 is an LMS manager while holding portal user #12. A portal learner has no Preview and no override.
• The module gate is an analyst-app concept. requireModuleAccessJson('lms') is applied only when the learner is an analyst. What entitles a portal learner is the assignment itself.
• A deadline is a picked calendar day stored at midnight — the third kind of stored date. Compare calendar days (lmsIsOverdue()), and render with fmtNaiveDate(), never fmtDate(). Two screens disagreed about the same column for exactly this reason.
• admin@localhost fails email validation (no TLD) and is correctly counted unreachable. It is the default administrator address on a fresh install, so it is a poor test recipient.
• The portal header used to overwrite $translationNamespaces. A page needing a third namespace — the course player speaks lms — got every label rendered as its own key. It is ?? now.
• self-service/includes/auth.php must be required after session_start(), or it redirects a perfectly well signed-in person to the login page.
• LMS and LMSPlayer are top-level consts and are not on window. A test harness must click real buttons rather than calling w.LMS.switchTab().

---

See also

• Training for Portal Users — the user-facing guide
• People Groups Developer Guide
• LMS
• Timezones and Time Handling — the kinds of stored date