---
title: "Custom Data patterns and examples"
description: "Typical Custom Data scenarios: directories and journals, operator UI, process integration — based on the Custom Data v2 workspace."
---

# Custom Data patterns and examples

Custom Data is not only “storage for the bot”. In v2 one module serves three roles: the **administrator** designs the table and imports data, **operators and managers** work with lists in a comfortable UI, and the **integrator** connects the same table to the process. This document helps you pick a pattern for your task — without unnecessary code where UI is enough, and without keeping Google Sheets “forever” when both people and automation need the same data.

---

## How to choose quickly

| Your task | Where to look |
|-----------|---------------|
| Cities, stores, categories — bot **shows** a list | [Directory](#archetype-1-directory-the-process-reads) + [Routing in process](#pattern-routing-via-directory) |
| CSAT, requests, feedback — bot **writes** after a dialog | [Journal](#archetype-2-journal-the-process-writes) + [Save from process](/en/customdata/how-to/save-data-from-scenario.md) |
| Operators **maintain a list** (statuses, filters, board) | [Operator patterns](#patterns-for-operators-and-managers) |
| Data already in Excel / Google Sheets | [Import from file](/en/customdata/how-to/import-data-from-file.md) or [Google Sheets](/en/customdata/how-to/import-from-google-sheets.md) |
| Field on **one client’s card** (manager, segment) | **Client fields**, not Custom Data → [Extend contacts](/en/customdata/how-to/extend-client-contacts.md) |
| Full CRM for the whole business | External system; Custom Data is an internal service directory → [Compared to other approaches](/en/customdata/explanation/custom-data-vs-other-approaches.md) |

**Client Fields** and **User Fields** are for client or operator attributes, not standalone record registers.

---

## Two main archetypes

In real projects almost all Custom Data tables fall into two models. The archetype defines **who fills data** and **how to create the table**.

### Archetype 1: Directory (the process reads)

**Idea:** the table is filled by an **administrator** (import, manual edit), and the process **reads** records — cities, stores, categories, routing branches.

| | |
|---|---|
| **Who writes** | Administrator, integrator (import / editor) |
| **Who reads** | Process (`custom_modules__get`), sometimes operator for checks |
| **Where structure comes from** | Client file (most often) or from scratch |
| **Typical examples** | Stores by city, product categories, branch codes, language branches |

**Best v2 start:** **New table → From file (Excel/CSV)** or **Data import** into a new table. An empty directory without rows rarely makes sense — data usually already lives in the client’s spreadsheet.

**Field example (stores):** `city`, `address`, `phone`, `lang_code`.

### Archetype 2: Journal (the process writes)

**Idea:** rows are **created by the process** during a dialog (rating, request, survey answer). Operators and supervisors **view and change** records in the UI — filters, board, card.

| | |
|---|---|
| **Who writes** | Process (`custom_modules__set` / save from input block) |
| **Who reads / edits** | Operators, supervisors, Metabase reports |
| **Where structure comes from** | Journal starter, CSAT starter, or design from scratch |
| **Typical examples** | CSAT after dialog, callback requests, survey entries, processing queue |

**Best v2 start:** **Starters** (e.g. quality rating) or **From scratch** with fields matching what the process collects. After save — **Use in process** tab and wire blocks.

**Field example (CSAT):** `chat_id`, `rating`, `comment`, `created_at`.

> **Important:** a starter gives **structure and hints**, not ready automation. Until the process writes to the table, the journal stays empty — that is normal during design.

---

## Table creation patterns (administrator / integrator)

### Pattern: Directory from file → data ready to use

**Task:** move existing Excel/CSV into the platform and use it in the process immediately.

**v2 path:**
1. **New table → From file** or **Data import** (new table).
2. Wizard: source → name and group → column mapping → **Preview before import** → import.
3. **View data** — verify rows in the table.
4. **Use in process** — wire read access to the bot.

**When it fits:** routing directories, SKU catalogs, location lists — the most common path in production.

→ [Import from file](/en/customdata/how-to/import-data-from-file.md)

### Pattern: Journal from starter → process + team UI

**Task:** collect CSAT or a request register: bot writes, supervisor sees the list.

**v2 path:**
1. **New table → Starters** (quality rating, tasks, etc.) or **From scratch**.
2. Editor: fields → **Field display** → optionally **UI settings** (chart, highlighting).
3. Save → **Use in process**: write / read / **Ask AI**.
4. In records table — **Saved view** “Open today” for operators.

**When it fits:** feedback, NPS, callback requests, internal queues.

→ [Starters](/en/customdata/how-to/use-model-starters.md) · [Process tab](/en/customdata/how-to/use-scenario-tab-on-model.md)

### Pattern: Ask AI during design

**Task:** describe the need in words (“repair requests with address, status, priority”) and get a draft structure.

**v2 path:** **New table → Ask AI** → Instance Agent suggests fields → you review in **Model editor** → save.

**When it fits:** non-standard domain when starters do not fit but you need a quick draft.

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

### Pattern: Refresh a directory without manual CRUD

**Task:** update a catalog weekly from Google Sheets or a new file.

**v2 path:** **Data import** into an **existing** table → **Add to current records** or **Clear model and import again** (with confirmation only) → **Preview before import**.

**Do not confuse with legacy:** old custom action `google_sheets_fetch_data` in processes is a deprecated workaround; administrators have native **Data import**.

→ [Google Sheets](/en/customdata/how-to/import-from-google-sheets.md) · [Import from file](/en/customdata/how-to/import-data-from-file.md)

---

## Patterns for operators and managers

These patterns show why Custom Data is more convenient than an external spreadsheet for daily team work.

### Pattern: Working list with a saved view

**Task:** supervisor opens “my open requests today” with the same columns and filters every day.

**How it works:** in the records **Table**, apply **Filter** and **Sorting** → **Save view** → optionally **Make shared for everyone**. The team switches view tabs without reconfiguring.

**Permissions:** view — broad role; shared view and edit — module permissions.

→ [Saved views](/en/customdata/how-to/use-saved-views.md)

### Pattern: Status board (Kanban)

**Task:** move requests or tasks across “New → In progress → Closed” by drag-and-drop.

**How it works:** **List** or **Table relation** field for grouping → **Table / Board** toggle → drag-and-drop updates status. The process sees the same value as the operator on the board.

**When it fits:** journals with a `status` field, internal queues, pipeline without a separate task tracker.

→ [View records](/en/customdata/how-to/view-model-records.md) (table and board)

### Pattern: Quick edit in grid or card

**Task:** operator changes one or two fields (comment, status, assignee) without opening CRM.

**How it works:** inline edit in the table or record **Card** in the side panel. Semantic types (**User**, **Subject**, **Email**) provide dropdowns instead of raw text.

### Pattern: Macro from a row

**Task:** “Send to process” or “Check in CRM” button right on the record.

**How it works:** in editor **UI settings** — **Macros** → row button or selection button → launch process with id and field context.

**When it fits:** operator action on one journal row without opening the builder.

→ [Row macros](/en/customdata/how-to/use-row-macros.md)

### Pattern: Export with current filter

**Task:** manager sends a data slice to an analyst or Excel for a meeting.

**How it works:** apply filter → **Export** (CSV, XLS, PDF, etc.) — the file contains what is on screen.

→ [Export data](/en/customdata/how-to/export-model-data.md) · [Export filtered](/en/customdata/how-to/export-filtered-data.md)

---

## Process integration patterns (integrator)

### Pattern: Routing via directory

**Task:** user picks a city → bot shows stores in that city.

**Sequence:** `custom_modules__get` (all or by `lang_code`) → keyboard with cities → `get` with `city` filter → message with addresses.

**Model:** `stores` — `city`, `address`, `lang_code`.

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

### Pattern: Write to journal after dialog

**Task:** save a rating or request after a survey.

**Sequence:**
- Simple path: input block with **Save to Custom Data**.
- Flexible path: `custom_modules__set` with `module_name` and fields.

**Model:** `csat_feedback` — `chat_id`, `rating`, `comment`, `created_at`.

→ [Save from process](/en/customdata/how-to/save-data-from-scenario.md) · [custom_modules__set](/en/customdata/how-to/use-custom-modules-set.md)

### Pattern: Update client row (reg_user_id)

**Task:** one row per client, process appends attributes (city, segment, external id).

**Sequence:** `custom_modules__update` with `reg_user_id` key — updates existing row, no duplicate.

**When Client Fields are better:** if data belongs on the **client card** in Operator Line, not a separate register.

### Pattern: Inline buttons with record id

**Task:** show requests as buttons; on click load the full record.

**Sequence:** get list → inline buttons with `callback_data` = id → `inline_call_back` → continue with record fields.

**Typical for:** journals where the user (not operator) picks from their own list.

### Pattern: Link between tables

**Task:** product references category; table shows label, not only id.

**How it works:** **Table relation** field → starters like “Products and categories” or two manually created tables.

→ [Association between tables](/en/customdata/how-to/create-association-between-tables.md)

### Pattern: Analytics (Metabase)

**Task:** CSAT and NPS on dashboards.

**Sequence:** process writes to journal → Metabase reports on instance table. Optionally enable **statistics** under the table in UI (chart by `rating` field).

**Richer display:** charts, row highlighting, map — [Advanced cases](/en/customdata/explanation/advanced-custom-data-cases.md).

---

## Summary matrix

| Pattern | Archetype | Who maintains data | v2 UI | Process |
|---------|-----------|-------------------|-------|---------|
| Directory from file | Directory | Admin (import) | Table, export | get |
| Journal + operators | Journal | Process + operator | Table, Board, views | set / update |
| City → location routing | Directory | Admin | Browse | get + keyboard |
| CSAT / NPS | Journal | Process | Statistics, export | set |
| Request queue | Journal | Process + operator | Kanban, macros | set + get |
| Profile update | Journal / hybrid | Process | Rarely | update |
| Catalog from Google | Directory | Admin (import) | Table | get |
| Metabase | Journal | Process | Optional charts | set |

---

## Common mistakes

| Mistake | Why it hurts | Better |
|---------|--------------|--------|
| Create CSAT starter and wait for data without a process | Empty journal — nothing writes | **Use in process** first, then test dialog |
| Keep directory in Google Sheets “for operators” | Two UIs, sync, permissions | Import → Custom Data → platform roles |
| Custom Data for “client’s manager” field | That is profile, not a register | **Client fields** |
| Rename field after process is wired | Breaks get/set | Check **Use in process** before change |
| Empty directory “from scratch” | Nothing to show in bot | **From file** or import |

---

## Related documents

- [What is Custom Data](/en/customdata/explanation/what-is-custom-data.md) — module concepts
- [Compared to other approaches](/en/customdata/explanation/custom-data-vs-other-approaches.md) — why not a separate system
- [Advanced Custom Data cases](/en/customdata/explanation/advanced-custom-data-cases.md) — validation, charts, map
- [Create a table](/en/customdata/how-to/create-model.md)
- [Integrator Hub](/en/customdata/integrator-hub.md) · [Admin Hub](/en/customdata/admin-hub.md)