Про те, як дані з 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: Код дії отримує параметри

У коді дії:

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[].placeholderPlaceholder у полі вводу
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".

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

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

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