ERPNext Frappe Document Controller

In ERPNext and the Frappe Framework, document lifecycle hooks allow developers to control the behavior of a Document at various stages like save, submit, cancel, or update.

I use the terms Hooks, Events, and Methods somewhat interchangeably, they all refer to the same idea: injecting logic into specific moments of the document lifecycle.

Each event is triggered based on the initiating action: save, submit, cancel, or update.

⚠️ Important: If you modify the document (or another document) after db_insert or db_update, those changes won’t persist automatically. You must explicitly call frappe.db.commit()

Usage

Custom Document

To define your own controller for a custom DocType you’ve created, subclass from Document and implement any hooks you need:

import frappe
from frappe.model.document import Document

class Person(Document):
    def validate(self):
      self.mark_as_worlds_best_boss()

    def mark_as_worlds_best_boss(self):
      if self.name == "Michael Scott"
        self.is_worlds_best_boss = True

Frappe will automatically call your validate() method at the appropriate point in the save lifecycle.

Attatch to Standard Document

If you want to add logic to standard ERPNext DocTypes (e.g. Sales Order, User, etc.), use hooks.py in your custom app:

doc_events = {
	"User": {
		"validate": "dunder_mifflin.utils.doc_events.mark_as_worlds_best_boss",
	},
}

Then define the method like this:

def mark_as_worlds_best_boss(doc, method):
    if doc.name == "Michael Scott":
        doc.is_worlds_best_boss = True

Reference

• Frappe Docs – Controller Methods