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

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.

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.

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

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 · Process tab

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

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 · Import from file

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

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 (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

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 · Export filtered

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

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 · custom_modules__set

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

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.

Summary matrix

Common mistakes

Related documents

• What is Custom Data — module concepts
• Compared to other approaches — why not a separate system
• Advanced Custom Data cases — validation, charts, map
• Create a table
• Integrator Hub · Admin Hub