Step-by-Step: Mapping System Hooks
Hooks tell the engine which events count as evidence. Follow this precise sequence:
- Identify the Event: Navigate to System Hooks. In the WordPress Hook Name box, search for your trigger (e.g.
learndash_course_completed). - Label for the Builder: Enter a Friendly Label (e.g. "Health & Safety Exam"). This is what you will see when building logic later.
- Link to Item: Use the dropdown to select the specific Course, Lesson, or Page. Note: Leave as "Any Item" if any completion of that type should count.
- Commit: Click Save Mapping. The hook will now appear in your Builder sidebar.
init or wp_head. These fire on every click and will flood your database with invalid records.The Deep Scanner recursively iterates through hook arguments to extract User_ID and Item_ID. Evidence is stored in the mt_qe_evidence table as an Immutable Record. This ensures the achievement persists even if the source plugin or course is later deleted from the website.
Step-by-Step: Building Frameworks
Construct the logic pathways (Rules of Combination) for your credentials:
- Initiate: Click + Build New Framework and provide a clear title.
- Create Modules: Click Add Requirement Group. Each group acts as a logical container for related tasks.
- Apply Logic: Set the Group Rule. Use ALL for mandatory units, or COUNT/PERCENT for elective pools.
- Populate: Drag your Mapped Hooks or Document Upload tools from the sidebar into the group.
- Compliance: For Document Uploads, set the Supervisor and Sensitive status.
- Finalise: Set an Auto-Retire Date if needed, then click Save Framework.
The engine executes a Recursive Evaluation. Every time evidence is recorded, the system re-traverses the logic tree. A certificate is issued ONLY when the Root Node returns 100% completion. Metadata associated with manual uploads is stored in mt_qe_submissions until approved.
Learner Auditing & Diagnostics
Monitor progress and troubleshoot awards on the Learners hub.
- The Status Dot: Blue (In Progress) vs Green (Achieved).
- The Diagnostic Report: Click Diagnostic Report to see the live checklist. Identify blockers marked with ⏳.
- Accessing Certificates: If achieved, the system displays the official icon:
The Diagnostic Report executes a live logic pass via an asynchronous background request. It bypasses all database caches to provide a real-time "Snapshot of Truth" regarding the learner's evidence ledger. This serves as the definitive audit trail for Quality Assurance teams.
Master Diagnostic Guide
| Common Query | Actionable Resolution for Support Staff |
|---|---|
| "I finished the course but no certificate." | Check the heatmap. If Blue, click Diagnostic Report. If a Document Upload is marked ⏳, you must approve it in the Approvals tab. |
| "The checklist shows ⏳ for a finished course." | Verify that the Post/Page selected in System Hooks matches the ID of the course the learner actually completed. |
| Testing awarded logic. | Use the Test Hooks simulator. Select the learner and the hook, click Fire Hook, and read the green log to see if the certificate was triggered. |
Frontend Deployment Shortcodes
| Shortcode | Resulting Learner Interface |
|---|---|
[mtdc_qual_dashboard] | Digital Wallet: Grid of earned awards with PDF download and LinkedIn verification links. |
[mtdc_qual_progress id="X"] | Interactive Checklist: Real-time progress bar and task list for Framework X. |
[mtdc_submit_evidence] | Secure Upload Portal: Protected form for submitting manual files to the vault. |
Grading, Retakes & Evidence Expiration
The MT Credentials Engine autonomously manages the full lifecycle of a learner's achievement. Instead of issuing duplicate certificates for every retake, it maintains a single, permanent verification record that intelligently updates based on the learner's current compliance state.
When a framework is evaluated, the engine dynamically calculates the Total Possible Points across all mandatory requirements. It converts the learner's earned points into a percentage and checks it against your defined tiers.
- Requirement 1: Final Exam (Max 100 points)
- Requirement 2: Practical Assessment (Max 50 points)
- Requirement 3: ID Verification (Mandatory, 0 points)
If a learner passes but later improves their score, the system instantly upgrades their active certificate without changing the verification URL.
| Attempt | Score | Result |
|---|---|---|
| Initial | 100 / 150 (66%) | Pass (Cert Issued) |
| Retake Exam | 135 / 150 (90%) | Distinction (Upgraded) |
Note: The ledger records "🔄 Certificate Updated" and a new congratulatory email is automatically dispatched.
Time-sensitive documents (e.g., Annual DBS Checks, First Aid Certs) actively dictate the validity of the overall framework.
- Active State: Learner uploads a DBS check valid until Dec 31st. The Certificate is Valid.
- Expiration Event: On Jan 1st, the document officially expires. The engine drops the earned points for that requirement to 0.
- Suspension: Because the mandatory document is now at 0 points, the overall framework evaluates to Fail. The certificate status changes to
revoked. - Public View: The original Verification URL now displays a red Credential Invalid warning. The learner's dashboard tags the specific requirement with EXPIRED.
- Restoration: The learner uploads a new DBS check. Once approved, the certificate is instantly restored to
valid.
To prevent "Schrödinger's Certificate" (where a certificate remains technically valid in the database because nobody has viewed the learner's profile to trigger the math engine), the system utilizes a proactive Cron Job.
At midnight, the mt_daily_expiration_sweep routine runs a high-speed text search across the JSON payloads in the database. It isolates only the User IDs whose documents expired that exact day and surgically recalculates them. It then stamps the immutable Achievement Ledger with ❌ Certificate Revoked, ensuring your compliance auditing is 100% automated.