Skip to content

fix(scorm): mark Welcome page unmarkForCompletion so LMS completion reports#5

Merged
RichardoC merged 1 commit into
mainfrom
fix-report
Jul 8, 2026
Merged

fix(scorm): mark Welcome page unmarkForCompletion so LMS completion reports#5
RichardoC merged 1 commit into
mainfrom
fix-report

Conversation

@RichardoC

Copy link
Copy Markdown
Owner

The 0.0.3 release reported 0% completion to an LMS even
though the learner finished every quiz. Root cause, traced through the
HAR of a real attempt plus Xerte's xttracking_scorm1.2.js + xenith.js:
with navigation="Menu with Page Controls", Xerte inserts a built-in
Table-of-Contents page as x_pages[0] AFTER toCompletePages is built
from currActPage over the 43 content nodes. So every content page's
page_nr (used by exitInteraction to mark completedPages[i]) is
currActPage + 1 -- a systematic off-by-one:

  • toCompletePages[0] == 0 could only be matched by page_nr == 0 (the
    menu), which is never exited (menu pages are excluded from
    x_endPageTracking), so completedPages[0] (the first content page,
    "Welcome") stayed false forever.
  • getSuccessStatus() returns 'incomplete' whenever any completedPages[i]
    is false, so finishTracking() set cmi.core.lesson_status='incomplete'
    (a no-op against Moodle's pre-set 'incomplete'), and the LMS never
    left the incomplete state. cmi.core.score.raw WAS being sent (75, then
    100) but never mattered to the displayed completion.

Changes to source/data.xml + source/preview.xml (identical):

  • unmarkForCompletion="true" on the Welcome page
    (linkID="PG1781882348053"). This makes markedPages skip currActPage
    == 0, so toCompletePages becomes [1,2,...,42], aligning with the
    content pages' page_nr values. completedPages[0] (Welcome) is now
    marked true when the learner leaves it.

Validated end-to-end through a running XOT (docker-container branch)
instance on host port 8088:

  • Pushed source/data.xml + source/preview.xml into the container; both
    carry unmarkForCompletion="true" on the Welcome page and are
    byte-identical to the repo source.
  • play.php?template_id=1 returns 200; HTML5 editor opens.
  • SCORM export is valid SCORM 1.2 (one SCO, 13 MB) and the exported
    template.xml carries unmarkForCompletion="true", trackingMode="full",
    trackingWeight 1x7 + 21, trackingPassed="80%", 45 questions, 8
    quizzes, 0 empty options -- all unchanged from 0.0.3 except the fix.
  • Drove the exported package against a SCORM 1.2 mock API: a completed
    run sends cmi.core.lesson_status="passed" (score.raw=100), a failing
    run sends lesson_status="failed" (score.raw=62.5), and an incomplete
    run sends lesson_status="incomplete" + cmi.core.exit="suspend".
    Before the fix the completed run reported "incomplete".

Trade-off: the Final quiz (page_nr == 43) is still outside
toCompletePages (no index 43), so its completion is not tracked in
completedPages -- but its score is still tracked via its interactions
and trackingWeight="21", so the LMS grade and pass/fail are correct.
The Welcome page is no longer "required" for completion, which is
acceptable for an intro page. A proper fix would be in the Xerte engine
(xenith.js: build toCompletePages from page_nr after the menu is
inserted), but that would not survive XOT rebuilds; this content-level
workaround is used because the release workflow builds from the XOT
engine. Do not remove unmarkForCompletion="true" from the Welcome page
without a replacement fix -- re-introducing the off-by-one will silently
break LMS completion reporting again.

Guidance updates:

  • docs/PROJECT_CONTEXT.md: added "SCORM completion bug fix" section
    documenting the root cause, fix, and trade-off; noted the Welcome
    page carries unmarkForCompletion="true" in the current-state list.
  • docs/COURSE_VERIFICATION.md: added "LMS completion fix (post-0.0.3)"
    section with the HAR evidence, root cause, fix, and validation
    results.

Generated with pi 0.80.3 and GLM 5.2

…eports

The 0.0.3 release reported 0% completion to an LMS even
though the learner finished every quiz. Root cause, traced through the
HAR of a real attempt plus Xerte's xttracking_scorm1.2.js + xenith.js:
with navigation="Menu with Page Controls", Xerte inserts a built-in
Table-of-Contents page as x_pages[0] AFTER toCompletePages is built
from currActPage over the 43 content nodes. So every content page's
page_nr (used by exitInteraction to mark completedPages[i]) is
currActPage + 1 -- a systematic off-by-one:

- toCompletePages[0] == 0 could only be matched by page_nr == 0 (the
  menu), which is never exited (menu pages are excluded from
  x_endPageTracking), so completedPages[0] (the first content page,
  "Welcome") stayed false forever.
- getSuccessStatus() returns 'incomplete' whenever any completedPages[i]
  is false, so finishTracking() set cmi.core.lesson_status='incomplete'
  (a no-op against Moodle's pre-set 'incomplete'), and the LMS never
  left the incomplete state. cmi.core.score.raw WAS being sent (75, then
  100) but never mattered to the displayed completion.

Changes to source/data.xml + source/preview.xml (identical):
- unmarkForCompletion="true" on the Welcome page
  (linkID="PG1781882348053"). This makes markedPages skip currActPage
  == 0, so toCompletePages becomes [1,2,...,42], aligning with the
  content pages' page_nr values. completedPages[0] (Welcome) is now
  marked true when the learner leaves it.

Validated end-to-end through a running XOT (docker-container branch)
instance on host port 8088:
- Pushed source/data.xml + source/preview.xml into the container; both
  carry unmarkForCompletion="true" on the Welcome page and are
  byte-identical to the repo source.
- play.php?template_id=1 returns 200; HTML5 editor opens.
- SCORM export is valid SCORM 1.2 (one SCO, 13 MB) and the exported
  template.xml carries unmarkForCompletion="true", trackingMode="full",
  trackingWeight 1x7 + 21, trackingPassed="80%", 45 questions, 8
  quizzes, 0 empty options -- all unchanged from 0.0.3 except the fix.
- Drove the exported package against a SCORM 1.2 mock API: a completed
  run sends cmi.core.lesson_status="passed" (score.raw=100), a failing
  run sends lesson_status="failed" (score.raw=62.5), and an incomplete
  run sends lesson_status="incomplete" + cmi.core.exit="suspend".
  Before the fix the completed run reported "incomplete".

Trade-off: the Final quiz (page_nr == 43) is still outside
toCompletePages (no index 43), so its completion is not tracked in
completedPages -- but its score is still tracked via its interactions
and trackingWeight="21", so the LMS grade and pass/fail are correct.
The Welcome page is no longer "required" for completion, which is
acceptable for an intro page. A proper fix would be in the Xerte engine
(xenith.js: build toCompletePages from page_nr after the menu is
inserted), but that would not survive XOT rebuilds; this content-level
workaround is used because the release workflow builds from the XOT
engine. Do not remove unmarkForCompletion="true" from the Welcome page
without a replacement fix -- re-introducing the off-by-one will silently
break LMS completion reporting again.

Guidance updates:
- docs/PROJECT_CONTEXT.md: added "SCORM completion bug fix" section
  documenting the root cause, fix, and trade-off; noted the Welcome
  page carries unmarkForCompletion="true" in the current-state list.
- docs/COURSE_VERIFICATION.md: added "LMS completion fix (post-0.0.3)"
  section with the HAR evidence, root cause, fix, and validation
  results.

Generated with pi 0.80.3 and GLM 5.2
@github-actions

github-actions Bot commented Jul 8, 2026

Copy link
Copy Markdown

📖 Course content preview

Download the course-preview artifact from the workflow run and open index.html to read the full course (pages + quizzes, correct answers marked ✓):

This preview is generated from source/data.xml by tools/render_preview.py. It is for review only — the playable SCORM package is built by the release workflow.

@RichardoC RichardoC merged commit 683131b into main Jul 8, 2026
1 check passed
@RichardoC RichardoC deleted the fix-report branch July 8, 2026 11:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant