#操作前イベント

#はじめに

操作前イベントプラグインは、作成、更新、削除といった操作のリクエストが送信された後、実際に処理される前にトリガーされるインターセプト機能を提供します。

トリガーされたワークフロー内で「ワークフローを終了」ノードが実行された場合、または他のノードの実行が失敗した場合（エラーや未完了など）、そのフォーム操作はインターセプトされます。それ以外の場合は、予定された操作が正常に実行されます。

「応答メッセージ」ノードと組み合わせることで、クライアントに返される応答メッセージを設定し、適切な情報を提示できます。操作前イベントは、クライアントから送信される作成、更新、削除などの操作リクエストを承認またはインターセプトするためのビジネスバリデーションやロジックチェックに利用できます。

#トリガーの設定

#トリガーの作成

ワークフローを作成する際、タイプとして「操作前イベント」を選択します。

#コレクションの選択

インターセプトワークフローのトリガーで最初に設定するのは、操作に対応するコレクションです。

次にインターセプトモードを選択します。このワークフローにバインドされた操作ボタンのみをインターセプトするか、またはこのコレクションの選択されたすべての操作をインターセプトするか（どのフォームから来たかに関わらず、対応するワークフローをバインドする必要もありません）を選択できます。

#インターセプトモード

現在サポートされている操作タイプは「作成」、「更新」、「削除」です。複数の操作タイプを同時に選択できます。

#操作の設定

トリガー設定で「このワークフローにバインドされたフォームが送信された場合にのみインターセプトをトリガー」モードを選択した場合、フォーム画面に戻り、対応する操作ボタンにこのワークフローをバインドする必要があります。

ワークフローのバインド設定で対応するワークフローを選択します。通常、トリガーデータのコンテキストはデフォルトの「フォームデータ全体」で十分です。

#インターセプトの条件

「操作前イベント」では、対応する操作がインターセプトされる2つの条件があります。

1. ワークフローが任意の「ワークフローを終了」ノードに到達した場合。前述の使用説明と同様に、トリガーされたワークフローのデータが「条件判断」ノードで事前に設定された条件を満たさない場合、「いいえ」の分岐に進み、「ワークフローを終了」ノードが実行されます。この時点でワークフローは終了し、リクエストされた操作はインターセプトされます。
2. ワークフロー内の任意のノードの実行が失敗した場合。ノードの実行エラーやその他の例外状況を含みます。この場合、ワークフローは対応するステータスで終了し、リクエストされた操作もインターセプトされます。例えば、ワークフローが「HTTPリクエスト」を通じて外部データを呼び出す際に、リクエストが失敗した場合、ワークフローは失敗ステータスで終了すると同時に、対応する操作リクエストもインターセプトされます。

インターセプト条件が満たされると、対応する操作は実行されなくなります。例えば、注文の送信がインターセプトされた場合、対応する注文データは作成されません。

#対応する操作の関連パラメーター

「操作前イベント」タイプのワークフローでは、異なる操作に対して、トリガーからの異なるデータがワークフロー内で変数として使用できます。

#応答メッセージの出力

トリガーを設定した後、ワークフロー内で関連する判断ロジックをカスタマイズできます。通常、「条件判断」ノードの分岐モードを使用し、特定のビジネス条件の判断結果に基づいて、「ワークフローを終了」するかどうかを決定し、事前に設定された「応答メッセージ」を返します。

これで、対応するワークフローの設定が完了しました。次に、ワークフローの条件ノードで設定された条件を満たさないデータを送信して、インターセプターのインターセプトロジックをトリガーしてみてください。そうすると、返される応答メッセージを確認できます。

#応答メッセージのステータス

「ワークフローを終了」ノードが「成功」ステータスで終了するように設定されており、このノードが実行された場合、その操作のリクエストは引き続きインターセプトされますが、返される応答メッセージは「成功」（「エラー」ではなく）ステータスで表示されます。

#例

上記の基本的な使用説明を組み合わせ、ここでは「注文送信」シナリオを例にとります。ユーザーが注文を送信する際、選択されたすべての製品の在庫を検証する必要があるとします。選択されたいずれかの製品の在庫が不足している場合、注文の送信はインターセプトされ、対応するプロンプトメッセージが返されます。すべての製品の在庫が十分になるまで各製品をループしてチェックし、その時点で処理を進め、ユーザーの注文データを作成します。

その他の手順は説明と同じです。ただし、1つの注文が複数の製品を対象とするため、データモデリングで「注文」<-- M:1 -- 「注文詳細」-- 1:M --> 「製品」という多対多のリレーションシップを追加するだけでなく、「操作前イベント」ワークフローに「ループ」ノードを追加し、各製品の在庫が十分であるかを繰り返しチェックする必要があります。

ループの対象は、送信された注文データ内の「注文詳細」配列として選択します。

ループ内の条件判断ノードは、現在ループ中の製品オブジェクトの在庫が十分であるかを判断するために使用されます。

その他の設定は基本的な使用方法と同じです。最終的に注文が送信される際、いずれかの製品の在庫が不足している場合、注文の送信はインターセプトされ、対応するプロンプトメッセージが返されます。テスト時には、1つの注文で複数の製品を送信してみてください。そのうち1つの製品の在庫が不足しており、もう1つの製品の在庫が十分である場合、返される応答メッセージを確認できます。

ご覧のとおり、応答メッセージでは最初の製品「iPhone 15 Pro」の在庫不足は示されておらず、2番目の製品「iPhone 14 Pro」の在庫不足のみが示されています。これは、ループ内で最初の製品の在庫が十分であったためインターセプトされず、2番目の製品の在庫が不足していたため、注文の送信がインターセプトされたためです。

#外部からの呼び出し

操作前イベント自体はリクエスト処理フェーズに組み込まれているため、HTTP API呼び出しによるトリガーもサポートしています。

操作ボタンにローカルでバインドされたワークフローの場合、次のように呼び出すことができます（posts コレクションの作成ボタンを例に説明します）。

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create?triggerWorkflows=workflowKey"

ここで、URLパラメーター triggerWorkflows はワークフローのキーであり、複数のワークフローキーはカンマで区切ります。このキーは、ワークフローキャンバス上部のワークフロー名にマウスカーソルを合わせると取得できます。

上記の呼び出しが実行されると、対応する posts コレクションの操作前イベントがトリガーされます。対応するワークフローが同期的に処理された後、データは正常に作成され、返されます。

設定されたワークフローが「終了ノード」に到達した場合、インターフェース操作のロジックと同じで、リクエストはインターセプトされ、データは作成されません。終了ノードのステータスが失敗に設定されている場合、返される応答ステータスコードは 400 であり、成功時は 200 です。

終了ノードの前に「応答メッセージ」ノードも設定されている場合、生成されたメッセージも応答結果で返されます。エラー時の構造は次のとおりです。

{
  "errors": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

「終了ノード」が成功に設定されている場合のメッセージ構造は次のとおりです。

{
  "messages": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

操作前イベントがグローバルモードで設定されている場合、HTTP APIを呼び出す際にURLパラメーター triggerWorkflows を使用して対応するワークフローを指定する必要はありません。対応するコレクション操作を直接呼び出すだけでトリガーされます。

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create"