Як створити кастомну дію в Action Jail

Ця інструкція допоможе створити нову дію з нуля — вручну або з використанням AI-генерації. Описано всі поля майстра та їх призначення.

Коли стане в пригоді

• Потрібна бізнес-логіка або інтеграція, якої немає серед стандартних дій.
• Є опис логіки, але не впевнені, як оформити код і параметри.
• Хочете використати AI для чернетки коду, конфігу або документації.

Що важливо знати

• Спочатку перевірте стандартні дії — у платформи є бібліотека з 98 стандартних дій. Якщо підходить стандартна дія, не створюйте кастомну. Див. Actions Reference.
• Системний ID не змінюється після створення — обирайте назву уважно.
• Ключі параметрів у JSON-конфігу мають збігатися з тим, що читає код через getCurrentNodeParamsJSON().

Перед початком

• Ви маєте роль з доступом до Меню -> Бібліотека дій.
• Перевірили Actions Reference — стандартної дії немає.
• Під рукою опис логіки: що має робити дія, які вхідні дані потрібні.
• Для AI-генерації: налаштований OpenAI-токен для обраного процесу (бота). Див. Налаштування AI-генератора.

Покрокова інструкція

Крок 1. Відкрити майстер

1. Перейдіть у Меню -> Бібліотека дій.
2. Натисніть Додати нову дію.
3. Відкриється майстер з п'ятьма секціями (акордеонами).

Крок 2. Інформація про дію

Поля:

Приклад: Відображуване ім'я — «Перевірка мови», системний ID — check_language, група — «Валідація».

Крок 3. Код реалізації

Що писати:

• JavaScript-функція, яка починається з action_ і експортується через module.exports.
• Параметри отримуйте через this.getCurrentNodeParamsJSON().
• Константи сценарію — через this.getCurrentConstJSON().

Шлях 1 — вручну:

async function action_check_language(params) {
  const { language_code } = this.getCurrentNodeParamsJSON();
  // логіка перевірки
  return language_code === 'uk' ? 'success' : 'error';
}
module.exports = action_check_language;

Шлях 2 — AI-генерація:

1. Заповніть відображуване ім'я та опис у секції «Інформація».
2. Розгорніть секцію «Код реалізації».
3. Натисніть Швидка генерація або Згенерувати код.
4. Перевірте та відредагуйте згенерований код.

Якщо коду багато, у заголовку нижньої панелі натисніть Відкрити код на весь екран — редактор відкриється у великому вікні, зміни синхронізуються з нижньою панеллю.

Важливо: Ключі з getCurrentNodeParamsJSON() (наприклад, language_code) потім потрібно додати в JSON-конфіг як параметри.

Крок 4. JSON конфігурація

Що задати:

• parameters — масив об'єктів. Кожен об'єкт: key (або name), type, label, required, description, defaultValue тощо.
• ui.groups — групування полів для форми (accordion).
• json_example — приклад валідного JSON.
• events_schema — можливі значення return для роутингу (success, error тощо).

Шлях 1 — вручну: Відредагуйте JSON у редакторі. Мінімальний приклад:

{
  "parameters": [
    {
      "key": "language_code",
      "type": "string",
      "label": "Код мови",
      "required": true,
      "description": "Код мови для перевірки (uk, en, ru)"
    }
  ],
  "ui": {
    "layout": "accordion",
    "groups": [
      {
        "id": "main",
        "title": "Основні параметри",
        "fields": ["language_code"]
      }
    ]
  },
  "json_example": { "language_code": "uk" },
  "events_schema": [
    { "name": "success", "label": "Успіх", "description": "Мова відповідає" },
    { "name": "error", "label": "Помилка", "description": "Мова не відповідає" }
  ]
}

Шлях 2 — AI-генерація:

1. Заповніть код у секції «Код реалізації».
2. Розгорніть секцію «JSON конфігурація».
3. Натисніть Згенерувати з коду.
4. AI проаналізує код і витягне параметри з getCurrentNodeParamsJSON() у JSON-схему.
5. Перевірте та відредагуйте результат.

Крок 5. UI схема

UI-схема — це візуальне представлення parameters та ui.groups. Зазвичай вона синхронізується з JSON-конфігом автоматично.

• Якщо ви редагували JSON — перевірте, що поля в UI-схемі відображаються коректно.
• Можна додавати та редагувати поля у візуальному списку параметрів.

Типи полів: string, number, boolean, textarea, select, url, Credential тощо. Кожен тип відповідає певному віджету у формі в Scenario Builder.

Параметр типу Credential — інтегратор обирає запис з Секретів для сценаріїв замість вводу токена вручну. У коді дії використовуйте серверні helpers (див. використати секрет у custom action). Для поля в JSON-конфігу:

{
  "key": "api_credential_slug",
  "type": "credential",
  "label": "API секрет",
  "required": true,
  "store": "slug"
}

Крок 6. Документація

Що писати:

• Markdown: опис дії, параметри, приклад використання, значення return.

Шлях 1 — вручну: Напишіть текст у Markdown-редакторі.

Шлях 2 — AI-генерація:

1. Натисніть Згенерувати документацію.
2. AI створить Markdown за назвою, кодом та параметрами.
3. Відредагуйте за потреби.

Крок 7. Зберегти та протестувати

1. Натисніть Завершити (для нової дії) або Зберегти (для редагування).
2. Відкрийте розділ Тестування (для кастомних дій).
3. Введіть тестові параметри (JSON або повний state) і натисніть Test Action.
4. Перевірте результат, логи та помилки.

Що відбувається після

• Дія з'являється у бібліотеці Action Jail.
• Її можна обрати в блоці Action у Конструкторі сценаріїв.
• Поля форми будуть побудовані з parameters та ui.groups — див. Про те, як дані з Action Jail потрапляють у Scenario Builder.

Як переконатися, що все вдалось

• Дія відображається у бібліотеці та відкривається без помилок.
• Системний ID унікальний.
• У блоці Action у сценарії з'являються поля форми з правильними підписами.
• Тестування проходить успішно з тестовими параметрами.

Інші способи

• Клонування — якщо є подібна дія, оберіть її → Зробити копію → змініть код і параметри.
• AI-генерація — для чернеток коду, конфігу та документації; завжди перевіряйте результат вручну.

Пов'язані інструкції

• Про те, як дані з Action Jail потрапляють у Scenario Builder
• Секції редактора дій
• Налаштування AI-генератора
• Як створити й підтримувати дію
• Actions Reference
• Використати секрет у custom action