# Employee Auto-Provisioning (HRMS → LMS)

When HR creates an **Employee** record in Smooth HR, Smooth LMS automatically ensures the linked **User** can access the learning portal. This happens through a server-side hook—`on_employee_created` in `lms.lms.hrms_integration`—registered on the **Employee** record `after_insert` event. No manual role assignment, or IT ticket is required for standard hires.

Auto-provisioning is the first integration touchpoint in the hire-to-learn journey. It runs **before** onboarding mandatory enrollment ([Onboarding Mandatory Training](https://smoothhiring.com/help/lms/hrms-integration/onboarding-mandatory-training)) and **before** HR assigns ad-hoc courses ([Assign Training From Hr](https://smoothhiring.com/help/lms/hrms-integration/assign-training-from-hr)). Understanding this step prevents the most common support issue: "My new hire cannot log in to `/lms`."

> **Help URL:** [Employee Auto Provisioning](https://smoothhiring.com/help/lms/hrms-integration/employee-auto-provisioning)

> **Prerequisite HR guides:** [People Overview](https://smoothhiring.com/help/hrms/people/overview), [User Roles & Permissions](https://smoothhiring.com/help/hrms/getting-started/user-roles-permissions)

---

## Table of Contents

1. [What happens automatically](/#what-happens-automatically)
2. [Prerequisites on the HR side](/#prerequisites-on-the-hr-side)
3. [The LMS Student role](/#the-lms-student-role)
4. [Hook behavior step by step](/#hook-behavior-step-by-step)
5. [Employee creation paths in HR](/#employee-creation-paths-in-hr)
6. [Desk verification checklist](/#desk-verification-checklist)
7. [Bulk imports and migrations](/#bulk-imports-and-migrations)
8. [Security and permissions](/#security-and-permissions)
9. [Troubleshooting](/#troubleshooting)
10. [Related guides](/#related-guides)

---

## What happens automatically

On **Employee** `after_insert`:

1. Smooth LMS reads `doc.user_id` on the new Employee.
2. If `user_id` is empty, the hook **exits silently**—no error is shown to HR.
3. If a User exists, LMS checks whether **LMS Student** is already in `user.roles`.
4. If missing, LMS **appends** the role and saves the User with `ignore_permissions=True`.

The employee can then sign in and see courses at `/lms` (subject to enrollments). Auto-provisioning does **not** enroll courses by itself—that occurs when **Employee Onboarding** is created ([Onboarding Mandatory Training](https://smoothhiring.com/help/lms/hrms-integration/onboarding-mandatory-training)) or when HR/moderators assign training.

This design keeps HR workflows simple: create Employee with User ID, and LMS access follows. Refer to the integration overview at [Overview](https://smoothhiring.com/help/lms/hrms-integration/overview) for the full capability map alongside [Documents & Compliance](https://smoothhiring.com/help/hrms/documents-compliance/overview) and [Onboarding](https://smoothhiring.com/help/hrms/onboarding/overview).

---

## Prerequisites on the HR side

| Requirement | Why it matters | HR guide |
|-------------|----------------|----------|
| **User ID** populated on Employee | Hook target | [People](https://smoothhiring.com/help/hrms/people/overview) |
| User account enabled | Login works | [Roles](https://smoothhiring.com/help/hrms/getting-started/user-roles-permissions) |
| Employee linked before onboarding training | Enrollment uses `employee.user_id` | [Employee Onboarding](https://smoothhiring.com/help/hrms/onboarding/employee-onboarding) |
| Email unique on User | LMS identifies `member` by email | Standard account rules |

### Creating User + Employee together

Typical flow from [Employee Onboarding](https://smoothhiring.com/help/hrms/onboarding/employee-onboarding):

1. Recruiting completes in [Recruitment](https://smoothhiring.com/help/hrms/recruitment/overview).
2. HR submits onboarding from a [Template](https://smoothhiring.com/help/hrms/onboarding/onboarding-templates).
3. HR clicks **Create Employee** (or equivalent) when ready.
4. Smooth HR creates/links the **user account** and **Employee** with matching email.
5. LMS hook grants **LMS Student** immediately on insert.

If HR creates Employee records manually from `/app/employee/new-employee`, ensure **User ID** is set in the same session—do not save an Employee "to fill in later" if you expect same-day LMS access.

---

## The LMS Student role

**LMS Student** is the baseline learner role in Smooth LMS:

| Capability | LMS Student | Notes |
|------------|-------------|-------|
| Access `/lms` portal | Yes | After login |
| View enrolled courses | Yes | Via **LMS Enrollment** |
| View own assignments | Yes | **LMS Training Assignment** (owner read) |
| Create courses | No | Requires **Moderator** |
| Assign training to others | No | Requires **Moderator** or API role |
| HR compliance records | No | Separate HR roles |

HR staff who also take training should have **both** HR roles and **LMS Student**. HR Manager alone does not grant LMS portal course access unless configured separately.

Cross-reference [User Roles & Permissions](https://smoothhiring.com/help/hrms/getting-started/user-roles-permissions) when auditing role overlap between HR and L&D teams.

---

## Hook behavior step by step

Source reference (`lms.lms.hrms_integration.on_employee_created`):

```
Employee after_insert
  → if not doc.user_id: return
  → load User(doc.user_id)
  → if LMS Student not in roles:
       append role LMS Student
       save User (ignore_permissions)
```

**Idempotent:** Re-saving Employee does not re-trigger `after_insert`. If provisioning failed silently (no user_id), fixing User ID and creating a **new** Employee is wrong—instead add **LMS Student** manually once, or use a one-off script.

**Not triggered on update:** Promotions, department changes, or manager updates on existing Employee do not re-run provisioning. Existing users retain LMS Student.

---

## Employee creation paths in HR

| Path | When used | LMS impact |
|------|-----------|------------|
| Manual Employee form | Rehire, acquisition, intern | Hook on insert if user_id set |
| From Job Offer / Applicant | Standard hire | User often created during offer acceptance |
| Employee Onboarding → Create Employee | Onboarding workflow | Preferred; aligns with [portal](https://smoothhiring.com/help/hrms/onboarding/onboarding-portal) |
| Data import | Migration | Hook runs per row if insert; bulk fix may be needed |

For contractors vs employees, decide policy: if contractors need training but not full HR records, you may create simplified Employee rows or standalone Users—document your rule so [compliance](https://smoothhiring.com/help/hrms/documents-compliance/employee-compliance) and LMS stay aligned.

---

## Desk verification checklist

After creating a test Employee:

1. Open **User** from Employee → **User ID** link.
2. Scroll to **Roles** table → confirm **LMS Student** present.
3. Log in as that user → navigate to `/lms`.
4. Confirm portal loads (empty catalog is OK before enrollment).
5. Create **Employee Onboarding** → verify mandatory enrollments per [Onboarding Mandatory Training](https://smoothhiring.com/help/lms/hrms-integration/onboarding-mandatory-training).
6. Optionally assign a non-mandatory course via [Assign Training From Hr](https://smoothhiring.com/help/lms/hrms-integration/assign-training-from-hr).

For admins, **LMS Settings** ([Lms Settings General](https://smoothhiring.com/help/lms/settings/lms-settings-general)) controls whether **Show Employees** appears in batch sidebars—useful when HR and L&D co-manage cohorts.

---

## Bulk imports and migrations

Importing thousands of Employees via Data Import Tool:

- Include **user_id** column or map email → User creation first.
- `after_insert` fires per record—expect slower imports; run off-hours.
- Employees imported with `ignore_links` may skip Users—audit with:

  `User` list filtered by users missing **LMS Student** but linked on Employee.

- Historical hires already active: ask Smooth support to grant **LMS Student** access to existing employees who already have a linked login.

Migrated users from a legacy LMS still need Smooth LMS **LMS Enrollment** rows—provisioning only handles roles, not content migration.

---

## Security and permissions

The hook uses `ignore_permissions=True` because HR Users creating Employees typically cannot edit arbitrary User roles. Only the **LMS Student** role is appended—never **Moderator** or **System Manager**.

Review [role separation](https://smoothhiring.com/help/hrms/getting-started/user-roles-permissions) policies:

- HR should not self-assign Moderator without L&D approval.
- Terminated employees: disable **User** enabled flag in HR offboarding ([Tenure](https://smoothhiring.com/help/hrms/tenure/overview))—LMS access stops at login, but enrollments remain for records.

---

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| No LMS Student role | Empty user_id on Employee | Set User ID; add role manually if insert already passed |
| User cannot login | User disabled / no password | Reset password; check enabled |
| Role present but /lms 403 | Missing website permissions / LMS not installed | Verify `lms` app on site |
| Duplicate users | Email mismatch Applicant vs Employee | Align emails before Create Employee |
| Hook never ran | Employee created before LMS app install | Backfill roles via report |

---

## Related guides

- [HRMS + LMS Integration Overview](https://smoothhiring.com/help/lms/hrms-integration/overview)
- [Onboarding Mandatory Training](https://smoothhiring.com/help/lms/hrms-integration/onboarding-mandatory-training)
- [Assign Training from HR](https://smoothhiring.com/help/lms/hrms-integration/assign-training-from-hr)
- [People Overview](https://smoothhiring.com/help/hrms/people/overview)
- [Employee Onboarding](https://smoothhiring.com/help/hrms/onboarding/employee-onboarding)
- [Onboarding Portal](https://smoothhiring.com/help/hrms/onboarding/onboarding-portal)
- [User Roles & Permissions](https://smoothhiring.com/help/hrms/getting-started/user-roles-permissions)
- [Recruitment Overview](https://smoothhiring.com/help/hrms/recruitment/overview)
- [LMS Settings — General](https://smoothhiring.com/help/lms/settings/lms-settings-general)

---

_Last updated: May 2026_

---

## Day-in-the-life examples

**Example 1 — Standard full-time hire**

Acme Corp completes [recruitment](https://smoothhiring.com/help/hrms/recruitment/overview) for a warehouse associate. HR submits [Employee Onboarding](https://smoothhiring.com/help/hrms/onboarding/employee-onboarding) from a template that includes I-9 upload tasks. When HR clicks **Create Employee**, Frappe creates User `associate@acme.com` and Employee `HR-EMP-0042` with matching **User ID**. Within the same request, LMS appends **LMS Student**. The associate receives portal links for [onboarding paperwork](https://smoothhiring.com/help/hrms/onboarding/onboarding-portal) and `/lms` training. No L&D moderator touches role tables manually.

**Example 2 — Rehire with existing User**

A former employee returns; HR reactivates User instead of creating duplicate. New Employee insert still fires the hook—but role already present, so save is skipped. L&D assigns refresher courses via [Assign Training from HR](https://smoothhiring.com/help/lms/hrms-integration/assign-training-from-hr) rather than relying on onboarding mandatory set.

**Example 3 — Migration gap**

Legacy HRIS import creates 500 Employees without user_id. Hook never ran. HR runs audit script, creates Users in batch, sets user_id, manually adds LMS Student—or re-insert is impossible; use data fix. Plan migration checkpoints with [Getting Started](https://smoothhiring.com/help/hrms/getting-started/overview) staging site.

---

## Governance checklist for HRIS admins

| Control | Owner | Frequency |
|---------|-------|-----------|
| Active Employee has user_id | HR Operations | Monthly |
| Active Employee User has LMS Student | L&D admin | Monthly |
| Terminated User disabled | HR Offboarding | Per event |
| Role change to Moderator documented | IT Security | Per change |
| SSO email matches Employee company email | IT + HR | Per hire |

Publish checklist alongside [Documents & Compliance](https://smoothhiring.com/help/hrms/documents-compliance/overview) audit calendar so learning access reviews coincide with compliance attestations.

---

## FAQ

**Does updating Department re-provision LMS?** No. Only `after_insert` on Employee.

**Can we remove LMS Student on promotion to manager?** Yes manually, but managers often still take training—keep role unless policy forbids learner UI.

**Does Applicant User get LMS Student before Employee exists?** Not via this hook. Applicants are not employees; training starts post-hire.

**What about employees without email?** Rare; Frappe User requires email—align with [People](https://smoothhiring.com/help/hrms/people/overview) standards.

---

---

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