LMS Authoring

How FreeITSM lets you write a course, rather than only upload a SCORM package authored elsewhere. Companion to the module hub LMS; for the AI helpers see LMS AI Authoring.

Before this, publishing a single page of text meant buying Articulate or Rise, exporting a zip and uploading it — a strange front door for a free, self-hosted ITSM. Now you press Create and write the course in the app.

---

Why native, not "compile to SCORM"

A tempting alternative is to author in a database but compile to a SCORM zip and play it in the existing iframe. FreeITSM deliberately does not do this, for two reasons that outweigh the portability a zip would give:

1. You'd write the player twice. A SCORM package is static files; something inside it must still render the lessons, collect answers, grade, and call the SCORM API — the same player code, plus a compiler and a manifest generator. Native is strictly less code, not more.
2. The answer key would ship to the browser. If grading happens inside the package, the correct answers sit in a JS file the learner can open in devtools — exactly why SCORM quizzes are trivially cheatable. Native keeps grading on the server (see below).

The database is the source of truth either way, so "Export as SCORM" remains a viable future feature — generated on demand for portability to another LMS — without being the runtime.

---

The content model

A course is a tree, three tables deep, all cascading on delete:

lms_courses  (content_type='native', pass_mark)
  └─ lms_lessons        (ordered; body = TinyMCE HTML)
       └─ lms_questions (question_type: single | multiple | truefalse)
            └─ lms_answers  (answer_text, is_correct  ← the key)

• Lessons are written in TinyMCE, the same editor and same trust level as a Knowledge article — including inline base64 images, so a lesson carries its own media with nothing on disk to lose or leak. Reorder by dragging; display_order is the position.
• Questions hang off a lesson and are asked at its end. Three types: choose-one, choose-several, true/false. Each has an optional explanation shown to the learner after they answer.
• Answers are a question's options. is_correct is the answer key and never leaves the server (see Grading).

The editor (lms/editor.php)

Gated by lms.manage. Left: the lessons, draggable. Right: the selected lesson's body in TinyMCE, and the questions that follow it.

• Course settings — title, description, and the pass mark (0–100, or blank for "no pass mark").
• Lessons — add, rename, write, reorder, delete. A lesson save writes only the body; questions have their own endpoint.
• Questions — a modal per question: the text, the type, the answers (radio for single/true-false, checkboxes for multiple — the control tells the author the rule), which are correct, and the explanation.

Question validation happens at the door, server-side in api/lms/questions.php, and refuses author mistakes rather than discovering them in the results:

• at least two answers, each with text;
• at least one correct answer (a question with none would silently mark everyone wrong);
• a single / truefalse question may not have two correct answers (a contradiction) — the error nudges you to "Choose several".

Preview comes back here (#1407)

Preview opens the real learner player in the same tab, which is the point — you see exactly what a learner sees, through the same access gate. What it used to do afterwards was drop you on the course list, three clicks from the lesson you had been editing.

player.php?course_id=N&from=editor now sends the player's back button to editor.php?course_id=N. ⚠️ The parameter is checked against the capability, not just read: anyone can type &from=editor, and a learner must never be handed a link to an authoring screen they cannot open. It is resolved in player.php above the native handoff, so the authored-course player — which draws its own toolbar — gets the same answer.

🔴 "Unsaved changes" and why it must not compare stored text with editor text (#1409)

Moving between lessons asks before discarding an edit. That check compared the lesson as the API returned it against editor.getContent() — and those are two different serialisations of the same document. TinyMCE re-writes whatever it is handed, and by default (entity_encoding: 'named') turns non-ASCII into named entities:

stored        ...example — a Customers table...
getContent()  ...example — a Customers table...

So the lesson counted as modified from the instant it opened, and every navigation asked about changes nobody had made.

🔑 A dirty check must compare like with like. The baseline is taken from the editor, immediately after the content lands in it, so whatever normalising the widget does has already happened on both sides.

⭐ It stayed hidden because content typed into the editor is saved in the editor's own encoding and compares equal on the way back in. Only text that reaches the database without passing through TinyMCE is affected — which is exactly what AI-drafted content is, and AI writing uses em dashes and curly quotes as a matter of course. It surfaced the first time a whole course was drafted rather than typed.

⚠️ The baseline is captured in setEditorBody and in TinyMCE's init handler, because that write can be deferred (the editor and the lesson fetch race at start-up, see #1398) and the baseline has to follow the content rather than the request to set it. It is re-taken after a successful save, which was the same fault more quietly: a lesson stayed "modified" immediately after being written.

The native player (lms/native-player.php)

An authored course has no package and no launch URL, so player.php detects content_type = 'native' and hands off to the native player instead of the SCORM iframe. It renders lesson-by-lesson from the database, so it inherits the app's theme and dark mode rather than being a foreign white box.

• A contents list, a progress bar, and resume (the last lesson is the bookmark).
• At the end, an answer review: what you got wrong, the correct answer, and the explanation.
• Content is fetched from api/lms/course_content.php — the one endpoint that returns a course to a learner, and the one that never selects is_correct. There is no filtering step to forget: the answer key is simply never on the wire.

Grading is server-side

api/lms/native_progress.php grades a submission by re-reading the correct answers from lms_answers and comparing. The client posts only which answer ids were chosen; it has no key to check against and cannot be made to lie about the result.

• Right = exactly the correct set, no more and no less (ticking every box is marked wrong).
• Score = percentage of questions correct across the whole course.
• With a pass mark, the learner is passed / failed against it and may retake; without one, finishing is completed; a course with no questions is completed on reaching the last lesson.

Reuse: authored results ride the SCORM rails

The clever bit that avoided a second admin UI: the grader writes each result as SCORM CMI rows into lms_cmi_data using the real element names — cmi.interactions.N.id, .learner_response, .result, .correct_responses.0.pattern, and cmi.score.raw. Because the admin Progress tab and the Learner Data drill-down already read those, an authored course lights them up with no new admin code at all. See LMS.

---

The learner/manager split

The LMS is the pilot module for Roles (RBAC "Layer 2"). The whole surface is divided by one capability, lms.manage:

Surface	Gate	Who
Admin dashboard, editor, all management APIs	lms.manage	Managers + admins
My Courses page + its feed	the lms module	Every learner
Playback, learner content / progress / SCORM-runtime APIs	assigned-to-me or lms.manage	Learners (their courses) + managers (any, = Preview)

Enforcement lives in one helper file, includes/lms_access.php, so the rule can't drift between the pages, the APIs and the player:

• lmsCanManage($conn, $analystId) — thin wrapper over analystHasCapability('lms.manage') (so is_admin bypasses).
• lmsCourseAssignedTo($conn, $analystId, $courseId) — is the course assigned to a group the analyst is in?
• lmsCanAccessCourse(...) — manage or assigned. The playback gate.
• requireLmsCourseAccessJson($conn, $courseId) — the 403 twin for learner APIs.
• lmsMyCourses($conn, $analystId) — the assigned-to-me feed behind My Courses.

lms/ (the dashboard) routes a non-manager to my-courses.php, and the header nav adapts — learners see My Courses + Help, managers additionally get Dashboard + Settings.

Manager ≠ admin. A manager is a non-administrator who holds an lms.manage Role. This is exactly the point of the Roles system: delegate running the LMS without handing someone the whole System module.

---

SCORM upload safety

Uploaded packages extract into lms/content/<id>/ — a web-served directory Apache can execute from — so an unguarded ZipArchive::extractTo() would let anyone with the LMS ship a .php shell and run code as the web server. includes/lms_package.php vets every entry before anything is written (and before the course row is created, so a rejected upload leaves nothing behind):

• an allowlist of course file types (HTML/CSS/JS/images/media/fonts/PDF) — never .php, never an extension-less file;
• rejection of any path that escapes the folder (zip-slip: ../…, absolute, C:\…);
• zip-bomb caps — total uncompressed size, entry count, and per-entry compression ratio.

Only the vetted entries are extracted, never the whole archive. As defence in depth, a committed .htaccess in lms/content/ disables code execution for the whole tree — and .htaccess is itself on the deny list, so a package can't ship one to undo it.

---

Key files

File	Role
lms/editor.php · assets/js/lms-editor.js	The authoring surface (gated by lms.manage)
lms/native-player.php · assets/js/lms-native-player.js	The learner's player for authored courses
lms/my-courses.php · assets/js/lms-my-courses.js	The learner landing
api/lms/lessons.php · questions.php	Author-side content APIs (return the key)
api/lms/course_content.php	Learner content feed (never returns the key)
api/lms/native_progress.php	Server-side grading + progress
api/lms/my_courses.php	The assigned-to-me feed
includes/lms_access.php	The learner/manager access rules
includes/lms_package.php	Safe SCORM extraction

Related pages

• LMS — the module hub
• LMS AI Authoring — the three AI helpers in the editor
• Roles & Permissions — the lms.manage capability
• Knowledge — the article source for AI-drafted lessons