# First Setup

This guide walks through the first production-ready configuration of Smooth LMS on your Smooth HRMS account (Smooth HR already enabled). You will enable portal navigation, create categories, publish a pilot course, link employees to users, and validate HR onboarding enrollment for mandatory training.

> **Help URL:** [smoothhiring.com/help/lms/getting-started/first-setup](https://smoothhiring.com/help/lms/getting-started/first-setup)

---

## Table of Contents

1. [Prerequisites](/#prerequisites)
2. [Install and migrate](/#install-and-migrate)
3. [Configure LMS Settings](/#configure-lms-settings)
4. [Categories and portal branding](/#categories-and-portal-branding)
5. [Service roles and test users](/#service-roles-and-test-users)
6. [Publish a pilot course](/#publish-a-pilot-course)
7. [HR employee linkage](/#hr-employee-linkage)
8. [Mandatory training smoke test](/#mandatory-training-smoke-test)
9. [Desk paths](/#desk-paths)
10. [Step-by-step checklist](/#step-by-step-checklist)
11. [Tips](/#tips)
12. [Troubleshooting](/#troubleshooting)
13. [Related guides](/#related-guides)
14. [HRMS integration](/#hrms-integration)

---

## Prerequisites

- A Smooth HRMS account with **Smooth HR** enabled.
- **Smooth LMS** enabled on your account.
- SMTP or email queue working for cohort confirmations and training reminders.
- HR has created at least one **Company** and **Employee** with company email.

Optional: test quiz/certificate PDF download from the desk.

---

## Confirm Smooth LMS is enabled

1. Confirm **Smooth LMS** appears in your app switcher after login (contact Smooth support if it is missing).
2. 
3. After a platform update, sign out and back in; contact Smooth support if menus look outdated.
4. If the learning portal looks broken after an update, hard-refresh the browser or contact Smooth support.
5. Confirm **Workspace** "Learning" exists and app icon opens `/desk/learning`.

Default LMS roles and certificate templates are created automatically when Smooth LMS is enabled on your account.

---

## Configure LMS Settings

Open `/app/lms-settings/LMS%20Settings` (single record).

**General tab**

- **Allow Guest Access** — off for internal HRMS sites.
- **Prevent Skipping Videos** — enable for compliance video lessons.
- **Default Home** — portal landing experience.

**Notifications**

- Enable **Send notification for published courses** when rolling out new libraries.
- Enable batch notifications if using cohorts.

**Sidebar tab**

Turn on items employees need:

- Courses, Batches (cohorts), Statistics (admins), Certifications as appropriate.
- Disable Jobs/Programming if not used to reduce noise.

**Signup**

- **Disable Signup** on private employee-only sites.
- Map **User Category** options for corporate personas.

Save settings before user acceptance testing.

---

## Categories and portal branding

1. Open `/app/lms-category` — create folders: Safety, Leadership, IT, Onboarding.
2. Sample categories may already exist; rename them to match your taxonomy.
3. Upload **Meta Image** and SEO fields in LMS Settings for external-facing sites.
4. Optional: configure **Web Page** home linked from Learning workspace.

Assign every course to a category for catalog filters on `/lms/courses`.

---

## Service roles and test users

Create three test users:

| User | Roles |
|------|-------|
| lms-admin@test.com | System Manager + Moderator |
| lms-author@test.com | Course Creator + LMS Student |
| lms-learner@test.com | LMS Student only |

Verify author can open `/lms/courses/new/edit` while learner cannot.

---

## Publish a pilot course

1. As author, create **Workplace Safety Orientation** course.
2. Add trainer row (Course Instructor) with author user.
3. Add one **Module** (Course Chapter) and two lessons (markdown + quiz).
4. Set **Short Introduction** and **Description** (required fields).
5. Enable **Completion Certificate** if testing certificates.
6. Check **Published**; set **Published On** date.
7. Browse `/lms/courses` as learner; complete content.

Monitor `/app/lms-enrollment` for progress.

---

## HR employee linkage

For each employee who must train:

1. Open [Employee](https://smoothhiring.com/help/hrms/people/employee-records) record.
2. Set **User ID** to company email user.
3. Save—integration adds **LMS Student** if missing.
4. Invite user to set password if new account.

Without `user_id`, onboarding training assignment will not run.

---

## Mandatory training smoke test

1. Edit pilot course: enable **Mandatory Training**, set **Validity Period (Days)** e.g. 365.
2. Create **Employee Onboarding** for a test hire linked to employee with user.
3. Submit onboarding—verify **LMS Enrollment** and **LMS Training Assignment** created (30-day default due).
4. Learner portal home shows mandatory widget with due date.
5. Complete course; assignment status moves to Completed.

Alternatively call assign mandatory training API as Moderator with employee user list + due date.

---

## Desk paths

| Step | Path |
|------|------|
| Learning home | `/desk/learning` |
| LMS Settings | `/app/lms-settings/LMS%20Settings` |
| Categories | `/app/lms-category` |
| Courses | `/app/lms-course` |
| Portal catalog | `/lms/courses` |
| Training assignments | `/app/lms-training-assignment` |

---

## Step-by-step checklist

- [ ] Smooth LMS is available on your account
- [ ] LMS Settings sidebar configured
- [ ] LMS Category masters created
- [ ] Roles assigned to L&D team
- [ ] Pilot course published on portal
- [ ] Employee users linked
- [ ] Mandatory enrollment tested via onboarding
- [ ] Quiz submission PDF prints from desk
- [ ] Certificate generated (if enabled)
- [ ] Documentation shared with managers (`/lms/courses` link)

---

## Tips

- Run through the learner and author smoke tests on a test account after seed scripts.
- Keep production **disable_signup** on to prevent public accounts.
- Document canonical URL `{site}/lms/courses` in employee handbook.
- Schedule quarterly review of unpublished draft courses in `/app/lms-course`.

---

## Troubleshooting

| Issue | What to do |
|-------|------------|
| Smooth LMS is not enabled on your account | Contact Smooth support |
| Workspace missing | Contact Smooth support to refresh your Learning workspace |
| Portal 403 | User needs LMS Student; check session |
| Settings not saving | Clear cache; verify single LMS Settings row |
| No training assignment on onboarding | Mandatory published courses; employee user_id |
| Assets 404 | Hard-refresh the browser or contact Smooth support |

---

## Related guides

- [Smooth LMS overview](https://smoothhiring.com/help/lms/getting-started/overview)
- [Desk vs portal](https://smoothhiring.com/help/lms/getting-started/desk-vs-portal)
- [Create a course](https://smoothhiring.com/help/lms/courses/create-a-course)
- [Mandatory training and validity](https://smoothhiring.com/help/lms/courses/mandatory-training-and-validity)

---

## HRMS integration

First setup succeeds when HR master data is reliable—see [Employee records](https://smoothhiring.com/help/hrms/people/employee-records). Align onboarding templates with LMS mandatory courses per [Employee Onboarding overview](https://smoothhiring.com/help/hrms/onboarding/overview). Plan how completion evidence flows into [Employee Compliance](https://smoothhiring.com/help/hrms/documents-compliance/employee-compliance) before go-live.

## Post-setup validation script

Manually verify: (1) learner login → portal home, (2) author login → editor, (3) moderator assign training, (4) desk quiz PDF print, (5) onboarding creates enrollment. Record results in internal QA doc. After each Smooth LMS release, sign out and back in; contact support if anything looks wrong to re-run v16 desk patches.

## 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.

---

_Last updated: May 2026_