# Work Instruction (WI) — Feature & Functionality Guide

**Purpose of this document:** a single, code-grounded source of truth for everything the **Work
Instruction (WI)** module 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/WorkInstruction`) and frontend (`gb4.7mfe/projects/workinstruction`) code as of
2026-08-20. Sections marked **[Internal only — not for marketing]** describe known gaps and should
not appear in customer-facing material.

**Module boundary:** Work Instruction is a standalone 3-tier module
(`WiSL`/`WiBLL`/`WiDAL`), architecturally separate from the **Skill Management** module
(`SkillManagementSL`/`BLL`/`DAL`) — separate backend project tree, separate Angular federation
frontend project. The two integrate, but do not share code: WI *reads* Skill Management's skill and
employee-skill data (querying the same underlying tables directly, not via an API call) to gate
execution and compute skill gaps. Skill/role taxonomy, employee skill profiles, manual assessment,
and the Skill Matrix all live in the separate **Skill Management** module — see
`Docs/SkillManagement-Feature-Functionality-Guide.md` for that side. TMS's training/assessment
functionality (which feeds Skill Management, not WI directly) is documented in
`Docs/TMS-Feature-Functionality-Guide.md`.

---

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

GB5 Work Instruction turns static "how-to" documents into a governed, versioned, and — critically —
**enforced** digital work instruction platform. Instructions are authored through a full hierarchy
(process → sub-process → section → step → step content) and governed by a formal
Draft→Review→Approve→Publish→Archive workflow with **append-only version history**: every change is
permanently snapshotted, so a manufacturer can prove exactly what instruction, at what revision, an
operator was following on any given day.

What makes WI more than a document viewer is its integration with Skill Management: a Work
Instruction can attach required skills to a specific step or operation, each with a configurable
**Log / Warn / Block** enforcement level, and execution can be refused outright for an
under-qualified operator — a real shop-floor safety control, not just a report. Add QR-code
identification at every point of use (workstation, employee badge, work order), a full
roster-and-shift-staffing system with skill-gap analysis, and a visual **Line Digital Twin / Plant
Overview** showing live staffing and skill readiness per line and across the whole site, and WI
becomes the operational backbone connecting "what needs to be done," "who's qualified to do it,"
and "did they actually do it, correctly, and on time."

---

## 2. Functional Area Catalog

### 2.1 Work Instruction Authoring & Governance
- Full Work Instruction authoring: process → sub-process → section → step → step content
  hierarchy, including per-step attached content and checklists.
- **Formal governance workflow**: Draft → In Review → Approved → Published → Archived, with illegal
  transitions rejected outright (e.g., a Work Instruction still in Draft cannot be published).
- **Append-only version history** — every status transition snapshots the full Work Instruction
  state as a permanent version record. Version history can never be deleted by design (a hard
  system rule, enforced in code) — this is the audit backbone for regulated environments that must
  prove which instruction revision was live on any given date.
- **Version Compare** — a side-by-side UI to see exactly what changed between two versions of a
  Work Instruction.
- **Step Checklists** — per-employee, per-step checklist responses are persisted (currently
  current-state only; see §7 for a versioning caveat).

### 2.2 Workstation & Production Line Master Data
- **Workstation** and **Workstation Config** — master data for physical workstations, including
  per-workstation display configuration (font scale, display mode: kiosk / tablet / dual-monitor) —
  built for shop-floor screens, not just office use. The Workstation Display Screen now actually
  applies this configuration (font scale, layout, step/cycle timer visibility) per workstation —
  fixed 2026-08-20; before that date the setting was fully configurable but silently ignored by the
  display screen itself.
- **Production Line** and **Line–Station Map** — defines which workstations belong to which
  production line, and in what sequence.

### 2.3 Skill/Competency Requirements & Eligibility
- **WI Skill/Competency Requirement** — attach required skills (and, where available, competencies)
  to a specific Work Instruction, each with an **Enforcement level: Log, Warn, or Block**.
- **Eligibility Evaluation** — given an employee and a Work Instruction, GB5 computes whether that
  employee is cleared to execute it: a `Block`-level unmet skill requirement makes them ineligible;
  `Warn`/`Log`-level gaps are surfaced but never stop execution.
- This feature reads employee skill levels directly from the Skill Management module's data (see
  `Docs/SkillManagement-Feature-Functionality-Guide.md`) — it is the mechanism that turns skill data
  from a report into an actual shop-floor safety control.

### 2.4 Scan-Code / QR Verification
- Any Work Instruction, workstation, employee badge, or work-order-detail can generate a scannable
  QR code for fast, error-free identification at the point of use — no typing IDs on a shop floor.
- Four distinct scan surfaces are provided: per-Work-Instruction, per-workstation, per-employee
  (badge/entry card), and per-work-order-detail — covering the common shop-floor "scan in" moments
  (operator badge-in at a station, work-order pickup, WI lookup).
- **Unified verify-on-scan** (added 2026-08-20): scanning any of the four code types now returns a
  single, real valid/invalid result from one endpoint (`VerifyScan`) — a Workstation/Employee scan
  checks for a real current assignment, a Work Instruction scan checks it's actually Published (not
  Draft/Archived), and a Work-Order-Detail scan checks the work order isn't cancelled/closed. All
  four scan screens now support live camera/hardware-scanner input, not just QR generation.

### 2.5 Roster & Shift Staffing
- **Line Shift Roster** — plan and confirm who's working which line on which shift, with a
  Planned-vs-Actual distinction (a forecast roster can never be directly "confirmed" — only an
  Actual roster can, preventing a planning artifact from being mistaken for a confirmed schedule).
- **Copy-Forward** — clone a prior roster into a new date in one action (with absences correctly
  reset, not carried forward).
- **Line Shift Staffing** — assign specific employees to specific workstations for a shift, with
  guardrails against double-assigning a workstation to two active operators at once.
- **Mark Absent / Replacement** — record an absence and, in the same action, name the replacement
  operator — a real shift-management workflow, not just a status flag.
- **Line–Operation Map & Staffing Gap** — maps operations to lines and computes where a shift is
  under-staffed relative to what the line's operations require.
- **Planned vs. Actual** reporting for shift-level accountability.

### 2.6 Skill Gap Analysis, Digital Twin & Plant Overview
- **Skill Gap for Roster** — for a given roster (a real, planned or actual shift), computes each
  assigned employee's gap against the skill requirements of the workstations/Work Instructions
  they're assigned to — turning "who's on shift" and "what does this line need" into a single
  readiness report. Draws on employee skill levels from Skill Management.
- **Line Digital Twin** — a visual, per-line, per-workstation live view: which stations are staffed,
  by whom, and whether that person is fully qualified — a shop-floor situational-awareness screen,
  not a static org chart. As of 2026-08-20 this is genuinely push-based: a SignalR hub notifies the
  open screen the instant a relevant staffing, allocation, or execution-status change happens,
  rather than requiring a manual refresh.
- **Plant Overview** — the same concept rolled up across every line in the plant, for a
  site-leadership-level view of overall staffing/skill readiness.
- This is the newest and most visually distinctive part of the platform — see §7 for its rollout
  status.
- **Raise Training Needs for Gaps (added 2026-08-20)** — a deliberately-triggered action
  (`POST /Wi/RaiseTrainingNeedsForRosterGaps`), separate from the read-only gap report above so
  viewing the screen never itself spams Training Need creation: recomputes the roster's skill gap
  and publishes one `wi.skillgap.detected` Dapr event per employee/skill pairing with a Warn or
  Block enforcement gap (Log-enforcement gaps are skipped — lowest signal, never blocks execution
  anyway). TMS subscribes and auto-raises a Training Need for High/Critical-severity gaps — see the
  Skill Management guide's §2.7 for the full producer/consumer mechanics. Backend-complete; no
  frontend button wired to it yet (see §7).

### 2.7 Work Instruction Assignment, Execution & Acknowledgement
- **Assignment resolution** — Work Instructions can be assigned/resolved by entity, by workstation,
  or by employee, with a specificity-based resolution so the most relevant instruction wins when
  several could apply.
- **Acknowledgement gate** — an employee can be required to acknowledge (read/understand) a Work
  Instruction before execution is allowed to start.
- **Execution gating on start** — starting execution runs through a defined sequence of checks:
  a real, valid work order reference (if supplied); acknowledgement completed; no unmet
  `Block`-level skill requirement (execution is refused outright, with the specific missing skills
  named, if one exists); only then does the execution record get created.
- **Step-by-step execution tracking** — every active step gets its own trackable execution record
  from the moment execution starts, so step-level completion (and, downstream, time-study data) is
  always capturable, never inferred after the fact.
- This gating sequence is where the module stops being a passive document viewer and becomes an
  active control: an under-skilled operator is stopped at the point of execution, not flagged in a
  report the next day.

### 2.8 Analytics
- **Compliance Summary**, **Execution History**, and **Time Study Summary** endpoints provide the
  data backbone for reporting on Work Instruction adoption, execution patterns, and time-per-step.
- A dedicated **WI Analytics** screen (added 2026-08-20) consumes all three: a compliance-rate chart
  and per-WI summary tiles, a Std/Avg/Max time-study comparison chart per step, and a raw execution
  history table — filterable by Work Instruction and date range.

### 2.9 Master Data Summary
Workstation, Workstation Config, Production Line, Line–Station Map, Line–Operation Map — all
standard admin-configurable CRUD screens with grid + form + select-list support. (Skill/role/employee
skill master data lives in the separate Skill Management module.)

---

## 3. For Developers

- **Backend layout**: `GB5Solution/WorkInstruction/{WiSL,WiBLL,WiDAL}`, the standard GB5 3-tier
  convention (FastEndpoints / BLL / Dapper).
- **Dependency on Skill Management, not a call into it**: WI's eligibility evaluation and skill-gap
  computation query `MEMPLOYEESKILLPROFILE`/`MSKILL`/`MSKILLLEVEL`/etc. directly — there is no
  service call from `WiBLL`/`WiDAL` into `SkillManagementSL`. Both modules read the same underlying
  tables. Any schema change to employee skill data must be coordinated across both codebases even
  though there's no compile-time dependency forcing that.
- **Enforcement enum**: `WiDAL/DTO/Wi/WiEnums.cs` defines `Enforcement: Log=0, Warn=1, Block=2`.
  A Designer-UI/backend numbering mismatch on this exact enum caused a real safety-relevant bug
  (Block silently read back as Warn) — fixed 2026-08-15, see §7. Double-check any new UI touching
  this enum uses the same numbering as the backend, not a re-derived one.
- **Execution gating**: `WiExecutionBLL.StartExecution` runs an explicit, numbered gate sequence
  (work-order validity → acknowledgement → Block-skill check → execution+step-row creation) with
  AutoNumber rollback on failure. Read the gate comments in that method before modifying it — two
  of the four gates were added as fixes for real bugs (unchecked work order reference, missing
  step-row seeding) rather than being there from the start.
- **Scan-code generation is generic, verification is unified** (as of 2026-08-20): QR generation is
  still a single, shared BLL method (`WiScanCodeBLL.GenerateScanCode`) used for all four scan
  surfaces, but there is now a dedicated `WiScanCodeBLL.VerifyScan`/`POST /Wi/VerifyScan` that parses
  the `{Prefix}:{EntityId}` payload server-side and dispatches to the right check per type
  (`ResolveForWorkstation` for `WS:`, `GetCurrentAssignmentForEmployee` for `EMP:`, a `WiStatus ==
  Published` check for `WI:`, a `TINDENT.STATUS <> 2` check for `WOD:`), returning one uniform
  `WiScanVerifyResultDTO { IsValid, EntityType, EntityId, Message, Data }`. FE scan cards
  (`workstationscancard`, `employeeentrycard`, `wiscancode`, `workorderdetailscancode`) all call this
  one endpoint now instead of each doing its own client-side prefix parsing.
- **SignalR hub added 2026-08-20**: `WiSL/EndPoints/Hubs/WiHub.cs` (`/hubs/wi`), following the same
  BLL-decoupled `IHubContext` pattern as DXP (`IWiHubNotifier` in `WiBLL/Common`, concrete
  `WiHubNotifier` in `WiSL`, registered singleton in `WiModule.cs`) — not CollabHub's direct-push
  style, since BLL must stay ASP.NET-free. Wired into `WiExecutionBLL` (Start/CompleteStep/
  CompleteExecution), `LineRosterBLL` (staffing saves/absences), and
  `LineProductionPlanAllocationBLL` (save/delete). FE consumes it in `linedigitaltwin` and
  `workstationdisplayscreen` only — the scan-code generation screens deliberately stay poll-free/
  push-free since generating a QR is a one-shot action, not a live dashboard.
- **Outbound cross-module event added 2026-08-20**: `WiSkillGapBLL.RaiseTrainingNeedsForRosterGaps`
  injects `DaprClient` directly (same constructor-injection pattern as
  `TxSkillUpgradeBLL` in TMS) and publishes topic `wi.skillgap.detected` on component `"pubsub"` —
  the first outbound Dapr event this module has ever published (previously WI only *read* Skill
  Management's tables; it had no producer-side event of its own). Payload carries no PII beyond
  EmployeeId/SkillId/levels needed for TMS to act, plus the standard `TenantId`/`DatabaseName`/
  `ClientId`/`UserId` tuple every cross-service GB5 event includes so the subscriber can reconstruct
  a `LoginDTO`. Non-fatal per-event try/catch, same as every other Dapr publish in this codebase.
- **Frontend layout**: `gb4.7mfe/projects/workinstruction/**`, an Angular native-federation
  micro-frontend with an intentionally empty `app.routes.ts` — routing is resolved by the host shell
  from `MWEBFORM.WEBFORMSECONDURL` menu rows at runtime, not by an Angular router config in the
  sub-app. A component only becomes reachable once its `MMENU`/`MWEBFORM` rows exist — several
  genuine "built but unreachable" gaps have come from this exact pattern (see §7). Its
  `federation.config.js` exposes 21 named components matching the feature areas in this document.

---

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

Configurable today through the UI: Workstation and Workstation Config (including kiosk/tablet
display mode), Production Lines and Line–Station mapping, WI Skill/Competency Requirements and their
enforcement level, Line Shift Roster and Staffing, and full Work Instruction authoring end-to-end
(process/sub-process/section/step/content/checklist).

**Enforcement level is the key configuration decision for any go-live**: every WI Skill/Competency
Requirement has a Log/Warn/Block setting. Implementers should walk through this deliberately per
client — Block is a hard execution gate (operators will be stopped mid-workflow), so it should be
rolled out only where the skill requirement is genuinely non-negotiable; Warn/Log are the safer
default while a client's skill data is still being populated and verified in the companion Skill
Management module.

**Competency requirements exist as a configuration field today but cannot be evaluated** — there is
no employee-competency data source anywhere in the system yet, so any Competency Requirement will
always report as "Unverifiable," never as met or unmet. Do not configure Competency Requirements as
if they will gate execution — only Skill Requirements do that today.

**Prerequisite**: Skill Management's taxonomy, role requirements, and employee skill profiles must
be populated *before* configuring WI enforcement rules — WI eligibility checks read that data
directly and will simply find nothing if it hasn't been set up yet.

**Menu wiring is a real go-live checklist item, not a formality**, in this module specifically:
several fully-built features (Line Digital Twin/Plant Overview, fixed 2026-08-19; WI Analytics,
fixed 2026-08-20) had zero navigable menu entry for a period after the backend/frontend code was
complete. Before any client demo or go-live, confirm every feature the client expects to see
actually has a working `MMENU`/`MWEBFORM` row — don't assume "it's in the codebase" means "a user
can reach it."

**Workstation Config now visibly matters**: setting Display Mode (Kiosk/Twin-Monitor/Tablet/Single),
Font Scale, and step/cycle timer visibility on a workstation's config actually changes what that
workstation's Display Screen renders, as of 2026-08-20. Before that date this configuration was
silently ignored by the display screen — if a client configured it earlier and didn't see any
visual change, that was a real gap, not a misconfiguration on their part.

---

## 5. For End Users — Roles & Journeys

- **Operator / Shop-floor employee**: scan in at a workstation or badge-scan for identification;
  acknowledge the Work Instruction assigned to their station; get stopped (or warned) at execution
  start if they're missing a required skill; step through the Work Instruction with checklist
  responses.
- **Line Supervisor / Team Lead**: plan and confirm shift rosters, assign staffing to workstations,
  mark and replace absences, check the Skill Gap for Roster report before a shift starts, and use the
  Line Digital Twin to see live station coverage.
- **Plant / Operations Leadership**: use the Plant Overview for a site-wide staffing/skill readiness
  view, and Compliance/Execution-History analytics for adoption and process monitoring.
- **Work Instruction Author / Quality**: author and govern Work Instructions through the full
  Draft→Review→Approve→Publish→Archive workflow, using Version Compare to audit exactly what
  changed and when.

---

## 6. For Marketing / Sales

Lead with what's real, working, and differentiated:
- Work Instructions here aren't a static document viewer — they're an **active execution control**:
  a Work Instruction can refuse to start for an under-skilled operator, with a configurable
  Log/Warn/Block enforcement level per requirement, so a client can dial in exactly how strict to be
  as their skill data matures.
- **QR/scan-code identification** at every point of use (workstation, badge, work order, Work
  Instruction) — designed for real shop-floor conditions, not office data entry.
- **Live, genuinely push-based Line Digital Twin and Plant Overview** — a visual staffing and
  skill-readiness view per line and across the whole plant that updates the instant something
  changes on the shop floor (SignalR push, added 2026-08-20), not a static org chart, not a screen
  that needs refreshing.
- **Scan-and-verify at every point of use** — workstation, employee badge, Work Instruction, and
  work-order QR codes all resolve to a real, instant valid/invalid result through one unified check,
  not just an ID lookup.
- **Analytics out of the box** — compliance rate, execution history, and time-study (standard vs.
  actual duration per step) reporting for Work Instruction adoption and process performance.
- **Append-only version history** with side-by-side compare — a genuine audit backbone for
  regulated manufacturing (automotive, medical device, aerospace, food/pharma) that must prove what
  instruction revision was in force on any given day.
- A full shift-management layer (roster, staffing, absence/replacement, staffing-gap detection)
  built specifically around production lines, not a generic scheduling tool retrofitted to
  manufacturing.
- **Do not yet promise**: skill-gated Competency Requirements (data field exists, cannot yet be
  evaluated), or versioned checklist-response history — see §7 for accurate current status of each.

---

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

| Area | Status |
|---|---|
| Competency-based eligibility | Data model and UI field exist, but there is no employee-competency data source anywhere in the system — every Competency Requirement evaluates as "Unverifiable," never met/unmet. This is a real, by-design gap, not a bug. |
| Enforcement numbering (Log/Warn/Block) | Designer-UI picklist and backend enum previously used different numeric codings, silently inverting Block↔Warn on a safety-relevant field. Fixed in code 2026-08-15 with a one-time data remap; verify any custom reports/exports built before that date against the corrected values. |
| Line Digital Twin / Plant Overview menu wiring | Backend and FE existed, but had **zero** navigable menu entry until 2026-08-19 — genuinely unreachable by any user before that date. Confirm this is live-verified in your target environment before demoing. |
| Checklist response versioning | Step checklist responses are persisted as current-state only; there is no version/history table analogous to the Work Instruction version-history mechanism (§2.1). A checklist re-save overwrites, it does not append. |
| Real-time/push infrastructure | **RESOLVED 2026-08-20.** `WiHub` (`/hubs/wi`) + `IWiHubNotifier`/`WiHubNotifier` added, wired into `WiExecutionBLL`/`LineRosterBLL`/`LineProductionPlanAllocationBLL`; FE consumes it in Line Digital Twin/Plant Overview and Workstation Display Screen. Live-verified: the hub negotiates correctly and offers LongPolling (required — the custom `Login` header doesn't survive a WebSocket handshake in this codebase). A full trigger→push→FE-refresh round trip was code-reviewed but not exercised with a live browser/WebSocket client this round — confirm that specifically before a client demo. Scan-code generation screens deliberately remain poll-free/push-free (one-shot actions, not dashboards). |
| WI Analytics UI coverage | **RESOLVED 2026-08-20.** New `wianalytics` screen (Compliance Summary chart+tiles, Time Study Std/Avg/Max chart, Execution History table) consumes all three endpoints, with a real seeded menu entry. A genuine routing bug was fixed along the way: `wi.ts` had mapped the 3 analytics keys to `/wi/Analytics/...`, but the real route is `/WiAnalytics/...` (no `wi` segment) — would have 404'd if ever called. Endpoints return unbounded `IEnumerable<T>` (no server-side paging) — fine for typical date ranges, but a very large range on Execution History could return a lot of rows client-side; not re-architected into `BaseReportEndpoint` this round. |
| Scan-code "verify on scan" logic | **RESOLVED 2026-08-20.** New unified `POST /Wi/VerifyScan` — Workstation/Employee checks reuse the existing assignment-resolution logic (now with a real client), a Work Instruction scan is valid only if `WiStatus == Published`, and a Work-Order-Detail scan is valid if the parent `TINDENT.STATUS <> 2` (open/not cancelled). All four scan screens now do real camera/hardware-scanner verification, not just generation; the two that already had scan input (Workstation, Employee) were refactored off their own client-side prefix parsing onto this one endpoint. |
| Cross-module data coupling | Eligibility and skill-gap features depend on Skill Management's schema with no compile-time enforcement of that dependency (both modules query the same tables independently). A schema change made only in Skill Management's codebase could silently break WI features — coordinate changes across both. |
| Skill-gap-driven Training Need creation | **Backend-complete 2026-08-20, no FE trigger yet.** `RaiseTrainingNeedsForRosterGaps` + `wi.skillgap.detected` + TMS's new `WiSkillGapSubscriber`/`ProposeTrainingNeed` are wired end-to-end and build clean, but there is no button/UI on the Skill Gap for Roster screen calling this endpoint — it's reachable only via direct API call today. Also depends on the receiving tenant having at least one `MTRAININGDOMAIN` row configured (see the TMS/Skill Management guides) or the auto-raise silently no-ops (non-fatally) on the TMS side. Not yet browser/live-verified. |

---

*Compiled from a live code audit of `GB5Solution/WorkInstruction` and
`gb4.7mfe/projects/workinstruction` on 2026-08-20, updated same day after the SignalR push, WI
Analytics screen, and unified scan-verify gaps were closed (see §7 — three rows marked RESOLVED
2026-08-20). See `Docs/SkillManagement-Feature-Functionality-Guide.md` for the companion module
supplying the skill/employee-skill data this module gates on, and `Docs/TMS-Feature-Functionality-
Guide.md` for the training/assessment side that feeds Skill Management. Re-verify dated items (§7)
against current code/DB state before relying on them in a live client conversation.*