#Подія користувацької дії

#Вступ

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, але необхідно передати надіслані дані як контекст виконання:

```bash
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.