Як налаштувати поле «Список по API» (ActionJail)?

Тип Список по API підвантажує опції випадаючого списку з ActionJail-дії під час редагування запису. Це зручно, коли перелік значень динамічний (оператори, магазини, довідник з CRM) і не вміщується в статичний Список.

Коли знадобиться

• Потрібен dropdown із даних, які змінюються (користувачі, статуси зовнішньої системи, довідник API).
• Статичний Список не підходить — занадто багато значень або вони оновлюються автоматично.
• Системний тип (Користувач, Тема…) не покриває ваш кейс — потрібна власна jail-дія.

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

Де працює dropdown сьогодні

• клієнтські поля в діалозі оператора;
• динамічні поля в операторських формах (Table view, OperatorLine);
• не у таблиці записів і не у боковій картці запису — там значення показується як текст, поки не буде окремо підключено вибір зі списку (заплановано).

Коли обрати інший тип

• фіксований перелік → Список;
• посилання на іншу таблицю Custom Data → Звʼязок з таблицею;
• користувач / тема / тег платформи → Системні типи.

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

• Є доступ до ActionJail (створення або редагування дії на інстансі).
• Відкритий Редактор моделі Custom Data (або клієнтські поля в Settings).
• Зрозуміло, які дані має повертати список і що саме зберігати в полі (ID, код, назва).

Крок 1. Створити ActionJail-дію

1. Відкрийте ActionJail → Створити дію (або відредагуйте існуючу).
2. Задайте технічну назву — саме її оберете в полі моделі (наприклад action_list_stores або aj_list_operators).
3. У тілі дії:
   • прочитайте параметри запиту з констант: query (пошук), limit, offset — їх передає платформа при відкритті списку;
   • сформуйте масив елементів;
   • збережіть результат у result у форматі { rows, count };
   • поверніть 'success'.

Контракт відповіді

this.setCurrentStateConstant('result', {
  rows: [
    { id: 1, label: 'Київ — Центр' },
    { id: 2, label: 'Львів — Головний' },
  ],
  count: 2, // загальна кількість (для пагінації)
});

Кожен елемент rows — об'єкт. У ньому обов'язково має бути властивість з ім'ям, яке ви вкажете в Полі підпису в списку (типово label, name або title). Якщо в полі треба зберігати ID, вкажіть label_key: id — тоді в комірку потрапить значення id з обраного рядка.

Мінімальний приклад дії

const appPath = process.cwd();
const OpModels = require(appPath + '/modules/extra/operator_panel/db/models');

async function action_list_active_operators() {
  const state = await this.getCurrentStateJSON();
  const query = String(state?.const?.query || '').trim();
  const limit = Number(state?.const?.limit) || 20;
  const offset = Number(state?.const?.offset) || 0;

  const where = { active: true };
  // за потреби — фільтр по query

  const rows = await OpModels.OpUsers.findAll({
    where,
    attributes: [ 'id', 'first_name', 'last_name' ],
    limit,
    offset,
    raw: true,
  });

  const formatted = rows.map((row) => ({
    id: row.id,
    label: [ row.first_name, row.last_name ].filter(Boolean).join(' '),
  }));

  this.setCurrentStateConstant('result', {
    rows: formatted,
    count: formatted.length,
  });

  return 'success';
}

module.exports = action_list_active_operators;

Платформа викликає дію через GET /kw/tickets/custom_list/<назва_дії> з query-параметрами query, limit, offset.

Крок 2. Налаштувати поле в Custom Data

1. У редакторі моделі на вкладці Поля оберіть тип Список по API.
2. У блоці Джерело списку:
   • ActionJail-дія — ваша дія з кроку 1;
   • Поле підпису в списку — ключ для підпису та збереження (label, id, name…).
3. Збережіть модель.

У columns_json це виглядає так:

"store_ref": {
  "type": "STRING",
  "label": "Магазин",
  "select_api_action": {
    "name": "action_list_stores",
    "label_key": "label"
  }
}

Крок 3. Перевірити

1. Відкрийте форму оператора, де показується це поле (не таблицю даних, якщо dropdown там ще не підключено).
2. Відкрийте список — мають з’явитися рядки з дії.
3. Оберіть значення, збережіть — у БД має потрапити властивість з label_key обраного елемента.
4. Якщо список порожній — перевірте назву дії, логи ActionJail і що result.rows не порожній.

Типові помилки

Пов'язані матеріали

• Налаштувати тип поля
• Довідник семантичних типів полів
• Налаштувати системні типи полів — якщо підходить довідник платформи