# TMS (Training Management System) — Feature & Functionality Guide

**Purpose of this document:** a single, code-grounded source of truth for everything TMS does today
in GB5, organized so sections can be lifted directly into audience-specific deliverables — developer
reference, implementation/config guide, admin guide, end-user help, and marketing/sales collateral.
Every claim below is grounded in the actual backend (`GB5Solution/TMS`, `GB5Solution/FLS`) and frontend
(`gb4.7mfe/projects/training`, `features/gbfls`, `features/gbsurvey`, `features/gbtmsfeedback`) code as
of 2026-08-18. Sections marked **[Internal only — not for marketing]** describe known gaps and should
not appear in customer-facing material.

---

## 1. Executive Summary (marketing/sales-friendly)

TMS is GB5's end-to-end Learning & Development platform: it takes a training need all the way from
intake, through curriculum design, scheduled delivery, learner enrollment (with manager+HR approval
and automatic waitlisting), assessment and grading, certification with tamper-evident digital
signatures and QR verification, satisfaction feedback, and — its standout differentiator — **automatic
skill-level upgrades**: when an employee passes a mapped assessment or completes a mapped programme,
GB5 can automatically (or with human review) raise their recorded skill level in the Skill Management
module, closing the loop between "we detected a skill gap" and "the system record now reflects the
employee is qualified." Training operations are visible in real time through role-based dashboards
(Learner "My Learning" portal, Trainer daily schedule, L&D leadership Plan-vs-Actual dashboard) and
posted nightly into GB5's shared KPI-card framework for HR leadership (Compliance Coverage, Nomination
Approval Turnaround, Cost per Trained Employee, Assessment Pass Rate, and 7 more).

Assessments and feedback surveys can be delivered two ways — in-app for logged-in employees, or via a
tokenized public link (no login required) for external/offline audiences — through a single, unified
respond experience shared with GB5's generic Feedback/Survey engine (FLS). This "bridge" architecture
means any future GB5 module can plug its own content into the same link/reminder/tracking
infrastructure without re-building a delivery pipeline.

---

## 2. Functional Area Catalog

### 2.1 Training Needs Intake
- Central register (`Training Need Register`) for raising and tracking training demand, with a
  12-source taxonomy describing *why* a need exists: Manual HR, Skill Gap, Competency Gap, Appraisal
  Output, OKR Review, RCA/CAPA Action, Business Change, Periodic Schedule, Manager Nomination,
  Self-Nominated, Regulatory Requirement, Retraining.
- Formal lifecycle: **Draft → Submitted → Under Review → Approved → Linked/Closed** (or **Rejected**).
  Only Draft needs are freely editable; every other transition is a controlled workflow action.
- Fields: domain, priority, target audience, compliance deadline, recommended/linked programme.
- **Programmatic auto-raise (added 2026-08-20)**: `ITrainingNeedBLL.ProposeTrainingNeed` is a new,
  generalized, non-interactive entry point any producer module can call to raise a need
  automatically — tagged with the correct `NeedSourceType` and a `SourceRefEntity`/`SourceRefId`
  pointer back to the triggering record, idempotent (repeated calls for the same source return the
  existing open need rather than duplicating). It resolves via `SaveTrainingNeed` under the hood, so
  a system-raised need still lands in Draft for human review, same as a manually-entered one; the
  only behavioral difference is `RaisedById = -1` (system-raised, not a human).
- **[Internal only]** only one of the 12 sources is wired to a real producer today — **Skill Gap**,
  via Work Instruction's roster gap screen (`wi.skillgap.detected` → TMS's `WiSkillGapSubscriber` →
  the previously-unwired `TSKILLGAPLINK` bridge table → `ProposeTrainingNeed`). Appraisal, OKR,
  RCA/CAPA, Business Change, and the rest of the taxonomy remain data-field-only — those modules
  would need to build their own gap/need-detection logic and publish their own
  `{module}.something.detected` event before they could plug into the same generalized mechanism.
  Requires the tenant to have at least one `MTRAININGDOMAIN` row configured, or any auto-raise
  attempt fails validation (non-fatally to whatever triggered it) — flag as a go-live prerequisite.

### 2.2 Curriculum & Programme Design
- **Training Programme** authoring: identity, scope & capacity, description, and a full curriculum
  hierarchy — **Sessions** within a programme, **Topics** within a session (three configurable
  complexity levels: programme-only, +sessions, +topics).
- **Prerequisites** — programme-to-programme prerequisite chains.
- **Skill Map** — links a programme (or a specific assessment within it) to the skill(s) and level(s)
  it should grant on successful completion — the data backbone of the automatic skill-upgrade feature
  (§2.9).
- **Competency Map** — links a programme to organizational competencies.
- 16 programme types (Induction, Technical, Behavioural, Safety, Compliance, Leadership,
  Cross-Functional, Dojo, OJT, System Training, Process Training, Product Knowledge, Soft Skills,
  Refresher, Certification Prep, Coaching) and 9 delivery modes (Classroom, Online, Blended, Dojo, OJT,
  Virtual, Hybrid, Self-Paced, Webinar).
- **Programme Catalogue** — a browsable, filterable (domain/type/delivery/complexity/provider) view for
  choosing what to schedule or nominate into.
- **Revision History** — every update to a programme's full curriculum snapshots the *entire prior
  state* (sessions, topics, prerequisites, skill/competency maps, and even the linked assessment
  content) as a JSON record before applying the change — a genuine, append-only audit trail, not just
  a "last modified" timestamp.

### 2.3 Scheduling & Delivery
- **Training Instance** — a scheduled, capacity-bounded run of a programme, with its own lifecycle
  (Draft → Open → Enrolment Closed → In Progress → Completed, or Cancelled/Postponed).
- Per-instance session occurrences and delivery configuration (internal trainer vs. external
  vendor/trainer).
- Instance-level **Feedback dispatch** panel: pick a feedback instrument, pick learners, send via the
  FLS delivery pipeline, track submitted/pending/overdue counts live, and nudge stragglers with one
  click. Supports an optional certificate-blocking flag (surfaced in status; see §2.8's caveat).

### 2.4 Nomination & Enrollment
- Nomination entry point with duplicate-guarding (no double-enrolling the same employee in the same
  instance) and automatic **waitlisting** with position tracking when an instance is at capacity.
- **Two-tier approval workflow**: Nominated → Manager Approved → HR Approved → Enrolled, with
  Manager-Rejected/HR-Rejected as distinct terminal states (previously-rejected employees can
  re-nominate — rejection doesn't permanently block a future attempt).
- **Withdrawal** supported from any pre-completion state, automatically freeing a held seat.
- **Attendance** tracking per session (Present/Absent/Partial/Excused), with bulk entry for an entire
  session roster in one action.
- **Completion** recording (Completed/Partial/Failed/No-Show/Withdrawn) with pass/fail flag — this is
  one of the two triggers for automatic skill upgrades (§2.9).

### 2.5 Assessment Engine
- **Authoring**: two modes — *Simple* (a flat, inline question list) and *Structured/Paper* (sections
  built from a shared Question Bank, filtered by type/difficulty/tag, with configurable randomisation,
  time limits, one-question-at-a-time pacing, review-allowed, and LMS-delivered flags).
- **Question Bank**: a reusable pool of MCQ / True-False / Multi-select / Short-answer / Matching /
  Ordering questions, tagged by difficulty, skill, topic, and industry, with a usage-count tracker so
  frequently-reused questions are visible.
- **Delivery**: assessments can be taken three ways —
  1. **In-app**, live, by a logged-in learner, through a full quiz-taking player: question navigation
     (prev/next/flag/jump), a countdown or elapsed timer with auto-submit on timeout, and per-type
     answer controls.
  2. **Manual/offline entry** — a proctor or trainer records the outcome of a paper/in-person exam
     directly, for audiences who never touch the system live.
  3. **Via a tokenized public link** — a one-time access link (no login) that opens the same
     assessment content in a lightweight standalone player; ideal for external candidates or anyone
     without an in-app account.
- **Scoring**: objective answers are auto-graded on submit against the defined correct answer; a
  pass/fail outcome is computed against a configurable pass-threshold percentage.
- **Manual grading**: short-answer/free-text questions marked "requires manual evaluation" are held in
  a visible **pending-review** state (with a dedicated stat tile and per-row badge in the Assessment
  Attempts screen) until a human grades them through an in-app grading UI (mark correct/incorrect +
  assign marks per question), after which the same scoring/pass-threshold/skill-upgrade logic re-runs.
- **Assessment Assignment lifecycle**: formally assign an assessment to an employee with a due date
  (Assigned → In Progress → Completed/Skipped/Missed); completion resolves automatically when a
  matching attempt is submitted or graded; skipping requires a documented reason; overdue assignments
  can be swept to "Missed" in bulk.
- **AI-assisted question generation / AI-assisted subjective grading** — architected as pluggable
  extension points today; see §7 for current status.

### 2.6 Feedback & Satisfaction Surveys
- Trainer/programme satisfaction feedback is delivered through GB5's shared Feedback/Learning-Survey
  (FLS) engine — the same generic, configurable survey-rendering pipeline used platform-wide, not a
  TMS-specific form renderer.
- Dispatch to every enrolled learner in a batch with one action; live status tracking (Not
  Started/Opened/In Progress/Submitted/Expired/Opted Out) and one-click nudging of anyone who hasn't
  responded.
- **Aggregated Trainer Rating** — per-trainer average scores across dimensions (knowledge, clarity,
  engagement) and overall completion rate, for a chosen period.
- Feedback response is trackable as an optional gate on certificate issuance (see §2.8's caveat on
  current enforcement status).

### 2.7 Training Effectiveness Evaluation (Kirkpatrick Model)
- A distinct, more rigorous evaluation track from day-to-day satisfaction feedback: supports all four
  Kirkpatrick levels — Reaction, Learning, Behaviour, Results.
- **Evaluation Plan** — defines the level, target audience, trigger (on completion / scheduled date /
  manual), and follow-up window (immediate, or 30/90/180/365 days later — critical for Behaviour/Results
  evaluations that must be measured well after training ends).
- **Evaluation Template** — a versioned question set per plan.
- **Evaluation Instance** — the actual dispatch to a respondent, with its own status lifecycle (Pending
  → Sent → Completed, or Overdue/Cancelled), including response-count and average-score visibility.
- **Evaluation Insight** — a dedicated space for HR/L&D to author a written synthesis over a cohort of
  responses, explicitly intended to drive downstream action (programme revisions, further skill-gap
  analysis, follow-up training).

### 2.8 Certification Management
- Issue, track, renew, and revoke training certificates, each with a status (Active/Expired/
  Revoked/Renewal-In-Progress).
- **Tamper-evident**: every issued certificate carries a detached digital signature (SHA-256 hash +
  RSA signature) and a QR-coded verification token.
- **Public verification** — anyone (no login) can scan/visit the verification link and get a live
  Valid/Revoked/Expired/Active status straight from GB5, independent of the physical/PDF document.
- **Renewal** never edits a certificate in place — it always mints a new certificate record (new number,
  new expiry) linked back to the same underlying completion, and re-runs the full signing pipeline; the
  prior certificate is marked renewed, not deleted.
- **Revocation** is a one-way action requiring a documented reason; revoked certificates can never be
  renewed.
- Scheduled renewal/expiry alerting is modeled (reminder / expiry-warning / expired-notice, across
  Email/In-App/SMS/All channels) — **[Internal only]** no automated scheduler currently dispatches these
  alerts; treat as a manually-logged mechanism today, not a live automated reminder pipeline, until a
  scheduler is wired up.
- **[Internal only]** the "block certificate until feedback submitted" flag is tracked and surfaced in
  feedback status reporting, but is not yet enforced inside the certificate-issuance code path — do not
  represent this as an enforced gate to customers yet.

### 2.9 Automatic Skill-Level Upgrades (flagship cross-module integration)
- When an employee **passes a mapped assessment** or **completes a mapped programme with a pass
  outcome**, GB5 automatically checks the programme/assessment's Skill Map (§2.2) and either:
  - **Auto-approves** the skill-level upgrade immediately (if the mapping is configured for
    auto-approval), or
  - Raises a **Skill Upgrade Proposal** for human review.
- A dedicated **Skill Upgrade Review** queue lets a manager or skill-owner approve or reject each
  proposal with remarks.
- On approval (automatic or manual), GB5 publishes a real-time event that the Skill Management module
  consumes to update the employee's actual recorded skill level — closing the loop from "training
  happened" to "the organization's skills record is current" without manual data re-entry.
- Every proposal, approval, and rejection is written to the audit/event log for traceability.

### 2.10 Master Data
- **Training Domains** (12 seeded: Production, Quality, Maintenance, Safety, HR, Finance, IT Systems,
  Commercial, Admin, Cross-Functional, Product Knowledge, R&D Engineering).
- **Training Venues** (Training Room, Conference Room, Shop Floor, Dojo Station, Virtual, External),
  each typed for capacity/logistics planning.
- **External Vendor Register** (Training Provider, Certifier, Consultant, LMS Provider, MOOC).
- **Trainer Directory** — internal (employee-linked) or external (vendor-linked) trainer profiles.

### 2.11 Dashboards & Personal Portals
- **"My Learning" Learner Portal** — an employee's personal home for training: active enrollments,
  active certificates, year-to-date summary, training schedule, certificate wallet, and full training
  history.
- **Trainer Dashboard** — today's sessions, upcoming sessions, active training instances, session
  history, attendance summaries, and the trainer's own aggregated rating.
- **L&D / HR Leadership "Plan vs Actual" Dashboard** — enrollment funnel, domain-wise completion,
  trainer workload, expiring-certificate watchlist, open training needs, programme performance, and a
  Gantt-style plan-vs-actual timeline per associate.
- **HR Training Operations KPI cards** — 11 KPIs posted nightly into GB5's shared KPI dashboard
  framework for HR leadership: Compliance Coverage %, Nomination Approval Turnaround (days), Cost per
  Trained Employee, Venue Utilization %, Assessment Pass Rate %, First-Attempt Pass Rate %, Skill
  Upgrade Approval Rate %, Certificate Renewal Compliance %, Expiring Certificates (30-day window),
  Feedback Response Rate %, and Learning Gain %.

### 2.12 Reporting
- **Training Compliance Coverage Register** — per mandatory training need: target vs. actual headcount
  coverage, deadline, overdue flag.
- **Training Compliance Coverage Summary** — the same metric rolled up by training domain.
- **Nomination Approval SLA Register** — per enrollment: how long nomination spent at each approval
  step, current bottleneck owner, days in current step — a direct tool for spotting where approvals are
  stalling.
- All three reports respect the same role-based record/date-range limits as GB5's other reports (no
  bypassing FE-enforced limits via direct API access).

### 2.13 Unified Respond Experience (delivery infrastructure)
- One shared "open a link, answer it, submit it" experience serves **both** TMS Assessment delivery and
  TMS/general Feedback delivery — plus, going forward, any other GB5 module that wants to deliver
  content via a tokenized link without building its own infrastructure.
- Works two ways: a public tokenized link (no login — ideal for external respondents or email/SMS
  distribution) or an authenticated **"My Pending Items"** self-service list for logged-in employees,
  which leads into the exact same respond experience.
- Native survey/feedback content renders through a generic, multi-question-type engine (rating,
  NPS, single/multi-choice, yes/no, free text) with section-by-section progress, auto-saved drafts, and
  a configurable thank-you message.
- Assessment content, delivered through the same link infrastructure, renders through its own
  purpose-built quiz UI instead — each content type owns its own rendering while sharing the link,
  reminder, and status-tracking plumbing underneath.

---

## 3. For Developers

- **Backend layout**: `GB5Solution/TMS/{TMSSL,TMSBLL,TMSDAL}` following the standard GB5 3-tier
  convention (FastEndpoints / BLL / Dapper). Hosted in `HRFinanceHost`. TMS calls into FLS's BLL
  interfaces directly (in-process DI, not HTTP) for token/link lifecycle — see
  `AssessmentFlsBridge`/`FeedBack` areas.
- **Frontend layout**: `gb4.7mfe/projects/training/**` for authenticated, in-app TMS screens;
  `features/gbfls/**` + `features/gbsurvey/**` for the shared respond experience (including the
  `FLS_BRIDGE_REGISTRY` extension point at `features/gbsurvey/bridge/fls-bridge-registry.ts`);
  `features/gbtmsfeedback/**` exists as an alternate feedback-UI component set but is currently
  unwired (see §7).
- **Extending the respond pipeline for a new content type**: (1) tag your module's FLS respondent rows
  with your own `SourceObjectTypeId`; (2) expose a token-keyed fetch/submit endpoint pair; (3) add one
  entry to `FLS_BRIDGE_REGISTRY`. No changes to the shared shell component are required.
- **Known architectural quirks worth knowing before touching this code**:
  - `TrainingProgram` (singular) is separate, near-dead code shadowing the real `TrainingProgramme`
    (plural) — its BLL interface has zero methods. Don't build on it; treat `TrainingProgramme` as
    authoritative.
  - The nightly KPI-posting job computes TMS's 11 KPIs directly against TMS's own tables, bypassing the
    generic Finance-oriented BI/KPI evaluation engine — this was a deliberate choice, not an oversight.
  - `tmsscheduledashboard`'s production/federated route resolution currently points at a `tms` remote
    that doesn't exist (the component actually lives in the `training` remote) — works in local/dev
    builds only; will fail to load in a true federated deployment until the routing entry is corrected.
  - `LearnerPortalComponent` currently has a hardcoded test `EmployeeId` rather than reading the logged-in
    user — fix before any real user-facing demo or release.

---

## 4. For Implementers / Admins — What's Configurable

Configurable today through the TMS UI: Training Domains, Venues, External Vendors, Trainer Profiles,
full Programme authoring (identity/scope/sessions/topics/prerequisites/skill map/competency map),
Session/Assessment authoring (Simple or Structured/Paper), Evaluation Plans, Training Needs, Training
Instances/scheduling, and feedback dispatch configuration.

Exists in the data model but has **no dedicated admin screen yet**: the Question Bank can only be
populated indirectly through picklists inside assessment authoring — there is no standalone
"manage my question bank" screen today. Plan implementation timelines accordingly if a client wants to
pre-load a large question bank independently of building assessments one at a time.

Hardcoded (not admin-configurable via UI): question-type taxonomy, assessment/certificate/enrollment
status enumerations, and the FLS bridge's content-type registry — these are code-level constants,
changed only by a developer.

---

## 5. For End Users — Roles & Journeys

- **Learner**: nominate for programmes from the catalogue (or get nominated), track approval status,
  attend and get marked present, take assessments (timed, auto-graded, with a results/score breakdown
  on reopening a completed attempt), respond to feedback surveys and evaluations via a link or the
  in-app "My Pending Items" list, view and download certificates, and see everything in one "My
  Learning" home.
- **Trainer**: see today's and upcoming sessions, mark attendance, review assessment attempts including
  grading pending manual-review responses, see personal rating feedback.
- **Manager**: approve/reject nominations from their team, review and approve/reject automatic
  skill-upgrade proposals for their reports.
- **HR / L&D Admin**: design curriculum, schedule instances, manage the full enrollment/approval
  pipeline, run compliance and SLA reports, monitor the leadership Plan-vs-Actual dashboard and the
  nightly-posted KPI cards, issue/renew/revoke certificates, dispatch and monitor feedback.

---

## 6. For Marketing / Sales

Lead with what's real, working, and differentiated:
- A genuinely end-to-end L&D platform — need, curriculum, delivery, enrollment (with approval workflow
  and waitlisting), assessment (timed, auto-graded, with manual-grading fallback), feedback, and
  tamper-evident certification with public QR verification — in one connected system, not point tools
  stitched together.
- **Automatic skill-record upgrades on training success** is the standout, hard-to-copy capability:
  training outcomes flow straight into the organization's live skills record, with human review where
  it matters.
- A flexible delivery model: the same assessment or feedback survey can reach a logged-in employee
  in-app or an external/offline respondent via a simple link — no separate tooling needed for either
  audience.
- Real-time operational visibility: a personal learner portal, a trainer's daily view, and an HR
  leadership dashboard with 11 posted KPIs, all drawn from the same live data.
- **Do not yet promise**: AI-generated assessment questions or AI-graded subjective answers (both are
  wired for a future upgrade but currently no-ops), automatic feedback-blocks-certificate enforcement,
  or automated certificate-renewal reminders — see §7 for accurate current status of each.

---

## 7. Known Gaps / Roadmap Items — [Internal only, not for marketing]

| Area | Status |
|---|---|
| AI question generation | Endpoint and extension point exist; default implementation returns nothing. No real AI wired in yet. |
| AI subjective-answer grading | Same — extension point exists, default is a no-op; manual grading UI is the real path today. |
| LMS Bridge | Metadata/mapping table only; no actual sync engine to a real external LMS exists yet. |
| Certificate renewal/expiry alerts | Data model + log table exist; no scheduler currently dispatches them automatically. |
| Feedback-blocks-certificate gate | Tracked and shown in status reporting; not yet enforced in the certificate-issuance code path. |
| Training-need auto-raise from Skill Gap/Appraisal/OKR | **Partially resolved 2026-08-20.** The generalized receiving mechanism (`ITrainingNeedBLL.ProposeTrainingNeed`) is built and one real producer is wired end-to-end (Work Instruction's Skill Gap → `wi.skillgap.detected` → `WiSkillGapSubscriber` → `TSKILLGAPLINK` → auto-raised need), but no FE button triggers it yet (API-only today) and it isn't browser/live-verified. Appraisal/OKR/RCA-CAPA/etc. still have no producing logic anywhere — they'd need their own gap-detection + event-publish built first. Also requires the tenant to have configured at least one `MTRAININGDOMAIN` row. |
| Question Bank admin screen | Full CRUD component exists in code but has no menu entry — currently unreachable by any user. |
| Trainer Portal ("today's sessions" standalone view), generic per-response CRUD screen | Built and even packaged for deployment, but have no menu wiring — unreachable today. |
| `features/gbtmsfeedback` component set (batch panel / learner history / trainer rating card) | Fully built, backend-integrated, but not plugged into any reachable screen — the live batch-feedback experience today runs through Training Instance's own inline panel instead. |
| Assessment Assignment "Missed" sweep | Exists as an endpoint; not on a schedule — must be triggered manually/externally today. |
| KPI card OU-access bug (gap #5, TMS KPI dashboard) | Root-caused and fixed in code (`GetKPIValues`'s whole-org sentinel handling), pushed 2026-08-18; **not yet live/browser-verified** on GB5DEMO — confirm before treating this as fully closed. |
| `tmsscheduledashboard` federation routing | Works in local/dev builds; the production module-federation route entry points at a remote that doesn't exist — needs a routing fix before relying on this dashboard in a federated deployment. |
| Learner Portal identity | Currently shows a hardcoded test employee's data instead of the logged-in user's — must be fixed before customer-facing use. |
| `TrainingProgram` (singular) legacy code | Dead/shadow code next to the real `TrainingProgramme` (plural); recommend removal or at least developer-facing clarification. |

---

*Compiled 2026-08-18 from direct code inspection of `gbBE/gb5` (`GB5Solution/TMS`, `GB5Solution/FLS`) and
`gb/gb4.7mfe` (`projects/training`, `features/gbfls`, `features/gbsurvey`, `features/gbtmsfeedback`).
Re-verify against current code before reuse if significant time has passed — several items in §7 are
mid-remediation and may have changed.*