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

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

---

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

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

---

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

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

---

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

- [ ] Ви маєте роль з доступом до `Меню -> Бібліотека дій`.
- [ ] Перевірили [Actions Reference](/uk/actionjail/reference/actions-reference.md) — стандартної дії немає.
- [ ] Під рукою опис логіки: що має робити дія, які вхідні дані потрібні.
- [ ] Для AI-генерації: налаштований OpenAI-токен для обраного процесу (бота). Див. [Налаштування AI-генератора](/uk/actionjail/how-to/admin-ai-generator-setup.md).

---

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

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

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

---

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

**Поля:**

| Поле | Що вводити | Де видно в сценарії |
|------|------------|---------------------|
| **Відображуване ім'я** | Назва, яку бачать користувачі при виборі дії | Список дій, назва обраної дії в блоці Action |
| **Системний ID** | Унікальний ідентифікатор, тільки латиниця, цифри, підкреслення. Префікс `action_` додається автоматично | Використовується в сценаріях, не змінюється |
| **Опис** | Коротке пояснення призначення дії | Підказки, довідники |
| **Група** | Категорія для групування. Можна створити нову через «Додати групу» | Фільтр «Оберіть action групу» у сайдбарі блоку Action |

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

---

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

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

**Шлях 1 — вручну:**
```javascript
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 у редакторі. Мінімальний приклад:
```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](/uk/actionjail/how-to/use-saved-credential-in-custom-action.md)). Для поля в JSON-конфігу:

```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](/uk/actionjail/explanation/action-to-scenario-flow.md).

---

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

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

---

## Інші способи

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

---

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

- [Про те, як дані з Action Jail потрапляють у Scenario Builder](/uk/actionjail/explanation/action-to-scenario-flow.md)
- [Секції редактора дій](/uk/actionjail/explanation/action-editor-sections.md)
- [Налаштування AI-генератора](/uk/actionjail/how-to/admin-ai-generator-setup.md)
- [Як створити й підтримувати дію](/uk/actionjail/how-to/admin-manage-actions.md)
- [Actions Reference](/uk/actionjail/reference/actions-reference.md)
- [Використати секрет у custom action](/uk/actionjail/how-to/use-saved-credential-in-custom-action.md)