Leave Management — One-Stop Guide

1. How to open leave for the first time

Employee / manager path

1. Sign in

   Use an account on a team where leave is enabled.

2. Open People → Leave management

   Direct URL: /people/leaves (legacy /hrms/leaves redirects here).

3. Confirm balances appear

   Balance cards show PL/CL/SL (and specials). Empty cards usually mean opening balances were never imported and accrual has not run yet — not a UI bug.

4. Apply

   Use Apply leave / create drawer: pick type, dates, half-day if needed, notes/docs, then submit.

Admin first-time path (before anyone applies)

1. Application Config — turn on org + role leave flags (§3).
2. Global Policy Center — publish a policy (§4–5).
3. Holidays + working-day rules (§8).
4. Employee leave config — dry-run OB import, then live (§9–10).
5. Enable schedulers ACCRUAL / CF / COMP_OFF_EXPIRE (§11).
6. Prove apply → approve on a test employee (§12–13).

2. Big picture — configure then use

flowchart LR
  A[App Config flags] --> B[Publish policy]
  B --> C[Holidays + working days]
  C --> D[Opening balances / accrual]
  D --> E[Employee applies]
  E --> F[Manager / delegate approves]
  F --> G[Balance debit + timesheet + attendance]
            

3. What must be configured (flags)

Path: Admin → Application configuration → select the org unit / team → HRMS / Modules / role templates.

Org flags (leaveAdditional)

Role modules

• peopleModules.leavesEnabled — shows People → Leave management
• peopleModules.holidaysEnabled — People → Holidays
• adminModules.leavePoliciesEnabled — classic policies + Employee leave config
• adminModules.globalLeavePoliciesEnabled — Global Policy Center, Test Lab, legal calendars, working-day rules
• Manager: approveTeamEnabled — required for approve actions
• Optional: universalApprovalInboxEnabled — leave in /workspace/approvals

Menu rule: UI needs org leaveManagementEnabled and role peopleModules.leavesEnabled. APIs gate on the org flag only.

4. What to update — admin screen map

5. How to create / publish a new leave policy

Primary console: Admin → Leave admin → Global Policy Center.

1. Create or select a jurisdiction

   Examples: IN, IN-KA, IN-MH, AE. Used for resolve, holiday calendars, and working-day scope.

2. Apply a country / CFA template into a draft

   Choose CFA-IN-KA, CFA-IN-MH, CFA-IN-HR, CFA-IN-TN-CBE, or a blank draft. Edit entitlements, accrual, carry-forward, and special-leave JSON while unpublished.

3. Simulate / Policy Test Lab

   Dry-run resolve for a sample employee. Lab scenarios may gate publish. Open /admin/leave/policy-test-lab.

4. Assign holiday calendar key

   Key must match People → Holidays location keys (e.g. IN-KA).

5. Configure working-day rules

   Team default, jurisdiction pattern (e.g. Mon–Fri or Sun–Thu), or employee override.

6. Publish the version

   Published versions are immutable. To change rules later, clone a new draft and publish again. Publish activates accrual eligibility — it does not create balances.

flowchart TD
  J[Jurisdiction] --> T[Apply template]
  T --> D[Edit draft version]
  D --> S[Simulate / Test Lab]
  S --> H[Holiday key + WDR]
  H --> P[Publish]
  P --> R[Accrual + eligibility live]
            

APIs (for automation / support): jurisdictions POST /api/v2/leave/global/jurisdictions · apply template POST /api/v2/leave/global/templates/{id}/apply · simulate POST /api/v2/leave/global/simulate · publish POST /api/v2/leave/global/versions/{versionId}/publish.

6. Supported leave policies — how each is configured

PL means Privilege Leave (earned) — not paternity. Paternity is PATERNITY.

7. CFA India location packs (defaults)

Production prefill: migration 09-cfa-leave-india-production-prefill.sql. Resolve uses employee work location / jurisdiction.

Shared: MATERNITY / PATERNITY / MSL / COMPOFF / FLOATING; PL CF max 45 with excess LAPSE by default.

8. Holidays & working days

Holidays

1. Create holidays in People → Holidays with a Location key (e.g. ["IN-KA"]).
2. Assign that key to the jurisdiction in Global Policy Center → Holiday calendars.
3. Optional: publish Legal Calendars so official holidays sync into People holidays.

Working-day resolution (priority)

flowchart TD
  L[Leave create / submit] --> R[LeaveWorkingDayResolver]
  R --> O{Employee WDR override?}
  O -->|Yes| P[Resolved workdays]
  O -->|No| J{Employee jurisdiction?}
  J -->|Yes| JW[Jurisdiction WDR]
  JW --> P
  J -->|No| TW[Team-default WDR]
  TW -->|Hit| P
  TW -->|Miss| FB[Work schedule / shift / Mon-Fri]
  FB --> P
            

9. Opening balances, Adjust, and dry-run

Canonical page: Admin → Employee leave config (/admin/employee-leave-config).

1. Select the team in the header filter so employees load.
2. Download OB template (Opening balance template panel / header button). Rows are employee × leave type (PL/CL/SL by location). entitlementAmount and amount start blank — fill from ZingHR / HR export only.
3. Dry-run import (never skips this)

   POST /api/v2/admin/data-import/leave-balance?userTeamId={team}&actorId={you}&dryRun=true

   Body may also include "dryRun": true (query wins). Dry-run validates only — no writes. Fix failures from reportCsv / results[].

4. Live import — same endpoint with dryRun=false only after dry-run is clean.
5. Single employee correction — select person → Adjust balance (opening entitlement and/or +/− available days) with a reason. Adjustments of 5+ days require a second confirmer employee id.
6. Spot-check balance cards, then prove apply on People → Leaves.

CSV columns (template)

userTeamId, employeeId, empCode, location, suggestedPack, leaveTypeCode, leaveTypeId, entitlementAmount, amount, comment

Aliases accepted: PAT→PATERNITY, MAT→MATERNITY, COFF→COMPOFF.

flowchart TD
  AP[Published policy] --> AJ[LEAVE_ACCRUAL job]
  AJ --> BL1[Ledger credit ACCRUAL]
  HR[OB import / Adjust] --> BL2[Ledger ADJUST_HR]
  BL1 --> UI[Visible on Leave Management]
  BL2 --> UI
            

10. Make sure leaves are assigned to every employee

“Assigned” means each active employee has: (1) a resolved published policy / jurisdiction, (2) leave type balances on the ledger, (3) correct holiday + working-day resolution.

1. Confirm published policy for the team / jurisdictions covering all work locations.
2. Assign jurisdictions (and WDR overrides if needed) for employees whose location differs from team default.
3. Bulk OB import for cutover so every employee × PL/CL/SL row exists — do not invent amounts.
4. For new joiners after cutover — either Adjust on hire, include them in a follow-up import, or rely on monthly LEAVE_ACCRUAL once entitlement rules apply.
5. Verify coverage — on Employee leave config, sample employees across locations; KPI strip shows low-balance / pending signals.
6. Smoke apply as 2–3 employees from different packs (e.g. KA vs MH) before broad rollout.

11. How schedulers pick and execute policies

Jobs live in fs_schedule_model. Enable via production migration 11-cfa-leave-schedules-enable.sql. Manual run (ops): POST /api/v2/admin/jobs/{scheduleType}/run?userTeamId=.

If leaveManagementEnabled is false, jobs exit as SKIPPED. Check last run status on the schedule row and the accrual-source banner in Global Policy Center.

12. How employees apply for leave

1. Open People → Leave management.
2. Review balance cards for the leave type you need.
3. Click Apply leave. Choose type (PL/CL/SL/special/floating), start/end, half-day if allowed, reason, and required documents.
4. Confirm day count (server recalculates — holidays and weekly offs are excluded).
5. Submit. System validates overlap, working days, special rules, documents, and balance; then places a pending hold on the balance and notifies the approver.
6. Track status on the same page (CREATED → SUBMITTED → APPROVED / REJECTED). Withdraw is allowed for draft/submitted only.

Floating: you must pick a published catalogue option. Maternity: child number maps duration. Comp-off: uses credited bank entries with expiry.

13. Leave request approval process

flowchart TD
  C[CREATE draft] --> S[SUBMIT]
  S --> H[Reserve PENDING_HOLD]
  H --> N[Notify approver]
  N --> D{Approve or Reject?}
  D -->|Approve| A[Debit DEBIT_APPROVE]
  A --> P[Promote TaskActivity LEAVE]
  P --> T[Optional attendance sync]
  D -->|Reject| R[Release hold + comment]
            

Who can approve

• Reporting manager with approveTeamEnabled — via ApprovalAuthorityService.canAct(..., LEAVE).
• Delegate when approval delegation is enabled and scope includes LEAVE.
• HR / admin where role policy allows acting in scope (see Approvals inbox / leave pending panel).

Where to approve

1. People → Leave management — Pending approvals panel for requests in your scope.
2. Workspace → Approvals (/workspace/approvals) when universal inbox is enabled.
3. Approve or reject. Reject requires a comment; pending balance is released.
4. On approve: ledger debit, promote leave days to timesheet TaskActivities, optional attendance LEAVE / HALF_DAY marks.

After approval — cancel / promotion failures

• Cancel (after approve) credits balance back and reverses promotion where supported.
• If timesheet rows are missing, check promotionStatus, GET /api/v2/leaves/.../promotion-failures, and schedule LEAVE_PROMOTION_RETRY. Manual: POST /api/v2/leaves/{id}/promote.

14. Go-live checklist

Check items locally in the browser (saved only on this device).

15. FAQ & common mistakes