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

#Введение

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

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

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

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

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

v.1.6.0+

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

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

#Коллекция

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

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

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

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

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

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

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

v1.6.0+

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

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

#Одна запись

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

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

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

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

v1.6.0+

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

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

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

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

#Пример

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

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

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

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

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