#Подія "До дії"

#Вступ

Плагін "Подія 'До дії'" надає механізм перехоплення операцій, який може бути активований після надсилання запиту на створення, оновлення або видалення, але до його обробки.

Якщо в активованому робочому процесі виконується вузол "Завершити робочий процес", або якщо будь-який інший вузол не виконується (через помилку чи інше незавершення), дія форми буде перехоплена. В іншому випадку запланована дія буде виконана у звичайному режимі.

Використання цього плагіна разом із вузлом "Повідомлення-відповідь" дозволяє налаштувати повідомлення, яке повертатиметься клієнту, надаючи відповідні підказки. Події "До дії" можна використовувати для бізнес-валідації або логічних перевірок, щоб дозволити або перехопити запити клієнта на створення, оновлення та видалення.

#Налаштування тригера

#Створення тригера

Під час створення робочого процесу оберіть тип "Подія 'До дії'":

#Вибір колекції

У тригері робочого процесу перехоплення насамперед потрібно налаштувати колекцію, що відповідає дії:

Потім оберіть режим перехоплення. Ви можете перехоплювати лише кнопки дій, прив'язані до цього робочого процесу, або перехоплювати всі вибрані дії для цієї колекції (незалежно від того, з якої форми вони походять, і без необхідності прив'язувати відповідний робочий процес):

#Режим перехоплення

Наразі підтримуються такі типи дій: "Створити", "Оновити" та "Видалити". Можна одночасно вибрати кілька типів дій.

#Налаштування дії

Якщо в налаштуваннях тригера обрано режим "Запускати перехоплення лише при надсиланні форми, прив'язаної до цього робочого процесу", вам також потрібно повернутися до інтерфейсу форми та прив'язати цей робочий процес до відповідної кнопки дії:

У налаштуваннях прив'язки робочого процесу оберіть відповідний робочий процес. Зазвичай, для контексту даних, що запускають процес, достатньо залишити значення за замовчуванням "Усі дані форми":

#Умови для перехоплення

У події "До дії" існують дві умови, які призведуть до перехоплення відповідної операції:

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"
    }
  ]
}

Якщо подію "До дії" налаштовано в глобальному режимі, вам не потрібно використовувати параметр URL triggerWorkflows для вказівки відповідного робочого процесу під час виклику HTTP API. Просто виклик відповідної дії колекції запустить її.

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"