Skip to main content

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โ€‹

StatusBadgeDescription
PendingYellowAwaiting approval. Balance is reserved in pending_days.
ApprovedGreenApproved by a manager. Days moved from pending_days to used_days.
RejectedRedRejected by a manager. Days removed from pending_days.
CancelledGrayCancelled 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:

SettingOptionsDefault
Approval WorkflowSingle Level / Multi Level / Auto ApproveSingle Level
Auto-Approve Leave TypesSelect specific leave typesNone

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

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:

ViewFilter
All Leave RequestsNo filter
Pending RequestsStatus = Pending
Approved RequestsStatus = Approved
Rejected RequestsStatus = 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:

CardTypeDescription
Leave Requests by StatusPie chartDistribution of requests across statuses
Leave Requests by TypeBar chartCount of requests grouped by leave type
Pending Leave RequestsTableLatest 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โ€‹

ActionPending DaysUsed DaysAvailable Days
Submit request+daysโ€”decreases
Approve request-days+daysunchanged
Reject request-daysโ€”increases
Cancel (was pending)-daysโ€”increases
Cancel (was approved)โ€”-daysincreases

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.

UserCan Cancel OwnCan Cancel Others
EmployeeYes (with permission)No (data scoping prevents seeing others)
AdministratorYesYes (if they have the permission)
Super AdminYesYes (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 RequestNew RequestResult
Jan 10โ€“12 (Approved)Jan 11โ€“14Blocked โ€” overlaps on Jan 11โ€“12
Jan 15โ€“15 (Pending)Jan 15โ€“15Blocked โ€” exact same date
Jan 1โ€“31 (Approved)Jan 10โ€“10Blocked โ€” contained within existing range

Allowed (No Overlap)โ€‹

Existing RequestNew RequestResult
Jan 10โ€“12 (Approved)Jan 13โ€“15Allowed โ€” adjacent but not overlapping
Jan 10โ€“12 (Rejected)Jan 10โ€“12Allowed โ€” rejected requests are ignored
Jan 10โ€“12 (Cancelled)Jan 10โ€“12Allowed โ€” 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:

SettingDefaultDescription
Carryover EnabledYesMaster switch for the carryover feature
Max Carryover Days10Global cap on carried-forward days across all leave types
Carryover Expiry (months)3Carried-forward days expire this many months into the new fiscal year

Per Leave Type Settingsโ€‹

Each leave type has its own carryover configuration:

FieldDescription
Carry ForwardEnable/disable carryover for this specific leave type
Max Carry Forward DaysMaximum 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.