SCORM Export

Author: James Derick Billate
Reviewer: Jethro Lagmay & Joylynne Esportuno
Creation Date: June 30, 2026
Status: Approved and Merged
References: https://github.com/wyzlab/WyzQuests/issues/41

INTRODUCTION AND GOALS

Problem Summary: This feature completes the overall goal of WyzQuests being an authoring tool. SCORM Export converts every quest into a SCORM-compliant package that can be uploaded to other Learning Management Systems (LMS). The package includes Computer Managed Instruction (CMI) handling and Sharable Content Object (SCO) launch files, making the content usable across different LMS channels and learners.

Goals and Non-Goals: There is already implementation of SCORM CMI behavior, particularly for learner progress, completion status, score, and current navigation/location within the quest. The feature supports SCORM 1.2 and SCORM 2004 single-SCO export for quests. The learner resume/backtracking experience when exiting midway still needs continued validation across LMS platforms. This feature does not cover Multi-SCO Adventure export, xAPI export, advanced sequencing, or fully offline asset bundling.

HIGH-LEVEL ARCHITECTURE

System Diagram:

Technologies Used:

Frontend: Next.js, React, Tailwind CSS, Shadcn Components, React Hook Form, Zod validation, Sonner toast.

Backend: RESTful APIs, TypeScript, Clerk authentication, agency ownership verification, Supabase, standardized API responses.

Packaging: JSZip, dynamic imsmanifest.xml, index.html, scorm-wrapper.js, and scorm-functions.js.

Standards: SCORM 1.2 and SCORM 2004.

DETAILED DESIGN & IMPLEMENTATION

Schema:

SCORM Export does not introduce a dedicated database table. It reads quest data from the existing quests table and uses the quest's canvas_metadata to launch the hosted player experience.

Relevant quest fields:

• id

• title

• introduction

• description

• enrollment_limit

• duration

• learning_objectives

• canvas_metadata

• creator_id

API Specification:  

GET /api/creator/share/scorm
Fetches the quest created by a Creator for SCORM launch/player initiation.

POST /api/creator/export/single-sco
Initiates the creation of a single-SCO SCORM package for SCORM 1.2 or SCORM 2004.

• Core Logic and Workflow:
  Choose a quest created by the Creator, preferably with a published or approved status.

• Choose SCORM 1.2 or SCORM 2004 as export version.

• Enter or accept the mastery score.

• Click the export button and wait for package generation.

• The API validates authentication, quest ID, SCORM version, mastery score, and quest ownership.

• The API fetches quest details from Supabase.

• generateExportPackage(version, parsedMasteryScore, questData) creates the package.

• JSZip generates a ZIP file buffer.

• The API returns the ZIP response.

• The browser downloads the generated package.

Generated package files:

• imsmanifest.xml: Defines the SCORM package, organization, SCO resource, schema version, and mastery score.

• index.html: Launches the WyzQuests SCORM player inside an iframe and passes restore/query parameters.

• scorm-wrapper.js: Finds the LMS SCORM API, initializes SCORM, reads saved location/suspend data, listens for player messages, and terminates on unload.

• scorm-functions.js: Implements SCORM data model writes for completion, success, location, suspend data, score, commit, initialize, and terminate.

SCORM Data Model Coverage:

SCORM 1.2:

• cmi.core.lesson_status

• cmi.core.lesson_location

• cmi.suspend_data

• cmi.core.score.max

• cmi.core.score.raw

SCORM 2004:

• cmi.completion_status

• cmi.success_status

• cmi.location

• cmi.suspend_data

• cmi.score.scaled

• cmi.score.max

• cmi.score.raw

INFRASTRUCTURE AND OPERATIONS

Dependencies: No known major dependency beyond validation and package generation dependencies. Current implementation uses Zod validation on the frontend mastery score form, backend mastery score checking, Clerk authentication, Supabase, agency ownership verification, and JSZip.

Monitoring and Alerting:

• No major monitoring is required because this feature is primarily an export process.

• Alert notification should be sent or logged whenever internal services fail to return accurate export data or package generation throws an error.

• Monitor export failures from /api/creator/export/single-sco.

• Monitor quest fetch failures from /api/creator/share/scorm.

Deployment Plan:

• Ensure all CMI behavior corresponds to SCORM 1.2 and SCORM 2004 documentation.

• Ensure imsmanifest.xml complies with SCORM standardization.

• Ensure generated package files are included in the ZIP.

• Ensure APP_URL or server base URL is configured correctly for the SCORM launch iframe.

• Validate export in a local SCORM harness and SCORM Cloud before release sign-off.

TESTING AND QUALITY ASSURANCE

Testing Strategy:

• Locally, use scorm-again by /jcputney.

• Install the package with npm.

• Add a local dev-scorm.js file when exporting a quest for local validation.

// SCORM 1.2
window.API = new window.Scorm12API({
  autocommit: true,
  logLevel: 1,
});
 
// SCORM 2004
window.API_1484_11 = new window.Scorm2004API({
  autocommit: true,
  logLevel: 1,
});

• Add this in index.html for local testing:

<script src="./dev-scorm.js"></script>

• Upload the ZIP file to SCORM Cloud for testing instead of directly relying on a production LMS first.

• Test SCORM 1.2 export.

• Test SCORM 2004 export.

• Confirm the package imports successfully.

• Confirm quest launch works.

• Confirm completion status is recorded.

• Confirm score is recorded when applicable.

• Confirm location/suspend data behavior when exiting and relaunching midway.

Known Limitations:

• Learner midway backtracking/resume behavior still needs full LMS-by-LMS validation.

• Export uses a launch iframe pointing back to the WyzQuests SCORM player rather than fully embedding every asset into an offline package.

• SCORM Cloud test evidence should be captured before claiming final acceptance complete.

• Advanced SCORM sequencing is not implemented.

MAINTENANCE AND SUPPORT

Troubleshooting:

• Re-export the quest.

• Confirm the quest exists and belongs to the Creator or allowed agency scope.

• Confirm SCORM version is scorm12 or scorm04.

• Confirm mastery score is valid.

• Inspect the generated ZIP and confirm imsmanifest.xml, index.html, scorm-wrapper.js, and scorm-functions.js exist.

• Run local validation with scorm-again.

• Upload to SCORM Cloud for further validation.

• Check browser console logs for "SCORM is not initialized" if the LMS API cannot be found.

Document Version

1.0 - Draft, Feature pushed but in need for further development 06/30/2026

1.1 - Enhanced documentation for SCORM Export 07/10/2026