Trained is not the same as qualified

Training records answer a question about the past: did this person finish this course? A qualification answers a question about now: may this person do this work today? The two come apart in ordinary ways. A course can be finished but the practical never observed. A forklift licence can lapse last week. A person can change job and still hold the old job's record. The module exists to keep the second question honest.

It replaces the learning-management and skills-matrix tools a business usually pays for. The specification names Cornerstone, Docebo, TalentLMS, LMS365, UL ComplianceWire, Vector LMS, AG5, Poka Skills, Workerbase and GembaDocs Skills Matrix, and the vendors describe what they do on their own pages ^[7]. The specification states the purpose in one sentence: prove that every person doing a job is trained and currently qualified for it.

What is in, and what is not

The module is wide enough to replace the tools above and narrow enough to leave people records and course authoring to the places built for them.

• In: skills, job roles and requirements by role, equipment or operation; assignments by trigger (new hire, role change, document revision, recertification, corrective action); SCORM 1.2 and 2004, xAPI, cmi5, video, document and quiz content, and instructor-led sessions; on-the-job training with practical assessment signed by an assessor; qualification status with expiry and the point-of-use check; the skills matrix with coverage and single-point-of-failure analytics.
• Out: HR employment records (M21). Course authoring tools: the module imports packages, and authoring stays external.

The standards, and what each one is used for

ISO 9001 clause 7.2 is the spine of the module. It asks an organisation to determine the competence people need, make sure they have it, evaluate whether the actions taken were effective, and keep documented evidence. Each of those four verbs becomes tables and rules in the module.

The statutory standards matter because they say who must be trained before doing the work. Powered industrial trucks ^[4] and lockout and tagout ^[5] are OSHA standards with their own training paragraphs, and NFPA 70E ^[6] covers electrical safety. Read the paragraph that applies to your work and copy its refresher rule into the skill's recert_months; do not rely on a rule of thumb. If you make regulated product, ISO 13485 ^[2] and 21 CFR 211.25 ^[3] add personnel qualification requirements.

Nine capabilities in three tiers

Each capability carries a tier. MVP must exist for a small or mid-size business to cancel the incumbent subscription with confidence. STD is parity with mainstream tools. BIC marks best-in-class differences. This course builds every MVP capability, and of the STD ones it builds the point-of-use check and the skills matrix (by area); content delivery (the SCORM, xAPI and cmi5 player) and instructor-led sessions are taught here and built later. BIC is advanced work.

Thirteen tables on the shared spine

Every table in the module starts with the standard columns every platform table has: id, tenant_id, created_at, created_by, updated_at, updated_by, row_version, archived_at and ext. The module has no people list, job list, machine list or file store of its own. It points at core_person, core_job_role, core_equipment, core_attachment and core_e_signature. Its own tables share the prefix trn_.

This course builds eight of them: trn_skill, trn_role_requirement, trn_course, trn_assignment, trn_completion, trn_practical_assessment, trn_qualification and trn_external_certificate. The other five are trn_curriculum and trn_curriculum_course (an ordered set of courses for a role), trn_ilt_session and trn_ilt_attendance (instructor-led sessions and their rosters) and trn_lrs_statement (a minimal xAPI record store). Add them later as a numbered migration. Types are written as in the specification: text, int, num (a decimal number), bool, ts (a timestamp with time zone), uuid and json; an arrow means a foreign key; req means required.

Skills and levels

A skill is a definition, not an event. category says what kind of skill it is, max_level says how many steps it has, recert_months says how long a qualification lasts before it must be renewed (empty means it does not expire) and evidence_type says what kind of proof the skill needs. Evidence type is the most important choice, because it decides what the module will accept: a course, on-the-job training observed by an assessor, an exam, an external certificate, or read-and-understood after a document changes. Skills-matrix vendors describe the same idea of levels and requirements on their own pages ^[1][2][3].

Requirements say who needs what

A requirement row ties a skill and a level to a job role, a machine or an operation, and says whether it is mandatory. At least one of the three targets must be set. A filler operator job role might need the filling skill at level 2; the filler itself might need lockout and tagout at level 1 for anyone who services it. The point-of-use check in chapter 4 reads these rows, so a machine with no requirement row is a machine the check cannot protect. The module lists such machines so the gap is visible.

Assignments by trigger

Nobody should have to remember to assign training. An assignment is created by an event, carries its reason and the id of what caused it, and has a due date. The module consumes three events from other modules: hr.job_assignment.changed (a new hire or a role change), doc.revision.effective (a revised procedure that people must read) and qms.capa_action.training_required (training demanded by a corrective action). A fourth trigger is the module's own clock: a qualification nearing its expiry gets a recertification assignment, or, when no course grants the skill (an external certificate), is listed for the administrator to renew. The module publishes trn.assignment.created and trn.assignment.completed in return.

• Idempotent. Running the assignment job twice must add nothing: a unique key on person, course, source type and source id stops a retry creating a second copy. Idempotent means that doing it again has the same result as doing it once.
• Overdue. An assignment still open after its due_at moves to overdue, and the person and their supervisor are told. Notifications that cost money, such as texts, are a separate choice made later.
• Waived, with approval. A waiver sets waived_by and waiver_reason after an approval. A waiver of a regulatory assignment, or by the person themselves, should be refused.

Course content and what it reports

Content comes in as packages. SCORM (Sharable Content Object Reference Model) is a packaging format that lets a course made in one tool run in any system that can launch it ^[1]. A SCORM 1.2 package reports cmi.core.lesson_status (passed, failed, completed and so on) and cmi.core.score.raw. A SCORM 2004 package reports cmi.completion_status, cmi.success_status and cmi.score.scaled. xAPI ^[2] is a newer standard in which the course sends statements of the form actor, verb, object and a result to a learning record store. cmi5 ^[3] is a launch profile on top of xAPI that says how a learning system starts a course and what it must receive. The specification names xAPI 1.0.3 and IEEE 9274.1.1-2023 (the IEEE standard for xAPI 2.0). Workerbase is one of the tools this module replaces, and its own page describes its worker training and qualification product ^[5].

Two rules keep completions honest. First, the server and not the browser decides passed: the player sends a score and the server compares it with the course's passing_score. Second, a document is acknowledged by signing: the person re-enters their password and a signature is created with the meaning acknowledged, tied to the course, version, person and time. A video, a quiz and a document are all course_type values; so are ilt (instructor-led) and ojt (on-the-job). Video completion tracking is only as good as what the player can report, so give the course a quiz where the evidence matters.

The practical assessment

For a hands-on skill the evidence is an observed demonstration. The assessor picks the person, the skill and the target level, and works through a checklist: a list of steps, each with a description, a mandatory flag, an observed yes or no and a note. The server, not the phone, sets the result: competent only when every mandatory step is observed. The module refuses an assessor who is the trainee, or who does not hold the skill above the target level (or at the skill's top level when the target is the top level) at that moment.

Both people sign, each re-entering their password: the trainee first with the meaning performed, then the assessor with the meaning verified. The assessor signs last, and the assessor's route records the completion after the second signature, because the trainee has no right to insert an on-the-job completion. Each signature stores a fingerprint (a hash) of the assessment's content, so a change to any checklist answer afterwards would no longer match. The assessment is then sealed: the database refuses any change except filling in the two signature ids. A signature is attributable, which is what auditors of regulated records look for ^[4].

From evidence to a qualification

A qualification is one row per person and skill. It holds the level, a status, when it was granted, when it expires, and the basis: what earned it. The four basis types are completion, assessment, external and grandfathered. A grandfathered qualification is a signed decision to accept existing experience, with a level, a reason and an expiry the business chooses, so the person is assessed before it runs out.

• A course grants the level the course says, but not above level 1 for a hands-on skill. If the skill's evidence type is ojt, a course shows someone was taught, not that they can do the work, so that level 1 is recorded as in_training; only an assessment or a signed grandfathered decision makes such a skill qualified.
• An assessment grants its target level only when the result is competent and both signatures are on the same fingerprint.
• An external certificate grants the skill's level until its own expiry, and the skill's evidence type must be external_certificate. The certificate's scan is the evidence; trn_external_certificate holds the issuer, number and dates (a forklift licence, OSHA 10 or 30, NFPA 70E).
• Expiry. Otherwise expires_at is qualified_at plus the skill's recert_months, and empty when there is none. qualified_at is the date of the evidence (the completion, the assessment or the certificate's issue date), not the day the row is written, so importing old records never moves an expiry forward. A housekeeping job moves lapsed rows to expired and tells the person and supervisor, but it is a convenience for reports. It must not be what protects the plant (chapter 4).
• Nothing is deleted. A supervisor can suspend a qualification and an administrator can revoke it with a reason; history stays in the completions, assessments and audit log. Events trn.qualification.granted and trn.qualification.expired are published for other modules.

Is this person qualified now?

The point-of-use check is one question from other modules: is person X currently qualified for operation or equipment Y? MES asks it before a step starts, CMMS before a work order is assigned, and a permit before it is issued. The answer is allow or deny with a reason in words, so the screen can say what is missing and who to ask.

A good implementation is a database function, for example trn_check_qualification(person_id, equipment_id, operation_ref), behind an API route used by the other modules. For each mandatory requirement on the machine or operation it returns the skill, the required level, the level held, allowed or not, and the reason. It denies when there is no qualification row, the status is anything but qualified, the level is too low, the expiry is not later than the database clock at that moment, the skill needs an external certificate and no unexpired one exists, or the person is not active. It fails closed: when it cannot be sure, it says no.

-- A sketch of the heart of the check (Postgres). Names are the module's; $1 is the person, $2 the machine.
-- It leaves out the is_active test and the external-certificate test that the text above lists.
select r.skill_id, r.required_level, q.level,
       coalesce((q.status = 'qualified' and q.level >= r.required_level
                 and (q.expires_at is null or q.expires_at > clock_timestamp())), false) as allowed
from trn_role_requirement r
left join trn_qualification q
  on q.skill_id = r.skill_id and q.person_id = $1 and q.tenant_id = r.tenant_id
where r.equipment_id = $2 and r.mandatory and r.archived_at is null;

The query reads the real clock when it runs (clock_timestamp(); in Postgres now() stays fixed for the whole transaction, so a test that waits inside one transaction would not see an expiry pass), so it needs no job to have run first. A person with no qualification row gets false from the coalesce, not an empty answer. That is the compliance rule in the specification: the qualification check must evaluate expiry at the moment of use, not from a cached nightly status. The definition of done is a test: the check denies a person whose qualification expired one minute ago.

The live skills matrix

The matrix is the same data seen across people instead of one person at a time: skills across, people down, the level held against the level required. Because it reads the live tables at a given time, it can show who is current, who expires within 30 days, who has expired and who is missing, for an area (and, once you add those views, a shift or a role). Vendors describe such matrices on their own pages ^[1][2][3]. Positions or skills with too few qualified people are the gaps, and a skill held by exactly one person is a single point of failure: if that person is away, the work stops.

Compute every figure from dates and rows at an as-at time, defaulting to now: expiry comes from expires_at, not from a stored expired status, and a row counts only when its status is qualified. A snapshot built overnight would make the matrix and the check disagree. The module's definition of done asks that matrix counts update in real time: grant a qualification, and the next read shows it.

Move the data, then retire the old tool

The migration note in the specification is short. Export training records and certificates from the incumbent as CSV and files; import them as completions with their original dates and evidence; and map legacy course codes to the new skills. Keep history as it was: never move a date forward to make a record look current, and never let an old record grant more than its evidence supports. A legacy classroom course for a hands-on skill maps to level 1 at most and is listed as needing an assessment. Everything already expired is flagged at once and gets a recertification assignment, or is listed for the administrator as a certificate to renew when no course grants the skill. Anyone who has done the work for years with no signed practical needs a grandfathered decision, signed and time-limited, so they are assessed before it expires.

Run old and new side by side for at least a week for one area, compare the counts, and explain every difference. A person the old tool called qualified and the new one blocks is the difference to understand first. Cancel the old subscription only after the cutover works and the export is stored, and record the saving from your invoices.