ERPNext Controllers - Implementation

This skill helps you determine HOW to implement server-side DocType logic. For exact syntax, see

erpnext-syntax-controllers

.

Version

v14/v15/v16 compatible

Main Decision: Controller vs Server Script?

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

│ WHAT DO YOU NEED? │

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

│ │

│ ► Import external libraries (requests, pandas, numpy) │

│ └── Controller ✓ │

│ │

│ ► Complex multi-document transactions with rollback │

│ └── Controller ✓ │

│ │

│ ► Full Python power (try/except, classes, generators) │

│ └── Controller ✓ │

│ │

│ ► Extend/override standard ERPNext DocType │

│ └── Controller (override_doctype_class in hooks.py) │

│ │

│ ► Quick validation without custom app │

│ └── Server Script │

│ │

│ ► Simple auto-fill or calculation │

│ └── Server Script │

│ │

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

Rule

Controllers for custom apps with full Python power. Server Scripts for quick no-code solutions. Decision Tree: Which Hook? WHAT DO YOU WANT TO DO? │ ├─► Validate data or calculate fields before save? │ └─► validate │ NOTE: Changes to self ARE saved │ ├─► Action AFTER save (emails, linked docs, logs)? │ └─► on_update │ ⚠️ Changes to self are NOT saved! Use db_set instead │ ├─► Only for NEW documents? │ └─► after_insert │ ├─► Only for SUBMIT (docstatus 0→1)? │ ├─► Check before submit? → before_submit │ └─► Action after submit? → on_submit │ ├─► Only for CANCEL (docstatus 1→2)? │ ├─► Prevent cancel? → before_cancel │ └─► Cleanup after cancel? → on_cancel │ ├─► Before DELETE? │ └─► on_trash │ ├─► Custom document naming? │ └─► autoname │ └─► Detect any change (including db_set)? └─► on_change → See references/decision-tree.md for complete decision tree with all hooks. CRITICAL: Changes After on_update ┌─────────────────────────────────────────────────────────────────────┐ │ ⚠️ CHANGES TO self AFTER on_update ARE NOT SAVED │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ❌ WRONG - This does NOTHING: │ │ def on_update(self): │ │ self.status = "Completed" # NOT SAVED! │ │ │ │ ✅ CORRECT - Use db_set: │ │ def on_update(self): │ │ frappe.db.set_value(self.doctype, self.name, │ │ "status", "Completed") │ │ │ └─────────────────────────────────────────────────────────────────────┘ Hook Comparison: validate vs on_update Aspect validate on_update When Before DB write After DB write Changes to self ✅ Saved ❌ NOT saved Can throw error ✅ Aborts save ⚠️ Already saved Use for Validation, calculations Notifications, linked docs get_doc_before_save() ✅ Available ✅ Available Common Implementation Patterns Pattern 1: Validation with Error def validate ( self ) : if not self . items : frappe . throw ( _ ( "At least one item is required" ) ) if self . from_date

self . to_date : frappe . throw ( _ ( "From Date cannot be after To Date" ) ) Pattern 2: Auto-Calculate Fields def validate ( self ) : self . total = sum ( item . amount for item in self . items ) self . tax_amount = self . total * 0.1 self . grand_total = self . total + self . tax_amount Pattern 3: Detect Field Changes def validate ( self ) : old_doc = self . get_doc_before_save ( ) if old_doc and old_doc . status != self . status : self . flags . status_changed = True def on_update ( self ) : if self . flags . get ( 'status_changed' ) : self . notify_status_change ( ) Pattern 4: Post-Save Actions def on_update ( self ) :

Update linked document

if self . linked_doc : frappe . db . set_value ( "Other DocType" , self . linked_doc , "status" , "Updated" )

Send notification (never fails the save)

try : self . send_notification ( ) except Exception : frappe . log_error ( "Notification failed" ) Pattern 5: Custom Naming from frappe . model . naming import getseries def autoname ( self ) :

Format: CUST-ABC-001

prefix

f"CUST- { self . customer [ : 3 ] . upper ( ) } -" self . name = getseries ( prefix , 3 ) → See references/workflows.md for more implementation patterns. Submittable Documents Workflow DRAFT (docstatus=0) │ ├── save() → validate → on_update │ └── submit() │ ├── validate ├── before_submit ← Last chance to abort ├── [DB: docstatus=1] ├── on_update └── on_submit ← Post-submit actions SUBMITTED (docstatus=1) │ └── cancel() │ ├── before_cancel ← Last chance to abort ├── [DB: docstatus=2] ├── on_cancel ← Reverse actions └── [check_no_back_links] Submittable Implementation def before_submit ( self ) :

Validation that only applies on submit

if self . total

50000 and not self . manager_approval : frappe . throw ( _ ( "Manager approval required for orders over 50,000" ) ) def on_submit ( self ) :

Actions after submit

self . update_stock_ledger ( ) self . make_gl_entries ( ) def before_cancel ( self ) :

Prevent cancel if linked docs exist

if self . has_linked_invoices ( ) : frappe . throw ( _ ( "Cannot cancel - linked invoices exist" ) ) def on_cancel ( self ) :

Reverse submitted actions

self . reverse_stock_ledger ( ) self . reverse_gl_entries ( ) Controller Override (hooks.py) Method 1: Full Override

hooks.py

override_doctype_class

{ "Sales Invoice" : "myapp.overrides.CustomSalesInvoice" }

myapp/overrides.py

from erpnext . accounts . doctype . sales_invoice . sales_invoice import SalesInvoice class CustomSalesInvoice ( SalesInvoice ) : def validate ( self ) : super ( ) . validate ( )

ALWAYS call parent

self . custom_validation ( ) Method 2: Add Event Handler (Safer)

hooks.py

doc_events

{ "Sales Invoice" : { "validate" : "myapp.events.validate_sales_invoice" , } }

myapp/events.py

def validate_sales_invoice ( doc , method = None ) : if doc . grand_total < 0 : frappe . throw ( _ ( "Invalid total" ) ) V16: extend_doctype_class (New)

hooks.py (v16+)

extend_doctype_class

{ "Sales Invoice" : "myapp.extends.SalesInvoiceExtend" }

myapp/extends.py - Only methods to add/override

class SalesInvoiceExtend : def custom_method ( self ) : pass Flags System

Document-level flags

doc . flags . ignore_permissions = True

Bypass permissions

doc . flags . ignore_validate = True

Skip validate()

doc . flags . ignore_mandatory = True

Skip required fields

Custom flags for inter-hook communication

def validate ( self ) : if self . is_urgent : self . flags . needs_notification = True def on_update ( self ) : if self . flags . get ( 'needs_notification' ) : self . notify_team ( )

Insert/save with flags

doc . insert ( ignore_permissions = True , ignore_mandatory = True ) doc . save ( ignore_permissions = True ) Execution Order Reference INSERT (New Document) before_insert → before_naming → autoname → before_validate → validate → before_save → [DB INSERT] → after_insert → on_update → on_change SAVE (Existing Document) before_validate → validate → before_save → [DB UPDATE] → on_update → on_change SUBMIT validate → before_submit → [DB: docstatus=1] → on_update → on_submit → on_change → See references/decision-tree.md for all execution orders. Quick Anti-Pattern Check ❌ Don't ✅ Do Instead self.x = y in on_update frappe.db.set_value(...) frappe.db.commit() in hooks Let framework handle commits Heavy operations in validate Use frappe.enqueue() in on_update self.save() in on_update Causes infinite loop! Assume hook order across docs Each doc has its own cycle → See references/anti-patterns.md for complete list. References decision-tree.md - Complete hook selection with all execution orders workflows.md - Extended implementation patterns examples.md - Complete working examples anti-patterns.md - Common mistakes to avoid