frappe-impl-serverscripts
/frappe-impl-serverscripts
Use when implementing server-side features via Setup > Server Script: document validation, auto-fill, API endpoints, scheduled tasks, permission queries. Covers sandbox-safe coding, script type selection, testing, migration to controllers. Keywords: how to implement server script, which script type, sandbox limitation, Document Event, API script, Scheduler Event, Permission Query, migrate to controller, no-code automation, run code on save, auto-fill field, server-side validation, scheduled script.
- Author
- vyogotech ↗
- Repository
- frappe-apps-manager ↗
- Licence
- MIT
- Last repository change
- 19.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 19.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when implementing server-side features via Setup > Server Script: document validation, auto-fill, API endpoints, scheduled tasks, permission queries. Covers sandbox-safe coding, script type selection, testing, migration to controllers. Keywords: how to implement server script, which script type, sandbox limitation, Document Event, API script, Scheduler Event, Permission Query, migrate to controller, no-code automation, run code on save, auto-fill field, server-side validation, scheduled script.
Original author description
Use when implementing server-side features via Setup > Server Script: document validation, auto-fill, API endpoints, scheduled tasks, permission queries. Covers sandbox-safe coding, script type selection, testing, migration to controllers. Keywords: how to implement server script, which script type, sandbox limitation, Document Event, API script, Scheduler Event, Permission Query, migrate to controller, no-code automation, run code on save, auto-fill field, server-side validation, scheduled script.
How it works
- CRITICAL: Sandbox Limitations
- Workflow 1: Create a Server Script
- Workflow 2: Choose the Script Type
- Workflow 3: Document Event: Validation
- Workflow 4: Document Event: Auto-Calculate
- Workflow 5: Document Event: Create Related Document
- Workflow 6: API Endpoint
- Workflow 7: Scheduler Event
- Workflow 8: Permission Query
- Event Name Mapping
SKILL.md preview
---
name: frappe-impl-serverscripts
description: >
Use when implementing server-side features via Setup > Server Script:
document validation, auto-fill, API endpoints, scheduled tasks,
permission queries. Covers sandbox-safe coding, script type selection,
testing, migration to controllers. Keywords: how to implement server
script, which script type, sandbox limitation, Document Event, API
script, Scheduler Event, Permission Query, migrate to controller,
no-code automation, run code on save, auto-fill field, server-side validation, scheduled script.
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
author: OpenAEC-Foundation
version: "2.0"
---
# Server Scripts — Implementation Workflows
Step-by-step workflows for building server-side features without a custom app. For exact syntax, see `frappe-syntax-serverscripts`.
**Version**: v14/v15/v16 | **v15+ Note**: Server Scripts disabled by default — enable with `bench set-config server_script_enabled true`
## CRITICAL: Sandbox Limitations
```
ALL IMPORTS BLOCKED — RestrictedPython sandbox
import json → ImportError: __import__ not found
from frappe.utils → ImportError
import requests → ImportError
SOLUTION: Use pre-loaded namespace:
frappe.utils.nowdate() frappe.utils.flt()
frappe.parse_json(data) json.loads() (json IS available)
frappe.as_json(obj) json.dumps()
frappe.make_get_request(url) (replaces requests.get)
```
**Rule**: If you need `import` statements beyond `json`, ALWAYS use a Controller instead.
## Workflow 1: Create a Server Script
1. Enable server scripts: `bench set-config server_script_enabled true`
2. Navigate to **Setup > Server Script** (or awesomebar: "New Server Script")
3. Select **Script Type** (see decision tree below)
4. Configure type-specific settings (DocType, event, API method, cron)
5. Write script in the editor
6. Save — script is active immediately
7. Test by triggering the configured event
8. Use "Compare Versions" button to diff changes
## Workflow 2: Choose the Script Type
```
WHAT DO YOU NEED?
│
├── React to document save/submit/cancel?
│ └── Document Event
│ └── Select DocType + Event (Before Save, After Save, etc.)
│
├── Create a REST API endpoint?
│ └── API
│ └── Set method name + guest access setting
│ └── Endpoint: /api/method/{method_name}
│
├── Run task on schedule (daily/hourly/cron)?
│ └── Scheduler Event
│ └── Set cron pattern or frequency
│
└── Filter list views per user/role?
└── Permission Query
└── Select DocType — set `conditions` variable
```
> See [references/decision-tree.md](references/decision-tree.md) for complete decision tree.
## Workflow 3: Document Event: Validation
**Goal**: Validate Sales Order before save.
**Step 1**: Choose event — "Before Save" maps to `validate` hook.
**Step 2**: Write sandbox-safe script:
```python
# Type: Document Event | Event: Before Save | DocType: Sales Order
errors = []
if not doc.customer:
errors.append("Customer is required")
if doc.delivery_date and doc.delivery_date < frappe.utils.today():
errors.append("Delivery date cannot be in the past")
for item in doc.items:
if item.qty <= 0:
errors.append(f"Row {item.idx}: Quantity must be positive")
if errors:
frappe.throw("<br>".join(errors), title="Validation Error")
```
**Rules**:
- ALWAYS collect errors and throw once (better UX than multiple throws)
- NEVER call `doc.save()` in Before Save — framework handles it
- ALWAYS use `frappe.throw()` — `msgprint` does NOT stop save
## Workflow 4: Document Event: Auto-Calculate
**Goal**: Auto-calculate totals and set derived fields.
```python
# Type: Document Event | Event: Before Save | DocType: Purchase Order
doc.total_qty = sum(item.qty or 0 for item in doc.items)
doc.total_amount = sum((item.qty or 0) * (item.rate or 0) for item in doc.items)
if doc.total_amount > 50000:
doc.requires_approval = 1
doc.approval_status = "Pending"
if doc.supplier and not doc.supplier_name:
doc.supplier_name = frappe.db.get_value("Supplier", doc.supplier, "supplier_name")
```
**Rule**: ALWAYS modify `doc` fields directly in Before Save — they are automatically persisted.
## Workflow 5: Document Event: Create Related Document
**Goal**: Create a ToDo when a new Lead is inserted.
```python
# Type: Document Event | Event: After Insert | DocType: Lead
frappe.get_doc({
"doctype": "ToDo",
"allocated_to": doc.lead_owner or doc.owner,
"reference_type": "Lead",
"reference_name": doc.name,
"description": f"Follow up with new lead: {doc.lead_name}",
"date": frappe.utils.add_days(frappe.utils.today(), 1),
"priority": "High" if doc.status == "Hot" else "Medium"
}).insert(ignore_permissions=True)
```
**Rules**:
- ALWAYS use After Insert or After Save for creating related docs
- NEVER create documents in Before Save — `doc.name` may not exist yet
- ALWAYS use `ignore_permissions=True` for system-generated documents
## Workflow 6: API Endpoint
**Goal**: Create authenticated REST API returning customer data.
```python
# Type: API | Method: get_customer_dashboard | Allow Guest: No
# Endpoint: /api/method/get_customer_dashboard
customer = frappe.form_dict.get("customer")
if not customer:
frappe.throw("Parameter 'customer' is required")
# ALWAYS check permissions
if not frappe.has_permission("Customer", "read", customer):
frappe.throw("Access denied", frappe.PermissionError)
orders = frappe.db.count("Sales Order", {"customer": customer, "docstatus": 1})
revenue = frappe.db.get_value("Sales Invoice",
filters={"customer": customer, "docstatus": 1},
fieldname="sum(grand_total)") or 0
frappe.response["message"] = {
"customer": customer,
"total_orders": orders,
"total_revenue": revenue
}
```
**Rules**:
- ALWAYS validate input parameters
- ALWAYS check permissions (even with Allow Guest: No)
- ALWAYS cap query limits: `min(frappe.utils.cint(limit), 100)`
- NEVER expose full documents — return only needed fields
## Workflow 7: Scheduler Event
**Goal**: Daily reminder for overdue invoices.
```python
# Type: Scheduler Event | Cron: 0 9 * * * (daily at 9:00)
BATCH_SIZE = 50
today = frappe.utils.today()
overdue = frappe.get_all("Sales Invoice",
filters={
"status": "Unpaid",
"due_date": ["<", today],
"docstatus": 1
},
fields=["name", "customer", "owner", "due_date", "grand_total"],
limit=BATCH_SIZE
)
for inv in overdue:
days = frappe.utils.date_diff(today, inv.due_date)
if not frappe.db.exists("ToDo", {
"reference_type": "Sales Invoice",
"reference_name": inv.name,
"status": "Open"
}):
frappe.get_doc({
"doctype": "ToDo",
"allocated_to": inv.owner,
"reference_type": "Sales Invoice",
"reference_name": inv.name,
"description": f"Invoice {inv.name} is {days} days overdue"
}).insert(ignore_permissions=True)
frappe.db.commit() # REQUIRED in scheduler scripts
```
**Rules**:
- ALWAYS add `frappe.db.commit()` at end of scheduler scripts
- ALWAYS add `limit` to queries — prevent memory exhaustion
- ALWAYS use `try/except` + `frappe.log_error()` in loops
- NEVER run scheduler scripts that process unlimited records
## Workflow 8: Permission Query
**Goal**: Users see only their territory's customers.
```python
# Type: Permission Query | DocType: Customer
user_territory = frappe.db.get_value("User", user, "territory")
user_roles = frappe.get_roles(user)
if "System Manager" in user_roles:
conditions = "" # Full access
elif user_territory:
conditions = f"`tabCustomer`.territory = {frappe.db.escape(user_territory)}"
else:
conditions = f"`tabCustomer`.owner = {frappe.db.escape(user)}"
```
**Rules**:
- ALWAYS give System Manager full access (`conditions = ""`)
- ALWAYS use `frappe.db.escape()` for user input in SQL
- ALWAYS set `conditions` variable — it is the output
- Permission Query only affects `frappe.db.get_list`, NOT `frappe.db.get_all`
## Event Name Mapping
| UI Name | Internal Hook | Best For |
|---------|---------------|----------|
| Before Validate | `before_validate` | Pre-validation defaults |
| **Before Save** | **`validate`** | Validation + calculations (MOST COMMON) |
| After Save | `on_update` | Notifications, audit logs |
| After Insert | `after_insert` | Create related docs (new only) |
| Before Submit | `before_submit` | Submit-time validation |
| After Submit | `on_submit` | Post-submit automation |
| Before Cancel | `before_cancel` | Cancel prevention |
| After Cancel | `on_cancel` | Cleanup after cancel |
| Before Delete | `on_trash` | Delete prevention |
## Sandbox-Safe API Quick Reference
| Need | Use (NOT import) |
|------|-------------------|
| Parse JSON | `frappe.parse_json()` or `json.loads()` |
| Serialize JSON | `frappe.as_json()` or `json.dumps()` |
| Today's date | `frappe.utils.today()` |
| Now (datetime) | `frappe.utils.now()` |
| Add days | `frappe.utils.add_days(date, n)` |
| Date diff | `frappe.utils.date_diff(d1, d2)` |
| Float conversion | `frappe.utils.flt(val)` |
| Int conversion | `frappe.utils.cint(val)` |
| HTTP GET | `frappe.make_get_request(url)` |
| HTTP POST | `frappe.make_post_request(url, data)` |
| Render template | `frappe.render_template(tmpl, ctx)` |
| Log error | `frappe.log_error(msg, title)` |
| Send email | `frappe.sendmail(recipients, subject, message)` |
## When to Migrate to Controller
ALWAYS migrate to a Document Controller when:
- You need `import` statements (beyond `json`)
- Script exceeds 100 lines
- You need try/except with rollback
- You need `frappe.enqueue()` for background jobs
- You need to extend an existing ERPNext DocType
- Multiple scripts on same DocType become hard to manage
**Migration path**: See `frappe-impl-controllers` for controller implementation.
## Related Skills
- `frappe-syntax-serverscripts` — Exact sandbox API reference
- `frappe-errors-serverscripts` — Error handling and anti-patterns
- `frappe-core-database` — `frappe.db.*` operations
- `frappe-core-permissions` — Permission system details
- `frappe-impl-controllers` — When to migrate from Server Script
> See [references/decision-tree.md](references/decision-tree.md) for complete decision trees.
> See [references/workflows.md](references/workflows.md) for extended patterns.
> See [references/examples.md](references/examples.md) for 10+ complete examples.
Versions
The database has no other skills named frappe-impl-serverscripts.
Identical content appears in 2 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version ee626d40e041 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100frappe-syntax-serverscripts
Use when writing Python code for ERPNext/Frappe Server Scripts including Document Events, API endpoints, Scheduler Events, and Permission Queries. Prevents the #1 AI mistake: using import statements in Server Scripts (sandbox blocks ALL imports). Covers frappe.* methods, event… - 100frappe-errors-serverscripts
Use when debugging or preventing errors in Frappe Server Scripts. Prevents ImportError (the #1 error), NameError for restricted builtins, sandbox violations, doc_events not firing, wrong script type selection, SQL injection, permission denied in scheduled scripts, infinite… - 100frappe-api-handler
Create custom API endpoints and whitelisted methods for Frappe applications. Use when building REST APIs or custom endpoints. - 95frappe-client-script-generator
Generate JavaScript client-side form scripts for Frappe DocTypes. Use when creating form customizations, field validations, custom buttons, or client-side logic for Frappe/ERPNext forms. - 100reports
Create reports in Frappe including Report Builder, Query Reports (SQL), and Script Reports (Python + JS). Use when building data analysis views, dashboards, or custom reporting features. - 100testing
Write and run tests for Frappe apps including unit tests, integration tests, and UI tests. Use when adding test coverage, debugging test failures, or setting up CI for Frappe projects.