---
pkg: '@nocobase/plugin-workflow-custom-action-trigger'
title: "カスタムアクションイベント"
description: "カスタムアクションイベントトリガー：カスタムアクションボタンにバインドし、クリック時にワークフローをトリガーして、ボタン駆動の自動化を実現します。"
keywords: "ワークフロー,カスタムアクションイベント,Custom Action,ボタントリガー,ワークフローバインド,NocoBase"
---
# カスタムアクションイベント

## 紹介

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

## ワークフローの作成

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

![「カスタムアクションイベント」ワークフローの作成](https://static-docs.nocobase.com/20240509091820.png)

## トリガーの設定

### コンテキストタイプ

> v.1.6.0+

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

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

![トリガー設定_コンテキストタイプ](https://static-docs.nocobase.com/20250215135808.png)

### データテーブル

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

![トリガー設定_データテーブルの選択](https://static-docs.nocobase.com/20250215135919.png)

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

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

![トリガー設定_使用するリレーションデータの選択](https://static-docs.nocobase.com/20250215135955.png)

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

## 操作の設定

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

### コンテキストなし

> v1.6.0+

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

![ブロックへのアクションボタン追加_操作パネル](https://static-docs.nocobase.com/20250215221738.png)

![ブロックへのアクションボタン追加_カレンダー](https://static-docs.nocobase.com/20250215221942.png)

![ブロックへのアクションボタン追加_ガントチャート](https://static-docs.nocobase.com/20250215221810.png)

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

![ボタンへのワークフローバインド_操作パネル](https://static-docs.nocobase.com/20250215222120.png)

![バインドするワークフローの選択_コンテキストなし](https://static-docs.nocobase.com/20250215222234.png)

### 単一レコード

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

![ブロックへのアクションボタン追加_フォーム](https://static-docs.nocobase.com/20240509165428.png)

![ブロックへのアクションボタン追加_テーブル行](https://static-docs.nocobase.com/20240509165340.png)

![ブロックへのアクションボタン追加_詳細](https://static-docs.nocobase.com/20240509165545.png)

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

![ボタンへのワークフローバインド](https://static-docs.nocobase.com/20240509165631.png)

![バインドするワークフローの選択](https://static-docs.nocobase.com/20240509165658.png)

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

![ボタンクリックによるトリガー結果](https://static-docs.nocobase.com/20240509170453.png)

### 複数レコード

> v1.6.0+

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

![ブロックへのアクションボタン追加_テーブル](https://static-docs.nocobase.com/20250215222507.png)

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

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

![20250215224436](https://static-docs.nocobase.com/20250215224436.png)

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

![20250215224736](https://static-docs.nocobase.com/20250215224736.png)

## 使用例

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

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

![例_サンプルデータテーブル](https://static-docs.nocobase.com/20240509172234.png)

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

![例_ワークフローの作成](https://static-docs.nocobase.com/20240509173106.png)

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

![例_トリガー設定](https://static-docs.nocobase.com/20240509173148.png)

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

![例_ビジネスロジックの編成](https://static-docs.nocobase.com/20240509174159.png)

:::info{title=ヒント}
「[応答メッセージ](../nodes/response-message.md)」ノードは、同期のカスタムアクションイベントで使用でき、クライアントに通知メッセージを返すために利用されます。非同期モードでは使用できません。
:::

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

![例_アクションボタンの追加](https://static-docs.nocobase.com/20240509174525.png)

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

![例_ワークフローバインドダイアログを開く](https://static-docs.nocobase.com/20240509174633.png)

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

![例_ワークフローの選択](https://static-docs.nocobase.com/20240509174723.png)

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

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

![例_指標が送検基準を満たさない](https://static-docs.nocobase.com/20240509175026.png)

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

![例_送検成功](https://static-docs.nocobase.com/20240509175247.png)

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

## 外部呼び出し

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

:::info{title="ヒント"}
外部呼び出しもユーザーの身元に基づく必要があるため、HTTP API を介して呼び出す際は、通常のインターフェースから送信されるリクエストと同様に、認証情報を提供する必要があります。これには `Authorization` リクエストヘッダーまたは `token` パラメータ（ログイン時に取得したトークン）、および `X-Role` リクエストヘッダー（ユーザーの現在のロール名）が含まれます。
:::

### コンテキストなし

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

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

### 単一レコード

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

```bash
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 を渡す必要はありませんが、送信するデータを実行コンテキストのデータとして渡す必要があります。

```bash
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 と更新するデータの両方を渡す必要があります。

```bash
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 に対応するデータ行が読み込まれ、次に渡されたデータオブジェクトのプロパティで元のデータ行を上書きして、最終的なトリガーデータコンテキストが生成されます。

:::warning{title="注意"}
リレーションデータが渡された場合も上書きされます。特にプリロードで使用するリレーションデータ項目が設定されている場合、渡すデータの取り扱いには注意が必要です。リレーションデータが予期せず上書きされる可能性があります。
:::

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

![ワークフロー_key_確認方法](https://static-docs.nocobase.com/20240426135108.png)

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

:::info{title="ヒント"}
HTTP API を介してトリガー操作を呼び出す際は、ワークフローの有効状態やデータテーブル設定が一致しているかにもご注意ください。一致しない場合、呼び出しが成功しないか、エラーが発生する可能性があります。
:::

### 複数レコード

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

```bash
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 のデータがトリガーコンテキスト内のデータとして使用されます。
