#Пользовательское событие

#Введение

В NocoBase есть встроенные типовые действия с данными (создание, удаление, обновление, просмотр и т.д.). Когда этих действий недостаточно для сложных бизнес-задач, можно использовать пользовательское событие в рабочем процессе. Если привязать это событие к кнопке «Запустить рабочий процесс» в блоке страницы, по нажатию пользователя будет запускаться соответствующий рабочий процесс.

#Создание рабочего процесса

При создании рабочего процесса выберите «Пользовательское событие»:

#Настройка триггера

#Тип контекста

v1.6.0+

Тип контекста определяет, к каким кнопкам в блоках можно привязать рабочий процесс:

• Без контекста: глобальное событие, которое можно привязать к кнопкам действий в панели действий и блоках данных.
• Одна запись: можно привязать к кнопкам действий в блоках данных, например в строках таблицы, формах и деталях.
• Несколько записей: можно привязать к кнопкам массовых действий в таблице.

#Коллекция

Когда тип контекста — «Одна запись» или «Несколько записей», нужно выбрать коллекцию для привязки модели данных:

#Связанные данные для использования

Если в рабочем процессе нужно использовать данные связей из строки данных, вызвавшей событие, здесь можно выбрать поля глубоких связей:

Эти поля будут автоматически предзагружены в контекст рабочего процесса после срабатывания события, и их можно будет использовать в рабочем процессе.

#Настройка действия

Конфигурация кнопок действий в разных блоках зависит от типа контекста, настроенного в рабочем процессе.

#Без контекста

v1.6.0+

В панели действий и других блоках данных можно добавить кнопку «Запустить рабочий процесс»:

После добавления кнопки привяжите ранее созданный рабочий процесс без контекста. Ниже пример для кнопки в панели действий:

#Одна запись

В любом блоке данных кнопку «Запустить рабочий процесс» можно добавить в панель действий для одной записи, например в формах, строках таблицы, деталях и т.д.:

После добавления кнопки привяжите ранее созданный рабочий процесс:

После этого нажатие этой кнопки будет запускать пользовательское событие:

#Несколько записей

v1.6.0+

В панели действий блока таблицы при добавлении кнопки «Запустить рабочий процесс» появляется дополнительная опция выбора типа контекста: «Без контекста» или «Несколько записей»:

Когда выбран «Без контекста», это глобальное событие, и его можно привязывать только к рабочим процессам без контекста.

Когда выбран «Несколько записей», можно привязать рабочий процесс для нескольких записей, который используется для массовых действий после выбора нескольких записей (сейчас поддерживается только в таблицах). Доступные рабочие процессы ограничены теми, что настроены под коллекцию текущего блока данных:

При нажатии кнопки запуска нужно отметить в таблице хотя бы часть строк данных; иначе рабочий процесс не запустится:

#Пример

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

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

Затем создайте рабочий процесс типа «Пользовательское событие». Если нужна оперативная обратная связь от процесса операции, можно выбрать синхронный режим (в синхронном режиме нельзя использовать асинхронные узлы, например «Ручная обработка»):

В конфигурации триггера выберите коллекцию «Образцы»:

Выстройте логику процесса в соответствии с бизнес-требованиями. Например, разрешайте отправку на инспекцию только когда параметр индикатора больше 90; иначе показывайте соответствующее сообщение:

После настройки и включения рабочего процесса вернитесь в интерфейс таблицы и добавьте кнопку «Запустить рабочий процесс» в колонке действий таблицы:

Далее в меню конфигурации кнопки выберите привязку рабочего процесса и откройте всплывающее окно конфигурации:

Добавьте ранее включённый рабочий процесс:

После сохранения поменяйте текст кнопки на название действия, например «Отправить на проверку. На этом настройка завершена.

Для использования выберите любые данные образца в таблице и нажмите кнопку «Отправить на проверку», чтобы запустить пользовательское событие. Согласно логике выше, если параметр индикатора образца меньше 90, после нажатия будет показана следующая подсказка:

Если параметр индикатора больше 90, процесс выполнится штатно: будет создана «Запись проверки», а статус образца изменится на «Отправлен»:

На этом базовое пользовательское событие готово. Аналогично для бизнес-процессов со сложными операциями, например обработка заказов или отправка отчётов, также можно применять пользовательские события.

#Внешний вызов

Запуск пользовательских событий не ограничен действиями в пользовательском интерфейсе; его также можно выполнять через HTTP API. Для этого пользовательские события предоставляют новый тип действия trigger для действий коллекций, который можно вызывать через стандартный API действий NocoBase.

#Без контекста

Рабочий процесс без контекста нужно запускать через ресурс 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 строки данных, подставив его вместо <:id> в URL.

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

После успешного вызова будет запущено пользовательское событие для соответствующей коллекции 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 в качестве контекста триггера.