bench get-app https://github.com/Taha-Khouildi/frappe-leave-rules

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Taha-Khouildi%2Ffrappe-leave-rules)](https://frappegems.com/gems/apps/Taha-Khouildi/frappe-leave-rules)

Leave Rules for Frappe HRMS

A custom Frappe HRMS extension that adds configurable minimum advance-notice rules for Leave Applications without modifying HRMS core.

Problem and feature

Standard HRMS supports Leave Type policies and Leave Block Lists, but it does not let an administrator require each Leave Type to be requested a configurable number of days in advance. Leave Rules adds that missing server-side policy, with optional company-specific overrides.

Examples:

• Annual-style leave can require 15 calendar days.
• Casual Leave can require 3 calendar days.
• Sick Leave can allow same-day requests with 0 days.

Architecture

Leave Application
       |
       v
Frappe validate lifecycle
       |
       v
leave_rules doc_events hook
       |
       v
validate_advance_notice()
       |
       v
Find exact-company rule, then global fallback
       |
       v
Calculate from_date - posting_date in calendar days
       |
       v
Enough notice?
    /       \
  Yes       No
   |         |
Continue   frappe.throw()

All custom behavior lives in this app. The hook augments the normal controller lifecycle; it does not override or patch Frappe, ERPNext, or HRMS classes.

Installation

Install from a Git repository in a normal Bench:

cd /home/frappe/frappe-bench
bench get-app https://github.com/your-org/leave_rules.git
bench --site your-site install-app leave_rules
bench --site your-site migrate

For this Docker project, source is persisted on the host and soft-linked into Bench:

cd /home/ahat/hrms/docker
docker compose exec frappe bash -lc '
  cd /home/frappe/frappe-bench
  bench get-app --soft-link /workspace/leave_rules
  bench --site hrms.localhost install-app leave_rules
  bench --site hrms.localhost migrate
'

The host checkout is /home/ahat/hrms/docker/leave_rules, exposed inside the container as /workspace/leave_rules. Bench resolves apps/leave_rules to that host-owned source.

Configuration

In Desk, open Leave Advance Notice Rule and create a record:

Field	Example	Meaning
Leave Type	Privilege Leave	Leave Type governed by the rule
Minimum Notice Days	10	Required calendar-day interval
Company	Test Company (Demo)	Optional exact-company scope
Enabled	Yes	Whether the rule participates in lookup
Description	Annual leave notice	Optional administrator note

An exact-company rule takes priority. If none exists, an enabled global rule with no Company is used. If neither exists, standard HRMS behavior continues unchanged.

Only one enabled rule may exist for a Leave Type and scope. Disabled duplicates are allowed, but cannot be enabled while another active rule conflicts.

Calculation example

Posting Date:        01/09/2026
Leave Start:         20/09/2026
Actual Notice:       19 calendar days
Required Notice:     10 calendar days
Result:              accepted

A start date of 05/09/2026 supplies only 4 days and is rejected with a clear French message. Weekends and holidays are counted. A 0-day rule permits a same-day request.

Demo

The repeatable helper uses the existing demo employee, company, and Privilege Leave master. It ensures a valid submitted allocation and 10-day rule, persists the accepted case, and attempts the rejected case through normal Leave Application insertion:

cd /home/ahat/hrms/docker
docker compose exec frappe bash -lc '
  cd /home/frappe/frappe-bench
  bench --site hrms.localhost execute leave_rules.demo.run_demo
'

Expected results:

• Posting 01/09/2026, start 20/09/2026: 19 days, accepted.
• Posting 01/09/2026, start 05/09/2026: 4 days, rejected.

Testing

cd /home/ahat/hrms/docker
docker compose exec frappe bash -lc '
  cd /home/frappe/frappe-bench
  bench --site hrms.localhost set-config allow_tests true
  bench --site hrms.localhost run-tests \
    --module leave_rules.leave_rules.doctype.leave_advance_notice_rule.test_leave_advance_notice_rule \
    --skip-before-tests --lightmode
  bench --site hrms.localhost run-tests --app leave_rules \
    --skip-before-tests --lightmode
  bench --site hrms.localhost set-config allow_tests false
'

Tests cover rule selection and precedence, threshold boundaries, disabled and unrelated rules, negative and duplicate configuration, permissions, French error content, hook registration, and a real Leave Application insertion.

Why doc_events and validate

doc_events is Frappe's supported extension point for adding behavior to an existing DocType without modifying its controller. Server-side validate covers Desk, APIs, imports, background jobs, and other save paths before the document is written or submitted. Normal HRMS validation still runs.

Compatibility

• Frappe Framework: version 17 development branch used by this project
• ERPNext: version 17 development branch used by this project
• Frappe HRMS: version 17 development branch used by this project
• Python: follows the active Bench runtime

Pin and test exact upstream versions before production deployment.

Limitations

• Notice is measured in calendar days, not working days.
• Rules apply to all employees matching Leave Type and company; there are no department, grade, or employee exceptions.
• Administrators must maintain rules in Desk; there is no bulk policy wizard.
• The policy does not replace HRMS Leave Block Lists or other Leave Type validations.

Future improvements

• Working-day calculation using the employee's Holiday List
• Role-based emergency override with audit history
• Department, branch, grade, or employee-specific scopes
• Client-side preview of required and supplied notice before save
• Policy reports and notification reminders

Screenshots

Configurable advance-notice rule

Administrators can set a minimum notice period for a Leave Type and optionally scope it to one Company.

Valid leave allocation

The employee has a submitted Privilege Leave allocation covering the demonstration period, so normal HRMS allocation validation remains active.

Insufficient notice rejected

With a posting date of 01/09/2026 and leave starting on 05/09/2026, only 4 calendar days are supplied against the required 10 days. The server-side hook blocks the save with a clear French message.

Sufficient notice accepted

A Privilege Leave application starting on 21/09/2026 supplies 20 calendar days of notice and saves normally as an open application.

Additional evidence recommended for a technical report:

1. Host leave_rules source tree
2. hooks.py and validations.py
3. Passing automated tests
4. bench --site hrms.localhost list-apps

License

MIT. See license.txt.