#操作後イベント

#はじめに

システム内でユーザーが行うすべてのデータ変更は、通常、何らかの操作を通じて行われます。具体的には、フォームの「送信」ボタンやデータブロック内の「操作」ボタンなどのクリックが一般的です。操作後イベントは、これらのボタン操作にワークフローを紐付け、ユーザーの操作が成功した後に特定のプロセスをトリガーするために使用されます。

例えば、データの新規作成や更新を行う際、ユーザーはボタンの「ワークフローを紐付ける」オプションを設定することで、操作完了後に紐付けられたワークフローをトリガーできます。

実装レベルでは、操作後イベントの処理はミドルウェア層（Koaのミドルウェア）で行われるため、NocoBaseへのHTTP APIコールによっても、定義済みの操作後イベントをトリガーすることが可能です。

#インストール

これは組み込みのプラグインなので、インストールは不要です。

#トリガー設定

#ワークフローの作成

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

#実行モード

操作後イベントの場合、作成時に実行モードを「同期」または「非同期」から選択できます。

ユーザー操作後すぐに実行し、結果を返す必要があるプロセスであれば、同期モードを使用できます。それ以外の場合は、デフォルトで非同期モードになります。非同期モードでは、ワークフローがトリガーされた後、その操作はすぐに完了し、ワークフローはアプリケーションのバックグラウンドでキューとして順次実行されます。

#コレクションの設定

ワークフローキャンバスに入り、トリガーをクリックして設定ポップアップを開きます。まず、紐付けるコレクションを選択する必要があります。

#トリガーモードの選択

次に、トリガーモードを選択します。これには「ローカルモード」と「グローバルモード」の2種類があります。

各モードの詳細は以下の通りです。

• ローカルモードは、このワークフローが紐付けられた操作ボタンでのみトリガーされます。このワークフローが紐付けられていないボタンをクリックしてもトリガーされません。用途の異なるフォームで同じプロセスをトリガーするかどうかを考慮し、このワークフローを紐付けるかどうかを決定できます。
• グローバルモードは、コレクションに設定されているすべての操作ボタンでトリガーされます。どのフォームからの操作であるかを区別せず、対応するワークフローを紐付ける必要もありません。

ローカルモードで現在紐付けがサポートされている操作ボタンは以下の通りです。

• 新規作成フォームの「送信」ボタンと「保存」ボタン。
• 更新フォームの「送信」ボタンと「保存」ボタン。
• データ行（テーブル、リスト、カンバンなど）の「データを更新」ボタン。

#操作タイプの選択

グローバルモードを選択した場合、操作タイプも選択する必要があります。現在、「データ作成操作」と「データ更新操作」がサポートされています。どちらの操作も、成功後にワークフローをトリガーします。

#関連データのプリロードの選択

後続のプロセスでトリガーされたデータの関連データを使用する必要がある場合、プリロードする関連フィールドを選択できます。

トリガー後、これらの関連データをプロセス内で直接使用できます。

#操作設定

ローカルトリガーモードの操作の場合、ワークフローの設定が完了したら、ユーザーインターフェースに戻り、対応するデータブロックのフォーム操作ボタンに、このワークフローを紐付ける必要があります。

「送信」ボタン（「データを保存」ボタンを含む）に設定されたワークフローは、ユーザーが対応するフォームを送信し、データ操作が完了した後にトリガーされます。

ボタン設定のメニューから「ワークフローを紐付ける」を選択すると、紐付け設定ポップアップが開きます。このポップアップでは、トリガーするワークフローを複数設定できます。何も設定しない場合は、トリガーは不要であることを意味します。各ワークフローについて、まずトリガーするデータがフォーム全体のデータなのか、それともフォーム内の特定の関連フィールドのデータなのかを限定する必要があります。その後、選択したデータモデルに対応するコレクションに基づいて、そのコレクションモデルに一致するように設定されたフォームワークフローを選択します。

#例

ここでは、新規作成操作を例にデモンストレーションを行います。

「経費精算申請」のシナリオを想定します。従業員が経費精算を申請した後、金額の自動承認と、上限額を超えた場合の手動承認を行います。承認された申請のみが通過し、その後、財務部門で処理されるという流れです。

まず、「経費精算」コレクションを作成します。以下のフィールドを持ちます。

• プロジェクト名：単一行テキスト
• 申請者：多対一（ユーザー）
• 金額：数値
• ステータス：単一選択（「承認済み」、「処理完了」）

次に、「操作後イベント」タイプのワークフローを作成し、トリガー内のコレクションモデルを「経費精算」コレクションに設定します。

ワークフローを有効な状態に設定した後、プロセスの具体的な処理ノードは後で設定します。

次に、インターフェース上に「経費精算」コレクションのテーブルブロックを作成し、ツールバーに「追加」ボタンを追加して、対応するフォームフィールドを設定します。そして、フォームの「送信」操作ボタンの設定項目で、ボタンの「ワークフローを紐付ける」設定ダイアログを開き、コンテキストとしてフォーム全体のデータを選択し、ワークフローとして以前作成したワークフローを選択します。

フォームの設定が完了したら、ワークフローのロジック設計に戻ります。例えば、金額が500元を超える場合は管理者に手動承認を要求し、そうでない場合は直接承認します。承認後に経費精算記録を作成し、財務部門でさらに処理されるという流れです（省略）。

後続の財務処理を省略すると、これで経費精算申請プロセスの設定が完了です。従業員が経費精算申請を記入して送信すると、対応するワークフローがトリガーされます。費用金額が500未満の場合は、自動的に記録が作成され、財務部門でのさらなる処理を待ちます。そうでない場合は、上長による承認が行われ、承認後も同様に記録が作成され、財務部門に引き渡されます。

この例のプロセスは、通常の「送信」ボタンにも設定できます。具体的なビジネスシナリオに応じて、まず記録を作成してから後続のプロセスを実行する必要があるかどうかを決定できます。

#外部からの呼び出し

操作後イベントのトリガーは、ユーザーインターフェースからの操作に限定されず、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 コレクションの操作後イベントがトリガーされます。

この操作で一対一の関連データ（多対多は現在未サポート）のイベントをトリガーする必要がある場合、パラメータで ! を使用して、関連フィールドのトリガーデータを指定できます。

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

上記の呼び出しが成功すると、対応する categories コレクションの操作後イベントがトリガーされます。

#よくある質問

#操作前イベントとの違い

• 操作前イベント：ある操作（新規作成、更新など）が実行される前にトリガーされます。操作実行前、プロセス内でリクエストされたデータの検証や処理を行うことができます。プロセスが中断された場合（リクエストがインターセプトされた場合）、その操作（新規作成、更新など）は実行されません。
• 操作後イベント：ユーザーの操作が成功した後にトリガーされます。この時点ではデータはすでに正常に送信され、データベースに保存されており、成功した結果に基づいて関連するプロセスを継続して処理できます。

下図の通りです。

#コレクションイベントとの違い

操作後イベントとコレクションイベントには類似点があり、効果としてはどちらもデータ変更後にトリガーされるプロセスです。しかし、実装レベルはそれぞれ異なります。操作後イベントはAPIレベルを対象としており、コレクションイベントはコレクションのデータ変更を対象としています。

コレクションイベントはシステムのより下層に近く、ある状況では、あるイベントによるデータ変更が別のイベントをトリガーし、連鎖反応を引き起こす可能性があります。特に、一部の関連コレクションのデータが現在のコレクションの操作中に変更された場合、関連コレクションに関するイベントもトリガーされることがあります。

コレクションイベントのトリガーには、ユーザー関連の情報は含まれません。一方、操作後イベントはユーザーエンドに近く、ユーザー操作の結果です。プロセスのコンテキストにはユーザー関連の情報も含まれるため、ユーザー操作に関連するプロセスを処理するのに適しています。NocoBaseの将来の設計では、トリガーに使用できる操作後イベントがさらに拡張される可能性があります。したがって、ユーザー操作によるデータ変更のプロセスを処理するには、操作後イベントの使用を強く推奨します。

もう一つの違いは、操作後イベントは特定のフォームボタンにローカルで紐付けることができる点です。複数のフォームがある場合、一部のフォームの送信でこのイベントをトリガーし、他のフォームではトリガーしないように設定できます。一方、コレクションイベントはコレクション全体のデータ変更を対象とするため、ローカルで紐付けることはできません。