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

#Вступ

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

#Створення робочого процесу

При створенні робочого процесу виберіть «Подія користувацької дії»:

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

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

v.1.6.0+

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

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

#Колекція

Коли тип контексту — один запис або кілька записів, необхідно вибрати колекцію для прив'язки моделі даних:

#Пов'язані дані для використання

Якщо вам потрібно використовувати пов'язані дані рядка, що активує робочий процес, ви можете вибрати тут глибокі поля зв'язків:

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

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

Налаштування кнопок дій у різних блоках відрізняється залежно від типу контексту, налаштованого в робочому процесі.

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

v1.6.0+

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

Після додавання кнопки прив'яжіть раніше створений робочий процес без контексту, на прикладі кнопки на панелі операцій:

#Один запис

У будь-якому блоці даних до панелі дій для одного запису можна додати кнопку «Запустити робочий процес», наприклад, у формах, рядках таблиць, деталях тощо:

Після додавання кнопки прив'яжіть раніше створений робочий процес:

Після цього натискання цієї кнопки запустить подію користувацької дії:

#Кілька записів

v1.6.0+

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

Якщо вибрано «Без контексту», це глобальна подія, і можна прив'язати лише робочі процеси без контексту.

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

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

#Приклад

Наприклад, у нас є колекція «Зразки». Для зразків зі статусом «Зібрано» необхідно передбачити дію «Відправити на перевірку». Ця дія спочатку перевірить основну інформацію про зразок, потім створить запис «Запис перевірки» і, нарешті, змінить статус зразка на «Відправлено». Оскільки цю послідовність процесів неможливо виконати простими натисканнями кнопок «додати, видалити, редагувати, переглянути», для її реалізації можна використовувати подію користувацької дії.

Спершу створіть колекцію «Зразки» та колекцію «Записи перевірок», а потім введіть базові тестові дані до колекції «Зразки»:

Потім створіть робочий процес «Подія користувацької дії». Якщо вам потрібен швидкий зворотний зв'язок від процесу операції, ви можете вибрати синхронний режим (у синхронному режимі не можна використовувати асинхронні вузли, такі як ручна обробка):

У налаштуваннях тригера для колекції виберіть «Зразки»:

Налаштуйте логіку в процесі відповідно до бізнес-вимог. Наприклад, дозволяйте відправку на перевірку лише тоді, коли параметр індикатора більший за 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 є ключем робочого процесу; кілька ключів робочих процесів розділяються комами. Цей ключ можна отримати, навівши курсор миші на назву робочого процесу у верхній частині полотна робочого процесу:

Після успішного виклику буде запущено подію користувацької дії для відповідної колекції 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 як контекст тригера.