Про те, як дані з Action Jail потрапляють у Scenario Builder

Коли ви створюєте дію в Action Jail і додаєте її в сценарій, дані з редактора дій перетворюються на форму параметрів у блоці Action. Ця сторінка пояснює, як саме це відбувається, де видно кожне поле і чому структура саме така.

Контекст і проблема

Користувач сценарію (аналітик, implementation) додає блок Action і обирає дію з бібліотеки. Йому потрібно:

Побачити зрозумілі поля для введення параметрів (email, тема, число, вибір).
Не писати JSON вручну, якщо є форма.
Розуміти, як значення з форми передаються в код дії.

Адміністратор, який створює дію в Action Jail, має налаштувати:

Код реалізації (JavaScript).
Схему параметрів (що очікує код).
Як ці параметри відображатимуться в формі (назви, поля, групи).

Проблема: Якщо не зрозуміти зв'язок між полями в Action Jail і тим, що бачить користувач сценарію, можна створити дію з неправильною конфігурацією — форма буде порожньою або параметри не потраплять у код.

Основні концепції

Що зберігається в Action Jail

Кожна дія зберігає:

Інформація — назва, системний ID, опис, група.
Код — JavaScript-функція, яка виконується на бекенді.
JSON конфігурація — схема параметрів (parameters), групування (ui.groups), приклад (json_example).
UI схема — візуальне представлення тих самих параметрів (синхронізовано з JSON).
Документація — Markdown для довідників.

Що зберігається в ноді сценарію

Коли ви додаєте блок Action в сценарій і обираєте дію:

У ноді зберігається тільки templateId (назва дії) + значення параметрів (values).
Схема параметрів (типи, поля, групи) не копіюється в ноду — вона динамічно підвантажується з Action Jail при відкритті блоку.

Чому так: Якщо адміністратор змінить схему параметрів дії (додасть поле, змінить тип), усі сценарії, що використовують цю дію, автоматично отримають оновлену форму. Не потрібно оновлювати кожен сценарій окремо.

Потік даних: Action Jail → Scenario Builder

┌─────────────────────────────────────────────────────────────────────────────┐
│  Action Jail (редактор дії)                                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│  Інформація: displayName, name, description, group_id                        │
│  Код: action_xxx()                                                           │
│  JSON конфіг: parameters, ui.groups, json_example, events_schema            │
│  Документація: Markdown                                                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │  Зберігається в бібліотеці дій
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Блок Action у сценарії                                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  node.data:                                                                  │
│    templateId: "action_send_email"   ← посилання на дію                     │
│    templateConfig.values: { to: "...", subject: "..." }  ← тільки значення   │
│                                                                              │
│  При відкритті блоку:                                                        │
│    → Завантажуються parameters з Action Jail (динамічно)                    │
│    → Форма будується з parameters + ui.groups                                │
│    → values підставляються в поля форми                                      │
└─────────────────────────────────────────────────────────────────────────────┘

Крок 1: Користувач відкриває блок Action

Система:

Читає templateId з ноди (наприклад, action_send_email).
Завантажує з Action Jail повну інформацію про дію: parameters, ui, json_example.
Якщо є parameters — показує режим Form (поля форми).
Якщо parameters порожні — показує режим JSON (Monaco-редактор).

Крок 2: Форма будується з parameters + ui.groups

Кожен елемент з parameters стає полем форми:

type: "string" → input для тексту
type: "number" → input для числа
type: "boolean" → перемикач
type: "select" → випадаючий список

Групи з ui.groups відображаються як секції акордеону. Поля з parameters розподіляються по групах за полем key у групі.

Крок 3: Користувач вводить значення

Коли користувач змінює поле форми:

Значення зберігається в templateConfig.values (тільки значення, без схеми).
При виконанні сценарію Engine передає values у код дії через this.getCurrentNodeParamsJSON().

Крок 4: Код дії отримує параметри

У коді дії:

const { to, subject } = this.getCurrentNodeParamsJSON();

Ключі to, subject — це ті самі key або name з parameters у JSON-конфігу. Значення беруться з templateConfig.values.

Де видно кожне поле

Поле в Action Jail	Де видно в Scenario Builder	Примітка
Відображуване ім'я	Вибір дії при додаванні блоку Action, назва обраної дії в блоці	Користувач бачить саме це ім'я
Група	Фільтр «Оберіть action групу» у сайдбарі блоку Action	Допомагає швидко знайти дію
Опис	Підказки, довідники	Не відображається безпосередньо в формі
parameters[].key	Ключ у `values`, який читає код через `getCurrentNodeParamsJSON()`	Має збігатися з тим, що в коді
parameters[].label	Підпис поля в формі
parameters[].placeholder	Placeholder у полі вводу
parameters[].type	Тип віджета (input, number, switch, select)
ui.groups	Секції акордеону в формі параметрів	Групування полів
json_example	Дефолтні значення при першому відкритті
events_schema	Можливі значення для роутингу (наприклад, success → наступний блок)

Режими редагування: Form ↔ JSON

У блоці Action є два режими:

Form — поля форми, побудовані з parameters. Зручно для більшості користувачів.
JSON — прямий ввід JSON. Користувач бачить і редагує templateConfig.values (тільки значення).

Обидва режими синхронізовані: зміна в формі оновлює JSON, зміна в JSON оновлює форму. Схема параметрів завжди береться з Action Jail, не з ноди.

Наслідки для адміністраторів

При створенні дії:

Переконайтеся, що ключі в parameters збігаються з тим, що читає код через getCurrentNodeParamsJSON().
Якщо в коді є const { email } = this.getCurrentNodeParamsJSON(), то в parameters має бути поле з key: "email" або name: "email".

При зміні схеми:

Додавання нового параметра — усі сценарії отримають нове поле в формі.
Видалення параметра — старі значення в сценаріях ігноруються; код не отримає цей ключ.
Зміна типу — форма оновиться; перевірте, що існуючі значення в сценаріях коректні.

Коли дія не виконається: чат уже в оператора

Дія в сценарії виконується лише поки чатом керує сценарій. Щойно чат передано в операторську панель (нода підключення до оператора, передача у Fast Line або в skill-групу), рушій перестає просувати позицію в сценарії для цього чату — щоб бот не писав поверх живого оператора.

Що це означає для автора дії:

Дія, поставлена на полотні після передачі оператору, не виконається — ані одразу, ані по таймеру.
Помилки при цьому не буде: сценарій просто «завмирає» на місці, лог виглядає штатно.
Це стосується і відкладених переходів (ноди інтервалу/таймера), і кастомних дій з Action Jail.

Як перевірити, чи ваша дія в цій пастці. Пройдіть шлях від стартової ноди до вашої дії: якщо між ними є нода підключення до оператора або передачі у Fast Line — дія недосяжна.

Що робити натомість: логіку, яка має відпрацювати вже після передачі оператору, будуйте засобами операторської панелі — таймери, автоматичні правила, статуси — а не продовженням сценарію. Для автозакриття неактивних чатів використовуйте таймери операторської панелі.

Пов'язані документи

Секції редактора дій — що заповнювати в кожній секції
Живий оператор у діалозі — що відбувається зі сценарієм після передачі оператору
Як створити кастомну дію — покрокова інструкція з усіма полями
Actions Reference — довідник стандартних дій