---
title: "Патерни та приклади Custom Data"
description: "Типові сценарії роботи з Користувацькими даними: довідники й журнали, UI для операторів, підключення до процесів — на основі робочого простору Custom Data v2."
---

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

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

---

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

| Ваша задача | Куди дивитись |
|-------------|---------------|
| Міста, магазини, категорії — бот **показує** список | [Довідник](#архетип-1-довідник-сценаріи-читає) + [Роутинг у процесі](#патерн-роутинг-через-довідник) |
| CSAT, заявки, feedback — бот **записує** після діалогу | [Журнал](#архетип-2-журнал-сценаріи-пише) + [Запис з процесу](/uk/customdata/how-to/save-data-from-scenario.md) |
| Оператори **ведуть список** (статуси, фільтри, дошка) | [Патерни для операторів](#патерни-для-операторів-і-менеджерів) |
| Дані вже в Excel / Google Sheets | [Імпорт з файлу](/uk/customdata/how-to/import-data-from-file.md) або [Google Sheets](/uk/customdata/how-to/import-from-google-sheets.md) |
| Поле на **картці одного клієнта** (менеджер, сегмент) | **Поля клієнта**, не Custom Data → [Розширити контакти](/uk/customdata/how-to/extend-client-contacts.md) |
| Потрібен окремий CRM на весь бізнес | Зовнішня система; Custom Data — внутрішній довідник для сервісу → [Порівняння з іншими підходами](/uk/customdata/explanation/custom-data-vs-other-approaches.md) |

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

---

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

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

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

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

| | |
|---|---|
| **Хто пише дані** | Адміністратор, інтегратор (імпорт / редактор) |
| **Хто читає** | Процес (`custom_modules__get`), інколи оператор для перевірки |
| **Звідки структура** | З файлу клієнта (найчастіше) або з нуля |
| **Типові приклади** | Магазини за містом, категорії товарів, коди відділень, мовні гілки |

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

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

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

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

| | |
|---|---|
| **Хто пише дані** | Процес (`custom_modules__set` / збереження з блоку вводу) |
| **Хто читає / змінює** | Оператори, супервайзери, звіти Metabase |
| **Звідки структура** | Стартер «журнал», CSAT-стартер або проектування з нуля |
| **Типові приклади** | CSAT після діалогу, заявки на дзвінок, записи опитування, черга на обробку |

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

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

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

---

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

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

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

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

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

→ [Імпорт з файлу](/uk/customdata/how-to/import-data-from-file.md)

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

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

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

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

→ [Стартери](/uk/customdata/how-to/use-model-starters.md) · [Вкладка процесу](/uk/customdata/how-to/use-scenario-tab-on-model.md)

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

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

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

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

→ [Ask AI для Custom Data](/uk/customdata/how-to/use-ask-ai-for-custom-data.md)

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

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

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

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

→ [Google Sheets](/uk/customdata/how-to/import-from-google-sheets.md) · [Імпорт з файлу](/uk/customdata/how-to/import-data-from-file.md)

---

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

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

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

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

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

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

→ [Збережені вигляди](/uk/customdata/how-to/use-saved-views.md)

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

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

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

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

→ [Дошка та Kanban](/uk/customdata/how-to/view-model-records.md) (перегляд записів)

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

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

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

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

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

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

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

→ [Макроси рядків](/uk/customdata/how-to/use-row-macros.md)

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

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

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

→ [Експорт даних](/uk/customdata/how-to/export-model-data.md) · [Експорт з фільтром](/uk/customdata/how-to/export-filtered-data.md)

---

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

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

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

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

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

→ [custom_modules__get](/uk/customdata/how-to/use-custom-modules-get.md)

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

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

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

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

→ [Зберегти з процесу](/uk/customdata/how-to/save-data-from-scenario.md) · [custom_modules__set](/uk/customdata/how-to/use-custom-modules-set.md)

### Патерн: Оновлення запису клієнта (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.

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

→ [Зв’язок між таблицями](/uk/customdata/how-to/create-association-between-tables.md)

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

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

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

**Складніше відображення:** графіки, підсвітка рядків, карта — [Складні кейси](/uk/customdata/explanation/advanced-custom-data-cases.md).

---

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

| Патерн | Архетип | Хто веде дані | UI v2 | Процес |
|--------|---------|---------------|-------|--------|
| Довідник з файлу | Довідник | Адмін (імпорт) | Таблиця, експорт | get |
| Журнал + оператори | Журнал | Процес + оператор | Таблиця, Дошка, вигляди | set / update |
| Роутинг місто → точки | Довідник | Адмін | Перегляд | get + keyboard |
| CSAT / NPS | Журнал | Процес | Статистика, експорт | set |
| Черга заявок | Журнал | Процес + оператор | Kanban, макроси | set + get |
| Оновлення профілю | Журнал / гібрид | Процес | Рідко | update |
| Каталог з Google | Довідник | Адмін (імпорт) | Таблиця | get |
| Metabase | Журнал | Процес | Опційно графіки | set |

---

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

| Помилка | Чому погано | Краще |
|---------|-------------|--------|
| Створити CSAT-стартер і чекати дані без процесу | Журнал порожній — ніхто не пише | Спочатку **Використання в процесі**, потім тест діалогу |
| Тримати довідник у Google Sheets «для операторів» | Два інтерфейси, sync, права | Імпорт → Custom Data → ролі в платформі |
| Custom Data для поля «менеджер клієнта» | Це профіль, не реєстр | **Поля клієнта** |
| Перейменувати поле після підключення процесу | Зламається get/set | Перевірити **Використання в процесі** перед зміною |
| Порожній довідник «з нуля» | Немає що показувати в боті | **З файла** або імпорт |

---

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

- [Що таке Custom Data](/uk/customdata/explanation/what-is-custom-data.md) — концепції модуля
- [Порівняння з іншими підходами](/uk/customdata/explanation/custom-data-vs-other-approaches.md) — чому не окрема система
- [Складні кейси Custom Data](/uk/customdata/explanation/advanced-custom-data-cases.md) — валідація, графіки, карта
- [Створити таблицю](/uk/customdata/how-to/create-model.md)
- [Integrator Hub](/uk/customdata/integrator-hub.md) · [Admin Hub](/uk/customdata/admin-hub.md)