frappe-impl-workflow

Frappe ワークフローの実装

Frappe でドキュメントワークフローを実装するためのステップバイステップガイドです。設計、設定、テスト、一般的な承認チェーンのパターンを説明します。

クイックリファレンス：実装チェックリスト

1. □ Design states and transitions on paper/diagram first
2. □ Create Workflow State records (master list)
3. □ Create Workflow Action Master records (Approve, Reject, etc.)
4. □ Create the Workflow DocType record
5. □ Add states with correct doc_status values
6. □ Add transitions with roles, actions, and conditions
7. □ Set allow_edit roles per state
8. □ Configure email notifications (optional)
9. □ Test every transition path with test users
10. □ Verify self-approval blocking works as expected

ステップ 1：ワークフローを設計する

UI を操作する前に、ワークフローを紙に書き出して整理します。

状態を特定する

必ず、ドキュメントの各段階をすべて列挙することから始めます。

Example — Purchase Order Approval:
  Draft → Pending Review → Pending Approval → Approved → Submitted → Cancelled

DocStatus を状態に割り当てる

送信可能な DocType では、必ず doc_status を正しく割り当てます。

段階	doc_status	意味
すべての「進行中」状態	0	ドキュメントは下書きで、編集可能
最終承認／有効状態	1	ドキュメントは送信済みで、ロックされている
キャンセル状態	2	ドキュメントはキャンセルされている

中間の承認状態に doc_status = 1 を割り当ててはいけません。 送信済みのドキュメントを下書きに戻すことはできません。送信後に進めることができるのは、別の送信済み状態への移行か、キャンセルのみです。

遷移を割り当てる

各状態について、可能な操作、実行できるユーザー、条件の有無を定義します。

Draft         →[Submit for Review / Creator]→     Pending Review
Pending Review →[Approve / Reviewer]→              Pending Approval
Pending Review →[Reject / Reviewer]→               Draft
Pending Approval →[Approve / Manager]→             Approved
Pending Approval →[Reject / Manager]→              Draft
Approved      →[Submit / Manager]→                 Submitted (doc_status=1)
Submitted     →[Cancel / Manager]→                 Cancelled (doc_status=2)

ステップ 2：前提となるレコードを作成する

2a. ワークフロー状態を作成する

Workflow State のリストに移動するか、API 経由で作成します。

# Create states with appropriate styles
states = [
    {"workflow_state_name": "Draft", "style": ""},
    {"workflow_state_name": "Pending Review", "style": "Primary"},
    {"workflow_state_name": "Pending Approval", "style": "Warning"},
    {"workflow_state_name": "Approved", "style": "Success"},
    {"workflow_state_name": "Submitted", "style": "Info"},
    {"workflow_state_name": "Rejected", "style": "Danger"},
    {"workflow_state_name": "Cancelled", "style": "Inverse"},
]
for s in states:
    if not frappe.db.exists("Workflow State", s["workflow_state_name"]):
        frappe.get_doc({"doctype": "Workflow State", **s}).insert()

使用可能なスタイル：Primary、Success、Warning、Danger、Info、Inverse（または空欄でデフォルト）。

2b. ワークフローアクションマスターを作成する

actions = ["Submit for Review", "Approve", "Reject", "Send Back", "Cancel"]
for action in actions:
    if not frappe.db.exists("Workflow Action Master", action):
        frappe.get_doc({
            "doctype": "Workflow Action Master",
            "workflow_action_name": action
        }).insert()

ステップ 3：ワークフローを作成する

UI 経由

Setup > Workflow > New Workflow に移動します。

1. Workflow Name を設定します（例：「Purchase Order Approval」）
2. Document Type を設定します（例：「Purchase Order」）
3. Is Active にチェックを入れます
4. States テーブルに状態を追加します
5. Transitions テーブルに遷移を追加します

Python 経由

workflow = frappe.get_doc({
    "doctype": "Workflow",
    "workflow_name": "Purchase Order Approval",
    "document_type": "Purchase Order",
    "is_active": 1,
    "send_email_alert": 1,
    "states": [
        {"state": "Draft", "doc_status": "0", "allow_edit": "Purchase User"},
        {"state": "Pending Approval", "doc_status": "0", "allow_edit": "Purchase Manager"},
        {"state": "Approved", "doc_status": "1", "allow_edit": "Purchase Manager"},
        {"state": "Rejected", "doc_status": "0", "allow_edit": "Purchase User"},
        {"state": "Cancelled", "doc_status": "2"},
    ],
    "transitions": [
        {
            "state": "Draft",
            "action": "Submit for Review",
            "next_state": "Pending Approval",
            "allowed": "Purchase User",
            "allow_self_approval": 1,
        },
        {
            "state": "Pending Approval",
            "action": "Approve",
            "next_state": "Approved",
            "allowed": "Purchase Manager",
            "allow_self_approval": 0,
        },
        {
            "state": "Pending Approval",
            "action": "Reject",
            "next_state": "Rejected",
            "allowed": "Purchase Manager",
        },
        {
            "state": "Rejected",
            "action": "Submit for Review",
            "next_state": "Pending Approval",
            "allowed": "Purchase User",
        },
        {
            "state": "Approved",
            "action": "Cancel",
            "next_state": "Cancelled",
            "allowed": "Purchase Manager",
        },
    ],
})
workflow.insert()

ステップ 4：高度な機能を設定する

条件付き遷移

条件を満たす場合にのみ遷移を表示するには、Python 条件を追加します。

# Only allow approval for orders above 50000 by Senior Manager
{
    "state": "Pending Approval",
    "action": "Approve",
    "next_state": "Approved",
    "allowed": "Senior Manager",
    "condition": "doc.grand_total > 50000",
}

# Standard approval for orders up to 50000
{
    "state": "Pending Approval",
    "action": "Approve",
    "next_state": "Approved",
    "allowed": "Purchase Manager",
    "condition": "doc.grand_total <= 50000",
}

条件では必ず doc.fieldname 構文を使用します（ドキュメントは辞書として公開されます）。

条件で使用できるもの：frappe.db.get_value()、frappe.db.get_list()、frappe.session.user、frappe.utils.now_datetime()、frappe.utils.add_to_date()、frappe.utils.get_datetime()。

自己承認の禁止

承認遷移で allow_self_approval = 0 を設定します。これにより、次のようになります。

• ドキュメントの所有者（作成者）は、この操作を実行できません
• 管理者は常にこの制限の対象外です
• 必要なロールを持つ他のユーザーは、この操作を実行できます

メール通知

1. Workflow で send_email_alert = 1 を設定します
2. 各状態の行で send_email = 1 を設定します（デフォルト）
3. 必要に応じて、next_action_email_template を使って Email Template をリンクします
4. 状態の行にカスタム message を追加し、通知文をインラインで設定します

状態変更時にフィールドを更新する

状態の行で update_field と update_value を使用して、ドキュメントのフィールドを自動的に設定します。

# Set approval_status when entering "Approved" state
{"state": "Approved", "doc_status": "1",
 "update_field": "approval_status", "update_value": "Approved"}

# Use expression to set approval date dynamically
{"state": "Approved", "doc_status": "1",
 "update_field": "custom_approved_on", "update_value": "frappe.utils.now()",
 "evaluate_as_expression": 1}

ステップ 5：ワークフローをテストする

手動テストのチェックリスト

1. テスト用ドキュメントを作成する — 最初の状態（Draft）から開始することを確認します
2. 使用可能なアクションを確認する — Draft からの遷移を持つロールにのみボタンが表示されることを確認します
3. 各遷移を実行する — 状態が正しく変わることを確認します
4. 却下パスをテストする — ドキュメントが正しい状態に戻ることを確認します
5. 自己承認をテストする — ドキュメントの所有者としてログインし、遷移がブロックされることを確認します
6. 条件をテストする — 条件を満たすドキュメントと満たさないドキュメントを作成し、ボタンの表示を確認します
7. メール通知をテストする — 状態変更時にメールが送信されることを確認します
8. 送信不可の DocType でテストする — すべての doc_status = 0 を確認します

プログラムによるテスト

# Get available transitions for a document
from frappe.model.workflow import get_transitions, apply_workflow

doc = frappe.get_doc("Purchase Order", "PO-00001")
transitions = get_transitions(doc)
# Returns list of dicts with action, next_state, allowed, etc.

# Apply a workflow action
updated_doc = apply_workflow(doc, "Approve")
# Returns the updated document after state change

一般的なワークフローパターン

パターン 1：逐次承認チェーン

Draft → Level 1 Review → Level 2 Review → Approved → Submitted

各レベルに固有のロールがあります。ドキュメントは承認を順番に進みます。

パターン 2：金額による条件付きルーティング

Draft → Pending Approval
  ├─[amount <= 10000 / Team Lead]─→ Approved
  ├─[amount <= 50000 / Manager]──→ Approved
  └─[amount > 50000 / Director]──→ Approved

各遷移に condition を使用して、ドキュメントの値に基づいてルーティングします。

パターン 3：却下ループを含むレビュー

Draft ←──[Reject]── Pending Review ──[Approve]──→ Approved
  └──[Submit for Review]──→ Pending Review

却下されたドキュメントは修正のために Draft に戻ります。作成者が再送信します。これは最も一般的な承認パターンです。

パターン 4：休暇の承認

Applied (doc_status=0, allow_edit=Employee)
  └─[Approve / Leave Approver]─→ Approved (doc_status=1)
  └─[Reject / Leave Approver]─→ Rejected (doc_status=0)
Approved
  └─[Cancel / HR Manager]─→ Cancelled (doc_status=2)

パターン 5：ドキュメントレビュー（送信不可）

送信不可のDocTypeでは、すべての状態でdoc_status = 0である必要があります。

Draft → Under Review → Reviewed → Published
(all doc_status = 0)

手動のDocStatusからワークフローへの移行

現在、DocTypeで手動の送信／キャンセルボタンを使用していて、ワークフローを追加したい場合は、次の手順に従います。

1. 既存のドキュメントをマッピングする — ワークフローエンジンは、ワークフローの作成時に、既存のドキュメントのdocstatusに基づいて状態へ自動的にマッピングします
2. 各docstatusに状態を定義する — ドキュメントで現在使用している各docstatus値に対して、少なくとも1つの状態を必ず用意します
3. 既存データでテストする — 既存の送信済みドキュメントに正しいワークフロー状態が表示されることを確認します
4. リストビューを更新する — override_statusを使用している場合、ステータス列がワークフローの状態に置き換わります

docstatus=0の状態がないまま、ワークフローを有効化しないでください。新しいドキュメントに有効な初期状態が設定されません。

判断ツリー

Starting a new workflow implementation?
│
├── What type of DocType?
│   ├── Submittable → can use doc_status 0, 1, 2
│   └── Non-submittable → ALL states must be doc_status = 0
│
├── How many approval levels?
│   ├── Single → Two-state: Draft → Approved
│   ├── Sequential → Chain: Draft → L1 → L2 → Approved
│   └── Conditional → Route by field values using conditions
│
├── Need self-approval blocking?
│   └── Set allow_self_approval = 0 on approval transitions
│
├── Need rejection/revision loop?
│   └── Add Reject transition back to Draft or previous state
│
├── Need email notifications?
│   ├── Enable send_email_alert on Workflow
│   └── Link Email Template on each state
│
└── Need automated field updates?
    └── Use update_field + update_value on target state

トラブルシューティング

問題	原因	解決策
アクションボタンが表示されない	ユーザーに必要なロールがない	ユーザーにロールを追加するか、ユーザーのロールに対する遷移を追加します
「自己承認は許可されていません」	ユーザーがドキュメントの所有者で、allow_self_approval=0	別のユーザーに承認してもらうか、フラグを1に設定します
「Workflow Stateが設定されていません」	ワークフロー有効化前にドキュメントが作成された	update_default_workflow_statusを実行するか、手動で状態を設定します
ドキュメントが状態から進まない	現在の状態とユーザーロールに対応する遷移先が定義されていない	不足している遷移を追加します
「送信前にキャンセルできません」	遷移元がdoc_status=0で、遷移先がdoc_status=2	送信済みの中間状態を追加します
誤ったユーザーにアクションが表示される	ロールの割り当て範囲が広すぎる	より具体的なロールを使用するか、条件を追加します

関連項目

• ワークフローパターン — 手順を詳しく説明したワークフローの例
• 判断ツリー — ワークフロー設計のための拡張判断ツリー
• 例 — 一般的なシナリオのコード例
• アンチパターン — 避けるべき間違い
• frappe-core-workflow — ワークフローエンジンの内部仕様とAPIリファレンス