---
pkg: '@nocobase/plugin-workflow-custom-action-trigger'
---

# Событие пользовательского действия

## Введение

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)

## Пример

Например, у нас есть коллекция «Образцы». Для образцов со статусом «Собран» необходимо предоставить операцию «Отправить на проверку», которая сначала проверяет основную информацию об образце, затем генерирует запись в коллекции «Записи о проверке» и изменяет статус образца на «Отправлен». Эту последовательность действий невозможно выполнить простым нажатием кнопок CRUD, поэтому для реализации можно использовать событие пользовательского действия.

Сначала создайте коллекцию «Образцы» и коллекцию «Записи о проверке», введите базовые тестовые данные в таблицу образцов:

![Пример_Коллекция образцов](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` для всех операций с коллекциями, который можно вызывать с помощью стандартного API действий NocoBase.

:::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 строки, заменив `<:id>` в URL.

Если вызов происходит для формы (например, создание или обновление), для формы создания новой записи 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) рабочего процесса, несколько ключей разделяются запятыми. Ключ можно узнать, наведя курсор на название рабочего процесса в верхней части холста:

![Просмотр ключа рабочего процесса](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 в качестве контекста триггера.