ERPNext Hooks - Implementation

This skill helps you determine HOW to implement hooks.py configurations. For exact syntax, see

erpnext-syntax-hooks

.

Version

v14/v15/v16 compatible (with V16-specific features noted)

Main Decision: What Are You Trying to Do?

┌─────────────────────────────────────────────────────────────────────────┐

│ WHAT DO YOU WANT TO ACHIEVE? │

├─────────────────────────────────────────────────────────────────────────┤

│ │

│ ► React to document events on OTHER apps' DocTypes? │

│ └── doc_events in hooks.py │

│ │

│ ► Run code periodically (hourly, daily, custom schedule)? │

│ └── scheduler_events │

│ │

│ ► Modify behavior of existing DocType controller? │

│ ├── V16+: extend_doctype_class (RECOMMENDED - multiple apps work) │

│ └── V14/V15: override_doctype_class (last app wins) │

│ │

│ ► Modify existing API endpoint behavior? │

│ └── override_whitelisted_methods │

│ │

│ ► Add custom permission logic? │

│ ├── List filtering: permission_query_conditions │

│ └── Document-level: has_permission │

│ │

│ ► Send data to client on page load? │

│ └── extend_bootinfo │

│ │

│ ► Export/import configuration between sites? │

│ └── fixtures │

│ │

│ ► Add JS/CSS to desk or portal? │

│ ├── Desk: app_include_js/css │

│ ├── Portal: web_include_js/css │

│ └── Specific form: doctype_js │

│ │

└─────────────────────────────────────────────────────────────────────────┘

Decision Tree: doc_events vs Controller Methods

WHERE IS THE DOCTYPE?

│

├─► DocType is in YOUR custom app?

│ └─► Use controller methods (doctype/xxx/xxx.py)

│ - Direct control over lifecycle

│ - Cleaner code organization

│

├─► DocType is in ANOTHER app (ERPNext, Frappe)?

│ └─► Use doc_events in hooks.py

│ - Only way to hook external DocTypes

│ - Can register multiple handlers

│

└─► Need to hook ALL DocTypes (logging, audit)?

└─► Use doc_events with wildcard "*"

Rule

Controller methods for YOUR DocTypes, doc_events for OTHER apps' DocTypes. Decision Tree: Which doc_event? WHAT DO YOU NEED TO DO? │ ├─► Validate data or calculate fields? │ ├─► Before any save → validate │ └─► Only on new documents → before_insert │ ├─► React after document is saved? │ ├─► Only first save → after_insert │ ├─► Every save → on_update │ └─► ANY change (including db_set) → on_change │ ├─► Handle submittable documents? │ ├─► Before submit → before_submit │ ├─► After submit → on_submit (ledger entries here) │ ├─► Before cancel → before_cancel │ └─► After cancel → on_cancel (reverse entries here) │ ├─► Handle document deletion? │ ├─► Before delete (can prevent) → on_trash │ └─► After delete (cleanup) → after_delete │ └─► Handle document rename? ├─► Before rename → before_rename └─► After rename → after_rename Decision Tree: Scheduler Event Type HOW LONG DOES YOUR TASK RUN? │ ├─► < 5 minutes │ │ │ │ HOW OFTEN? │ ├─► Every ~60 seconds → all │ ├─► Every hour → hourly │ ├─► Every day → daily │ ├─► Every week → weekly │ ├─► Every month → monthly │ └─► Specific time → cron │ └─► > 5 minutes (up to 25 minutes) │ │ HOW OFTEN? ├─► Every hour → hourly_long ├─► Every day → daily_long ├─► Every week → weekly_long └─► Every month → monthly_long ⚠️ Tasks > 25 minutes: Split into chunks or use background jobs Decision Tree: Override vs Extend (V16) FRAPPE VERSION? │ ├─► V16+ │ │ │ │ WHAT DO YOU NEED? │ ├─► Add methods/properties to DocType? │ │ └─► extend_doctype_class (RECOMMENDED) │ │ - Multiple apps can extend same DocType │ │ - Safer, less breakage on updates │ │ │ └─► Completely replace controller logic? │ └─► override_doctype_class (use sparingly) │ └─► V14/V15 └─► override_doctype_class (only option) ⚠️ Last installed app wins! ⚠️ Always call super() in methods! Implementation Workflow: doc_events Step 1: Add to hooks.py

myapp/hooks.py

doc_events

{ "Sales Invoice" : { "validate" : "myapp.events.sales_invoice.validate" , "on_submit" : "myapp.events.sales_invoice.on_submit" } } Step 2: Create handler module

myapp/events/sales_invoice.py

import frappe def validate ( doc , method = None ) : """ Args: doc: The document object method: Event name ("validate") Changes to doc ARE saved (before save event) """ if doc . grand_total < 0 : frappe . throw ( "Total cannot be negative" )

Calculate custom field

doc . custom_margin = doc . grand_total - doc . total_cost def on_submit ( doc , method = None ) : """ After submit - document already saved Use frappe.db.set_value for additional changes """ create_external_record ( doc ) Step 3: Deploy bench --site sitename migrate Implementation Workflow: scheduler_events Step 1: Add to hooks.py

myapp/hooks.py

scheduler_events

{ "daily" : [ "myapp.tasks.daily_cleanup" ] , "daily_long" : [ "myapp.tasks.heavy_processing" ] , "cron" : { "0 9 * * 1-5" : [ "myapp.tasks.weekday_report" ] } } Step 2: Create task module

myapp/tasks.py

import frappe def daily_cleanup ( ) : """NO arguments - scheduler calls with no args""" old_logs = frappe . get_all ( "Error Log" , filters = { "creation" : [ "<" , frappe . utils . add_days ( None , - 30 ) ] } , pluck = "name" ) for name in old_logs : frappe . delete_doc ( "Error Log" , name ) def heavy_processing ( ) : """Long task - use _long variant in hooks""" for batch in get_batches ( ) : process_batch ( batch ) frappe . db . commit ( )

Commit per batch for long tasks

Step 3: Deploy and verify bench --site sitename migrate bench --site sitename scheduler enable bench --site sitename scheduler status Implementation Workflow: extend_doctype_class (V16+) Step 1: Add to hooks.py

myapp/hooks.py

extend_doctype_class

{ "Sales Invoice" : [ "myapp.extensions.SalesInvoiceMixin" ] } Step 2: Create mixin class

myapp/extensions.py

import frappe from frappe . model . document import Document class SalesInvoiceMixin ( Document ) : """Mixin that extends Sales Invoice""" @property def profit_margin ( self ) : """Add computed property""" if self . grand_total : return ( ( self . grand_total - self . total_cost ) / self . grand_total ) * 100 return 0 def validate ( self ) : """Extend validation - ALWAYS call super()""" super ( ) . validate ( ) self . validate_margin ( ) def validate_margin ( self ) : """Custom validation logic""" if self . profit_margin < 10 : frappe . msgprint ( "Warning: Low margin invoice" ) Step 3: Deploy bench --site sitename migrate Implementation Workflow: Permission Hooks Step 1: Add to hooks.py

myapp/hooks.py

permission_query_conditions

{ "Sales Invoice" : "myapp.permissions.si_query" } has_permission = { "Sales Invoice" : "myapp.permissions.si_permission" } Step 2: Create permission handlers

myapp/permissions.py

import frappe def si_query ( user ) : """ Returns SQL WHERE clause for list filtering. ONLY works with get_list, NOT get_all! """ if not user : user = frappe . session . user if "Sales Manager" in frappe . get_roles ( user ) : return ""

No filter - see all

Regular users see only their own

return f"tabSales Invoice.owner = { frappe . db . escape ( user ) } " def si_permission ( doc , user = None , permission_type = None ) : """ Document-level permission check. Return: True (allow), False (deny), None (use default) NOTE: Can only DENY, not grant additional permissions! """ if permission_type == "write" and doc . status == "Closed" : return False

Deny write on closed invoices

return None

Use default permission system

Quick Reference: Handler Signatures Hook Signature doc_events def handler(doc, method=None): rename events def handler(doc, method, old, new, merge): scheduler_events def handler(): (no args) extend_bootinfo def handler(bootinfo): permission_query def handler(user): → returns SQL string has_permission def handler(doc, user=None, permission_type=None): → True/False/None override methods Must match original signature exactly Critical Rules 1. Never commit in doc_events

❌ WRONG - breaks transaction

def on_update ( doc , method = None ) : frappe . db . commit ( )

✅ CORRECT - Frappe commits automatically

def on_update ( doc , method = None ) : update_related ( doc ) 2. Use db_set_value after on_update

❌ WRONG - change is lost

def on_update ( doc , method = None ) : doc . status = "Processed"

✅ CORRECT

def on_update ( doc , method = None ) : frappe . db . set_value ( doc . doctype , doc . name , "status" , "Processed" ) 3. Always call super() in overrides

❌ WRONG - breaks core functionality

class CustomInvoice ( SalesInvoice ) : def validate ( self ) : self . my_validation ( )

✅ CORRECT

class CustomInvoice ( SalesInvoice ) : def validate ( self ) : super ( ) . validate ( )

FIRST!

self . my_validation ( ) 4. Always migrate after hooks changes

Required after ANY hooks.py change

bench --site sitename migrate 5. permission_query only works with get_list

❌ NOT filtered by permission_query_conditions

frappe . db . get_all ( "Sales Invoice" , filters = { } )

✅ Filtered by permission_query_conditions

frappe . db . get_list ( "Sales Invoice" , filters = { } ) Version Differences Feature V14 V15 V16 doc_events ✅ ✅ ✅ scheduler_events ✅ ✅ ✅ override_doctype_class ✅ ✅ ✅ extend_doctype_class ❌ ❌ ✅ permission hooks ✅ ✅ ✅ Scheduler tick 4 min 4 min 60 sec Reference Files File Contents decision-tree.md Complete hook selection flowcharts workflows.md Step-by-step implementation patterns examples.md Working code examples anti-patterns.md Common mistakes and solutions