novu-design-workflow

ワークフローの設計

Novu ワークフローの設計ルールです。ダッシュボード（ノーコード）で作成する場合も、@novu/framework を使ってコードで作成する場合も同じです。ここで決める内容（チャネル、重要度、クリティカル、ダイジェスト、条件）はどちらの方法でも共通で、異なるのは構文だけです。

コードで作成しますか？このスキルと framework-integration/ を併用して、workflow(...)、step.*、controlSchema、Bridge Endpoint の設定を行ってください。 ダッシュボードまたは Novu MCP で作成しますか？ここで設計した後、dashboard-workflows/ を使ってステップの内容（件名、本文、editorType、ヘッダー、条件）を設定してください。

このスキルを使う場面

ワークフローの設計を決める必要があるときに使用してください。

• 「注文確認ワークフローを設計して」
• 「支払いに失敗したとき、どのチャネルで送信すればよいですか？」
• 「この通知をクリティカルにして」
• 「ダイジェストにまとめるべきですか？」
• 「オフラインのサブスクライバー向けにフォールバックを追加して」
• 「X に適したテンプレートは何ですか？」

以下の場合には使用しないでください。既存のワークフローをトリガーする場合（trigger-notification/）、コードラッパーを作成する場合（framework-integration/）、UI で重要度を表示する場合（[inbox-integration/](../inbox-integration）。

重要度とクリティカル

独立した 2 つの設定です。ほとんどのワークフローではどちらも設定しません。

設定	値	デフォルト	効果
severity	LOW / MEDIUM / HIGH	未設定	Inbox で視覚的に優先順位を付けます（色、発光）。ダイジェストのスキップルールにも影響します。
critical	true / false	false	サブスクライバーの設定を無視し、ダイジェストをスキップし、遅延なしで利用可能なすべてのチャネルに配信します。

目安：

• ほとんどのワークフローでは severity を未設定のままにします。視覚的な優先順位付けが必要な場合にのみ設定してください。
• HIGH = 「今日中に対応する」（支払い失敗、翌日に期限切れとなるトライアル）。
• critical: true = 「設定に関係なく配信する」（アカウントの停止、セキュリティアラート、パスワードリセット）。
• critical: true ⇒ ダイジェストは自動的にスキップされ、チャネルに即時配信されます。

動作の一覧と readOnly と critical の違いについては、references/severity-and-critical.md を参照してください。

チャネルの選択

ユーザーがチャネルを指定した場合

指定されたチャネルのみを使用してください。フォールバックも追加のチャネルも追加しないでください。要求されたチャネルが組織で設定されていなくても、ユーザーが明示的に指定しているため追加してください。

「注文の発送時にプッシュ通知を送信して」→ push ステップを 1 つだけ設定します。それ以外は追加しません。

ユーザーがチャネルを指定していない場合

組織で設定されているチャネルから、次の優先順位で最大3つ選びます。

In-App  >  Email  >  Chat  >  Push  >  SMS

チャネル	用途	使用しない場合
In-App	製品内コンテンツのデフォルトです。ユーザーが製品内にいる場合は、必ず含めます。	受信者が表示できない場合（パスワードリセット、OTP、登録前）
Email	領収書、ドキュメント、非同期コミュニケーションに使用します。In-App の次のデフォルトのフォールバックです。	製品内での純粋な会話形式の通知
Chat	設定されており、かつ severity >= MEDIUM の場合に使用します。運用および社内フローには Slack/Teams を使用します。	マーケティングや重要度の低い通知
Push	購読者がオフラインで、すぐに通知する必要がある場合のフォールバックです。	購読者がオンラインの場合（代わりに In-App を使用）
SMS	最終手段です。他のチャネルが使えない場合にのみ使用します（真の緊急事態、OTP、規制関連）。	Email または Push で対応できる内容

完全な判断ツリーについては、references/channel-selection.md を参照してください。

ダイジェストのデフォルト設定

ダイジェストステップを追加する場合は、次の設定をデフォルトとして使用します。

• type: "regular"
• 遡る期間：5 minutes
• ダイジェスト時間：1 hour
• キー：subscriberId（会話形式のフローでは +threadId も追加）

次の場合はダイジェストをスキップします。

• severity: HIGH、または
• critical: true

ダイジェストキーの構成や会話形式の例については、references/digest-defaults.md を参照してください。

ユーザー状態のロジック

購読者がオンラインかどうかに応じて、ルーティングを調整します。

状態	動作
オンライン	In-App をすぐに送信します。Push はスキップします。重要度に応じて Email/Chat を遅らせます。
オフライン	注意を引くために Push または Chat を使用します。

デフォルトの遅延時間：

• B2B アプリ → 次の勤務時間
• B2C アプリ → 約 30 分

「購読者がオフライン」の条件はどちらのサーフェスでも同じです。詳細については、references/step-conditions.md を参照してください。

ワークフローテンプレート

ユースケースに合うテンプレートを選び、その構成に従ってください。各テンプレートでは、重要度、critical、アクション可能かどうか、インタラクションの種類に加え、ステップの順序を指定しています。

#	ユースケース	重要度	Critical	備考
1	注文確認	none	false	ダイジェスト配信、アプリ内通知 + メール + プッシュ（オフライン時のみ）
2	自分の投稿へのコメント	none	false	subscriberId + threadId でダイジェスト化
3	決済失敗	HIGH	false	アプリ内通知 + チャット + メール + プッシュ（オフライン時）
4	アカウント停止	HIGH	true	すべてのチャネル、設定を無視、ダイジェストなし
5	パスワードを忘れた場合	none	true	メール + SMS のみ、アプリ内通知なし
6	トライアル終了まであと1日	HIGH	false	アプリ内通知 + チャット + メール + プッシュ（オフライン時）
7	チャネルの明示的なリクエスト	n/a	n/a	ユーザーが指定したチャネルのみを使用
8	Webhook / 外部 API 呼び出し	varies	varies	チャネルのステップの後に step.http を追加
9	データを取得してから通知	varies	varies	最初に step.http を配置し、responseBodySchema を宣言

ASCII 形式のフロー全体と、テンプレートごとのメタデータは references/workflow-templates.md を参照してください。

ステップ条件

条件によって、ステップを実行するかどうかを決定します。「サブスクライバーがオフラインの場合のみ送信する」「アプリ内通知が確認されなかった場合のみメールを送信する」などのフォールバックに使用してください。

• ダッシュボードの作成者は JSON-Logic を記述します：{ "==": [{ "var": "subscriber.isOnline" }, "false"] }
• フレームワークの作成者は、ステップに skip: () => boolean コールバックを渡します。

セマンティクスは同じです。正規のスニペットと各スコープで利用可能な変数については、references/step-conditions.md を参照してください。

よくある落とし穴

1. 重要度をデフォルトで設定しないでください — 視覚的な優先順位付けが本当に必要な場合を除き、未設定のままにしてください。
2. critical: true と readOnly: true は同じではありません — readOnly は設定 UI でワークフローを非表示にするだけですが、critical は実行時に設定とダイジェストを無視します。references/severity-and-critical.md を参照してください。
3. ユーザーがチャネルを指定した場合、フォールバックを追加しないでください — 明示的なチャネル指定はそのとおりに扱います。
4. ユーザーがチャネルを指定していない場合、チャネル数は最大3つにしてください。 チャネルを増やすと、リーチが広がるのではなく、煩わしさが増します。
5. ダイジェストと critical: true を組み合わせないでください — critical なワークフローは即時に配信する必要があります。ダイジェストのステップは自動的にスキップされます。
6. 会話形式のフローではダイジェストキーが重要です — +threadId がないと、投稿 A と投稿 B へのコメントが同じダイジェストにまとめられます。
7. プッシュ通知はオフライン時のみ送信してください — オンラインのユーザーにプッシュ通知を送ると、アプリ内通知と重複します。
8. HTTP ステップには responseBodySchema が必要です — これがないと、後続のステップで {{ steps.<id>.<prop> }} を使ってレスポンスのプロパティを読み取れません。

参考資料

• チャネルの選択 — 判断フロー全体とチャネルごとのガイダンス
• 重要度と Critical — 動作マトリックス、設定とダイジェストの相互作用、readOnly と critical の違い
• ダイジェストのデフォルト設定 — ウィンドウ、キー、会話形式のダイジェストパターン
• ステップ条件 — JSON-Logic のスニペットと、フレームワークの skip に相当する処理
• ワークフローテンプレート — 重要度／critical／インタラクションの表を含む9つの参照フロー

関連項目

• dashboard-workflows/ — ダッシュボードまたは Novu MCP ワークフローのステップコンテンツ（subject、body、editorType、ヘッダー、条件）を作成します
• framework-integration/ — これらの設計をコード（workflow()、step.*、controlSchema、Bridge）に実装します
• manage-preferences/ — critical がサブスクライバーレベルの設定とどのように連動するかを説明します
• inbox-integration/ — Inbox で重要度がどのように視覚的に表示されるかを説明します
• trigger-notification/ — 設計したワークフローを実行する方法を説明します