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