Introduction: What Are DocType Events in Frappe?

DocType Events in Frappe Framework v15 are predefined lifecycle hooks that allow developers to execute custom logic when a document is created, updated, validated, submitted, or deleted.
They form the backbone of ERPNext customization, enabling automation, validation, integrations, and business rules.

What Are DocType Events?

DocType events are triggered automatically during a document’s lifecycle.

Common events include:

• Validation
• Save
• Submit
• Cancel
• Delete

Each event provides a safe extension point without modifying core code.

Why Use DocType Events?

DocType events allow clean, upgrade-safe customizations.

Key benefits:

• No core file modification
• Centralized business logic
• Consistent execution across UI, API, and background jobs
• Fully supported in Frappe v15

This makes them ideal for enterprise ERP workflows.

How DocType Events Work Internally

Frappe invokes event handlers during the document lifecycle using its ORM layer.

When a document action occurs:

• Frappe validates permissions
• Executes event hooks
• Commits changes to the database

This ensures predictable and transactional behavior.

List of Supported DocType Events (v15)

Frappe Framework v15 supports the following server-side DocType events:

Executing Code Using Hooks

The recommended way to attach logic to DocType events is via hooks.py.

Example: hooks.py

doc_events = {
"Sales Order": {
"validate": "my_app.events.sales_order.validate",
"on_submit": "my_app.events.sales_order.on_submit"
}
}

This approach keeps logic modular and upgrade-safe.

Writing Event Handler Methods

Each event handler receives the document object and event name.

Example: Python Event Handler

def validate(doc, method):
if not doc.customer:
frappe.throw("Customer is mandatory")

This code executes whenever the document is validated.

Using Multiple Events for a DocType

Frappe allows mapping multiple events for the same DocType.

doc_events = {
"Sales Invoice": {
"before_submit": "my_app.events.invoice.before_submit",
"on_submit": "my_app.events.invoice.on_submit"
}
}

This enables granular control across lifecycle stages.

Executing Code for All DocTypes

You can attach logic globally using the wildcard *.

doc_events = {
"*": {
"on_update": "my_app.events.common.log_update"
}
}

Use this sparingly for logging or auditing purposes.

Client-Side vs Server-Side DocType Events

DocType events are server-side and always execute, regardless of how the document is created.

Client Scripts should be used only for UI interactions.

Best Practices for DocType Events

• Keep handlers lightweight
• Avoid database writes in validate
• Use frappe.db.set_value carefully
• Log errors with frappe.log_error
• Avoid long-running tasks in submit events

These practices ensure performance and stability.

Common Use Cases

• Data validation
• Auto-calculations
• Ledger posting
• External API integration
• Status synchronization

DocType events power most ERPNext workflows.

Troubleshooting Common Issues

Event not firing?

• Ensure app is installed on the site
• Run bench migrate
• Verify hooks path

Unexpected behavior?

• Check for duplicate hooks
• Inspect server logs

Performance issues?

• Avoid loops and heavy queries

Industry Relevance

DocType events are critical in:

• Manufacturing ERP workflows
• Accounting and finance automation
• CRM lifecycle management
• Inventory controls

They enable scalable enterprise logic.

Target Audience

• Frappe Developers
• ERPNext Consultants
• Backend Engineers
• System Integrators

Technical Prerequisites

• Frappe Framework v15
• Custom App setup
• Python fundamentals
• Understanding of DocTypes

Official References (Verified)

Official Documentation:

https://docs.frappe.io/framework/user/en/guides/app-development/executing-code-on-doctype-events

Frappe GitHub (v15):

https://github.com/frappe/frappe/tree/version-15