# Quiz & Assessment Platform — Feature & Functionality Guide **Status legend used throughout this document:** - ✅ **Built & live** — implemented, compiles, part of the codebase today (as of 2026-08-28). - 🚧 **Planned, not built** — architecture is designed and agreed, but no code exists yet. Do not assume any 🚧 item works. This document assumes no prior knowledge of the codebase. If you are new to GB5, start with Section 1 and 2 before jumping to your role-specific section. --- ## 1. Executive Summary GB5 is building a unified **Quiz & Assessment platform** that lets any module — Training (TMS), Work Instructions (WI), Enablement (in-app guidance/announcements), and eventually a Learning Management System (LMS) and Interactive Document Management (IDMS) — attach a scored quiz or a "must-pass" gate to its own content, without every module reinventing question banks, scoring, or gating logic from scratch. **The core idea in one sentence:** there is now *one* shared question bank, *one* quiz-taking/scoring engine (owned by TMS), *one* shared way to tag content with a Course/Subject/Topic, and *one* generic "you must pass X before doing Y" gating mechanism — and every other module (WI today, Enablement today, LMS/IDMS tomorrow) plugs into these instead of building their own. **What exists today (✅ built):** - A shared Course/Subject/Topic/Learning-Object taxonomy (framework-level, usable by any module). - A standalone Quiz engine in TMS — quizzes that aren't tied to a training programme (e.g., "answer this one safety question before you proceed"). - A generic Validation Criteria model that lets Work Instructions (and, later, any module) say "you must pass quiz X / hold skill Y / have passed assessment Z before you can proceed" — without WI needing to know anything about how quizzes work internally. - Enablement (the in-app "Show" system — banners, tours, announcements) can now attach a quiz to a Show. - FLS (a general-purpose survey tool) no longer offers "Quiz"/"Test" as options — those are retired in favor of the real TMS Quiz engine, so there's exactly one place quizzes are scored, not two. **What is designed but not built (🚧 planned):** - Delivering quizzes through chat/voice channels (WhatsApp, Teams, Voice, etc.) via a module called **EIP** (already exists, for messaging/interaction) working together with a new module called **EAI** (does not exist yet, for AI capability). - AI-generated questions, AI-graded subjective answers, and "dynamic" questions that pull a live business fact (e.g., "what's the current stock of Item X?") into a question. - Adaptive "here's what to read next" suggestions for a learner. - Wiring any of this into a future LMS or into IDMS (neither exists yet). If you take away one thing from this document: **the foundation (taxonomy + quiz engine + gating) is real and working today; the AI/chat/voice/LMS layer is a designed-but-unbuilt roadmap.** --- ## 2. Concepts & Glossary (read this before anything else) | Term | What it means here | |---|---| | **Question Bank** (`MQUESTIONBANK`) | A shared pool of reusable questions (MCQ, True/False, Short Answer, Multi-Select, Matching, Ordering), each with marks, a difficulty level, and a correct answer. Already existed in TMS before this project; every quiz/assessment in the system draws questions from this one pool — nothing duplicates it. | | **Assessment** (`MSESSIONASSESSMENT`) | TMS's original, pre-existing concept: a scored test tied to a specific training programme/session/topic (e.g., "the post-training test for the Forklift Induction programme"). Always belongs to a training programme. | | **Quiz** (`MQUIZ`) — ✅ new | A *standalone* scored test that is **not** tied to a training programme. Can be attached to anything — an Enablement Show, a Work Instruction step, or nothing at all (a quiz that just exists and gets taken on demand). This is the new piece built for this project. | | **Quiz Mode: Instant vs. Structured** | A Quiz can be **Instant** (one question, answer it, get graded immediately — good for a quick in-the-flow check) or **Structured** (multiple sections, each pulling several questions from the bank by filter — like a real exam paper). | | **Attempt** (`TQUIZATTEMPT` / `TASSESSMENTATTEMPT`) | One person's try at a Quiz or Assessment. Records what was answered, the score, and whether they passed. A person can have multiple attempts (up to a configured maximum). | | **Course / Subject / Topic** (`MCOURSE` / `MSUBJECT` / `MTOPIC`) — ✅ new | A shared, three-level taxonomy for tagging *any* content in *any* module with a subject-matter classification (e.g., Course = "Warehouse Safety", Subject = "Manual Handling", Topic = "Lifting Technique"). Lives in the shared framework layer, not owned by TMS, so WI/Enablement/future-LMS/IDMS can all tag their own content the same way. | | **Learning Object** (`MLEARNINGOBJECT`) — ✅ new | A generic "wrapper" that says "this Quiz / this Work Instruction / this Show / this document is a piece of curriculum content, belonging to this Topic, taking about this long." This is a *curriculum/sequencing* concept — it's about *what order to learn things in* — and is deliberately separate from the *gating* concept below. | | **Validation Criteria & Assignment** (`MVALIDATIONCRITERIA` / `MVALIDATIONASSIGNMENT`) — ✅ new | The generic **gating** mechanism: "Entity X requires Validation Y, enforced as Block/Warn/Log." A criterion can be a Skill level, a passing Quiz, a passing formal Assessment, or (not yet implemented) a Certification. This is how, e.g., a Work Instruction says "you must pass this quiz before you can run this step." | | **Enablement / "Show"** | GB5's existing in-app guidance system — banners, product tours, announcements, checklists — surfaced to users inside the application. A "Show" can now (✅) have a Quiz attached to it. | | **Work Instruction (WI)** | GB5's shop-floor/operational instruction module — step-by-step instructions an employee follows to perform a task, with skill/eligibility gates before they're allowed to start. Now (✅) also checks the generic Validation Criteria gate, in addition to its own existing Skill checks. | | **FLS (Form Lifecycle Service)** | A general-purpose survey/feedback tool (registrations, forms, respondents, ratings). It used to *list* "Quiz" and "Test" as form types, but nothing ever actually scored them — that dead-end option has now (✅) been retired, redirecting people to the real TMS Quiz engine instead. | | **EIP (Enterprise Integration Platform)** | An **existing** GB5 module for multi-channel interaction — WhatsApp, Teams, Telegram, Slack, SMS, in-app chat, and voice. It has two dispatch paths: a fast "one-tap button" path (**DirectAction**) and a full back-and-forth conversational path (**Flow/Capability engine**). EIP does *not* do AI today — it's pure interaction/delivery. | | **EAI (planned name for the new AI module)** 🚧 | A **module that does not exist yet.** The plan is for it to own AI capability and its governance (which AI model, prompt versions, approval workflow, usage/cost tracking) as a separate concern from EIP's interaction/delivery job. EIP would *call* EAI when a chat/voice interaction needs an AI result — EAI would never talk to WhatsApp/Voice directly. | | **LMS (Learning Management System)** 🚧 | Does not exist yet ("coming soon"). The taxonomy and Learning Object work (✅ above) was deliberately built now so that when LMS is built, it can reuse the same Course/Subject/Topic and Learning Object tables instead of needing a new migration. | | **IDMS** | A separate, existing GB5 module (interactive document management). Not yet wired into the quiz taxonomy/gating — reserved slots exist so it can be, later. | --- ## 3. What's Built Today (✅) — Detailed Walkthrough ### 3.1 The Shared Taxonomy (Course / Subject / Topic / Learning Object) **Where it lives:** `GB5Framework` (the shared framework layer used by every module), not inside TMS. This was a deliberate choice — putting it in TMS would have meant every other module (WI, Enablement, future LMS/IDMS) had to depend on TMS just to tag its own content, which is backwards. Framework-level masters like `Country`/`City` already live here, so this follows the existing convention. **Tables:** - `MCOURSE` — top level (e.g., "Warehouse Safety Induction"). Can have a parent course (for course families). Can be a globally-shared course (visible to every tenant) or client-specific. - `MSUBJECT` — belongs to a Course (e.g., "Manual Handling"). - `MTOPIC` — belongs to a Subject, can have a parent topic (for sub-topics), carries a difficulty level and an optional linked Skill. - `TTOPICLINK` — a flexible "tag this thing with this topic" table, used when something needs many-to-many tagging rather than one primary topic (e.g., a Work Instruction that's relevant to several topics at once). - `MLEARNINGOBJECT` — wraps any real piece of content (a Quiz, a Work Instruction, a Show, a document, a video, an external link) as one addressable "unit of learning," tagged to one primary Topic, with a title, description, and estimated duration. This is the same concept most Learning Management Systems call a "Learning Object" or SCORM package. **Why two tagging mechanisms (direct link vs. `TTOPICLINK`)?** If something has exactly one topic and you need fast filtering (e.g., a quiz question filtered by topic), a direct column is used. If the relationship is optional or many-to-many (e.g., "this Work Instruction touches three different topics"), `TTOPICLINK` is used instead. Both patterns already existed elsewhere in GB5 and are reused here rather than inventing a third approach. **Bridging existing TMS data:** TMS's question bank already had free-text tag fields (`TOPICTAGS`, `INDUSTRYTAG`) before this project. Rather than breaking anything, a migration: 1. Added new `CourseId`/`SubjectId`/`TopicId` columns to the question bank and paper-section tables (default "not set"). 2. Auto-created a "Legacy TMS" course/subject and matched existing free-text tags into real Topic rows where possible. 3. Made question-bank searches check *both* the old free-text tags and the new Topic link during a transition period, so nothing broke. 4. (Planned, not urgent) A later step will retire the free-text path once everyone has migrated to real Topic tags. ### 3.2 The Standalone TMS Quiz Engine **Why a new engine, when TMS already had assessments?** TMS's existing `MSESSIONASSESSMENT` only makes sense *inside* a training programme (it needs a Programme/Session/Topic to belong to). There was no way to say "here's a quiz that exists on its own, maybe attached to a Show or a WI step, with no training programme involved at all." That's what `MQUIZ` adds. **Key tables:** - `MQUIZ` — the quiz definition: title, purpose, which Course/Subject/Topic it belongs to (optional), **Quiz Mode** (Instant or Structured), how questions are selected (Fixed/Random/Weighted), pass threshold %, max attempts, time limit, whether it's anonymous. - `MQUIZSECTION` — only used in Structured mode: one or more sections, each with its own question-count and filter (question type, difficulty, topic) — pulling from the shared question bank at quiz-start time, randomly if configured. - `TQUIZATTEMPT` — one row per attempt: who took it, when, from what triggering context (e.g., "this attempt was launched from Show #88" or "from WI #350"), total marks, marks obtained, score %, pass/fail. - `TQUIZATTEMPTRESPONSE` — one row per question answered within an attempt: the question, the given answer, whether it was marked correct, marks awarded. **How scoring works:** When an attempt is submitted, the system looks at each answered question's type: - Multiple-choice, True/False, Short Answer → exact (case-insensitive) match against the stored correct answer. - Multi-Select → the given options and correct options are compared as sets (order doesn't matter). - Matching/Ordering → compared as a normalized string. - If a question type can't be auto-graded, it's left pending for manual review (this is where a future AI-based evaluator would plug in — see Section 5). The learner's final score, pass/fail, and marks are always **computed server-side from the actual recorded answers** — the client can never just submit a score directly. This prevents someone from cheating by sending a fake "100%" straight to the API. **How question selection works:** Instant-mode quizzes pick N random questions from the shared bank, optionally scoped to a Topic. Structured-mode quizzes let each section define its own filter (question type, difficulty, topic) and pull that many questions at random (or in a fixed/weighted order) from the bank — this reuses the exact same "pull random rows from the shared pool" pattern TMS's existing assessment-paper system already used. **A Quiz can optionally be linked back to a formal Assessment** — `MSESSIONASSESSMENT` now has an optional `QuizId` field, so a training-programme assessment can *delegate* its questions to a shared standalone quiz instead of maintaining its own separate paper. This is optional; existing assessments are unaffected. ### 3.3 Validation Criteria — the Generic "You Must Pass This First" Gate **The problem this solves:** Before this, if a module (say WI) wanted to say "you can't do this until you've passed a quiz," it would have had to build its own quiz-specific "requirement" table, copy-pasting the same pattern every other module would also need. Instead, there's now one generic, reusable pair of tables any module can plug into. **How it works:** - `MVALIDATIONCRITERIA` defines *what* needs to be true: a type (Skill / Quiz / formal ProgrammeAssessment / Certification), which specific thing (which SkillId, which QuizId, which AssessmentId), a minimum score or level, and how many days the proof stays valid before it needs re-checking. - `MVALIDATIONASSIGNMENT` defines *who* requires it: which entity (a Work Instruction, a Show, a Training Programme, an IDMS document, ...), optionally which specific step within it, which criterion, and how strictly it's enforced (**Log** = just record it, **Warn** = allow through with a warning, **Block** = hard-stop). - A shared service (`IValidationCriteriaEvaluator`) answers "what has this person *not yet* satisfied for this entity?" by checking the right underlying table depending on the criterion type: a Skill checks the employee's stored skill level; a Quiz checks for a recent passing quiz attempt; a formal Assessment checks for a recent passing assessment attempt. Nothing new is invented for "where does the proof live" — it always points back to an existing, real record. **Example** (this is illustrative sample data, not literal seeded rows): | A Work Instruction step... | ...requires... | ...enforced as | |---|---|---| | "Operate Reach Truck, Cold Storage" (whole WI) | Forklift Operation skill, Intermediate level | Block | | Step 3, "Load Pallet onto Rack" | 80%+ on the "Warehouse Safety Pulse Check" quiz, within the last 90 days | Warn | | A Training Programme, "Forklift Operator Induction" | Passed the formal "Forklift Certification Final Exam" | Block | **Where this is actually wired in today:** Work Instruction's eligibility check now calls this evaluator in two places: 1. A "can I see if I'm eligible?" display check (never blocks, just shows what's missing). 2. The actual "start this Work Instruction" action — if a Block-level Validation Criterion is unmet, starting is refused with a clear error, exactly like WI's pre-existing Skill-level block already worked. **What was deliberately *not* touched:** WI already had its own Skill/Competency requirement tables before this project. Those were left completely alone — this is an *additional*, generic layer sitting alongside them, not a replacement. (A future, separate decision could migrate the old Skill-requirement table onto the new generic model, but that hasn't been done and isn't assumed.) ### 3.4 Enablement Integration Enablement's "Show" system (in-app banners, tours, checklists, announcements) already had a generic "attach content to this Show" mechanism (`ShowContentLink`) supporting several content types (an internal CMS article, an external URL, a file, a video, a document, a Work Instruction, and — a related but separate feature — a Training "Topic"). This project adds **Quiz** as one more attachable content type. A Show (or a specific step within a multi-step Show) can now point at a standalone Quiz. When the Show's content is displayed, the system automatically looks up the quiz's current title live (so if the quiz gets renamed later, the Show doesn't show a stale title) — the same pattern already used for the Work Instruction and Training links. **Practical implication:** an Enablement announcement like "Today's price briefing" could show an Instant-mode, single-question quiz right inside the announcement, without Enablement needing to know anything about how quizzes are scored — it just displays "Quiz #4002" and TMS handles everything else. ### 3.5 FLS — What Changed and Why FLS (Form Lifecycle Service) is a general survey/feedback tool. It has always had a "type" field for the forms it builds, and that list of types happened to include "Quiz" and "Test" — but **nothing in FLS ever actually scored a quiz**; those options were dead-ends that silently produced an unscored feedback form, not a real quiz. This has now been retired: those two options are marked archived/hidden, and the system now actively rejects any attempt to build a new FLS survey against them, with a message pointing the author at TMS's real Quiz engine instead. This avoids ever having two different, inconsistent places where "a quiz" could mean something different. **If you are building a survey/feedback form and it's genuinely a survey (not scored)** — nothing changes for you; FLS still works exactly as before for its real purpose (feedback, ratings, registrations). **If you were (or wanted to) build something in FLS labeled "Quiz" or "Test"** — that path is gone; use the TMS Quiz engine (Section 3.2) instead. --- ## 4. What's Planned But Not Built (🚧) — Read This as a Roadmap, Not a Feature List Nothing in this section exists in the codebase yet. It is documented here so that (a) developers building adjacent features don't duplicate this design, and (b) stakeholders understand where the platform is headed. ### 4.1 Delivering Quizzes Through Chat & Voice (via EIP) EIP (the existing interaction platform) has two ways of talking to a user: - **One-tap "DirectAction"** — a signed link or a WhatsApp-style button ("Approve" / "Option A") that triggers instantly, with no back-and-forth conversation. The plan is to use this for simple multiple-choice/True-False quiz questions — tap an answer, done. - **Conversational Flow** — a real back-and-forth chat (or a voice call), used for anything more open-ended: a subjective/short-answer question, an adaptive follow-up, or a spoken conversation. Both paths already exist in EIP for other purposes (approvals, notifications, chatbots) — the plan is to reuse them for quiz delivery, not build new delivery infrastructure. **Important, already-identified limitation:** EIP can send outbound emails, but there is no inbound email conversation path today — so a two-way "quiz by email" experience is explicitly deferred; email can only ever deliver a one-way notification or a single tap-to-answer link. ### 4.2 EAI — the Planned AI Module **EAI does not exist yet.** The plan is for it to be a brand-new module (its own layers, like every other GB5 module) whose only job is AI: which AI provider/model is used, versioned prompts, an approval step for AI-generated content before it goes live, and tracking how much each AI call costs. Deliberately, **no AI vendor has been chosen yet** — every planned capability is designed to ship first as a clearly-labeled "not configured" stub (matching a pattern already used elsewhere in GB5 for a different, unrelated AI feature), so the plumbing can be built and tested before anyone has to decide "which AI provider." **Planned AI capabilities (none built):** | Capability | What it would do | |---|---| | Generate Questions | Given a Course/Topic and source material, draft new question-bank questions for a human (subject-matter expert) to review and approve before they go live. | | Generate a Data-Bound Question | Given a question template like "What is the current stock of {Item}?" and a live business fact, produce a real question with a real, current answer — see 4.3. | | Evaluate an Answer | Grade a free-text or spoken answer against a rubric, with a confidence score and a flag if it needs a human to double-check. | | Suggest a Learning Path | After a quiz/assessment, suggest what a learner should read or study next, based on where they fell short. | **Who would call EAI:** TMS (for question generation and answer evaluation), and EIP (as a thin "ask EAI, format the result for this channel" step) — EAI itself would never talk to WhatsApp/Voice/etc. directly; that stays EIP's job. ### 4.3 Dynamic, Data-Driven Quiz Questions The original motivating idea behind this whole project: a quiz question that pulls in a *live* fact from another module — "What is the current price of Item X?", "How many units of Y do we have in stock right now?" — so staff are tested on real, current data relevant to their job, not a static textbook fact. The plan is a small, generic interface that any data-owning module (Inventory, Finance, HR) would implement to expose "facts" it owns, which the AI question-generation capability (4.2) would call to build the question, and which the grading step would compare the answer against. The live value is "frozen" onto the question at generation time, so if stock changes five minutes later, grading is still fair and deterministic. ### 4.4 Voice-Based Q&A Once 4.1 (chat/voice delivery) and 4.2 (AI evaluation) exist, voice needs almost no extra work: a voice call is just another "conversation," where the caller's spoken words arrive as ordinary text (an external phone/voice provider is expected to do the speech-to-text conversion — GB5 doesn't build that part), and the reply is converted to speech using EIP's existing voice-response mechanism. The only new rule planned: a scored voice attempt should require an extra identity check (like an OTP), since a phone call can't rely on someone already being logged into the app the way a chat session can. ### 4.5 Adaptive Learning Suggestions After a quiz/assessment, planned functionality would look at a learner's history and topic-level gaps (using the taxonomy from Section 3.1) and produce a ranked "read this next" list with a short explanation of *why* each item was suggested — delivered as a follow-up chat message once 4.1 exists. ### 4.6 LMS and IDMS Neither module exists yet. Because the taxonomy and Learning Object work (Section 3.1) and the generic gating model (Section 3.3) were built as shared, framework-level concepts from day one, the plan is that when LMS is eventually built, "a course" in LMS is just a new LMS-owned enrolment/offering table sitting *on top of* the existing `MCOURSE`/`MLEARNINGOBJECT` tables — not a new parallel taxonomy. The same applies to IDMS documents, which have a reserved (but unused) slot in the tagging system already. --- ## 5. Known Open Questions (not yet decided, flagged for whoever picks this roadmap up next) - **Which AI provider/vendor?** Not decided. Everything in Section 4.2 is designed to work with any provider, plugged in later. - **Does an in-app "Show" quiz-question flow (`ShowNature = Assessment`, an older, separate mechanism) get consolidated with the new standalone Quiz, or do both stay?** Currently both are allowed to coexist by design, but this hasn't been explicitly confirmed as the final answer. - **When EIP and the (not-yet-built) EAI module talk to each other, is that an in-process call or a network call?** Depends on how the two modules end up physically hosted/deployed — not yet decided. - **Should Work Instruction's older, quiz-unaware Skill-requirement table eventually be migrated onto the new generic Validation Criteria model?** Deliberately deferred — the old table was left untouched to avoid destabilizing a working gate; this is a candidate for later cleanup, not a current plan. - **Two-way email as a quiz channel** — explicitly out of scope for now; email can only ever be one-way (a notification or a single-tap link). --- ## 6. Role-Specific Guides ### 6.1 For Developers — Building *On Top Of* This Feature (i.e., your module wants to use quizzes/gating) **"I want my module's content to be tagged with a subject-matter Topic."** Use the shared taxonomy (`MCOURSE`/`MSUBJECT`/`MTOPIC`, `GB5Framework/FrameworkDAL/DTO/Taxonomy/`). If your entity has exactly one topic, add a direct `TopicId` FK column (see how the Quiz/QuestionBank tables do this). If it's many-to-many/optional, use `TTOPICLINK` instead — add your module's `EntityType` value to `TaxonomyEntityTypeConstant` (a slot is likely already reserved; check the constant file first). **"I want my content to be part of a curriculum sequence."** Wrap it as a `MLEARNINGOBJECT` (there's a `LOTYPE` value for most content kinds already — Quiz, WorkInstruction, Show, Video, Document, ExternalLink, etc.). This is purely a "what order to learn things in" concept — it does not gate anything by itself. **"I want to require that a user pass a quiz / hold a skill / have passed a formal assessment before doing something in my module."** This is the Validation Criteria model (`GB5Framework/FrameworkBLL/Validation/IValidationCriteriaEvaluator`). Register a `MVALIDATIONCRITERIA` (what's required) and a `MVALIDATIONASSIGNMENT` (which of your entities requires it, and how strictly), then call `GetUnmetValidationCriteriaAsync(yourEntityType, entityId, stepId, employeeId, ...)` from your own eligibility/start-execution logic — exactly as WorkInstruction's `WiExecutionBLL` does it today (that's the reference implementation to copy). **Do not build your own quiz-requirement table** — this is precisely the thing this model exists to prevent. **"I want to attach a quiz to my content the way Enablement did."** Look at `ShowContentLinkBLL.cs` in Enablement for the exact pattern: a polymorphic link table + a live-title-refresh call into TMS's `IQuizBLL.GetQuizById`. TMS's Quiz module is designed to be called from any module's BLL layer this way — it lives in `TMSBLL/Quiz/`, exposed via `IQuizBLL`/`IQuizAttemptBLL`. **Layering rules to respect (same as the rest of GB5):** SL → BLL → DAL only; BLL never touches ASP.NET types; DAL never contains business rules. Cross-module calls go **BLL-to-BLL** (e.g., Enablement's BLL calls TMS's `IQuizBLL`, never TMS's DAL directly). Reading another module's *own* database table directly with parameterized SQL is acceptable only for genuinely shared, unprefixed (`DBO.`) tables — which is how the Validation Criteria evaluator checks TMS's quiz/assessment attempt tables without needing a project reference to TMS at all. **Where to find working examples (all committed, all buildable today):** - Taxonomy 3-tier example: `GB5Framework/FrameworkDAL/DTO/Taxonomy/`, `FrameworkBLL/Taxonomy/`, `FrameworkSL/Endpoints/Taxonomy/`. - Full Quiz engine: `GB5Solution/TMS/TMSDAL/DTO/Quiz/`, `TMSBLL/Quiz/`, `TMSSL/EndPoints/Quiz/`. - Validation Criteria + evaluator: `GB5Framework/FrameworkDAL/DTO/Validation/`, `FrameworkBLL/Validation/`. - A real cross-module consumer of the evaluator: `GB5Solution/WorkInstruction/WiBLL/WiExecution/WiExecutionBLL.cs`. - A real "attach content" integration: `GB5Solution/Enablement/EnablementBLL/ShowContentLink/ShowContentLinkBLL.cs`. ### 6.2 For Developers — Extending the Quiz/Assessment Feature Itself - **Migrations** live per-module (`GB5Framework/Migration/`, `GB5Solution/TMS/Migration/`, `GB5Solution/Enablement/Migration/`), numbered sequentially (`V001`, `V002`, ...), written as idempotent `IF NOT EXISTS` blocks — never assume a migration has or hasn't run; always guard it. - **New question types, new Validation Criteria types, new LinkTypes, new LOTYPEs** are all additive numeric enums — never renumber an existing value, since these are persisted data, not display-only labels. - **A new AI capability (once EAI exists)** should be added as a new EAI endpoint + a provider-agnostic contract with a "not configured" stub — follow the existing `GB5Shared/RecordingIntelligence/IAICapabilityService.cs` pattern rather than inventing a new convention. - **A new EIP channel or delivery pattern** belongs entirely inside EIP's existing channel-handler/Flow-engine structure — the Quiz/EAI side should never need to know which chat channel it's being delivered through. ### 6.3 For Content & Lesson Creators - All quiz questions come from **one shared question bank** — before writing a brand-new question, search the bank; you may be able to reuse (or lightly adapt) an existing one instead of duplicating effort. - Tag your questions and quizzes with a **Course / Subject / Topic** wherever possible — this is what makes filtered/random question selection and future search/discovery work well. Untagged content still works, but is harder to find and can't be scoped by topic. - Decide **Instant vs. Structured** deliberately: use Instant for a single, quick "did you get this" check embedded in something else (a Show, a WI step); use Structured for a real, multi-section exam-style assessment. - **Not available yet:** AI-assisted question drafting, dynamic data-driven questions ("today's stock/price"), and voice-based delivery. If you need any of these today, they must be authored manually using the existing mechanisms — there is no AI shortcut in the product yet. - If you were previously using FLS to build a "Quiz" or "Test" — that option is gone. Build it as a real TMS Quiz instead (ask your admin/developer team if you don't have direct access to the TMS Quiz authoring API yet — a dedicated UI for this may not exist yet either; check with your project team). ### 6.4 For Admins - **Configuring a quiz:** pass threshold %, max attempts, time limit, whether it's Instant or Structured, and whether it's anonymous are all quiz-level settings (`MQUIZ`). Random/Fixed/Weighted question selection is set per section in Structured mode. - **Setting up a gate** ("this Work Instruction requires a passing quiz"): create a `MVALIDATIONCRITERIA` row (what's required, what score/level counts as passing, how long the pass stays valid) and a `MVALIDATIONASSIGNMENT` row (which WI/Show/etc. requires it, and whether it's a hard Block, a soft Warn, or just logged). There is no dedicated admin UI documented for this yet as of this writing — this is a direct-API/data-configuration capability today; check with your project team about UI availability. - **Attaching a quiz to an Enablement Show:** use the existing Show-content-link admin flow, choosing "Quiz" as the content type and selecting the quiz. - **FLS instrument types:** "Quiz" and "Test" no longer appear as valid, active options when building a new FLS survey — this is intentional (see Section 3.5), not a bug. - **Reporting:** attempt-level pass/fail and score data already exists in the database (`TQUIZATTEMPT`/`TASSESSMENTATTEMPT`) — team- or KRA-level rollup dashboards are not yet built as a specific deliverable; if you need one, it would be built using GB5's existing Analytics/Report Viewer tooling against this data, as its own request. ### 6.5 For Trainers - A **formal training-programme Assessment** (the concept you already know from TMS) can now optionally **delegate its questions to a shared standalone Quiz** instead of maintaining its own separate paper — this is optional; your existing assessments are unaffected if you don't use it. - Attempts that can't be auto-graded (e.g., a short-answer question with no exact stored answer) are left **pending for manual review** — there is a review/evaluate path for this (mirroring the existing assessment-attempt evaluation flow), it's just not AI-assisted yet. - You can see, per attempt: attempt number, score %, pass/fail, and which specific questions were answered how — nothing about this reporting shape has changed from what already existed for formal assessments; the standalone Quiz engine mirrors it exactly. ### 6.6 For End Users / Learners **What you can experience today:** a quiz question (or a full multi-section quiz) that might show up: - Inside an in-app announcement or tour (Enablement "Show"), - As part of a shop-floor Work Instruction, possibly as something you must pass before you're allowed to proceed with a task, - As part of your regular training-programme assessment (this already existed). You'll see your score and pass/fail status right after submitting. If a question needs a human to check it (a written answer, for instance), you may see "pending review" instead of an instant result. **What's coming, not yet available:** answering quiz questions via WhatsApp/Teams/voice call, an AI explaining *why* an answer was right or wrong, quiz questions built from live, real-time company data (like "what's today's price of X"), and personalized "read this next" suggestions after a quiz. None of these exist in the product yet. --- ## 7. Data Model Quick Reference | Table | Owner Module | Purpose | Status | |---|---|---|---| | `MCOURSE` / `MSUBJECT` / `MTOPIC` | GB5Framework | Shared subject-matter taxonomy | ✅ | | `TTOPICLINK` | GB5Framework | Many-to-many topic tagging for any entity | ✅ | | `MLEARNINGOBJECT` | GB5Framework | Curriculum-sequencing wrapper over any content type | ✅ | | `MVALIDATIONCRITERIA` | GB5Framework | Defines a gate: Skill/Quiz/ProgrammeAssessment/Certification + threshold | ✅ | | `MVALIDATIONASSIGNMENT` | GB5Framework | Assigns a gate to an entity (WI, Show, Programme, ...) with enforcement level | ✅ | | `MQUIZ` | TMS | Standalone quiz definition | ✅ | | `MQUIZSECTION` | TMS | Structured-mode section filter | ✅ | | `TQUIZATTEMPT` / `TQUIZATTEMPTRESPONSE` | TMS | Attempt header / per-question response | ✅ | | `MSESSIONASSESSMENT.QuizId` | TMS | Optional delegation from a formal assessment to a shared quiz | ✅ | | `MQUESTIONBANK` | TMS | Shared question pool (pre-existing, reused, not duplicated) | ✅ (pre-existing) | | `MASSESSMENTPAPER` / `MPAPERSECTION` / `TASSESSMENTATTEMPT` | TMS | Formal, programme-bound assessments (pre-existing) | ✅ (pre-existing) | | `TShowContentLink` (`LinkType=8`) | Enablement | Attaches a Quiz to a Show/step | ✅ | | `MSURVEYINSTRUMENTTYPE` (Quiz/Test rows) | FLS | Now archived/retired, redirects to TMS | ✅ (retired) | | `MEAICAPABILITY` / `TEAIINVOCATIONLOG` | EAI (new module) | AI capability registry + usage log | 🚧 not built | | Live-data "fact provider" abstraction | Shared, per producing module | Supplies dynamic quiz question data | 🚧 not built | ## 8. API Reference (built endpoints only) | Route | Purpose | |---|---| | `GET/POST/DELETE /Course/...`, `/Subject/...`, `/Topic/...`, `/TopicLink/...`, `/LearningObject/...` | Taxonomy CRUD (GB5Framework) | | `GET/POST/DELETE /Validation/...ValidationCriteria`, `/Validation/...ValidationAssignment` | Gating configuration CRUD (GB5Framework) | | `GET /Validation/GetUnmetValidationCriteria` | Cross-module eligibility check (query-only, never caches) | | `GET/POST/DELETE /Quiz/...` | Quiz definition CRUD (TMS) | | `GET/POST/DELETE /Quiz/...QuizSection` | Structured-mode section CRUD (TMS) | | `POST /Quiz/StartQuizAttempt`, `POST /Quiz/SubmitQuizAttempt`, `GET /Quiz/GetQuizAttempt` | Taking a quiz (TMS) | --- ## 9. Document Scope & Maintenance Note This document reflects the state of the codebase as of **2026-08-28**. Sections 3 and 7–8 describe code that exists and builds; Sections 4 and the corresponding roadmap rows describe design intent only. If you build any 🚧 item from Section 4, please update this document at the same time so it doesn't drift into describing unbuilt features as if they were real (the opposite mistake — describing real features as still "planned" — is just as important to avoid).