🌴 How Leave Application Works

A complete guide — from an employee requesting a day off, to a manager approving it, to the balance being updated automatically.

🌍 The Big Picture

Imagine you work at a company and you want to take a week off. Here is what happens, from start to finish:

📋 Types of Leave

Not all leave is the same. HRSanad supports many different leave types. Each one has its own rules — how many days you get, whether you need to submit a document, whether you get paid during it, and whether the company allows you to take more than your balance.

What HR configures for each leave type

⚖️ Leave Balance — How It Builds Up

Your leave balance is not just one number. It is calculated from five parts that add up together:

How the balance grows — Monthly Accrual

For leave types with accrual_method = "monthly", HRSanad credits a portion of your annual entitlement on the last day of every month. A cron job runs automatically at 20:05 UTC each day and credits the right amount to every active employee.

Running balance over the year. The red May column shows where 7.5 days were taken, resetting the available balance back to 2.5 days after that month's accrual.

Entitlements — seniority-based rates

Employees who have worked longer may get more leave. HRSanad supports entitlement bands by years of service:

📱 How an Employee Applies for Leave

Employees apply through the ESS Portal (Employee Self-Service). This is a separate, secure web portal where each employee can only see their own data.

1. Log into the ESS Portal

   The employee visits the ESS portal and logs in using their work email address or their mobile number (the system detects which format was entered). After successful login they see their personal dashboard.

2. Check your leave balance first

   On the Leave section, the employee sees their current balance for each leave type — how many days they have available right now. This prevents them submitting a request they cannot take.

   API: GET /v1/ess/leave-balance

3. Click "Apply for Leave" and fill the form

   • Leave Type — pick from the list (Annual, Sick, Emergency…)
   • From Date / To Date — the dates you want off
   • Reason — a short explanation (optional for annual, mandatory for some types)
   • Supporting Document — required for types like Sick Leave
4. System runs instant checks before submitting

   Before saving the request, the system automatically verifies:

   • Do you have enough balance? (If negative_balance = false and balance is insufficient → blocked with an error)
   • Do you already have another approved or pending leave that overlaps these dates? (Overlap → blocked)
   • Is the advance notice requirement met? (e.g., annual leave requires 7 days notice)

   If any check fails, the employee sees a clear error and the request is not saved.

5. Request is saved as "Submitted"

   If all checks pass, the request is saved with status submitted. The balance is not deducted yet — it is only deducted when the manager approves it. This is important: a submitted request is a pending request, not a confirmed leave.

   API: POST /v1/ess/leave-requests

6. Employee can track the status

   From the ESS portal, the employee can see all their requests and their current statuses. They can also cancel a request (while it's still submitted or even after it's approved, before the leave starts).

   API: GET /v1/ess/leave-requests

✅ The Approval Workflow

Once a request is submitted, the approval workflow begins. The manager or HR team is responsible for reviewing and making a decision.

Who can approve leave?

The full status machine

Every leave request moves through a series of statuses. The diagram below shows every possible path:

What happens at each status transition

↩️ Returning Early — The "Resumed" Status

Life happens. Sometimes an employee is approved for 10 days of leave but comes back after 6. HRSanad handles this cleanly with the Resume action.

days_actually_taken = calendar_days(start_date → actual_return_date) - 1
days_resumed        = max(0, days_requested - days_actually_taken)
new_taken_balance   = old_taken - days_resumed

🛡️ Business Rules & Guardrails

The system enforces these rules automatically — HR does not need to check them manually.

existing leave with status NOT IN
  ('rejected', 'cancelled')
AND dates overlap with new request
→ BLOCKED (error returned)

days = floor((end_date - start_date)
             / 86400000) + 1

🔗 How Leave Connects to Attendance & Payroll

🖥️ The HR Admin View

HR managers have a separate admin console that shows all leave requests across the company. They can filter, search, approve, and reject from one screen.

Leave Requests Page — what HR sees

Filters available to HR

• Filter by status: All / Submitted / Approved / Rejected / Cancelled / Resumed
• Filter by employee name or code
• Filter by year
• Pagination: 25 requests per page

Leave Types Management

HR Admin can create, edit, and deactivate leave types from the Leave Types page. Key actions:

• Create new leave types with full configuration
• Set entitlement bands per grade and service length
• Toggle a leave type active or inactive (inactive types cannot be used in new requests)
• Manually adjust an employee's balance (add or subtract days) with an audit note

📆 End of Year — Carry Forward & Encashment

At the end of each calendar year, unused leave days need to be resolved. HRSanad supports two mechanisms:

🎬 Full Walkthrough — A Real Example

1. Sara checks her balance

   Sara logs into ESS. Her annual leave balance shows: 12.5 days available (8 months × 2.5 days accrued, minus 7.5 days she already took in March).

2. Sara submits the request

   She selects: Leave Type = Annual, From = 15 Sep, To = 19 Sep, Reason = "Family holiday". She clicks Submit.

   The system checks: No overlap with existing leaves ✓ | Balance 12.5 ≥ 5 ✓ | 28 days advance notice given ✓

   Request saved: status = submitted. Sara's available balance still shows 12.5 (not yet deducted).

3. Manager receives the request

   Sara's line manager logs into the admin console. He sees Sara's request in yellow. He checks the team calendar — no other team member is off those dates. He clicks Approve.

4. Balance deducted automatically

   The system deducts 5 days: taken += 5. Sara's balance drops from 12.5 to 7.5 days. Status changes to approved. Sara gets a notification.

5. Leave dates arrive

   On 15–19 September, the TNA system marks Sara as on_leave (not absent) for all 5 days. She does not need to clock in.

6. Payroll at end of September

   When payroll is calculated, the engine sees Sara had 5 days on_leave (paid). Annual leave is is_paid = true, so those 5 days count as full working days — no salary deduction. Sara receives her full September salary.

7. October accrual

   At end of September, the cron job credits another 2.5 days. Sara's balance is now 10.0 days again.

🔌 API Quick Reference

Employee (ESS) endpoints

HR Admin endpoints

📌 Status Reference Card