ERPNext Syntax: Document Controllers

Document Controllers are Python classes that implement the server-side logic of a DocType.

Quick Reference

Controller Basic Structure

import frappe
from frappe.model.document import Document

class SalesOrder(Document):
    def validate(self):
        """Main validation - runs on every save."""
        if not self.items:
            frappe.throw(_("Items are required"))
        self.total = sum(item.amount for item in self.items)
    
    def on_update(self):
        """After save - changes to self are NOT saved."""
        self.update_linked_docs()

Location and Naming

DocType	Class	File
Sales Order	SalesOrder	selling/doctype/sales_order/sales_order.py
Custom Doc	CustomDoc	module/doctype/custom_doc/custom_doc.py

Rule: DocType name → PascalCase (remove spaces) → snake_case filename

---

Most Used Hooks

Hook	When	Typical Use
validate	Before every save	Validation, calculations
on_update	After every save	Notifications, linked docs
after_insert	After new doc	Creation-only actions
on_submit	After submit	Ledger entries, stock
on_cancel	After cancel	Reverse ledger entries
on_trash	Before delete	Cleanup related data
autoname	On naming	Custom document name

Complete list and execution order: See lifecycle-methods.md

---

Hook Selection Decision Tree

What do you want to do?
│
├─► Validate or calculate fields?
│   └─► validate
│
├─► Action after save (emails, linked docs)?
│   └─► on_update
│
├─► Only for NEW docs?
│   └─► after_insert
│
├─► On SUBMIT?
│   ├─► Check beforehand? → before_submit
│   └─► Action afterwards? → on_submit
│
├─► On CANCEL?
│   ├─► Check beforehand? → before_cancel
│   └─► Cleanup? → on_cancel
│
├─► Custom document name?
│   └─► autoname
│
└─► Cleanup before delete?
    └─► on_trash

---

Critical Rules

1. Changes after on_update are NOT saved

# ❌ WRONG - change is lost
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")

2. No commits in controllers

# ❌ WRONG - Frappe handles commits
def on_update(self):
    frappe.db.commit()  # DON'T DO THIS

# ✅ CORRECT - no commit needed
def on_update(self):
    self.update_related()  # Frappe commits automatically

3. Always call super() when overriding

# ❌ WRONG - parent logic is skipped
def validate(self):
    self.custom_check()

# ✅ CORRECT - parent logic is preserved
def validate(self):
    super().validate()
    self.custom_check()

4. Use flags for recursion prevention

def on_update(self):
    if self.flags.get('from_linked_doc'):
        return
    
    linked = frappe.get_doc("Linked Doc", self.linked_doc)
    linked.flags.from_linked_doc = True
    linked.save()

---

Document Naming (autoname)

Available Naming Options

Option	Example	Result	Version
field:fieldname	field:customer_name	ABC Company	All
naming_series:	naming_series:	SO-2024-00001	All
format:PREFIX-{##}	format:INV-{YYYY}-{####}	INV-2024-0001	All
hash	hash	a1b2c3d4e5	All
Prompt	Prompt	User enters name	All
UUID	UUID	01948d5f-...	v16+
Custom method	Controller autoname()	Any pattern	All

UUID Naming (v16+)

New in v16: UUID-based naming for globally unique identifiers.

{
  "doctype": "DocType",
  "autoname": "UUID"
}

Benefits:

• Globally unique across systems
• Better data integrity and traceability
• Reduced database storage
• Faster bulk record creation
• Link fields store UUID in native format

Implementation:

# Frappe automatically generates UUID7
# In naming.py:
if meta.autoname == "UUID":
    doc.name = str(uuid_utils.uuid7())

Validation:

# UUID names are validated on import
from uuid import UUID
try:
    UUID(doc.name)
except ValueError:
    frappe.throw(_("Invalid UUID: {}").format(doc.name))

Custom autoname Method

from frappe.model.naming import getseries

class Project(Document):
    def autoname(self):
        # Custom naming based on customer
        prefix = f"P-{self.customer}-"
        self.name = getseries(prefix, 3)
        # Result: P-ACME-001, P-ACME-002, etc.

Format Patterns

Pattern	Description	Example
{#}	Counter	1, 2, 3
{##}	Zero-padded counter	01, 02, 03
{####}	4-digit counter	0001, 0002
{YYYY}	Full year	2024
{YY}	2-digit year	24
{MM}	Month	01-12
{DD}	Day	01-31
{fieldname}	Field value	(value)

---

Controller Override

Via hooks.py (override_doctype_class)

# hooks.py
override_doctype_class = {
    "Sales Order": "custom_app.overrides.CustomSalesOrder"
}

# custom_app/overrides.py
from erpnext.selling.doctype.sales_order.sales_order import SalesOrder

class CustomSalesOrder(SalesOrder):
    def validate(self):
        super().validate()
        self.custom_validation()

Via doc_events (hooks.py)

# hooks.py
doc_events = {
    "Sales Order": {
        "validate": "custom_app.events.validate_sales_order",
        "on_submit": "custom_app.events.on_submit_sales_order"
    }
}

# custom_app/events.py
def validate_sales_order(doc, method):
    if doc.total > 100000:
        doc.requires_approval = 1

Choice: override_doctype_class for full control, doc_events for individual hooks.

---

Submittable Documents

Documents with is_submittable = 1 have a docstatus lifecycle:

docstatus	Status	Editable	Can go to
0	Draft	✅ Yes	1 (Submit)
1	Submitted	❌ No	2 (Cancel)
2	Cancelled	❌ No	-

class StockEntry(Document):
    def on_submit(self):
        """After submit - create stock ledger entries."""
        self.update_stock_ledger()
    
    def on_cancel(self):
        """After cancel - reverse the entries."""
        self.reverse_stock_ledger()

---

Virtual DocTypes

For external data sources (no database table):

class ExternalCustomer(Document):
    @staticmethod
    def get_list(args):
        return external_api.get_customers(args.get("filters"))
    
    @staticmethod
    def get_count(args):
        return external_api.count_customers(args.get("filters"))
    
    @staticmethod
    def get_stats(args):
        return {}

---

Inheritance Patterns

Standard Controller

from frappe.model.document import Document

class MyDocType(Document):
    pass

Tree DocType

from frappe.utils.nestedset import NestedSet

class Department(NestedSet):
    pass

Extend Existing Controller

from erpnext.selling.doctype.sales_order.sales_order import SalesOrder

class CustomSalesOrder(SalesOrder):
    def validate(self):
        super().validate()
        self.custom_validation()

---

Type Annotations (v15+)

class Person(Document):
    if TYPE_CHECKING:
        from frappe.types import DF
        first_name: DF.Data
        last_name: DF.Data
        birth_date: DF.Date

Enable in hooks.py:

export_python_type_annotations = True

---

Reference Files

File	Contents
lifecycle-methods.md	All hooks, execution order, examples
methods.md	All doc.* methods with signatures
flags.md	Flags system documentation
examples.md	Complete working controller examples
anti-patterns.md	Common mistakes and corrections

---

Version Differences

Feature	v14	v15	v16
Type annotations	❌	✅ Auto-generated	✅
before_discard hook	❌	✅	✅
on_discard hook	❌	✅	✅
flags.notify_update	❌	✅	✅
UUID autoname	❌	❌	✅
UUID in Link fields (native)	❌	❌	✅

v16-Specific Notes

UUID Naming:

• Set autoname = "UUID" in DocType definition
• Uses uuid7() for time-ordered UUIDs
• Link fields store UUIDs in native format (not text)
• Improves performance for bulk operations

Choosing UUID vs Traditional Naming:

When to use UUID:
├── Cross-system data synchronization
├── Bulk record creation
├── Global uniqueness required
└── No human-readable name needed

When to use traditional naming:
├── User-facing document references (SO-00001)
├── Sequential numbering required
├── Auditing requires readable names
└── Integration with legacy systems

---

Anti-Patterns

❌ Direct field change after on_update

def on_update(self):
    self.status = "Done"  # Will be lost!

❌ frappe.db.commit() in controller

def validate(self):
    frappe.db.commit()  # Breaks transaction!

❌ Forgetting to call super()

def validate(self):
    self.my_check()  # Parent validate is skipped

→ See anti-patterns.md for complete list.

---

Related Skills

• erpnext-syntax-serverscripts – Server Scripts (sandbox alternative)
• erpnext-syntax-hooks – hooks.py configuration
• erpnext-impl-controllers – Implementation workflows