Document Lifecycle Hooks (doc_events)

Quick Reference: Event Execution Order

Insert (new document)

Save (existing document)

Submit

Cancel

Delete

Other Operations

doc_events in hooks.py: Syntax

Basic Structure

# hooks.py
doc_events = {
    "Sales Invoice": {
        "on_submit": "myapp.events.sales_invoice.on_submit",
        "on_cancel": "myapp.events.sales_invoice.on_cancel",
    },
    "Purchase Order": {
        "validate": "myapp.events.purchase_order.validate",
    }
}

Wildcard: Apply to ALL DocTypes

doc_events = {
    "*": {
        "after_insert": "myapp.events.global_handler.after_insert_all",
        "on_update": "myapp.events.global_handler.track_changes",
    }
}

ALWAYS use "*" (string with asterisk) as the key. This fires the handler for every DocType.

Multiple Handlers per Event

doc_events = {
    "Sales Invoice": {
        "on_submit": [
            "myapp.events.accounting.create_gl_entries",
            "myapp.events.notifications.send_invoice_email",
        ]
    }
}

Handler Function Signature

# myapp/events/sales_invoice.py
def on_submit(doc, method=None):
    """
    doc    — the Document instance (e.g., Sales Invoice)
    method — string name of the event (e.g., "on_submit"), or None
    """
    if doc.grand_total > 10000:
        frappe.sendmail(...)

ALWAYS accept method as the second parameter (with default None). Frappe passes it automatically.

Decision Tree: Which Event to Use

"I need to validate data before saving"

→ Use validate. ALWAYS raise frappe.throw() here to block invalid saves.

"I need to set default values automatically"

→ Use before_validate. This runs before validate, so your defaults are set before validation checks.

"I need to run logic only on first creation"

→ Use after_insert. This fires ONLY on insert, NEVER on subsequent saves.

"I need to run logic on every save (insert + update)"

→ Use on_update. This fires on both insert and save operations.

"I need to create linked documents after submit"

→ Use on_submit. NEVER create linked docs in validate — the document is not yet committed.

"I need to reverse linked documents on cancel"

→ Use on_cancel. ALWAYS clean up GL entries, stock ledger entries, and linked docs here.

"I need to modify the document name"

→ Use autoname in the controller, or before_naming for conditional logic.

"I need to prevent deletion under certain conditions"

→ Use on_trash. Raise frappe.throw() to block deletion.

"I need to update a submitted document's fields"

→ Use before_update_after_submit for validation and on_update_after_submit for side effects.

"I need logic that runs only when values actually changed"

→ Use on_change. This fires only when at least one field value differs from the DB state.

doc_events vs Controller Events

Both mechanisms trigger the SAME events. The difference is WHERE you register them.

ALWAYS use doc_events when hooking into a DocType you do NOT own. NEVER modify another app's controller file directly.

Execution Order Within a Single Event

For a given event (e.g., validate):

1. Controller method runs first (def validate(self))
2. doc_events handlers run in app installation order
3. Wildcard "*" handlers run after specific DocType handlers

extend_doctype_class [v16+]

In Frappe v16+, extend_doctype_class provides a cleaner alternative to doc_events for adding methods to existing DocTypes.

hooks.py

extend_doctype_class = {
    "Sales Invoice": [
        "myapp.overrides.sales_invoice.SalesInvoiceExtension"
    ]
}

Extension Class (Mixin)

# myapp/overrides/sales_invoice.py
import frappe

class SalesInvoiceExtension:
    def validate(self):
        """This is called as part of the controller chain."""
        if self.grand_total < 0:
            frappe.throw("Grand total cannot be negative")

    def custom_method(self):
        """Custom methods are also available on the doc instance."""
        return self.items

Key Rules

• ALWAYS use extend_doctype_class over override_doctype_class in v16+ when multiple apps may extend the same DocType.
• Multiple apps can extend the same DocType — extensions stack via MRO.
• Class resolution order follows hooks priority: class Final(App2Mixin, App1Mixin, Original).
• Extension methods (like validate) run as part of the controller, NOT as separate doc_events handlers.

override_doctype_class [v14+]

Completely replaces the controller class. Use with extreme caution.

# hooks.py
override_doctype_class = {
    "ToDo": "myapp.overrides.todo.CustomToDo"
}

# myapp/overrides/todo.py
from frappe.desk.doctype.todo.todo import ToDo

class CustomToDo(ToDo):
    def validate(self):
        super().validate()  # ALWAYS call super() to preserve original logic
        # Your additions here

NEVER use override_doctype_class if extend_doctype_class is available (v16+). Only ONE app can override a DocType — last-installed app wins, silently breaking other apps.

Multi-App Event Ordering

When multiple apps register doc_events for the same DocType and event:

1. Handlers execute in app installation order (as listed in sites/{site}/site_config.json → installed_apps).
2. The order can be changed via Setup > Installed Applications > Update Hooks Resolution Order.
3. For override_doctype_class, the last-installed app wins (only one override applies).
4. For extend_doctype_class (v16+), all extensions stack cumulatively.

Transaction Behavior

All document events from before_validate through on_change run inside a single database transaction.

• If ANY event raises an exception, the ENTIRE operation rolls back (including db_insert/db_update).
• after_insert, on_update, on_submit, on_cancel — all run BEFORE the transaction commits.
• The transaction commits only AFTER all events complete successfully.
• after_delete runs after the DELETE statement but still within the request transaction.

NEVER assume data is committed to DB inside any event handler. Other concurrent requests will NOT see your changes until the full request completes.

Critical Rules

1. ALWAYS use frappe.throw() to abort operations — NEVER use raise Exception.
2. NEVER modify doc.name outside of autoname or before_naming.
3. ALWAYS call super().{event}() when overriding controller methods in subclasses.
4. NEVER use doc.save() inside validate or before_save — this causes infinite recursion.
5. ALWAYS use doc.flags.ignore_permissions = True explicitly if your hook needs to bypass permissions — NEVER assume hooks run as Administrator.
6. NEVER put slow operations (API calls, file I/O) in validate — use after_insert or on_update with frappe.enqueue() instead.
7. ALWAYS use doc.flags to communicate between events in the same request (e.g., doc.flags.skip_notification = True).
8. NEVER rely on on_change for critical logic — it only fires when values actually differ from the database state.

See Also

• Event Execution Order — Detailed Diagrams
• Working Examples for Common Patterns
• Anti-Patterns and Common Mistakes
• frappe-syntax-hooks-config — App-level hooks (scheduler, fixtures, permissions)
• Official docs: https://docs.frappe.io/framework/user/en/basics/doctypes/controllers