ERPNext Server Scripts Syntax
Server Scripts are Python scripts that run within Frappe's secure sandbox environment. They are managed via Setup → Server Script in the ERPNext UI.
CRITICAL: Sandbox Limitations
┌─────────────────────────────────────────────────────────────────────┐
│ ⚠️ NO IMPORTS ALLOWED │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ The sandbox blocks ALL import statements: │
│ import json → ImportError: __import__ not found │
│ from datetime import date → ImportError │
│ │
│ SOLUTION: Use Frappe's pre-loaded namespace: │
│ frappe.utils.nowdate() not: from frappe.utils import nowdate │
│ frappe.parse_json(data) not: import json; json.loads(data) │
│ │
└─────────────────────────────────────────────────────────────────────┘Server Script Types
| Type | Usage | Trigger |
|---|---|---|
| Document Event | React to document lifecycle | Save, Submit, Cancel, etc. |
| API | Custom REST endpoint | HTTP request to /api/method/{name} |
| Scheduler Event | Scheduled tasks | Cron schedule |
| Permission Query | Dynamic list filtering | Document list view |
Event Name Mapping (Document Event)
IMPORTANT: The UI event names differ from the internal hook names:
| UI Name (Server Script) | Internal Hook | When |
|---|---|---|
| Before Insert | before_insert | Before new doc to DB |
| After Insert | after_insert | After new doc saved |
| Before Validate | before_validate | Before validation |
| Before Save | validate | Before save (new or update) |
| After Save | on_update | After successful save |
| Before Submit | before_submit | Before submit |
| After Submit | on_submit | After submit |
| Before Cancel | before_cancel | Before cancel |
| After Cancel | on_cancel | After cancel |
| Before Delete | on_trash | Before delete |
| After Delete | after_delete | After delete |
Quick Reference: Available API
Always available in sandbox
# Document object (in Document Event scripts)
doc # Current document
doc.name # Document name
doc.doctype # DocType name
doc.fieldname # Field value
doc.get("fieldname") # Safe field access
doc.items # Child table (list)
# Frappe namespace
frappe.db # Database operations
frappe.get_doc() # Fetch document
frappe.get_all() # Multiple documents
frappe.throw() # Validation error
frappe.msgprint() # User message
frappe.log_error() # Error logging
frappe.utils.* # Utility functions
frappe.session.user # Current user
frappe.form_dict # Request parameters (API)
frappe.response # Response object (API)Decision Tree: Which Script Type?
What do you want to achieve?
│
├─► React to document save/submit/cancel?
│ └─► Document Event script
│
├─► Create REST API endpoint?
│ └─► API script
│
├─► Run task on schedule?
│ └─► Scheduler Event script
│
└─► Filter document list view per user/role?
└─► Permission Query scriptBasic Syntax per Type
Document Event
# Configuration:
# Reference DocType: Sales Invoice
# DocType Event: Before Save (= validate)
if doc.grand_total < 0:
frappe.throw("Total cannot be negative")
if doc.grand_total > 10000:
doc.requires_approval = 1API
# Configuration:
# API Method: get_customer_info
# Allow Guest: No
# Endpoint: /api/method/get_customer_info
customer = frappe.form_dict.get("customer")
if not customer:
frappe.throw("Customer parameter required")
data = frappe.get_all(
"Sales Order",
filters={"customer": customer, "docstatus": 1},
fields=["name", "grand_total"],
limit=10
)
frappe.response["message"] = dataScheduler Event
# Configuration:
# Event Frequency: Cron
# Cron Format: 0 9 * * * (daily at 9:00)
overdue = frappe.get_all(
"Sales Invoice",
filters={"status": "Unpaid", "due_date": ["<", frappe.utils.today()]},
fields=["name", "customer"]
)
for inv in overdue:
frappe.log_error(f"Overdue: {inv.name}", "Invoice Reminder")
frappe.db.commit()Permission Query
# Configuration:
# Reference DocType: Sales Invoice
# Output: conditions string for WHERE clause
user_roles = frappe.get_roles(user)
if "System Manager" in user_roles:
conditions = "" # Full access
elif "Sales User" in user_roles:
conditions = f"`tabSales Invoice`.owner = {frappe.db.escape(user)}"
else:
conditions = "1=0" # No accessReferences
- references/events.md - Complete event mapping and execution order
- references/methods.md - All available frappe.* methods in sandbox
- references/examples.md - 10+ working examples per script type
- references/anti-patterns.md - Sandbox limitations and common mistakes
Version Information
- Frappe v14+: Server Scripts fully supported
- Activation required:
bench --site [site] set-config server_script_enabled true - Frappe v15: No significant syntax changes for Server Scripts