# Про те, як дані з 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

Система:
1. Читає `templateId` з ноди (наприклад, `action_send_email`).
2. Завантажує з Action Jail повну інформацію про дію: `parameters`, `ui`, `json_example`.
3. Якщо є `parameters` — показує режим **Form** (поля форми).
4. Якщо `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: Код дії отримує параметри

У коді дії:
```javascript
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 — дія недосяжна.

**Що робити натомість:** логіку, яка має відпрацювати вже після передачі оператору, будуйте засобами операторської панелі — таймери, автоматичні правила, статуси — а не продовженням сценарію. Для автозакриття неактивних чатів використовуйте [таймери операторської панелі](/uk/settings/how-to/configure-timers.md).

---

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

- [Секції редактора дій](/uk/actionjail/explanation/action-editor-sections.md) — що заповнювати в кожній секції
- [Живий оператор у діалозі](/uk/scenariobuilder/explanation/connect-to-operator-node.md) — що відбувається зі сценарієм після передачі оператору
- [Як створити кастомну дію](/uk/actionjail/how-to/create-custom-action.md) — покрокова інструкція з усіма полями
- [Actions Reference](/uk/actionjail/reference/actions-reference.md) — довідник стандартних дій