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

#Введение

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

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

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

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

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

v.1.6.0+

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

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

#Коллекция

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

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

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

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

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

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

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

v.1.6.0+

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

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

#Одна запись

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

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

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

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

v.1.6.0+

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

При выборе "Без контекста" это глобальное событие, и к нему можно привязать только рабочие процессы без контекста.

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

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

#Пример

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

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

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

В настройках триггера выберите "Образцы" для коллекции:

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

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

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

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

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

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

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

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

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

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

Рабочий процесс, запущенный кнопкой, как в примере, можно вызвать следующим образом:

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",
    "indicator": 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",
    "indicator": 91
  }'
  "http://localhost:3000/api/samples:trigger/<:id>?triggerWorkflows=workflowKey"

Если одновременно переданы ID и данные, сначала будет загружена строка данных, соответствующая ID, а затем свойства из переданного объекта данных будут использованы для перезаписи исходной строки данных, чтобы получить окончательный контекст запуска данных.

Кроме того, параметр URL triggerWorkflows — это ключ рабочего процесса; несколько ключей рабочих процессов разделяются запятыми. Этот ключ можно получить, наведя курсор мыши на имя рабочего процесса в верхней части холста рабочего процесса:

После успешного вызова будет запущено пользовательское событие действия для соответствующей коллекции samples.

Если вам необходимо запустить событие для связанных данных "один к одному" (связи "один ко многим" в настоящее время не поддерживаются) в этом действии, вы можете использовать ! в параметре для указания данных триггера поля связи:

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

После успешного вызова будет запущено пользовательское событие действия для соответствующей коллекции categories.