Initial Configuration
After activating the HRM module, a few configuration steps are recommended before you start managing employees and running payroll. All settings are accessible from Settings > HRM Configuration in the sidebar.
General Settingsโ
Navigate to Settings > HRM Configuration > General to configure foundational options.
Fiscal Year Start Monthโ
Defines when your organization's fiscal year begins. This affects leave carryover processing and payroll period calculations.
- Default: January
- Options: Any month (JanuaryโDecember)
Example: If your fiscal year runs April to March, set this to April. Leave carryover will be processed on April 1st each year.
Employee Code Formatโ
Controls how employee codes are auto-generated when creating new employees.
| Format | Example | Description |
|---|---|---|
year_increment | 2026-001, 2026-002 | Prefixed with the current year, resets each year |
increment | 001, 002, 003 | Simple sequential numbering |
Attendance Settingsโ
Navigate to Settings > HRM Configuration > Attendance.
Working Hoursโ
| Setting | Default | Description |
|---|---|---|
| Standard Hours Per Day | 8 | Used for overtime calculations and payroll pro-rating |
| Work Start Time | 09:00 | Expected check-in time |
| Work End Time | 17:00 | Expected check-out time |
Week-Off Daysโ
Select which days of the week are non-working days.
- Default: Saturday, Sunday
- Used in payroll calculations (working days count) and automatic weekend attendance marking
Leave Management Settingsโ
Navigate to Settings > HRM Configuration > Leave Management.
Approval Workflowโ
| Mode | Behavior |
|---|---|
| Single Level (default) | One approver reviews and approves/rejects the request |
| Multi Level | Request passes through multiple approval stages |
| Auto Approve | Requests are automatically approved upon submission |
Auto-Approve Leave Typesโ
Select specific leave types that should bypass the approval workflow entirely. Useful for types like Work From Home or Compensatory Off where approval isn't required.
Leave Carryoverโ
| Setting | Default | Description |
|---|---|---|
| Carryover Enabled | Yes | Whether unused leave days carry forward to the next fiscal year |
| Max Carryover Days | 10 | Maximum number of days that can be carried forward |
| Carryover Expiry (months) | 3 | Carried-forward days expire after this many months into the new fiscal year |
Leave carryover is processed automatically on the first day of your fiscal year start month via a scheduled command.
Payroll Settingsโ
Navigate to Settings > HRM Configuration > Payroll.
Salary Calculation Basisโ
Determines how salary is computed for partial months or pro-rated periods.
| Mode | Description |
|---|---|
| Working Days (default) | Salary is pro-rated based on actual working days in the period |
| Working Hours | Salary is calculated based on hours logged |
| Fixed Monthly | Full monthly salary regardless of working days |
Overtimeโ
| Setting | Default | Description |
|---|---|---|
| Overtime Enabled | Yes | Whether overtime hours are factored into payroll |
| Overtime Multiplier | 1.5x | Multiplier applied to the hourly rate for overtime hours |
Notification Recipientsโ
Select users who should receive email notifications when payroll runs are completed. Typically set to HR managers or finance team members.
Departments & Projectsโ
Departmentsโ
Navigate to Settings > HRM Configuration > Departments to create your organizational departments before adding employees. Each employee is assigned to a department.
Examples: Human Resources, Engineering, Sales, Marketing, Finance.
Projectsโ
Navigate to Settings > HRM Configuration > Projects to define projects that employees can log time against in their timesheets.
Setting Up Leave Typesโ
Before employees can submit leave requests, you need to configure leave types. Navigate to Leave Management > Leave Types from the sidebar.
For each leave type, configure:
| Field | Description |
|---|---|
| Name | e.g., Annual Leave, Sick Leave, Maternity Leave |
| Days Per Year | Annual entitlement for this leave type |
| Is Paid | Whether this leave type is paid |
| Requires Approval | Whether requests need manager approval |
| Carry Forward | Whether unused days roll over to the next year |
| Max Carry Forward Days | Limit on days that can be carried forward |
| Is Active | Enable or disable the leave type |
You can use the php artisan hrm:seed-leave-data command to create a standard set of leave types (Annual, Sick, Personal, Maternity, Paternity, Bereavement, Unpaid, Work From Home) with sensible defaults.
Setting Up Payroll Componentsโ
Before running payroll, define your salary components under Payroll > Payroll Components.
Components fall into three categories:
| Type | Examples |
|---|---|
| Allowance (Earnings) | Basic Salary, House Rent Allowance, Transport Allowance, Bonus |
| Deduction | Provident Fund, Insurance Premium, Loan Repayment |
| Tax | Income Tax, Social Security Tax |
Each component supports two calculation methods:
- Fixed: A set monetary amount (e.g., $500 Transport Allowance)
- Percentage: A percentage of base or gross salary (e.g., 12% Provident Fund)
Run php artisan hrm:seed-payroll-data to generate a standard set of payroll components (4 allowances, 3 deductions, 2 taxes) with typical configurations.
Employee Portal Configurationโ
The Employee Portal is configured via the config/employee-portal.php file in the HRM module directory. These settings control what employees see and can do when they log in.
Key Optionsโ
| Setting | Default | Description |
|---|---|---|
enabled | true | Enable or disable the employee portal |
employee_role_name | Employee | Name of the role assigned to employee users |
auto_create_user | true | Automatically create a CRM user account when an employee is created |
landing_page | /timesheets | The page employees see after login |
Visible Menu Itemsโ
By default, employees can access:
- Timesheets
- Leave Requests
- Attendance
- Leave Balances
- Payslips
To grant employees access to pages from other modules, add the route path to the allowed_menu_items array in the config file.
Data Scopingโ
The portal automatically filters data so employees can only see their own records. This applies to leave requests, leave balances, attendance, timesheets, salary structures, payroll entries, and payslips.
Models excluded from scoping (visible to all employees):
- Employee โ so the BelongsTo dropdown works when creating records
- Leave Type โ so employees can see available leave types
Recommended Setup Orderโ
- Activate the module โ Enter your license code in Settings > HRM Configuration > Activation
- Configure general settings โ Set fiscal year and employee code format
- Create departments โ Add your organizational structure
- Create projects โ Define projects for timesheet tracking (if applicable)
- Set up leave types โ Configure leave categories and entitlements
- Configure attendance settings โ Set working hours and week-off days
- Set up payroll components โ Define earnings, deductions, and taxes
- Configure payroll settings โ Set calculation basis and overtime rules
- Add employees โ Start creating employee records (user accounts are created automatically)
- Assign salary structures โ Link payroll components to each employee
- Create leave balances โ Allocate leave entitlements for the current year