frappe-core-workflow

Name: frappe-core-workflow
Author: Impertio-Studio

151stars49forks

How to install frappe-core-workflow?

impertio-studio/frappe_claude_skill_package/frappe-core-workflow

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-core-workflow

Installs into the current project.

Summary

Use when creating or modifying Frappe Workflows, defining states and transitions, adding action conditions, or troubleshooting workflow permission errors. Prevents stuck documents from misconfigured transitions, missing state permissions, and circular workflow paths. Covers Workf

Files · 1

View on GitHub

SKILL.md

1	# Workflow Engine
2
3	The Frappe Workflow engine is a state machine that controls document lifecycle through configurable states, transitions, and role-based permissions. It governs when and how documents change status, who can perform actions, and what side effects occur on each transition.
4
5	## Quick Reference
6
7	```
8	Workflow DocType → Defines the state machine for a specific DocType
9	├── states (child table) → Workflow Document State rows
10	│ ├── state → Link to Workflow State
11	│ ├── doc_status → 0 (Draft), 1 (Submitted), 2 (Cancelled)
12	│ ├── allow_edit → Role that can edit in this state
13	│ ├── update_field → Field to update when entering state
14	│ ├── update_value → Value to set (literal or expression)
15	│ └── next_action_email_template → Email Template link
16	└── transitions (child table) → Workflow Transition rows
17	├── state → Source state (Link to Workflow State)
18	├── action → Link to Workflow Action Master
19	├── next_state → Target state (Link to Workflow State)
20	├── allowed → Role that can perform this action
21	├── allow_self_approval → Check (default: 1)
22	├── condition → Python expression (optional)
23	└── transition_tasks → Link to Workflow Transition Tasks
24	```
25
26	### Key Fields on Workflow DocType
27
28	\| Field \| Type \| Purpose \|
29	\|-------\|------\|---------\|
30	\| `workflow_name` \| Data \| Unique identifier \|
31	\| `document_type` \| Link → DocType \| Target DocType \|
32	\| `is_active` \| Check \| Only ONE workflow per DocType can be active \|
33	\| `workflow_state_field` \| Data \| Default: `workflow_state` \|
34	\| `override_status` \| Check \| Prevent workflow from overriding list view status \|
35	\| `send_email_alert` \| Check \| Email notifications with next possible actions \|
36
37	## How the Engine Works
38
39	### 1. Activation and Field Creation
40
41	When a Workflow is saved with `is_active = 1`:
42	- All other workflows for the same DocType are deactivated automatically
43	- A hidden Custom Field (`workflow_state_field`, default `workflow_state`) is created on the target DocType if it does not exist
44	- The field is type `Link` to `Workflow State`, with `hidden=1`, `allow_on_submit=1`, `no_copy=1`
45	- Existing documents with empty workflow state get their state set based on their current `docstatus`
46
47	### 2. State Resolution
48
49	Every document under a workflow has a `workflow_state` field. The engine resolves available transitions by:
50
51	1. Reading current `workflow_state` from the document
52	2. Filtering `workflow.transitions` where `transition.state == current_state`
53	3. Filtering by user roles: `transition.allowed in frappe.get_roles()`
54	4. Evaluating `transition.condition` via `frappe.safe_eval()` (if set)
55	5. Returning matching transitions as available actions
56
57	### 3. Applying a Transition
58
59	When `apply_workflow(doc, action)` is called:
60
61	1. Load document from DB (fresh read)
62	2. Get available transitions for current user
63	3. Find transition matching the requested `action`
64	4. Check self-approval: blocked if `allow_self_approval=0` AND user is document owner
65	5. Set `workflow_state_field` to `transition.next_state`
66	6. If `update_field` is set on the target state, update that field
67	7. Execute transition tasks (sync first, then async via `frappe.enqueue`)
68	8. Handle docstatus change based on source/target state `doc_status` values
69	9. Save/Submit/Cancel document accordingly
70	10. Add workflow comment
71
72	## Workflow and DocStatus Interaction
73
74	CRITICAL: The workflow engine controls docstatus transitions. You NEVER call `doc.submit()` or `doc.cancel()` directly on a workflow-controlled document. The workflow does it.
75
76	### DocStatus Transition Rules
77
78	\| Source doc_status \| Target doc_status \| Engine Action \| Valid? \|
79	\|:-:\|:-:\|---\|:-:\|
80	\| 0 (Draft) \| 0 (Draft) \| `doc.save()` \| YES \|
81	\| 0 (Draft) \| 1 (Submitted) \| `doc.submit()` \| YES \|
82	\| 1 (Submitted) \| 1 (Submitted) \| `doc.save()` \| YES \|
83	\| 1 (Submitted) \| 2 (Cancelled) \| `doc.cancel()` \| YES \|
84	\| 2 (Cancelled) \| ANY \| BLOCKED \| NO \|
85	\| 1 (Submitted) \| 0 (Draft) \| BLOCKED \| NO \|
86	\| 0 (Draft) \| 2 (Cancelled) \| BLOCKED \| NO \|
87
88	ALWAYS define your states so t

People who liked this also viewed

6 picks

Type

frappe-core-workflow

151stars49forks

View on GitHub

How to install frappe-core-workflow?

impertio-studio/frappe_claude_skill_package/frappe-core-workflow

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-core-workflow

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Workflow Engine
2
3	The Frappe Workflow engine is a state machine that controls document lifecycle through configurable states, transitions, and role-based permissions. It governs when and how documents change status, who can perform actions, and what side effects occur on each transition.
4
5	## Quick Reference
6
7	```
8	Workflow DocType → Defines the state machine for a specific DocType
9	├── states (child table) → Workflow Document State rows
10	│ ├── state → Link to Workflow State
11	│ ├── doc_status → 0 (Draft), 1 (Submitted), 2 (Cancelled)
12	│ ├── allow_edit → Role that can edit in this state
13	│ ├── update_field → Field to update when entering state
14	│ ├── update_value → Value to set (literal or expression)
15	│ └── next_action_email_template → Email Template link
16	└── transitions (child table) → Workflow Transition rows
17	├── state → Source state (Link to Workflow State)
18	├── action → Link to Workflow Action Master
19	├── next_state → Target state (Link to Workflow State)
20	├── allowed → Role that can perform this action
21	├── allow_self_approval → Check (default: 1)
22	├── condition → Python expression (optional)
23	└── transition_tasks → Link to Workflow Transition Tasks
24	```
25
26	### Key Fields on Workflow DocType
27
28	\| Field \| Type \| Purpose \|
29	\|-------\|------\|---------\|
30	\| `workflow_name` \| Data \| Unique identifier \|
31	\| `document_type` \| Link → DocType \| Target DocType \|
32	\| `is_active` \| Check \| Only ONE workflow per DocType can be active \|
33	\| `workflow_state_field` \| Data \| Default: `workflow_state` \|
34	\| `override_status` \| Check \| Prevent workflow from overriding list view status \|
35	\| `send_email_alert` \| Check \| Email notifications with next possible actions \|
36
37	## How the Engine Works
38
39	### 1. Activation and Field Creation
40
41	When a Workflow is saved with `is_active = 1`:
42	- All other workflows for the same DocType are deactivated automatically
43	- A hidden Custom Field (`workflow_state_field`, default `workflow_state`) is created on the target DocType if it does not exist
44	- The field is type `Link` to `Workflow State`, with `hidden=1`, `allow_on_submit=1`, `no_copy=1`
45	- Existing documents with empty workflow state get their state set based on their current `docstatus`
46
47	### 2. State Resolution
48
49	Every document under a workflow has a `workflow_state` field. The engine resolves available transitions by:
50
51	1. Reading current `workflow_state` from the document
52	2. Filtering `workflow.transitions` where `transition.state == current_state`
53	3. Filtering by user roles: `transition.allowed in frappe.get_roles()`
54	4. Evaluating `transition.condition` via `frappe.safe_eval()` (if set)
55	5. Returning matching transitions as available actions
56
57	### 3. Applying a Transition
58
59	When `apply_workflow(doc, action)` is called:
60
61	1. Load document from DB (fresh read)
62	2. Get available transitions for current user
63	3. Find transition matching the requested `action`
64	4. Check self-approval: blocked if `allow_self_approval=0` AND user is document owner
65	5. Set `workflow_state_field` to `transition.next_state`
66	6. If `update_field` is set on the target state, update that field
67	7. Execute transition tasks (sync first, then async via `frappe.enqueue`)
68	8. Handle docstatus change based on source/target state `doc_status` values
69	9. Save/Submit/Cancel document accordingly
70	10. Add workflow comment
71
72	## Workflow and DocStatus Interaction
73
74	CRITICAL: The workflow engine controls docstatus transitions. You NEVER call `doc.submit()` or `doc.cancel()` directly on a workflow-controlled document. The workflow does it.
75
76	### DocStatus Transition Rules
77
78	\| Source doc_status \| Target doc_status \| Engine Action \| Valid? \|
79	\|:-:\|:-:\|---\|:-:\|
80	\| 0 (Draft) \| 0 (Draft) \| `doc.save()` \| YES \|
81	\| 0 (Draft) \| 1 (Submitted) \| `doc.submit()` \| YES \|
82	\| 1 (Submitted) \| 1 (Submitted) \| `doc.save()` \| YES \|
83	\| 1 (Submitted) \| 2 (Cancelled) \| `doc.cancel()` \| YES \|
84	\| 2 (Cancelled) \| ANY \| BLOCKED \| NO \|
85	\| 1 (Submitted) \| 0 (Draft) \| BLOCKED \| NO \|
86	\| 0 (Draft) \| 2 (Cancelled) \| BLOCKED \| NO \|
87
88	ALWAYS define your states so t

People who liked this also viewed

6 picks

Type