#Событие до действия

#Введение

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

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

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

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

#Создание триггера

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

#Выбор коллекции

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

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

#Режим перехвата

Сейчас поддерживаются типы действий «Создание», «Обновление» и «Удаление». Можно выбрать несколько типов одновременно.

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

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

В конфигурации привязки рабочего процесса выберите соответствующий рабочий процесс. Обычно достаточно контекста данных триггера по умолчанию — «Данные всей формы»:

#Условия перехвата

В событии до действия есть два условия, при которых соответствующее действие будет перехвачено:

1. Рабочий процесс доходит до любого узла «Завершить рабочий процесс». Как и в предыдущих инструкциях, если данные, запустившие рабочий процесс, не соответствуют преднастроенным условиям в узле «Условие», выполнение перейдёт в ветвь «Нет» и выполнит узел «Завершить рабочий процесс». В этот момент рабочий процесс завершится, а запрошенное действие будет перехвачено.
2. Любой узел рабочего процесса завершается неуспешно, включая ошибки выполнения и другие исключения. В этом случае рабочий процесс завершается с соответствующим статусом, а запрошенное действие также перехватывается. Например, если рабочий процесс вызывает внешние данные через «HTTP запрос» и запрос завершается ошибкой, рабочий процесс завершится со статусом ошибки и перехватит соответствующий запрос действия.

После выполнения условий перехвата соответствующее действие больше не выполняется. Например, если отправка заказа перехвачена, соответствующие данные заказа не будут созданы.

#Связанные параметры соответствующего действия

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

#Вывод ответного сообщения

После настройки триггера можно настроить нужную логику проверок в рабочем процессе. Обычно используется режим ветвления узла «Условие», чтобы по результатам конкретных бизнес-условий решать, выполнять ли «Завершить рабочий процесс» и возвращать преднастроенное «Ответное сообщение»:

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

#Статус ответного сообщения

Если узел «Завершить рабочий процесс» настроен на выход со статусом «Успешно», запрос действия при выполнении этого узла всё равно будет перехвачен, но возвращаемое ответное сообщение отобразится со статусом «Успешно» (вместо «Ошибка»):

#Пример

Объединив базовые инструкции выше, рассмотрим пример сценария «Отправка заказа». Предположим, при отправке заказа нужно проверять остатки всех товаров, выбранных пользователем. Если по любому выбранному товару остаток недостаточен, отправка заказа перехватывается и возвращается соответствующее сообщение. Рабочий процесс циклически проверяет каждый товар, пока остатки всех товаров не окажутся достаточными, после чего продолжает выполнение и создаёт данные заказа.

Остальные шаги совпадают с инструкциями. Однако поскольку заказ включает несколько товаров, помимо добавления связи «многие-ко-многим» «Заказ» ← M:1 — «Позиция заказа» — 1:M → «Товар» в модели данных, в рабочем процессе «Событие до действия» нужно добавить узел «Цикл» для итеративной проверки достаточности остатка по каждому товару:

В качестве объекта цикла выбирается массив «Позиция заказа» из отправленных данных заказа:

Узел «Условие» внутри цикла используется для проверки, достаточен ли остаток текущего товара в итерации цикла:

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

Как видно, ответное сообщение не указывает, что у первого товара «iPhone 15 Pro» недостаточно запаса, а указывает только на второй товар «iPhone 14 Pro». Это происходит потому, что в цикле у первого товара остаток достаточен, поэтому перехвата нет, а у второго товара остаток недостаточен, и именно он перехватывает отправку заказа.

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

Само событие до действия внедряется на этапе обработки запроса, поэтому оно также поддерживает запуск через вызовы HTTP API.

Для рабочих процессов, локально привязанных к кнопке действия, вызов выглядит так (на примере кнопки создания коллекции posts):

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create?triggerWorkflows=workflowKey"

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

После выполнения этого вызова будет запущено событие до действия для соответствующей коллекции posts. После синхронной обработки соответствующего рабочего процесса данные будут созданы и возвращены в штатном режиме.

Если настроенный рабочий процесс доходит до узла «Завершить рабочий процесс», логика аналогична действию из интерфейса: запрос перехватывается, и данные не создаются. Если у узла «Завершить рабочий процесс» задан статус ошибки, код ответа будет 400; если успешно — 200.

Если перед узлом «Завершить рабочий процесс» также настроен узел «Ответное сообщение», сформированное сообщение тоже вернётся в результате ответа. Для ошибки структура такая:

{
  "errors": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

Структура сообщения, когда узел «Завершить рабочий процесс» настроен на успешное завершение:

{
  "messages": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

Если событие до действия настроено в глобальном режиме, при вызове HTTP API не нужно использовать URL-параметр triggerWorkflows для указания рабочего процесса. Достаточно вызвать соответствующее действие коллекции.

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create"