# User Roles and Permissions

**Help URL:** [https://smoothhiring.com/help/hrms/getting-started/user-roles-permissions](https://smoothhiring.com/help/hrms/getting-started/user-roles-permissions)

Smooth HR access is controlled through **users** and **roles** on your account. Four roles matter most for day-to-day HR: **HR Manager**, **HR User**, **Employee**, and **Onboarding User**. This guide explains what each role can do, how to assign them, how onboarding portal isolation works, and how to troubleshoot permission errors.

---

## Table of Contents

1. [How Frappe permissions work](/#how-frappe-permissions-work)
2. [HR Manager](/#hr-manager)
3. [HR User](/#hr-user)
4. [Employee](/#employee)
5. [Onboarding User](/#onboarding-user)
6. [System Manager and other roles](/#system-manager-and-other-roles)
7. [Assigning roles step by step](/#assigning-roles-step-by-step)
8. [Linking Users to Employee records](/#linking-users-to-employee-records)
9. [Onboarding portal access model](/#onboarding-portal-access-model)
10. [Permission matrix (summary)](/#permission-matrix-summary)
11. [Best practices](/#best-practices)
12. [Troubleshooting](/#troubleshooting)
13. [Related guides](/#related-guides)

---

## How access control works

| Concept | Description |
|---------|-------------|
| **User** | Login account (email) |
| **Role** | Permission bundle (HR Manager, Employee, …) |
| **Record permissions** | Per-role read/write/submit/cancel on each record type |
| **User Permissions** | Optional row-level restrictions (e.g. one Company) |

Roles are maintained at **User List** → `/app/user` → open user → **Roles** table.

Smooth HR also uses **role_home_page** in hooks: users with only **Onboarding User** land on `/desk/onboarding-portal` instead of People.

---

## HR Manager

**Who:** HR director, HRIS administrator, people operations lead.

**Typical responsibilities:**

- Configure **HR Settings**, companies, leave policies, payroll structures
- Create and submit **Employee Onboarding**, **Payroll Entry**, **Leave Policy Assignment**
- Manage **Employee Onboarding Template** and **Signature Template**
- Approve or override sensitive transactions
- Access dashboards across all modules

**Desk access:** Full Smooth HR desktop (all module icons). Can open onboarding portal via **Preview Portal** on Employee Onboarding.

**DocType examples (from permissions):**

| Area | HR Manager capability |
|------|----------------------|
| Employee Onboarding | Create, submit, amend, cancel |
| Employee Onboarding Template | Full access |
| Payroll Entry / Salary Slip | Submit payroll |
| Signature Envelope | Create and monitor multi-signer flows |

> Assign **HR Manager** sparingly — it is effectively admin for HR data.

---

## HR User

**Who:** Recruiters, HR coordinators, HR generalists without full config access.

**Typical responsibilities:**

- Maintain **Job Applicant**, **Interview**, **Employee** day-to-day fields
- Create **Employee Onboarding** from templates
- Process **Leave Application** and **Expense Claim** on behalf of employees (where permitted)
- Complete HR **Tasks** created from onboarding activities

**Desk access:** Smooth HR modules per assigned permissions; may not change all HR Settings sections.

**Difference from HR Manager:**

| Task | HR User | HR Manager |
|------|---------|------------|
| Edit HR Settings hiring/onboarding email | Often read-only | Yes |
| Submit payroll | Depends on site | Yes |
| Cancel submitted onboarding | Limited | Yes |
| Create onboarding templates | Yes (per record perm) | Yes |

Use **HR User** for team members who should not change global payroll or security settings.

---

## Employee

**Who:** Active workforce members using self-service.

**Typical responsibilities:**

- Submit **Leave Application**, **Expense Claim**, **Attendance Request**
- View own **Salary Slip** (if enabled)
- Update limited profile fields on linked **Employee** record

**Desk access:** Employee role on User; may see reduced module set (often Leaves, Expenses, and profile-related pages). Permissions vary by site policy.

**Setup requirements:**

1. Create **User** with employee's work email.
2. On **Employee**, set **User ID** to that user.
3. Assign role **Employee** (plus module-specific roles if you use custom apps).

Without **User ID** linkage, the employee cannot see their own leave balance or slips tied to employee identity.

---

## Onboarding User

**Who:** Candidates and new hires completing pre-boarding **before** full employee self-service.

**Purpose:** Restricted access so new hires only see the **Onboarding Portal** — not payroll, other employees, or company-wide lists.

**Behavior (from Smooth HR hooks and portal code):**

| Setting | Value |
|---------|-------|
| `role_home_page` | `/desk/onboarding-portal` |
| Desk restriction | Onboarding User without HR Manager / System Manager cannot browse standard HR modules |
| Record match | Portal loads **Employee Onboarding** tied to login email |

**How the role is assigned:**

When HR **submits** **Employee Onboarding**, Smooth HR:

1. Ensures role **Onboarding User** exists in the system.
2. Creates or updates a **User** for the onboarding email.
3. Appends **Onboarding User** role if missing.
4. Sends portal credentials / link (template from **HR Settings → Onboarding Portal Email Template**).

**After day one:** HR links full **Employee** user, assigns **Employee** role, and may remove **Onboarding User** when no longer needed.

---

## System Manager and other roles

| Role | Notes |
|------|-------|
| **System Manager** | Full account admin; bypasses most HR restrictions — use for IT only |
| **Leave Approver** / **Expense Approver** | Often assigned via Employee master, not global role |
| **Payroll User** | May exist on sites with separated payroll team |

Do not conflate **System Manager** with **HR Manager** — IT admins should not be the only HR configurators unless intentional.

---

## Assigning roles step by step

### New HR team member

1. Go to `/app/user` → **Add User**.
2. Enter email, first name, send welcome email.
3. In **Roles**, add **HR User** or **HR Manager**.
4. Optionally set **User Permissions** for a single Company.
5. Save.

### New hire (onboarding only)

Roles are usually auto-assigned on onboarding submit. To resend access:

1. Open `/app/employee-onboarding/{name}`.
2. Click **Send Portal Access**.
3. Confirm email on record matches hire's inbox.

### Promote hire to employee self-service

1. **Create → Employee** (or link existing).
2. Create **User** or reuse onboarding user.
3. Add **Employee** role; remove **Onboarding User** when appropriate.
4. Set **User ID** on Employee.

---

## Linking Users to Employee records

| Step | Location |
|------|----------|
| 1 | Open `/app/employee/{id}` |
| 2 | Set **User ID** = user's email/login |
| 3 | Ensure **Company Email** or **Personal Email** matches portal login |

Portal matching order (from onboarding portal logic):

1. Employee **user_id**
2. **Job Applicant** email
3. **Onboarding email** on Employee Onboarding record

Mismatch causes **No Onboarding Found** in the portal.

---

## Onboarding portal access model

```
HR Manager / HR User                    Onboarding User
        │                                      │
        ▼                                      ▼
 Employee Onboarding (desk)              Onboarding Portal page
        │                                      │
        ├─ Submit ──► Create User + Role         │
        ├─ Send Portal Access ──► Email         │
        └─ Preview Portal (read-only QA)       ├─ Forms + documents
                                                 ├─ Sign /sign/{token}
                                                 └─ Submit onboarding
```

HR reviews progress on **Employee Onboarding** fields: **Onboarding Progress**, **Documents Completed**, **Section Status**, **Onboarding Completed**.

---

## Permission matrix (summary)

| Capability | HR Manager | HR User | Employee | Onboarding User |
|------------|:----------:|:-------:|:--------:|:---------------:|
| HR Settings | ✓ | partial | — | — |
| Employee list (all) | ✓ | ✓ | own | — |
| Employee Onboarding | ✓ | ✓ | — | own via portal |
| Onboarding Template | ✓ | ✓ | — | — |
| Payroll Entry submit | ✓ | site-dependent | — | — |
| Leave Application (self) | ✓ | ✓ | ✓ | — |
| Onboarding Portal page | preview | preview | — | ✓ |
| Signature Template edit | ✓ | limited | — | — |

---

## Best practices

1. **Least privilege** — HR User for coordinators; HR Manager for 1–2 admins.
2. **Separate onboarding logins** — Do not add HR Manager to new hire portal test accounts.
3. **One User per person** — Avoid duplicate users for same email.
4. **Document role changes** — When offboarding, disable User rather than deleting history.
5. **Test portal** with **Preview Portal** before sending to candidates.
6. **Align emails** — Applicant email → onboarding email → User email must match.

---

## Troubleshooting

| Issue | What to do |
|-------|------------|
| User sees no Smooth HR app | Add HR Manager or HR User role |
| Permission denied on submit | Check record role permissions; escalate to HR Manager |
| Onboarding User sees full desk | Remove HR roles from test user; keep only Onboarding User |
| Portal: No Onboarding Found | Match User email to applicant/employee/onboarding email |
| Cannot preview portal | HR Manager or HR User required on preview page |
| New hire received no email | Check **Send Portal Access**; verify outgoing email; spam folder |
| Duplicate user on resend | Same user updated — reset password if needed |
| HR User cannot open HR Settings | Expected on some sites — escalate change to HR Manager |

---

## Role assignment scenarios (extended)

### Scenario: Contractor vs employee

Contractors may need **Employee** records for time tracking but not payroll. Assign **Employee** role only if they use self-service; otherwise HR enters data on their behalf with **HR User**.

### Scenario: Hiring manager as approver

Hiring managers often do not need **HR Manager**. Grant **HR User** only if they create onboarding records; otherwise keep them as **Leave Approver** on Department without desk HR roles.

### Scenario: IT provisioning tasks

IT staff completing onboarding **Tasks** need User accounts with permission to update **Task** or membership on the onboarding **Project** — not necessarily **HR Manager**.

### Scenario: Executive hire

Executives may receive a shortened onboarding template. Use **User Permissions** on Company plus a dedicated template filtered by **Employee Grade** rather than over-permissioning executive assistants with **HR Manager**.

---

## Auditing access

Periodically export `/app/user` list and review:

- Users with **HR Manager** who left the organization
- Stale **Onboarding User** accounts after hire conversion
- Shared inboxes used as User emails (avoid — breaks portal matching)

---

## Related guides

- [Getting Started overview](https://smoothhiring.com/help/hrms/getting-started/overview)
- [Company setup](https://smoothhiring.com/help/hrms/getting-started/company-setup)
- [Onboarding Portal](https://smoothhiring.com/help/hrms/onboarding/onboarding-portal)
- [Employee Onboarding](https://smoothhiring.com/help/hrms/onboarding/employee-onboarding)

---

_Last updated: May 2026_