#カスタムアクションイベント

#紹介

NocoBase には一般的なデータ操作（追加、削除、編集、参照など）が組み込まれています。これらの操作では複雑な業務ニーズを満たせない場合、ワークフローでカスタムアクションイベントを使用し、そのイベントをページブロックの「ワークフローをトリガー」ボタンにバインドすることで、ユーザーがクリックした際にカスタムアクションのワークフローをトリガーできます。

#ワークフローの作成

ワークフローを作成する際、「カスタムアクションイベント」を選択します。

#トリガーの設定

#コンテキストタイプ

v.1.6.0+

コンテキストタイプの違いにより、そのワークフローをどのブロックのボタンにバインドできるかが決まります。

• コンテキストなし：グローバルイベントです。操作パネルやデータブロックのアクションボタンにバインドできます。
• 単一レコード：テーブルのデータ行、フォーム、詳細などのデータブロックのアクションボタンにバインドできます。
• 複数レコード：テーブルの一括操作ボタンにバインドできます。

#データテーブル

コンテキストタイプが単一レコードまたは複数レコードの場合、バインドするデータモデルのデータテーブルを選択する必要があります。

#使用するリレーションデータ

ワークフロー内でトリガーされたデータ行のリレーションデータを使用する必要がある場合、ここで深い階層のリレーションフィールドを選択できます。

これらのフィールドは、イベントがトリガーされた後、ワークフローのコンテキストに自動的にプリロードされ、ワークフロー内で利用できるようになります。

#操作の設定

ワークフローで設定されたコンテキストタイプによって、異なるブロックでのアクションボタンの設定も異なります。

#コンテキストなし

v1.6.0+

操作パネルやその他のデータブロックで、「ワークフローをトリガー」ボタンを追加できます。

ボタンを追加した後、以前作成したコンテキストなしのワークフローをバインドします。操作パネルのボタンを例にします。

#単一レコード

任意のデータブロックで、単一レコードの操作バーに「ワークフローをトリガー」ボタンを追加できます（フォーム、テーブルのデータ行、詳細など）。

ボタンを追加した後、以前作成したワークフローをバインドします。

その後、このボタンをクリックすると、カスタムアクションイベントがトリガーされます。

#複数レコード

v1.6.0+

テーブルブロックの操作バーで「ワークフローをトリガー」ボタンを追加する際、コンテキストタイプを「コンテキストなし」または「複数レコード」から選択する追加オプションがあります。

「コンテキストなし」を選択した場合、グローバルイベントとなり、コンテキストなしタイプのワークフローのみをバインドできます。

「複数レコード」を選択した場合、複数レコードタイプのワークフローをバインドでき、複数のデータを選択した後の一括操作（現在はテーブルのみ対応）に使用できます。この際、選択可能なワークフローは、現在のデータブロックのデータテーブルに一致するように設定されたものに限定されます。

ボタンをクリックしてトリガーする際、テーブル内のデータ行がいくつか選択されている必要があります。選択されていない場合、ワークフローはトリガーされません。

#使用例

例えば、「サンプル」データテーブルがあり、「収集済み」（ステータス）のサンプルに対して「送検」操作を提供する必要があるとします。送検操作では、まずサンプルの基本情報をチェックし、次に「送検記録」データを生成し、最後にサンプルのステータスを「送検済み」に変更します。この一連のプロセスは、単純な「追加・削除・編集・参照」ボタンのクリックだけでは完結できません。このような場合に、カスタムアクションイベントを使用して実現できます。

まず、「サンプル」データテーブルと「送検記録」データテーブルを作成し、サンプルテーブルに基本的なテストデータを入力します。

次に、「カスタムアクションイベント」ワークフローを作成します。操作フローのフィードバックを素早く得たい場合は、同期モードを選択できます（同期モードでは、手動処理などの非同期タイプのノードは使用できません）。

トリガー設定で、データテーブルとして「サンプル」を選択します。

業務要件に基づいて、プロセス内のロジックを編成します。例えば、指標パラメータが 90 より大きい場合にのみ送検を許可し、それ以外の場合は問題を通知します。

ワークフローを設定して有効化した後、テーブル画面に戻り、テーブルの操作列に「ワークフローをトリガー」ボタンを追加します。

次に、ボタンの設定メニューで「ワークフローのバインド」を選択し、設定ダイアログを開きます。

以前有効化したワークフローを追加します。

送信後、ボタンのテキストを「送検」などの操作名に変更すれば、設定は完了です。

使用する際は、テーブル内で任意のサンプルデータを選択し、「送検」ボタンをクリックすると、カスタムアクションイベントがトリガーされます。先ほど編成したロジックに従い、サンプルの指標パラメータが 90 未満の場合、クリック後に以下のメッセージが表示されます。

指標パラメータが 90 より大きい場合は、プロセスが正常に実行され、「送検記録」データが生成され、サンプルのステータスが「送検済み」に変更されます。

これで、簡単なカスタムアクションイベントが完了しました。同様に、注文処理やレポート提出など、複雑な操作を伴うビジネスにおいても、カスタムアクションイベントを使用して実現できます。

#外部呼び出し

カスタムアクションイベントのトリガーは、ユーザーインターフェースの操作に限定されず、HTTP API 呼び出しによってもトリガーできます。特に、カスタムアクションイベントはすべてのデータテーブル操作に対して、ワークフローをトリガーする新しい操作タイプ trigger を提供しており、NocoBase の標準アクション API を使用して呼び出すことができます。

#コンテキストなし

コンテキストなしのワークフローは、workflows リソースに対してトリガー操作を行う必要があります。

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/workflows:trigger?triggerWorkflows=workflowKey"

#単一レコード

使用例で示したボタンによってトリガーされるワークフローと同様に、以下のように呼び出します。

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/samples:trigger/<:id>?triggerWorkflows=workflowKey"

この操作は単一レコードを対象としているため、既存のデータに対して呼び出す際は、データ行の ID を指定し、URL 内の <:id> 部分を置き換える必要があります。

フォームに対して呼び出す場合（新規作成や更新など）、新規データのフォームでは ID を渡す必要はありませんが、送信するデータを実行コンテキストのデータとして渡す必要があります。

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Sample 1",
    "id": 91
  }'
  "http://localhost:3000/api/samples:trigger?triggerWorkflows=workflowKey"

更新フォームの場合は、データ行の ID と更新するデータの両方を渡す必要があります。

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Sample 1",
    "id": 91
  }'
  "http://localhost:3000/api/samples:trigger/<:id>?triggerWorkflows=workflowKey"

ID とデータの両方が渡された場合、まず ID に対応するデータ行が読み込まれ、次に渡されたデータオブジェクトのプロパティで元のデータ行を上書きして、最終的なトリガーデータコンテキストが生成されます。

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

上記の呼び出しが成功すると、対応する samples テーブルのカスタムアクションイベントがトリガーされます。

#複数レコード

単一レコードの呼び出し方式と似ていますが、渡すデータは複数の主キーパラメータ（filterByTk[]）のみで、data 部分は不要です。

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/samples:trigger?filterByTk[]=1&filterByTk[]=2&triggerWorkflows=workflowKey"

この呼び出しにより、複数レコードモードのカスタムアクションイベントがトリガーされ、ID が 1 と 2 のデータがトリガーコンテキスト内のデータとして使用されます。