building-workflows

ワークフローの構築

PostHog のワークフローは、有向グラフです。アクションノード（actions）を並べ、エッジ（edges）で接続し、実行を開始する trigger ノードをちょうど 1 つ含みます。このグラフを JSON として作成し、MCP 経由で送信します。ユーザーには常に「ワークフロー」と呼んでください。「Hog flow」は内部コード名（HogFlow）であり、ユーザー向けの用語ではありません。

最大の失敗要因は、グラフ JSON の構造を誤ることです。バックエンドは actions／config を自由形式の JSON として保存しますが、ビジュアルエディターはすべてのノードを厳密なスキーマに照らして解析します。そのため、不正なノードは保存されても、ワークフロー全体のエディター表示を壊す可能性があります。グラフを作成または編集する前に、必ずreferences/graph-schema.mdを読んでください。これは仕様です。これらの例だけを参考に、ノードの形を独自に考案しないでください。

最初のメッセージングワークフローを始める前に

ユーザーがワークフローやメッセージングの設定を依頼した場合、またはまだ送信できない可能性のあるプロジェクトでメール、SMS、プッシュ通知のワークフローを依頼した場合は、何かを作成する前に workflows-setup-status を呼び出してください。未完了の設定手順と、アプリ内の各手順へのリンクが表示されます。未完了の手順をユーザーに案内し、送信ルールを設定してから、推奨ワークフローを提案します。手順と推奨するデフォルト設定については、references/onboarding.mdを読んでください。

Slack への投稿または Webhook の呼び出しのみを行う自動化では、メール設定は不要なので、この手順は省略してください。workflows-setup-status が利用できない場合は、そのまま以下のライフサイクルに進んでください。

ライフサイクル

ワークフローは、次の各段階に沿って進めてください。有効化に直行しないでください。

1. グラフを作成します。 references/graph-schema.md に従って actions と edges を作成します。function ノードでは、テンプレートを推測せず、cdp-function-templates-list で現在のカタログを一覧表示し、cdp-function-templates-retrieve で必須入力を確認してください。
2. ドラフトとして作成します。 workflows-create を実行します。ワークフローはすべて draft として作成され、まだ実行されません。
3. テスト実行します。 workflows-test-run は 一度に1ステップ 実行します。最初のステップから開始し（current_action_id を省略するか、トリガーを指定します）、トリガーの実際のペイロードに沿ったサンプル globals（{event, person, groups}）を使用します。event トリガーにはフィルターに一致するイベントが必要です。internal-event トリガーには filters.events に記載された名前のイベントが必要です（Slack トリガーの場合は、Slack プロパティバッグを含む $slack_message_received イベント）。また、人物は指定しません（references/graph-schema.md を参照）。status=skipped は、このペイロードではトリガーが起動しないことを意味します。ペイロードを作成した場合は、トリガーに一致するよう修正してください。実際の過去の実行から取得した場合（workflows-get-invocation）、誤っているのはペイロードではなくトリガーのフィルターです。結果には次のステップの ID（nextActionId）が含まれます。それを current_action_id として渡して再実行し、最後までステップごとに進めます。delay ノードは、その後のアクションに進んでスキップしてください（遅延はシミュレーションされません）。mock_async_functions=false を設定しない限り、非同期の副作用（HTTP／メール／SMS／プッシュ）はモックされます。各ステップのトレースを読み、実行された経路を確認してください。
4. 反復作業中はログを確認します。 workflows-logs には、ステップごとの実行トレース（DEBUG から ERROR までのレベル）が表示されます。これにより、ステップがスキップ、分岐、またはエラーになった理由を確認できます。
5. 編集してから再テストします。 workflows-patch-graph でグラフにパッチを適用します（ドラフトの編集を参照）。編集するたびに、それ以前のテスト結果は無効になります。次に進む前に、影響を受ける経路を再実行してください。ドラフトワークフローでは編集内容が直接適用されます。有効なワークフローではドラフトとして反映されます（稼働中のワークフローの変更を参照）。
6. 有効化します（ユーザーによる明示的な承認が必要です）。 workflows-enable を実行すると active に切り替わり、event／webhook／manual トリガーは、一致するアクティビティで起動するようになります。有効化後は実際の人物を対象に実行され、すべての変更は反映前にドラフト → テスト → 公開のサイクルを経る必要があります。そのため、テストを完了してから、ユーザーの明示的な承認を得て有効化してください。独断で有効化しないでください。
7. 実行します（バッチ／スケジュールのみ）。 batch または schedule ワークフローは、有効化しただけでは起動しません。workflows-run-batch で単発のブロードキャストを送信するか、workflows-schedule-create で繰り返しスケジュールを設定します。batch トリガーは対象者の人物全員に展開されるため、スケジュール設定には workflows-blast-radius のプレビューと、その確認トークンが必要です。schedule トリガーは対象者を指定せず、発生のたびに1回実行されるため、そのままスケジュールを設定してください。workflows-get で status=='active' であること、さらに読み取り専用の schedules フィールドに有効なエントリがあることを確認してください。
8. 監視します。 詳細を確認するには、workflows-global-stats（失敗しているワークフロー）から workflows-stats（1つのワークフローの傾向）、workflows-list-invocations（どの人物に対して失敗したか）、workflows-get-invocation（トリガーとなったペイロード）、workflows-logs（失敗したステップ）の順に調べます。

作業別にまとめたツールの全カタログ：references/lifecycle-and-debugging.md。

下書きの編集

置き換えるのではなく、パッチを適用します。 workflows-patch-graph で下書きを編集します。これは、ID を指定して順番に適用する操作の小さなリストです（update_action、add_action、remove_action、add_edge、remove_edge、replace_action_edges）。update_action はパッチをディープマージするため、メールの件名を変更するだけなら、グラフ全体ではなく数行で済みます。操作はサーバー側でアトミックに適用され（読み込み、順番に適用、検証、有効な場合のみ保存）、応答には更新後のグラフ全体が含まれるため、次の編集の前に再取得する必要はありません。これにより、すべてのアクションとエッジを再送信せずに、各ラウンドトリップを小さく保てます。

workflows-update が対応するのは、グラフパッチでは表現できない項目だけです。たとえば、name、description、exit_condition、conversion、trigger_masking、variables などのトップレベルフィールドです。actions／edges は明示的に拒否されます。部分的なリストを渡すと、省略したすべてのステップが黙って削除されてしまうため、グラフへの変更はすべて workflows-patch-graph で行ってください。

どのパッチの適用後も、変更した経路を再テストしてください（ステップ 3）。構造上有効なパッチでも、誤った経路に分岐することがあります。

メールの内容にも同じルールが適用されます。 function_email ステップ内のメールは、workflows-patch-action-email で編集します。テンプレートのパッチと同じ ID 指定の設計操作に加え、件名／プレヘッダー／本文／宛先に対する email_patch マージを使用し、HTML はサーバー側で再レンダリングされるため、設計と常に一致します。 メールの内容には、workflows-patch-graph の update_action ではなく、こちらを優先してください。design を変更する update_action では、保存済みの html が古いままになります。 ライブラリのテンプレートは、workflows-update-email-template（設計 JSON 全体を再送信します）ではなく、workflows-patch-email-template で編集します。 メールの設計の作成と編集には、designing-email-templates スキルを使用してください。

稼働中のワークフローを変更する

アクティブなワークフローを編集すると、実行中の内容が変更されるのではなく、ドラフトが作成されます。公開するまでは、実際のユーザーには何も反映されません。次のサイクルで進めてください。

1. 編集します。 アクティブなワークフローに対して workflows-patch-graph（コンテンツフィールドの場合は workflows-update）を実行すると、ドラフトに変更が書き込まれます。最初の編集時に稼働中のグラフがドラフトにコピーされ、以降の編集はその上に反映されます。workflows-get では、ステージングされたドラフトが draft に表示され、稼働中の設定は actions／edges に残ります。メタデータ（名前、説明）はすぐに稼働中の設定に反映されます。
2. ドラフトをテストします。 use_draft=true を指定して workflows-test-run を実行すると、稼働中の設定ではなく、ステージングされたドラフトが実行されます。変更したすべての経路を再テストしてください。
3. 意図を確認して公開します。 confirm を指定せずに workflows-publish を実行すると、in_flight_runs、confirm_token、impact の概要が返されます。概要には、削除されるステップごとに、そこに滞留しているユーザーのおおよその人数と、生き残るステップに移動するのか（moves_to）、終了するのかが示されます。また、参照箇所に到達した時点で、新しい生成元をすでに通過しているユーザーについて空になる可能性がある empty_variables（構造上の警告です。進行中の全員がまだ生成元より前にいても発生することがあります）と、ドラフトで削除される変数をスケジュールが上書きする schedule_conflicts も示されます。影響の概要をユーザーに伝え、承認を得てから、confirm=true とその confirm_token を指定して再度実行してください。409 はプレビュー後にドラフトが変更されたことを、400 はトークンの有効期限が切れたこと（15 分）を意味します。いずれの場合も、再度プレビューして承認を取り直してください。公開時にはすべてが再検証されるため、無効なドラフトは却下され、稼働中の設定は変更されません。
4. または、取り消します。 workflows-discard-draft を実行すると、ステージングされたドラフトが破棄されます。

進行中の実行は稼働中の設定に従います。公開後、フローの途中にいるユーザーは、新しいバージョンの現在のステップから続行します。すでに通過したステップは再実行されません。公開によって削除されたステップに滞留しているユーザーは、次に残っているステップへ進むか、行き止まりの場合は終了します。これは影響のプレビューで報告された内容と同じです。

タイミングの変更は、滞留中の実行に徐々に適用され、すぐには反映されません。待機時間の短縮（または待機時間帯の移動）を公開すると、対象の実行はレート制限付きの一括処理によって再スケジュールされます。まもなく起動予定の実行は、元の早い起動時刻がそのまま維持されます。一括処理によって起動時刻が早まる実行のみが対象となり、公開から数分以上経ってから、ばらつきを持たせて起動します（元の起動時刻より遅くなることはありません）。公開後しばらくの間、まだ滞留している実行があるのは想定どおりです。再公開したり、失敗として扱ったりせず、その旨をユーザーに伝えてください。

ロールバック

稼働中のコンテンツを変更するたびに、ワークフローのリビジョン履歴にスナップショットが追加されます。workflows-list-revisions ではバージョン（新しい順）が一覧表示され、workflows-get-revision では特定のバージョンの全コンテンツが返されます。ロールバック（または先のバージョンへの移行）するには、workflows-restore-revision でそのバージョンのコンテンツをドラフトにコピーします。稼働中の設定は変更されません。その後は通常の公開サイクルに従い、use_draft=true でテストし、プレビューして、承認します。プレビューには、ほかの公開と同様に、ロールバックが進行中のユーザーに与える影響が正確に表示されます。

すでにドラフトが開かれている場合、復元は 409 を返します。ドラフトを公開または破棄するか、overwrite=true を指定して置き換えてください。ロールバックで元に戻せないことが 2 つあります。新しいバージョンが稼働している間にすでに移動または終了した実行は、位置がそのまま維持されます（副作用はすでに発生しています）。また、待機時間を短縮する公開によって、滞留中の実行の起動時刻が早まっていた場合、ロールバックしても再び遅くはなりません。

サーバーが所有するもの。決して送信しないでください

サーバーがこれらをコンパイルし、管理します。手作業で作成すると、ワークフローが壊れる最短の原因になります。

• bytecode：フィルター、トリガー、条件、変換、マスキングのいずれかに設定されているもの。人間が読める properties／hash からサーバー側でコンパイルされます。省略してください。filters: {...} を送信し、bytecode は送信しないでください。
• trigger（トップレベル）。actions の trigger アクションから 導出 されます。読み取り専用です。このフィールドを設定するのではなく、トリガーノードを追加してトリガーを設定してください。
• billable_action_types、version、id、created_*。自動計算／管理されます。

最小の実例

イベントトリガー、1日待機、メール送信、終了。注：trigger は正確に1つで、終了以外のすべてのノードに出力エッジがあり、edges では一貫した ID を参照します。また、bytecode は送信しません。

{
  "name": "Nudge after signup",
  "description": "One day after signup, send a reminder.",
  "exit_condition": "exit_only_at_end",
  "actions": [
    {
      "id": "trigger_node",
      "name": "Signed up",
      "type": "trigger",
      "config": {
        "type": "event",
        "filters": { "events": [{ "id": "user signed up", "name": "user signed up", "type": "events", "order": 0 }] }
      }
    },
    {
      "id": "delay_1",
      "name": "Wait 1 day",
      "type": "delay",
      "config": { "delay_duration": "1d" }
    },
    {
      "id": "email_1",
      "name": "Reminder email",
      "type": "function_email",
      "config": {
        "template_id": "template-email",
        "template_uuid": "<uuid returned by workflows-create-email-template>",
        "message_category_type": "marketing",
        "inputs": {
          "email": {
            "value": {
              "to": { "email": "{person.properties.email}", "name": "" },
              "from": { "email": "[email protected]", "name": "Example" }
            }
          }
        }
      }
    },
    {
      "id": "exit_node",
      "name": "Exit",
      "type": "exit",
      "config": { "reason": "Done" }
    }
  ],
  "edges": [
    { "from": "trigger_node", "to": "delay_1", "type": "continue" },
    { "from": "delay_1", "to": "email_1", "type": "continue" },
    { "from": "email_1", "to": "exit_node", "type": "continue" }
  ]
}

メール本文は手書きの html ではなく、テンプレートライブラリから取得します。

1. まず再利用します。 workflows-list-email-templates でライブラリを一覧表示し、用途に合うテンプレートを選びます。ドリップキャンペーンでは通常、すべてのメールステップから1つの基本テンプレート（たとえば、ブランド付きのお知らせ）を参照します。
2. 適したものがない場合にのみ作成します。 designing-email-templates スキルを使い、デザインを先に作成して新しいテンプレートを作ります。design を作成し、html は省略します（サーバーがデザインから html をレンダリングします）。
3. 各ステップから参照します。 上記のように、各ステップの config.template_uuid にテンプレートの UUID を設定します。保存すると、テンプレートの件名、テキスト、html、デザインがステップにスナップショットとして保存されます。
4. ステップごとに内容を変えます。 workflows-patch-action-email のデザイン操作を使います。各ステップのスナップショットは個別に編集されるため、1つの基本テンプレートから作成した5つのステップに、それぞれ異なる内容を設定できます。

スナップショットは一方向です。ライブラリのテンプレートを後から編集しても、すでに参照しているステップは変わりません。また、ステップへのパッチ適用によってライブラリのテンプレートが変更されることもありません。テンプレートの編集内容がワークフローにも反映されるとユーザーが期待している場合は、その誤解を正してください。ステップにはコピーが保持されるため、それぞれ workflows-patch-action-email で更新する必要があります。

デザインと併せて、必ず実際に使えるプレーンテキストの text もテンプレートに設定してください。リッチコンテンツをブロックするクライアントには text のみが表示されるため、「placeholder」のような仮テキストが実際の受信トレイに届いてしまいます。

回避せず、ユーザーに明示すべき厳格なルール

• 行動に基づくターゲティングには対応していません。 「過去 M 日間にイベント X を N 回以上実行した」は、トリガーにもバッチ／スケジュールのオーディエンスにも指定できません。依頼された場合は、対応できないことを伝えて説明してください。壊れたフィルターで近似してはいけません。（バックエンドは、行動に基づくコホートをバッチオーディエンスで明示的に拒否します。）
• バッチオーディエンスで指定するのは、その人が「何をしたか」ではなく、「どのような人か」です。 人物プロパティ、および／または静的／プロパティベースのコホートのみが対象です。バッチオーディエンスのイベント／アクションフィルターは黙って破棄されるため、使用できません。
• オーディエンスは再評価される形式を優先してください。 バッチでは、インラインの人物プロパティ条件または動的（フィルターベース）コホートを使うと、条件を満たす人が再評価されます。静的コホートは固定リストなので、明示的に指定された集合に限って使用してください。