🏗️Leave Requests

Leave Requests are the core of the leave management workflow. Employees submit requests for time off, which then flow through an approval process. The system tracks the full lifecycle from submission through approval or rejection, with automatic balance updates at each step.

---

Submitting a Leave Request

As an Employee (Portal)

1. Navigate to Leave Requests from the sidebar.

2. Click Create.

3. Select the Leave Type.

4. Enter the Start Date and End Date.

5. Enter the number of Days (supports half-day increments, e.g., 0.5, 1.5).

6. Optionally add a Reason.

7. Click Save.

The Employee field is automatically set to the logged-in employee — it does not appear on the form.

As an Administrator

Administrators see the same form, but with an additional Employee field to select which employee the request is for. They can also fill in the Admin Notes field (hidden from employees).

From Employee Detail View

Administrators can create leave requests directly from an employee's detail page using the Create Leave Request action. The employee is pre-filled, and an additional Is Half Day toggle is available for convenience.

---

Validation Rules

The system enforces several validation rules when submitting or editing a leave request:

Days Validation

The number of days must match the date range:

• Full days: Days must equal end_date - start_date + 1

• Half days: Days must equal (end_date - start_date + 1) × 0.5

Any other value is rejected with an error message.

Overlap Detection

The system checks for overlapping leave requests for the same employee. A request is blocked if its date range overlaps with any existing approved or pending request.

Two date ranges overlap if: start_date_1 ≤ end_date_2 AND start_date_2 ≤ end_date_1

When editing an existing request, the overlap check excludes the current record.

---

Request Statuses

Status	Badge	Description
Pending	Yellow	Awaiting approval. Balance is reserved in pending_days.
Approved	Green	Approved by a manager. Days moved from pending_days to used_days.
Rejected	Red	Rejected by a manager. Days removed from pending_days.
Cancelled	Gray	Cancelled by the employee or administrator. Days restored.

---

Approval Workflow

Standard Flow

Employee submits request
         ↓
   Status: Pending
  (pending_days increased)
         ↓
  Manager reviews request
         ↓
┌─── Approve ───→ Status: Approved
│                 (pending_days → used_days)
│                 Employee notified
│
├─── Reject ────→ Status: Rejected
│                 (pending_days removed)
│                 Rejection reason recorded
│                 Employee notified
│
└─── (Employee) Cancel ──→ Status: Cancelled
                           (pending_days removed)

Auto-Approve Flow

For leave types configured for auto-approval (in Settings > Leave Management):

Employee submits request
         ↓
Observer detects auto-approve configuration
         ↓
Status: Approved immediately
(used_days increased)
No manager notification sent

Approval Workflow Settings

Navigate to Settings > HRM Configuration > Leave Management to configure the workflow:

Setting	Options	Default
Approval Workflow	Single Level / Multi Level / Auto Approve	Single Level
Auto-Approve Leave Types	Select specific leave types	None

---

Approving a Leave Request

Requires the approve leave requests permission.

1. Navigate to Leave Requests or open from the pending requests dashboard card.

2. Select one or more pending requests.

3. Click the Approve action.

4. Optionally add Admin Notes.

5. Confirm.

What happens:

• Status changes to Approved

• approved_by is set to the current user

• approved_at is set to the current timestamp

• Leave balance: pending_days decreases, used_days increases

• Employee receives a notification

---

Rejecting a Leave Request

Requires the approve leave requests permission.

1. Select one or more pending requests.

2. Click the Reject action.

3. Enter a Rejection Reason (required).

4. Optionally add Admin Notes.

5. Confirm.

What happens:

• Status changes to Rejected

• rejection_reason is recorded and visible to the employee

• Leave balance: pending_days decreases

• Employee receives a notification

---

Cancelling a Leave Request

Requires the cancel leave requests permission. Both employees and administrators can cancel requests.

1. Select a pending or approved request.

2. Click the Cancel action.

3. Confirm.

What happens:

• Status changes to Cancelled

• If the request was pending: pending_days decreases

• If the request was approved: used_days decreases (days are returned)

Note: Only pending and approved requests can be cancelled. Rejected and already-cancelled requests cannot be cancelled.

---

Table Views

The leave requests list includes four pre-configured views:

View	Filter
All Leave Requests	No filter
Pending Requests	Status = Pending
Approved Requests	Status = Approved
Rejected Requests	Status = Rejected

Available Filters

• Status — Pending, Approved, Rejected, Cancelled

• Start Date — date range

• End Date — date range

• Days — numeric range

---

Notifications

The system sends email notifications at key points in the leave request lifecycle:

When a Request is Submitted

A notification is sent to all users who have the approve leave requests permission. The email includes:

• Employee name and email

• Leave type, start/end dates, total days

• Reason (if provided)

• Link to view the request

When a Request Status Changes

The employee receives a notification when their request is approved, rejected, or cancelled. The email includes:

• Leave type, dates, and total days

• New status

• Rejection reason (if rejected)

• Approver's name

• Link to view the request

Email templates can be customized from Settings > Email Accounts > Templates.

---

Dashboard Cards

The leave management system provides three dashboard cards:

Card	Type	Description
Leave Requests by Status	Pie chart	Distribution of requests across statuses
Leave Requests by Type	Bar chart	Count of requests grouped by leave type
Pending Leave Requests	Table	Latest 15 pending requests requiring action

---

Approval & Rejection Workflow

The leave approval workflow controls how leave requests move from submission to resolution. The HRM module supports three workflow modes, configurable from the settings page.

---

Workflow Modes

Configure the workflow mode in Settings > HRM Configuration > Leave Management.

Single Level (Default)

The simplest workflow. One authorized user reviews and approves or rejects the request.

Employee → Submit → Manager/HR Approves or Rejects → Done

Any user with the approve leave requests permission can approve or reject requests.

Multi Level

Requests pass through multiple approval stages. This is suitable for organizations that require both a direct manager and HR sign-off.

Employee → Submit → Manager Approves → HR Approves → Done

Auto Approve

All leave requests are automatically approved on submission. No human review is needed.

Employee → Submit → Automatically Approved → Done

Tip: You can combine workflow modes with the Auto-Approve Leave Types setting to auto-approve specific types (e.g., Work From Home) while requiring approval for others (e.g., Annual Leave).

---

Auto-Approve for Specific Leave Types

Rather than auto-approving all requests, you can select specific leave types that bypass approval:

1. Go to Settings > HRM Configuration > Leave Management.

2. In Auto-Approve Leave Types, select the types (e.g., Work From Home, Compensatory Off).

3. Save.

When an employee submits a request for an auto-approved leave type:

• The status is immediately set to Approved.

• The leave balance is updated (used_days increased directly, no pending_days step).

• No notification is sent to managers.

• The employee does not receive an approval notification (since it's instant).

Requests for non-auto-approved leave types follow the standard approval workflow regardless of this setting.

---

Balance Updates by Action

Action	Pending Days	Used Days	Available Days
Submit request	+days	—	decreases
Approve request	-days	+days	unchanged
Reject request	-days	—	increases
Cancel (was pending)	-days	—	increases
Cancel (was approved)	—	-days	increases

---

Who Can Approve

Approval actions are controlled by the approve leave requests permission. This permission must be explicitly granted to a role — it is not included in the default Employee role.

Typical roles that should have this permission:

• HR Manager

• Department Head

• Team Lead

• Any administrator role

Super administrators can always approve requests (bypassed via Gate::before).

---

Rejection Reasons

When rejecting a leave request, a Rejection Reason is required. This reason is:

• Stored on the leave request record

• Visible to the employee in their leave request detail view

• Included in the status change notification email

Administrators can also add Admin Notes during approval or rejection. Admin notes are only visible to other administrators, never to the employee.

---

Cancelling a Leave Request

Employees and administrators can cancel leave requests that are in Pending or Approved status. Cancellation restores the consumed or reserved leave days back to the employee's balance.

---

Who Can Cancel

Cancellation requires the cancel leave requests permission. By default, employees have this permission and can cancel their own requests.

User	Can Cancel Own	Can Cancel Others
Employee	Yes (with permission)	No (data scoping prevents seeing others)
Administrator	Yes	Yes (if they have the permission)
Super Admin	Yes	Yes (bypasses all checks)

---

How to Cancel

1. Navigate to Leave Requests.

2. Find the request to cancel (must be Pending or Approved).

3. Click the Cancel Leave action (shown inline in the actions column).

4. Confirm the cancellation.

---

What Happens When Cancelled

Cancelling a Pending Request

Before: pending_days = 5, used_days = 10, available_days = 3 Cancel 2-day pending request After: pending_days = 3, used_days = 10, available_days = 5

• pending_days decreases by the request's days

• available_days increases accordingly

• The request status changes to Cancelled

Cancelling an Approved Request

Before: pending_days = 3, used_days = 12, available_days = 3 Cancel 2-day approved request After: pending_days = 3, used_days = 10, available_days = 5

• used_days decreases by the request's days

• available_days increases accordingly

• The request status changes to Cancelled

---

Restrictions

• Rejected requests cannot be cancelled (they're already resolved).

• Already cancelled requests cannot be cancelled again.

• The Cancel action button only appears for requests in Pending or Approved status.

---

Overlap Validation

The HRM module prevents employees from submitting leave requests that overlap with their existing approved or pending requests. This ensures accurate leave tracking and prevents double-booking of time off.

---

How It Works

When a leave request is created or updated, the system checks for overlapping date ranges:

1. Queries all leave requests for the same employee.

2. Filters to only approved and pending requests (rejected and cancelled are ignored).

3. When editing, excludes the current request from the check.

4. Tests for overlap using the formula: existing_start ≤ new_end AND new_start ≤ existing_end.

If an overlap is found, the request is rejected with a validation error.

---

Examples

Blocked (Overlap)

Existing Request	New Request	Result
Jan 10–12 (Approved)	Jan 11–14	Blocked — overlaps on Jan 11–12
Jan 15–15 (Pending)	Jan 15–15	Blocked — exact same date
Jan 1–31 (Approved)	Jan 10–10	Blocked — contained within existing range

Allowed (No Overlap)

Existing Request	New Request	Result
Jan 10–12 (Approved)	Jan 13–15	Allowed — adjacent but not overlapping
Jan 10–12 (Rejected)	Jan 10–12	Allowed — rejected requests are ignored
Jan 10–12 (Cancelled)	Jan 10–12	Allowed — cancelled requests are ignored

---

Cross-Type Overlap

Overlap validation applies across all leave types. An employee cannot have overlapping Annual Leave and Sick Leave requests — the dates must not conflict regardless of the leave type.

---

Leave Carryover

Leave Carryover allows unused leave days from one fiscal year to be carried forward to the next. This feature is configurable at both the global level (settings) and the individual leave type level.

---

How Carryover Works

At the end of each fiscal year, the system processes carryover for all employees:

1. For each employee's leave balance from the ending year:

   • Checks if the leave type has Carry Forward enabled.

   • Calculates unused days: total_days - used_days - pending_days.

   • Applies the carryover cap (the lesser of the leave type's Max Carry Forward Days and the global Max Carryover Days setting).

   • Creates or updates the next year's leave balance with the Carried Forward Days.

2. Carried-forward days have an expiry based on the Carryover Expiry setting.

---

Configuration

Global Settings

Navigate to Settings > HRM Configuration > Leave Management:

Setting	Default	Description
Carryover Enabled	Yes	Master switch for the carryover feature
Max Carryover Days	10	Global cap on carried-forward days across all leave types
Carryover Expiry (months)	3	Carried-forward days expire this many months into the new fiscal year

Per Leave Type Settings

Each leave type has its own carryover configuration:

Field	Description
Carry Forward	Enable/disable carryover for this specific leave type
Max Carry Forward Days	Maximum days that can carry forward for this type

The effective carryover cap is the lesser of the leave type limit and the global limit.

Example: Leave type allows 10 days carry forward, but global max is 5. Only 5 days will carry over.

---

Processing Carryover

Carryover is processed automatically via a scheduled command that runs on the first day of the fiscal year start month:

php artisan hrm:process-leave-carryover

Carryover Expiry

Carried-forward days are not permanent — they expire after a configurable period. Once expired, they are no longer counted in the available balance.