Smithery is now a part of Arcade.dev! Read more in our announcement here
Generate state machine logic for Frappe DocTypes. Use when implementing complex status workflows, state transitions, or document lifecycle management.
Generate state machine logic for managing complex document states and transitions in Frappe DocTypes.
These Frappe conventions apply to everything this skill generates, and override any conflicting example below.
bench (never ./env/bin/bench or a full path). Always pass --site <site> explicitly — never run a bare bench migrate / bench run-tests. Run bench start in the background and only if it isn't already running. Don't run discovery commands (which bench, bench --version).apps/<app>/<app>/<module>/doctype/<name>/<name>.json — the app name appears twice (directory + Python package) — with an empty __init__.py alongside. Never mkdir the folder; write the JSON and run bench --site <site> migrate to create the structure. Don't add creation, modified, owner, modified_by, or docstatus as fields — Frappe manages them.frappe.qb.get_query() over raw frappe.db.sql(). Use frappe.db.get_all() for server logic (ignores permissions) and frappe.db.get_list() for user-facing APIs (enforces them). Never use frappe.db.set_value() on a field with validation or lifecycle logic — load the doc and doc.save() so controller hooks run. Batch-fetch related records; never query inside a loop (N+1).frappe.db.commit() in controllers, request handlers, background jobs, or patches — Frappe auto-commits on success and rolls back on uncaught errors. Flush manually only to make a write visible to a subsequent frappe.enqueue() (or pass enqueue_after_commit=True).@frappe.whitelist() parameter so Frappe validates and casts it, and pass methods=[...] to pin the HTTP verb.Claude should invoke this skill when:
Pick the lightest mechanism that fits — most apps need only a status field, not docstatus.
Select (inline \n list) for a small fixed set of states; use a Link to a status master DocType when admins must extend the states, or when a status drives behavior and needs its own attributes.docstatus (0 Draft / 1 Submitted / 2 Cancelled) — only for genuine submit semantics, i.e. financial/legal immutability where a submitted document must not be edited (it can only be cancelled and amended). Set is_submittable: 1; do not declare docstatus as a field.frappe-workflow-generator.validate / before_save (reject illegal source→target moves).on_update / on_submit.frappe.db.set_value() to change a status — it bypasses transition validation and lifecycle hooks. Mutate the doc and doc.save() so validate/on_update run.Order Status State Machine:
class SalesOrder(Document):
def validate(self):
self.validate_state_transition()
def validate_state_transition(self):
"""Validate allowed state transitions"""
if not self.is_new():
old_status = frappe.db.get_value('Sales Order', self.name, 'status')
# Define allowed transitions
allowed_transitions = {
'Draft': ['Pending', 'Cancelled'],
'Pending': ['Confirmed', 'Cancelled'],
'Confirmed': ['In Progress', 'Cancelled'],
'In Progress': ['Completed', 'On Hold'],
'On Hold': ['In Progress', 'Cancelled'],
'Completed': [], # Terminal state
'Cancelled': [] # Terminal state
}
if old_status != self.status:
allowed = allowed_transitions.get(old_status, [])
if self.status not in allowed:
frappe.throw(
_(f'Cannot transition from {old_status} to {self.status}')
)
def on_submit(self):
self.status = 'Confirmed'
def on_cancel(self):
self.status = 'Cancelled'
Actions Based on State:
class PaymentEntry(Document):
def validate(self):
if self.status == 'Draft':
self.validate_draft_entry()
elif self.status == 'Submitted':
self.validate_submitted_entry()
def before_submit(self):
# Actions before state change
if self.payment_type == 'Pay':
self.validate_sufficient_balance()
self.status = 'Submitted'
def on_cancel(self):
# Reverse actions
if self.status == 'Submitted':
self.reverse_gl_entries()
self.status = 'Cancelled'
frappe-workflow-generator.frappe-doctype-architect; this skill implements the transition logic from that plan.State Management Examples:
