frappe-core-notifications

Frappe 通知システム

クイックリファレンス

チャネル	方法	ユースケース
メール	frappe.sendmail()	完全に制御できるプログラムからのメール送信
メール	Notification DocType（Email）	ドキュメントイベントに応じたノーコードのメール送信
システム	frappe.publish_realtime()	socket.io 経由のアプリ内リアルタイム通知
システム	Notification DocType（System）	ノーコードのアプリ内通知
SMS	Notification DocType（SMS）	ドキュメントイベントに応じたノーコードの SMS 送信
Slack	Notification DocType（Slack）	ノーコードの Slack webhook メッセージ
割り当て	frappe.desk.form.assign_to.add()	ドキュメントをユーザーに割り当てる（ToDo を作成）
ToDo	frappe.get_doc({"doctype": "ToDo", ...})	タスクを直接作成
コメント	doc.add_comment("Comment", text)	ドキュメントのタイムラインにコメントを追加
タグ	doc.add_tag("tag_name")	フィルタリング用にドキュメントにタグを付ける

---

判断ツリー

What notification mechanism do you need?
│
├─ Email on document event (no code)?
│  └─ Notification DocType → Channel: Email
│
├─ Programmatic email with custom logic?
│  └─ frappe.sendmail() in server script or hook
│
├─ Real-time in-app notification?
│  ├─ No-code → Notification DocType → Channel: System Notification
│  └─ Programmatic → frappe.publish_realtime()
│
├─ SMS on document event?
│  └─ Notification DocType → Channel: SMS (requires SMS Settings)
│
├─ Assign document to user?
│  ├─ No-code → Assignment Rule DocType
│  └─ Programmatic → frappe.desk.form.assign_to.add()
│
├─ Recurring document creation?
│  └─ Auto Repeat DocType
│
└─ Add comment or tag?
   ├─ Comment → doc.add_comment("Comment", text="...")
   └─ Tag → doc.add_tag("tag_name")

---

Notification DocType

Notification DocType を使うと、4 つのチャネルでノーコードの通知を設定できます。

イベントトリガー

イベント	発生するタイミング
New	ドキュメントが作成されたとき
Save	ドキュメントが保存されたとき
Submit	ドキュメントが送信されたとき
Cancel	ドキュメントがキャンセルされたとき
Value Change	特定のフィールド値が変更されたとき
Days Before	日付フィールドの値の N 日前
Days After	日付フィールドの値の N 日後
Method	カスタム Python メソッドが呼び出されたとき

条件の構文

Condition フィールドでは、必ず Python の式を使用してください。

# Status-based
doc.status == "Open"

# Date-based
doc.due_date == nowdate()

# Threshold-based
doc.grand_total > 40000

# Combined
doc.status == "Overdue" and doc.grand_total > 10000

使用可能なコンテキスト：doc、nowdate()、frappe.utils.*。

受信者の設定

ソース	説明
Document Field	ドキュメント上のメールアドレス／電話番号フィールド
Role	指定したロールを持つすべてのユーザー
Custom	ハードコードされたメールアドレス
All Assignees	ドキュメントに割り当てられたすべてのユーザー
Condition	受信者を絞り込む Jinja 式

Jinja メッセージテンプレート

<h3>Order Overdue</h3>
<p>Transaction {{ doc.name }} has exceeded its due date.</p>

{% if comments %}
Last comment: {{ comments[-1].comment }} by {{ comments[-1].by }}
{% endif %}

<ul>
  <li>Customer: {{ doc.customer }}</li>
  <li>Amount: {{ doc.grand_total }}</li>
</ul>

テンプレート変数：{{ doc }}、{{ doc.fieldname }}、{{ comments }}、{{ nowdate() }}。

印刷物を添付

ドキュメントの PDF を添付するには、Attach Print を設定します。カスタムレイアウトを使用するには、Print Format を選択します。

---

frappe.sendmail()：プログラムからのメール送信

frappe.sendmail(
    recipients=["[email protected]"],       # list of email addresses
    subject="Invoice Due",                  # email subject
    message="<p>Your invoice is due.</p>",  # HTML body
    template="invoice_reminder",            # Jinja template name (optional)
    args={"customer": "ACME"},              # template context variables
    attachments=[{"fname": "inv.pdf", "fcontent": pdf_bytes}],
    reference_doctype="Sales Invoice",      # links email to document
    reference_name="SINV-00001",
    delayed=True,                           # queue via Email Queue (default)
    now=False,                              # True = send immediately, skip queue
    sender="[email protected]",           # override sender
    cc=["[email protected]"],
    bcc=["[email protected]"],
    reply_to="[email protected]",
    expose_recipients="header",             # show recipients in email header
)

ルール：

• メールがドキュメントに関連する場合は、必ず reference_doctype と reference_name を設定してください。これにより、メールがドキュメントのタイムラインに表示されます。
• 本番環境では、now=True を設定しないでください。リクエストがブロックされます。Email Queue 経由でキューに登録するには、delayed=True（デフォルト）を使用してください。
• frappe.sendmail を呼び出す前に、"Enable Outgoing" が有効な Email Account が設定されていることを必ず確認してください。

Email Queue

メールは Email Queue DocType に登録され、スケジューラーによって送信されます。キューのステータスを確認するには、次のようにします。

# Check pending emails
pending = frappe.get_all("Email Queue", filters={"status": "Not Sent"}, limit=10)

---

frappe.publish_realtime()：システム通知

frappe.publish_realtime(
    event="msgprint",                      # event name
    message={"msg": "Task completed!"},    # dict payload
    user="[email protected]",               # target specific user
    doctype="Sales Invoice",               # broadcast to doctype room
    docname="SINV-00001",                  # broadcast to document room
    after_commit=True,                     # emit after transaction commits
)

ルームの種類

ルーム	対象
user:{email}	単一のユーザー（user= を設定）
doctype:{dt}	該当するリストを表示しているすべてのユーザー
doc:{dt}/{dn}	該当するドキュメントを表示しているすべてのユーザー
all	サイト全体のすべての Desk ユーザー
task_progress:{id}	バックグラウンドタスクの進行状況

組み込みイベント

イベント	目的
msgprint	ユーザーにメッセージダイアログを表示
list_update	ドキュメントリストビューを更新
docinfo_update	ドキュメント情報サイドバーを更新
progress	進行状況バーを表示

データベーストランザクション内から通知を送信する場合は、必ず after_commit=True を設定してください。設定しないと、データのコミット前にイベントが発生し、クライアントが古いデータを読み取る可能性があります。

---

割り当てルール

条件に基づいてドキュメントをユーザーに自動割り当てします（コード不要）。

設定フィールド

フィールド	目的
Document Type	ルールをトリガーする DocType
Assign Condition	Python 式（Notification と同じ）
Assignment Days	特定の曜日に限定
Users	割り当て先ユーザーのリスト
Assignment Rule	Round Robin、Load Balancing、または Based on Field

プログラムによる割り当て

from frappe.desk.form.assign_to import add, remove, close, clear

# Assign
add({
    "assign_to": ["[email protected]"],
    "doctype": "Task",
    "name": "TASK-00001",
    "description": "Please review this task",
    "priority": "High",
    "date": "2025-12-31",
})

# Remove assignment (cancels ToDo)
remove("Task", "TASK-00001", "[email protected]")

# Close assignment (only assignee can close)
close("Task", "TASK-00001", "[email protected]")

# Clear all assignments
clear("Task", "TASK-00001")

担当者とは異なるユーザーとして close() を呼び出さないでください。権限エラーが発生します。

---

自動繰り返し

スケジュールに従って、ドキュメントのコピーを定期的に作成します。

フィールド	目的
参照 DocType	繰り返す DocType
参照ドキュメント	コピー元のドキュメント
頻度	毎日、毎週、毎月、四半期ごと、半年ごと、毎年
開始日／終了日	スケジュールの期間
メールで通知	作成時に通知を送信

自動繰り返しには必ず終了日を設定してください。終了日がないスケジュールではドキュメントが無期限に作成され、デバッグが困難になります。

---

ToDo API

# Create ToDo directly
todo = frappe.get_doc({
    "doctype": "ToDo",
    "allocated_to": "[email protected]",
    "assigned_by": frappe.session.user,
    "description": "Review the quarterly report",
    "priority": "Medium",
    "date": "2025-12-31",
    "status": "Open",
    "reference_type": "Task",
    "reference_name": "TASK-00001",
}).insert(ignore_permissions=True)

ToDo のステータス：Open、Closed、Cancelled。

---

コメントとタグ

# Add comment (appears in document timeline)
doc.add_comment("Comment", text="Reviewed and approved")
doc.add_comment("Edit", "Values changed")

# Add/get tags
doc.add_tag("urgent")
tags = doc.get_tags()  # returns list of tag strings

---

バージョンの違い

機能	v14	v15	v16
通知 DocType	4 つすべてのチャネル	4 つすべてのチャネル	4 つすべてのチャネル
分前／分後	利用不可	利用可能	利用可能
frappe.publish_realtime	利用可能	利用可能	利用可能
割り当てルール	利用可能	利用可能	利用可能

---

関連項目

• references/email-system.md — Email Account、Email Queue、Communication の紐付け、Newsletter、Notification Log
• references/examples.md — 通知ワークフローの完全な例
• references/anti-patterns.md — よくある間違いと修正方法
• references/api-reference.md — API シグネチャの完全な一覧
• frappe-core-database — 通知で参照されるデータベース操作
• frappe-core-permissions — 通知へのアクセスに関する権限モデル