# Mandatory Training and Validity

Corporate deployments use **Mandatory Training** and **Validity Period (Days)** on **LMS Course** plus **LMS Training Assignment** rows to drive due dates, overdue status, portal widgets, and HR onboarding automation. This guide explains configuration, assignment APIs, renewal strategy, and how LMS complements HR compliance records.

> **Help URL:** [smoothhiring.com/help/lms/courses/mandatory-training-and-validity](https://smoothhiring.com/help/lms/courses/mandatory-training-and-validity)

---

## Table of Contents

1. [Course-level flags](/#course-level-flags)
2. [LMS Training Assignment](/#lms-training-assignment)
3. [Onboarding auto-enrollment](/#onboarding-auto-enrollment)
4. [assign_mandatory_training API](/#assign_mandatory_training-api)
5. [Learner portal experience](/#learner-portal-experience)
6. [Renewals and validity](/#renewals-and-validity)
7. [Reporting](/#reporting)
8. [Desk paths](/#desk-paths)
9. [Step-by-step](/#step-by-step)
10. [Tips](/#tips)
11. [Troubleshooting](/#troubleshooting)
12. [Related guides](/#related-guides)
13. [HRMS integration](/#hrms-integration)

---

## Course-level flags

On **LMS Course** → Course Settings:

| Field | Behavior |
|-------|----------|
| **Mandatory Training** (`is_mandatory`) | Marks course as required library item for automation |
| **Validity Period (Days)** (`validity_days`) | Shown when mandatory; describes how long completion counts before recertify |

Description on validity field: "After expiry, employees must recertify." Implement renewal by creating new assignment rows or re-enrollment campaigns—schedule via calendar playbooks.

Pair with **Disable Self Learning** so only assigned employees enroll.

---

## LMS Training Assignment

DocType **LMS Training Assignment** (`TA-####`):

| Field | Notes |
|-------|-------|
| **Employee** | Link to **User** (employee email) |
| **Course** | LMS Course |
| **Due Date** | Required |
| **Status** | Pending / In Progress / Completed / Overdue |
| **Assigned By** | Defaults to current user |
| **Completed On** | Set when training finished |

Moderators and System Managers create assignments; students read own rows.

---

## Onboarding auto-enrollment

Hook `on_onboarding_created` (`lms.lms.hrms_integration`):

1. Loads employee `user_id` from **Employee**.
2. Finds published courses where `is_mandatory = 1`.
3. Creates **LMS Enrollment** per missing course.
4. Creates **LMS Training Assignment** with due date = today + 30 days.

Requires HR onboarding document with **employee** field populated.

---

## assign_mandatory_training API

Whitelisted `assign_mandatory_training(course, employees, due_date)`:

- Callers: **System Manager**, **Moderator**
- Skips duplicate open assignments (Pending/In Progress)
- Auto-creates enrollment if missing
- Returns count assigned

Use for annual refresh, department sweeps, or ad-hoc remediation after incidents.

---

## Learner portal experience

`StudentHome` shows **Mandatory Training** list via `get_my_training_assignments` with course title, image, due date, status, progress from enrollment.

Overdue assignments remain visible until completed—pair with email jobs or HR outreach.

---

## Renewals and validity

Validity days are informational unless you operationalize:

1. Track **Completed On** + validity in reporting spreadsheet, or
2. Build scheduled job (custom) to create new assignments when expiry approaches, or
3. Mirror renewals in [Employee Compliance](https://smoothhiring.com/help/hrms/documents-compliance/employee-compliance) with renewal periods

LMS certificate printout can include completion date for auditors.

---

## Reporting

- Desk list `/app/lms-training-assignment` filtered by Overdue.
- Portal **Statistics** page shows Mandatory Training Compliance widget (counts assigned/completed/overdue) for admins.
- Learning workspace enrollment shortcuts for progress = 100.

Export quiz PDFs for proof of comprehension, not just completion click-through.

---

## Desk paths

| Item | Path |
|------|------|
| Courses (mandatory flags) | `/app/lms-course` |
| Training assignments | `/app/lms-training-assignment` |
| Enrollments | `/app/lms-enrollment` |
| Portal home | `/lms/courses` |
| Learning workspace | `/desk/learning` |

---

## Step-by-step

### Configure compliance course

1. Edit **Harassment Prevention** course.
2. Check **Mandatory Training**; set **Validity Period** 365.
3. Check **Disable Self Learning**.
4. Publish.

### Assign department

1. Moderator opens assign tool with course, user list, due date.
2. Submit—verify assignments created.
3. Email employees link to `/lms/courses`.

### Onboarding test

1. Create employee with user.
2. Submit **Employee Onboarding**.
3. Confirm enrollment + assignment.
4. Complete course; status → Completed.

### Renewal cycle

1. Before expiry, run assign API again with new due date.
2. Optionally reset enrollment progress via support script (custom).
3. Update HR compliance record renewal date.

---

## Tips

- Align due dates with payroll cutoff or audit seasons.
- Use 30-day onboarding default as template—adjust in hook if needed via custom app.
- Keep mandatory course count small for new hires (<5) to avoid fatigue.
- Document difference between LMS completion and HR compliance sign-off.

---

## Troubleshooting

| Issue | What to do |
|-------|------------|
| No auto-assign on onboarding | Employee user_id blank; no published mandatory courses |
| Duplicate assignments | API skips open rows—complete or cancel old row |
| Overdue but completed | Status not updating—verify assignment completion hook/customization |
| Validity ignored | Build renewal process—field alone does not auto-expire enrollment |
| Permission denied on assign | User needs Moderator role |

---

## Related guides

- [First setup](https://smoothhiring.com/help/lms/getting-started/first-setup)
- [Roles and permissions](https://smoothhiring.com/help/lms/getting-started/roles-and-permissions)
- [Enroll employees](https://smoothhiring.com/help/lms/cohorts/enroll-employees)

---

## HRMS integration

- [Employee Onboarding overview](https://smoothhiring.com/help/hrms/onboarding/overview) — triggers auto-enrollment
- [Employee records](https://smoothhiring.com/help/hrms/people/employee-records) — source of `user_id`
- [Employee Compliance](https://smoothhiring.com/help/hrms/documents-compliance/employee-compliance) — regulatory renewal ledger alongside LMS validity

Course completion certificates do not replace compliance records unless your process explicitly merges them.

## HR alignment workshop

Meet with compliance owners to define: which courses are mandatory, validity days, due date policy, and whether LMS completion satisfies [Employee Compliance](https://smoothhiring.com/help/hrms/documents-compliance/employee-compliance) or requires additional attestation. Document escalation for **Overdue** assignments—manager notification vs HR ticket.

Annual recertification: run Moderator bulk assign with new due dates; communicate via email linking `/lms/courses`.

## Governance, auditing, and data retention

Training data in Smooth LMS is standard Frappe JSON in MariaDB plus files in `public/files` and `public/scorm`. HR audits typically require evidence of **who** completed **what** by **when**. Export desk lists (**LMS Enrollment**, **LMS Quiz Submission**, **LMS Training Assignment**, **LMS Certificate**) to CSV for sampling. Quiz submission print formats provide question-level detail suitable for safety investigations or harassment prevention audits.

Retention policy should align with HR document retention: keep LMS submissions at least as long as related [Employee Compliance](https://smoothhiring.com/help/hrms/documents-compliance/employee-compliance) records. When employees depart, disable User accounts but retain enrollment history unless legal counsel approves purging. Version course content via amended records or annual duplicated courses so historical completions still reference the correct curriculum year.

System Managers should restrict **Moderator** role membership and enable login activity review on sensitive cohorts (executive leadership programs). Pair LMS reports with HR onboarding status from [Employee Onboarding overview](https://smoothhiring.com/help/hrms/onboarding/overview) to prove training preceded start date when required.

## Frequently asked questions

**Do employees need desk access?** No. **LMS Student** is portal-only by default; send `{site}/lms/courses` links.

**Can one user be both Course Creator and Moderator?** Yes on small teams; larger orgs should separate author vs publish duties.

**How do we handle contractors?** Create User + optional HR employee record; assign training like employees via [Employee records](https://smoothhiring.com/help/hrms/people/employee-records) linkage or direct enrollment.

**What breaks if HRMS is down?** LMS continues serving published content; new hire auto-enrollment pauses until Employee/Onboarding APIs succeed.

**Are certificates legally equivalent to HR compliance rows?** Not automatically—store PDFs on compliance or document types when statute requires.

## Performance and scale notes

Large enrollments (5,000+ users) should batch assign overnight via `assign_mandatory_training` rather than manual enrollment rows. Rebuild website cache after bulk publish. Monitor background workers if email notifications queue heavily. SCORM packages should be optimized zip exports to reduce disk usage during large uploads.

## Additional troubleshooting

| Issue | What to do |
|-------|------------|
| Slow portal after publish | Hard-refresh browser; contact Smooth support if portal styling is broken |
| Wrong user on certificate | Certificate issued to enrollment member—fix User linkage in HR |
| Bulk import partial failure | Check error log; validate Course Instructor rows exist |
| Cohort vs course progress mismatch | Learner must open each course inside cohort; enrollments are per course |
| Timezone confusion on due dates | Training assignment due dates are date-only—communicate timezone in email |

## Operations calendar (recommended)

| Cadence | Action | Where |
|---------|--------|-------|
| Weekly | Review overdue **LMS Training Assignment** | `/app/lms-training-assignment` |
| Monthly | Publish content changelog to employees | Email + `/lms/courses` |
| Quarterly | Role audit (Moderator/Creator) | `/app/user` |
| Annually | Recertify mandatory courses | Re-assign with new due dates |
| After upgrade | Sign out/in; smoke-test `/lms` portal | `/desk/learning` |

## Integration smoke tests with HRMS

1. Create test **Employee** with user — confirm **LMS Student** role.
2. Submit test **Employee Onboarding** — confirm enrollments when courses mandatory.
3. Complete course — attach quiz PDF to test **Employee Compliance** row.
4. Archive evidence in document compliance SOP.

## Support runbook (L1)

Collect: user email, course/cohort name, screenshot of error, timestamp. Check enrollment exists, course published, role present. Escalate to System Manager if SCORM extract failed or permission hooks deny batch access. Reference [Employee records](https://smoothhiring.com/help/hrms/people/employee-records) to fix missing `user_id` before reassigning training.

## Document history and change control

When updating this process, record the Smooth LMS app version, platform update date, and whether HRMS onboarding templates changed. Authors should note breaking changes in course release notes (quiz question changes may require reattempts). For regulated customers, maintain a binder linking LMS course ID to compliance control ID in [Employee Compliance](https://smoothhiring.com/help/hrms/documents-compliance/employee-compliance).

Desk administrators use `/desk/learning` for cross-course metrics; portal users rely on `/lms/courses` for consumption—both URLs should appear in internal SOP PDFs so auditors can reproduce learner steps without admin credentials.

---

_Last updated: May 2026_

---

## Smooth HR (HRMS)

| Guide | Link |
|-------|------|
| HR help home | [smoothhiring.com/help/hrms](https://smoothhiring.com/help/hrms) |
| Employee records | [hrms/people/employee-records](https://smoothhiring.com/help/hrms/people/employee-records) |
| Onboarding overview | [hrms/onboarding/overview](https://smoothhiring.com/help/hrms/onboarding/overview) |
| Onboarding templates | [hrms/onboarding/onboarding-templates](https://smoothhiring.com/help/hrms/onboarding/onboarding-templates) |
| Employee onboarding | [hrms/onboarding/employee-onboarding](https://smoothhiring.com/help/hrms/onboarding/employee-onboarding) |
| Documents & compliance | [hrms/documents-compliance/overview](https://smoothhiring.com/help/hrms/documents-compliance/overview) |
| Employee compliance | [hrms/documents-compliance/employee-compliance](https://smoothhiring.com/help/hrms/documents-compliance/employee-compliance) |
| Signature templates | [hrms/documents-compliance/signature-templates](https://smoothhiring.com/help/hrms/documents-compliance/signature-templates) |