Патерни та приклади Custom Data

Custom Data — це не лише «сховище для бота». У v2 один модуль закриває три ролі: адміністратор проєктує таблицю та імпортує дані, оператор або менеджер щодня працює зі списками в зручному інтерфейсі, інтегратор підключає ту саму таблицю до процесу. Цей документ допоможе обрати патерн під вашу задачу — без зайвого коду там, де достатньо UI, і без Google Sheets «назавжди», якщо дані потрібні і людям, і автоматизації.

Як швидко обрати підхід

Client Fields і User Fields — для атрибутів клієнта або оператора, не для окремих реєстрів записів.

Два головні архетипи

У реальних проєктах майже всі таблиці Custom Data зводяться до двох моделей. Від архетипу залежить, хто наповнює дані і як їх створювати.

Архетип 1: Довідник (сценарій читає)

Суть: таблиця наповнюється адміністратором (імпорт, ручне редагування), а процес читає записи — показує міста, магазини, категорії, гілки роутингу.

Найкращий старт у v2: Нова таблиця → З файла (Excel/CSV) або Імпорт даних у наявну таблицю. Порожній довідник без рядків рідко має сенс — дані заздалегідь живуть у таблиці клієнта.

Приклад полів (магазини): city, address, phone, lang_code.

Архетип 2: Журнал (сценарій пише)

Суть: рядки створює процес під час діалогу (оцінка, заявка, відповідь на опитування). Оператори та супервайзери переглядають і змінюють записи в UI — фільтри, дошка, картка.

Найкращий старт у v2: Стартери (наприклад, оцінка якості) або З нуля з полями під те, що збирає процес. Після збереження — вкладка Використання в процесі і підключення блоків.

Приклад полів (CSAT): chat_id, rating, comment, created_at.

Важливо: стартер дає структуру та підказки, не готову автоматизацію. Поки процес не записує в таблицю, журнал залишиться порожнім — це нормально на етапі проектування.

Патерни створення таблиці (адміністратор / інтегратор)

Патерн: Довідник з файлу → одразу робочі дані

Задача: перенести існуючий Excel/CSV у платформу і одразу використовувати в процесі.

Шлях у v2:

1. Нова таблиця → З файла або Імпорт даних (нова таблиця).
2. Майстер: джерело → назва та група → зіставлення колонок → Перегляд перед імпортом → імпорт.
3. Переглянути дані — перевірка рядків у таблиці.
4. Використання в процесі — підключення читання до бота.

Коли підходить: routing directories, каталоги SKU, списки точок — у client_flow це найпоширеніший шлях.

→ Імпорт з файлу

Патерн: Журнал зі стартера → процес + UI для команди

Задача: зібрати CSAT або реєстр заявок: бот пише, супервайзер бачить список.

Шлях у v2:

1. Нова таблиця → Стартери (оцінка якості, задачі тощо) або З нуля.
2. Редактор: поля → Відображення полів → за потреби UI-налаштування (графік, підсвітка).
3. Збереження → Використання в процесі: запис / читання / Ask AI.
4. У таблиці записів — Збережений вигляд «Відкриті за сьогодні» для операторів.

Коли підходить: feedback, NPS, callback-заявки, внутрішні черги.

→ Стартери · Вкладка процесу

Патерн: Ask AI на етапі проектування

Задача: описати задачу словами («таблиця заявок на ремонт з полями адреса, статус, пріоритет») і отримати чернетку структури.

Шлях у v2: Нова таблиця → Ask AI → Instance Agent пропонує поля → ви перевіряєте в Редакторі моделі → збереження.

Коли підходить: нестандартний домен, коли стартери не підходять, але потрібен швидкий draft.

→ Ask AI для Custom Data

Патерн: Оновлення довідника без ручного CRUD

Задача: раз на тиждень оновити каталог з Google Sheets або нового файлу.

Шлях у v2: Імпорт даних у існуючу таблицю → режим Додати до поточних записів або Очистити модель і імпортувати заново (лише з підтвердженням) → Перегляд перед імпортом.

Не плутати з legacy: старий custom action google_sheets_fetch_data у процесах — застарілий обхідний шлях; для адміністраторів є нативний Імпорт даних.

→ Google Sheets · Імпорт з файлу

Патерни для операторів і менеджерів

Ці патерни показують, чому Custom Data зручніше за зовнішню таблицю для щоденної роботи команди.

Патерн: Робочий список зі збереженим виглядом

Задача: супервайзер щодня відкриває «мої відкриті заявки» з однаковими колонками та фільтрами.

Як працює: у Таблиці записів застосуйте Фільтр і Сортування → Зберегти вигляд → за потреби Зробити спільним для всіх. Команда перемикається між вкладками виглядів без повторного налаштування.

Права: перегляд — широка роль; спільний вигляд і редагування — за дозволами модуля.

→ Збережені вигляди

Патерн: Дошка за статусом (Kanban)

Задача: заявки або задачі ведуть по колонках «Нова → В роботі → Закрита» перетягуванням.

Як працює: поле типу Список або Звʼязок з таблицею як групування → перемикач Таблиця / Дошка → drag-and-drop оновлює статус. Процес бачить те саме значення, що й оператор на дошці.

Коли підходить: журнали з полем status, внутрішні черги, pipeline без окремого task-tracker.

→ Дошка та Kanban (перегляд записів)

Патерн: Швидке редагування в сітці або картці

Задача: оператор змінює один-два поля (коментар, статус, відповідальний) без відкриття CRM.

Як працює: inline-редагування в таблиці або Картка запису в боковій панелі. Семантичні типи (Користувач, Тема, Email) дають випадаючі списки замість «сирого» тексту.

Патерн: Макрос з рядка

Задача: кнопка «Відправити в процес» або «Перевірити в CRM» прямо біля запису.

Як працює: у UI-налаштування редактора — Макроси → кнопка в рядку або для виділених записів → запуск процесу з контекстом id і полів.

Коли підходить: операторська дія над одним записом журналу без переходу в конструктор.

→ Макроси рядків

Патерн: Експорт з поточним фільтром

Задача: менеджер віддає зріз даних аналітику або в Excel для наради.

Як працює: застосуйте фільтр → Експорт (CSV, XLS, PDF тощо) — у файл потрапляє те, що видно на екрані.

→ Експорт даних · Експорт з фільтром

Патерни підключення до процесу (інтегратор)

Патерн: Роутинг через довідник

Задача: користувач обирає місто → бот показує магазини цієї міста.

Послідовність: custom_modules__get (усі або за lang_code) → клавіатура з містами → get з фільтром city → повідомлення з адресами.

Модель: stores — city, address, lang_code.

→ custom_modules__get

Патерн: Запис у журнал після діалогу

Задача: зберегти оцінку або заявку після опитування.

Послідовність:

• Простий шлях: блок вводу з Зберегти в Custom Data.
• Гнучкий шлях: custom_modules__set з module_name і полями.

Модель: csat_feedback — chat_id, rating, comment, created_at.

→ Зберегти з процесу · custom_modules__set

Патерн: Оновлення запису клієнта (reg_user_id)

Задача: один рядок на клієнта, процес дописує атрибути (місто, сегмент, зовнішній id).

Послідовність: custom_modules__update з ключем reg_user_id — не створює дублікат, а оновлює існуючий запис.

Коли краще Client Fields: якщо дані — частина картки клієнта в Operator Line, а не окремий реєстр.

Патерн: Inline-кнопки з id запису

Задача: показати список заявок кнопками; по кліку завантажити повний запис.

Послідовність: get списку → inline-кнопки з callback_data = id → inline_call_back → продовження сценарію з полями запису.

Типово для: журналів, де користувач (не оператор) обирає зі списку своїх записів.

Патерн: Зв’язок між таблицями

Задача: товар посилається на категорію; у таблиці видно назву, не лише id.

Як працює: поле Звʼязок з таблицею → стартери на кшталт «Товари і категорії» або дві таблиці, створені вручну.

→ Зв’язок між таблицями

Патерн: Аналітика (Metabase)

Задача: CSAT і NPS у дашбордах.

Послідовність: процес пише в журнал → Metabase будує звіти по таблиці інстансу. Додатково в UI можна увімкнути статистику під таблицею (графік за полем rating).

Складніше відображення: графіки, підсвітка рядків, карта — Складні кейси.

Підсумкова матриця

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

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

• Що таке Custom Data — концепції модуля
• Порівняння з іншими підходами — чому не окрема система
• Складні кейси Custom Data — валідація, графіки, карта
• Створити таблицю
• Integrator Hub · Admin Hub