Помощь по шагам
Помощь по Интеграму
Интеграм — конструктор приложений: в нём делают рабочие места для учёта, заказов, клиентов, отчётов. Данные хранятся в таблицах, а экраны собираются из шаблонов. Программировать с нуля не нужно.
Чтобы начать, не нужно изучать всё сразу. Исходный принцип платформы: максимальная требуемая квалификация не выше уровня пользователя Excel. Эта страница — короткое введение на пять минут; дальше можно спросить консультанта или найти нужное в оглавлении.
Что такое Интеграм
Что это
Интеграм (ideav.ru) — low-code платформа. База в ней — набор связанных таблиц: Клиент, Счёт, Договор, Встреча. У таблицы есть колонки (реквизиты), а поверх базы строятся рабочие места — страницы, с которыми работают сотрудники.
Значительная часть самого Интеграма построена его же средствами: пользователи, роли, меню и запросы — это обычные таблицы. Поэтому платформу можно дополнять под себя.
- Таблицы и связи вы описываете терминами своего бизнеса.
- Данные можно загрузить из Excel, смотреть и править в таблицах, похожих на Excel.
- Всё, что делается в интерфейсе, доступно и через API.
Для чего
Интеграм нужен, когда учёт вышел за пределы Excel, а заказная разработка слишком долгая или дорогая. Решение собирается из таблиц, запросов и готовых форм, а не пишется кодом.
- Заменить таблицы Excel и Google Sheets общей базой с ролями и правами доступа.
- Собрать рабочее место для сотрудника: список, карточка записи, отчёт.
- Менять структуру по ходу работы: новая колонка или справочник появляется сразу, без переписывания базы.
- Подключать внешние системы через API.
Как устроено
Разработка приложения идёт в четыре шага: описать структуру данных, наполнить её данными, настроить запросы, собрать рабочие места. Ниже — из чего состоит платформа.
Чтобы пользоваться Интеграмом, устройство изнутри знать не обязательно. Эти сведения нужны, чтобы понимать, почему платформа гибкая.
- Ядро
- Единый обработчик: имя базы берётся из первого сегмента адреса, дальше он выполняет команды — создать таблицу, добавить запись, построить отчёт.
- Хранение данных
- Все данные базы лежат в одной структуре из пяти полей:
id,up(родитель),t(тип),val(значение),ord(порядок). Такую модель называют квинтетами. Описание структуры и сами записи хранятся в ней одинаково. - Метаданные: типы
- Таблица — это тип. Первая колонка задаёт имя записи, остальные — реквизиты. Связей два вида: ссылка на справочник и подчинённая таблица (строки, принадлежащие родителю).
- Движок запросов
- Отчёт описывается декларативно: какие колонки, фильтры, агрегаты и формулы. Ядро само превращает описание в SQL-запрос. Вызывается через
report/…. - Шаблонизатор
- Рабочие места — HTML-шаблоны со вставками вида
{_global_.…}. Сервер подставляет данные, страница ходит в базу по API. - API
- Команды структуры (
_d_*) и данных (_m_*), чтение таблиц и отчётов. Вход — по ключу API или сессии. - Роли и права
- У пользователя одна роль. Роль перечисляет доступные таблицы и отчёты с уровнем READ, WRITE или BARRED; маска дополнительно ограничивает строки. Меню тоже привязано к роли.
Где применяют
- Бизнес-аналитик или руководитель отдела описывает структуру в таблицах и редакторе структуры и получает рабочее место.
- Партнёр-интегратор разворачивает готовые шаблоны для клиента и настраивает их под него.
- Сотрудник компании каждый день работает в готовых формах: вносит записи, смотрит отчёты, выгружает данные.
- Разработчик подключает внешние системы по API и собирает собственные страницы из шаблонов.
- Владелец небольшого бизнеса загружает свою таблицу Excel и получает на её основе рабочее приложение.
Как пользоваться помощью
- Не знаете, с чего начать, — спросите консультанта: он подскажет, какая часть справки нужна для вашей задачи.
- Знаете, что ищете, — найдите в оглавлении: статьи сгруппированы по темам.
- Незнакомое слово — загляните в словарик ниже.
- Читать всё подряд не нужно: для типовой задачи хватает одной-двух статей.
Словарик терминов
- База
- Рабочее пространство клиента: свои таблицы, пользователи и права. Адрес вида
ideav.ru/имя_базы. - Таблица (тип)
- Описание сущности: Клиент, Счёт, Договор. Иногда её называют термином, типом, классом или объектом.
- Запись
- Одна строка таблицы. Значение первой колонки — это имя самой записи.
- Реквизит
- Колонка таблицы, свойство записи: телефон, дата встречи, сумма.
- Базовый тип
- Вид значения колонки: короткий текст (
SHORT), длинный текст, дата, дата и время, целое и дробное число, файл, да/нет, пароль и другие. - Ссылка
- Реквизит, значение которого выбирают из справочника, как категорию клиента. Работает как внешний ключ.
- Справочник
- Таблица со значениями для выбора, например Категории. Устроена так же, как любая другая таблица.
- Подчинённая таблица
- Дочерние записи одного родителя, табличная часть: например, позиции заказа или встречи клиента.
- Квинтет
- Запись хранения из пяти полей:
id,up,t,val,ord. Из квинтетов состоят и данные, и описание структуры. - Редактор структуры
- Раздел меню Структура: здесь создают и связывают термины. Изменения сразу видны в таблицах.
- Запрос (отчёт)
- Правило выборки данных: колонки, фильтры, агрегаты, формулы. Вызывается через
report/…. - Рабочее место
- Страница-шаблон для конкретной роли: список, форма, отчёт.
- Шаблонизатор
- Часть сервера, которая подставляет данные и переменные вида
{_global_.…}в HTML-шаблон. - Роль
- Набор прав пользователя: к каким таблицам и отчётам есть доступ и с каким уровнем.
- Маска
- Дополнительный фильтр строк в правах роли: например, менеджер видит только своих клиентов.
- Токен (ключ API)
- Строка, по которой клиент или агент обращается к базе без логина и пароля.
- API
- Набор команд, через которые доступно всё, что делается в интерфейсе: структура, записи, пользователи, роли, запросы.
Готовые рецепты
Типовые бизнес-задачи, собранные из возможностей Интеграма: какие таблицы и реквизиты завести, какие запросы и роли настроить, какие кнопки и шаблоны добавить. Каждый рецепт — по шагам и со ссылками на базовые приёмы.
CRM и воронка продаж
в интерфейсе
Клиенты, сделки и справочник этапов — три связанные таблицы; воронка — это сделки, сгруппированные по этапу, а менеджер видит только своих клиентов по маске роли.
- Опишите структуру одним вызовом
_d_schema: справочник «Этап сделки» (unique: true), таблица «Клиент» с подчинённой таблицей «Контакт» (история звонков и встреч) и таблица «Сделка» со ссылками на «Клиент» и «Этап сделки», суммой (SIGNED) и датой. - В «Клиенте» добавьте ссылку «Менеджер» на справочник сотрудников и задайте ей значение по умолчанию
[USER_ID]: новый клиент закрепляется за тем, кто его завёл. - Создайте запрос «Воронка»: колонка «Этап сделки» (группировка), колонка «Сделок» с функцией
COUNT, колонка «Сумма» сSUM. - Создайте роли «Менеджер» и «Руководитель». Менеджеру дайте WRITE на «Клиент» и «Сделка», READ на справочники и маску на поле «Менеджер» со значением
[USER_ID]; руководителю — READ на всё без маски. - В таблицу сделок добавьте колонку-кнопку (базовый тип BUTTON) с действием «Ссылка» или «Запрос»: из строки сделки открывается карточка клиента или срез по нему.
- Загрузите клиентов из Excel батч-импортом, добавьте пункты меню ролям и заведите пользователей.
Канбан-вид воронки — это сделки, разложенные по колонкам-значениям справочника этапов; набор этапов задаёте вы.
{"tables": [
{"name": "Этап сделки", "unique": true},
{"name": "Клиент", "fields": [{"name": "Телефон"}, {"name": "Менеджер", "ref": "Пользователь", "default": "[USER_ID]"}],
"children": [{"name": "Контакт", "fields": [{"name": "Дата", "type": "DATE"}, {"name": "Итог", "type": "MEMO"}]}]},
{"name": "Сделка", "fields": [
{"name": "Клиент", "ref": "Клиент", "required": true},
{"name": "Этап сделки", "ref": "Этап сделки"},
{"name": "Сумма", "type": "SIGNED"}]}]}
Сотрудники ведутся в системной таблице «Пользователь»; если ссылка на неё не подходит под вашу схему, заведите свой справочник «Менеджер».
Подробнее: Схема одним вызовом · Маски: фильтр строк по роли · Кнопки в таблицах · Решения вместо Excel
Учёт заявок и задач с канбан-доской
в интерфейсе
Одна таблица «Заявка» со ссылками на справочники «Статус» и «Исполнитель», сроком и подчинённой таблицей комментариев; колонки канбана — значения справочника статусов.
- Через
_d_schemaсоздайте справочники «Статус» (Новая, В работе, Ждёт клиента, Закрыта — ваш набор) и «Приоритет». - Создайте таблицу «Заявка»: описание (
MEMO), «Статус», «Приоритет», «Исполнитель», «Срок» (DATE), вложение (FILE) и подчинённую таблицу «Комментарий» — это история обращения. - Выдайте роли «Исполнитель» WRITE на «Заявка» и READ на справочники. Свежесозданный справочник по умолчанию не выдан ни одной роли: без гранта выпадающий список будет пустым.
- Добавьте запрос «Просроченные»: колонка «Срок» с фильтром
<[TODAY]и скрытая колонка статуса, исключающая закрытые. - Для заявок с сайта дайте форму или рабочее место гостю (роль
guest) и ограничьте его права записью в «Заявка».
Роль guest работает, только если заведены и пользователь guest, и роль guest; иначе страница уводит на вход, а API отвечает 401.
Подробнее: Гостевой доступ · Синтаксис фильтров · Формы · Дашборды
Склад: приход, расход и остатки
в интерфейсе
Справочник номенклатуры и журнал движений с автором и датой; остаток — это запрос: сумма прихода минус сумма расхода по позиции.
- Создайте справочники «Номенклатура» (единица измерения, артикул, минимальный остаток) и «Склад».
- Создайте таблицу «Движение»: дата (
default: [TODAY]), ссылки на «Номенклатура» и «Склад», «Вид» (приход или расход) и «Количество» (NUMBER). - Постройте запрос «Остатки»: группировка по номенклатуре и складу, колонка с
SUMпо количеству и вычисляемая колонка-формула для итоговой разности прихода и расхода. - Для позиций ниже минимума добавьте отдельный запрос «Дефицит» с фильтром по вычисляемой колонке.
- Дайте кладовщику WRITE на «Движение», бухгалтеру и руководителю — READ на запросы.
- Стартовые остатки и номенклатуру загрузите из Excel импортом.
Сумму по подчинённым и ссылающимся записям (приём «подзапрос») описывает справочник по построению запросов.
Каждое движение — запись с автором и временем внесения, поэтому видно, кто и когда списал материал.
Подробнее: Подзапросы · Связи в запросах · Импорт данных · Складской учёт: готовое решение
Справочник номенклатуры с ценами
в интерфейсе
Номенклатура с группами и единицами — справочник, цены — подчинённая таблица с датой начала действия; прайсы поставщиков загружаются из Excel, а спорные соответствия подбирает шаблон «Сопоставление каталогов».
- Создайте справочники «Группа», «Единица» и таблицу «Номенклатура» (артикул, наименование, ссылки на группу и единицу).
- У «Номенклатуры» добавьте подчинённую таблицу «Цена»: дата начала действия (
DATE), сумма (SIGNED) и ссылка на «Поставщик» — так цены хранят историю. - Постройте запрос «Цены»: колонки позиции, поставщика, даты и суммы; сортировка по дате и фильтр по периоду через
FR_иTO_в адресе. - Загрузите прайс поставщика из Excel или CSV батч-импортом; ссылочные поля в файле указываются по названию.
- Если названия позиций у поставщиков отличаются от ваших, создайте базу из шаблона «Сопоставление каталогов»: спорные пары проверяет человек, решения запоминаются.
Подробнее: Импорт: ссылки по именам · Фильтры FR_ и TO_ · Шаблоны решений · Сопоставление каталогов
Производство: планирование заданий по станкам
для разработчика
Станки, позиции заказов, настройки и слоты-задания лежат в таблицах; планировщик по кнопке расставляет задания между датами «С» и «По», а оператор правит план на диаграмме Ганта.
- Заведите таблицы: «Станок» (с ограничениями: какое сырьё нельзя, какая ширина не бывает), «Позиция заказа» (сырьё, количество, срок изготовления), «Простой станка» (отпуск оборудования) и «Задание» (слот на станке: начало, конец, параметры резки).
- Заведите таблицу «Настройка» с рабочим днём, обедом, перерывами и весами штрафов: приоритеты (срок, переналадки, загрузка) тогда меняются данными, а не кодом.
- Дайте роли «Диспетчер» WRITE на «Задание» и «Простой станка», READ на справочники; технологу — WRITE на «Настройка».
- Подключите рабочее место с диаграммой Ганта: в нём задаются даты «С» и «По», раньше «С» задания не ставятся, а уже стоящие читаются начиная с «С».
- Добавьте кнопку автоматического планирования: она размещает ещё не обеспеченные позиции по станкам и времени, а оператор переставляет или фиксирует задания вручную.
- Для отчёта по цеху постройте запросы: загрузка станка по дням, просроченные задания, число переналадок.
Когда правила конфликтуют, приоритеты в демо-решении «Atex» такие: срок изготовления, затем грязное сырьё в конец дня, затем минимум переналадок, затем равномерная загрузка. Веса настраиваются.
Сам алгоритм планирования и диаграмма Ганта — рабочее место, которое пишется под производство (JS-шаблоны), а не пункт меню конструктора. Таблицы, права и отчёты вокруг него собираются без кода.
Подробнее: Рабочие места и шаблоны · Загрузка шаблонов и скриптов · Производственный учёт: готовое решение
Ввод показателей смены: оператор, мастер, руководитель
в интерфейсе
Цепочка «задание → замес → замер» со справочниками показателей и оборудования; оператор по маске видит свои задания, мастер ведёт простои и закрывает смену, руководитель смотрит дашборд.
- Создайте справочники: «Показатель контроля» (группа, единица, норма минимум и максимум), «Оборудование», «Вид поломки», «Статус задания» (новое, в работе, выполнено).
- Создайте рабочие таблицы цепочкой подчинения: «Задание» с подчинёнными «Замес» и «Простой»; «Замес» с подчинённой «Замер», ссылающейся на «Показатель контроля».
- Заведите роли «Руководитель», «Мастер», «Оператор» и «Наблюдающий» (только чтение того, что видит руководитель). Права опишите блоком
rolesв_d_schema. - Оператору поставьте маску на реквизит «Оператор» таблицы «Задание» со значением
[USER_ID]: чужие задания недоступны вместе с вложенными замесами и замерами. - Добавьте меню по ролям: «Все задания», «Новые», «В работе», «Выполнены» (адрес вида
tasks?status=new), экран «Ввод показаний» для оператора и мастера, «Дашборд» для руководителя. - Постройте отчёты за смену: замеры вне нормы, простои по оборудованию, выполнение заданий; дашборд руководителя собирайте теми же запросами.
Статусы в справочнике стоят под пунктами меню: пункт «В работе» просто открывает список с фильтром по статусу.
Подробнее: Маски · Меню ролей · Схема одним вызовом · Дашборды
Учёт рабочего времени и табель
в интерфейсе
Сотрудник вносит записи «дата, проект, часы» — по маске только свои; сводка по сотрудникам, проектам и месяцам строится запросом с группировкой и выгружается в Excel.
- Создайте справочники «Проект» и «Вид работ» и таблицу «Запись времени»: дата (
default: [TODAY]), ссылки на «Проект» и «Вид работ», часы (NUMBER), комментарий. - Добавьте в «Запись времени» ссылку «Сотрудник» со значением по умолчанию
[USER_ID]: запись закрепляется за тем, кто её внёс. - Роли: «Сотрудник» с WRITE на «Запись времени» и маской по полю «Сотрудник» (
[USER_ID]); «Руководитель» с READ без маски. - Постройте запрос «Часы»: группировка по сотруднику, проекту и периоду, колонка часов с
SUM; период задавайте параметрамиFR_иTO_в адресе. - Для табеля добавьте запрос по дням с фильтром по месяцу и выгрузите результат в Excel.
- Отпуска и больничные заведите как «Вид работ» либо отдельной таблицей и считайте теми же запросами.
Подробнее: Фильтры FR_ и TO_ · Права и фильтры запросов · Отчёты
HR-воронка кандидатов
в интерфейсе
Кандидаты, вакансии и справочник этапов найма; воронка — запрос с числом кандидатов и долей на каждом этапе, доступ к персональным данным ограничивается ролью.
- Создайте справочники «Этап найма» (от первого контакта до выхода на работу — ваш набор), «Источник» и «Вакансия».
- Создайте таблицу «Кандидат»: ФИО, контакты, ссылки на «Вакансия», «Этап найма» и «Источник», резюме (
FILE) и подчинённую таблицу «Контакт» — история собеседований и звонков. - Постройте запрос «Воронка найма»: группировка по этапу и вакансии,
COUNTпо кандидатам; долю этапа считайте вычисляемой колонкой. - Роли «Рекрутер» (WRITE на «Кандидат») и «Руководитель» (READ на запросы). Персональные данные видит только кадровая служба: остальным ролям поле можно закрыть правом BARRED.
- Добавьте напоминание о дате следующего контакта: колонка-кнопка с формулой или триггер при изменении этапа.
Подробнее: Права на таблицы и поля · Триггеры-формулы · Кадровый учёт: готовое решение
Договоры и документы: реестр, сроки, бланк
в интерфейсе
Контрагенты, договоры со сроками и файлами и справочник видов документов; бланк — рабочее место-шаблон, который подставляет данные договора и открывается на печать.
- Создайте справочники «Вид документа» и «Статус договора» и таблицы «Контрагент» и «Договор»: номер, дата, срок действия (
DATE), сумма (SIGNED), ссылки на контрагента, вид и статус, скан (FILE). - Запрос «Истекающие»: договоры, где «Срок» не позже даты через 30 дней; ссылку на него поставьте в меню руководителя.
- Напоминание: внешний планировщик по расписанию вызывает запрос «Истекающие» и рассылает письма через почту приложения (
POST /mydb/_mail, SMTP-ящик вашей компании). - Для бланка создайте HTML-шаблон рабочего места: блок запроса «Договор», в котором плейсхолдеры полей договора; нужный договор выбирает фильтр из адреса, например
/mydb/blank?FR_Номер=15. Изображение печати и подписи положите вdownloadбазы. - Добавьте в таблицу договоров колонку-кнопку «Ссылка» на бланк с подстановкой значения колонки, например
{Номер}. - Входящие и исходящие — отдельная таблица «Документ» с видом и статусом обработки; нумерацию ведёт отдельная колонка-формула.
Бланк — обычная HTML-страница, печатается средствами браузера; встроенного генератора PDF в источниках нет.
Подробнее: Шаблоны: фильтры из адреса · Блок с запросом · Загрузка файлов · Договоры и документы: готовое решение
Закупки: поставщики, заявки и сравнение цен
в интерфейсе
Поставщики, прайсы и заявки на закупку со статусами; сравнение цен — запрос по позиции, а согласование идёт по ролям.
- Создайте таблицы «Поставщик», «Номенклатура», «Прайс» (поставщик, позиция, цена, дата) и «Заявка на закупку» со статусом и подчинённой таблицей позиций.
- Загрузите прайс-листы поставщиков из Excel или CSV батч-импортом.
- Постройте запрос «Сравнение цен»: строка — позиция, колонки — минимальная цена (
MIN) и поставщик; фильтр по позиции передавайте черезFR_. - Роли: «Заказчик» (WRITE на «Заявка на закупку»), «Снабженец» (WRITE на «Прайс» и позиции), «Руководитель» (READ плюс смена статуса «Согласовано»).
- Если прайсы поставщиков разошлись по названиям, подключите массовое сопоставление номенклатуры (шаблон «Сопоставление каталогов»).
Подробнее: Сопоставление каталогов · Импорт данных · Рецепт: согласование по статусам
Согласование по статусам
для разработчика
Статус — ссылка на справочник; кнопка в строке меняет его через _m_set, а менять статус «Согласовано» может только роль согласующего.
- Создайте справочник «Статус» (получен, на согласовании, согласован, оплачен) и таблицу «Счёт» со ссылкой на него, суммой и ответственным.
- Роль «Исполнитель» получает WRITE на «Счёт», но на поле «Статус» — READ; роль «Согласующий» — WRITE на поле «Статус».
- В запросе «Счета на согласовании» добавьте вычисляемую HTML-колонку с кнопкой: ссылка вызывает
post("_m_set/<id записи>?t<id реквизита Статус>=<id статуса>"); идентификаторы берите изmetadata. - Для автоматики добавьте колонку-триггер на событие
UPDATEс условием{Статус} = "Оплачен": действие выполняется только при выполнении условия. - Сводку по статусам и просрочке по срокам оплаты постройте запросом с
COUNTиSUMпо статусу.
Триггеры колонок-кнопок срабатывают на сервере при любом способе записи: таблица, карточка, API или импорт. Цепочка триггеров ограничена глубиной 3.
Подробнее: События триггеров · Триггер-запрос · Изменить запись · Права на поля
Бронирование и расписание
для разработчика
Ресурсы и брони с началом и концом; свободное время показывает запрос по датам, а пересечение ловит колонка-запрос на событие CREATE, которая пишет результат проверки в запись.
- Создайте справочник «Ресурс» (кабинет, станок, сотрудник) и таблицу «Бронь»: «Ресурс», «Начало» и «Конец» (
DATETIME), «Клиент» или «Автор» (default: [USER_ID]). - Постройте запрос «Занятость»: колонки ресурса, начала и конца; период берётся из адреса через
FR_иTO_, ссылку «на сегодня» используйте как готовый срез. - Постройте запрос «Пересечения» с параметрами из строки (ресурс, начало, конец), который считает брони этого ресурса с пересекающимся интервалом.
- В «Бронь» добавьте колонку-кнопку (BUTTON) с действием «Запрос», событием
CREATEи записью результата: после создания в записи появится число конфликтов. - Подсветите брони с конфликтом запросом «Конфликты» и разберите их вручную; запрет на сохранение ядро по такой колонке не накладывает.
Подробнее: Триггер-запрос · Параметры запроса · Фильтры FR_ и TO_
Курсы и доступ к урокам
для разработчика
Курсы, уроки и записи слушателей; роль «Слушатель» читает уроки по маске-запросу, который возвращает только уроки купленных курсов.
- Создайте таблицы «Курс», «Урок» (с подчинением курсу, текст, ссылка на видео, признак «Бесплатный» типа
BOOLEAN) и «Запись на курс» (слушатель, курс, дата оплаты). - Постройте запрос «Мои уроки»: уроки курсов, на которые записан текущий пользователь (фильтр
[USER_ID]по колонке слушателя), плюс бесплатные. - Роль «Слушатель»: READ на «Урок» с маской из запроса, WRITE на свои отметки о прохождении; на «Запись на курс» — только READ.
- Записи на курс ведёт менеджер с ролью WRITE; после оплаты он добавляет запись, и уроки открываются слушателю.
- Публичную витрину (описание курса, бесплатные уроки) отдайте гостю через роль
guest, платные — только слушателю.
Маска роли может быть запросом (@IN([Запрос])); при смене схемы проверяйте, что запрос возвращает id уроков, а не названия.
Подробнее: Маски · Гостевой доступ · Переменные запросов
Портал для клиентов
для разработчика
Внешний клиент — пользователь с ролью «Клиент»: маска по его записи ограничивает строки, меню показывает только нужные страницы, а своя страница собирается шаблоном.
- Свяжите таблицу «Заказ» с «Клиент», а «Клиент» — с системным пользователем (ссылка «Пользователь»).
- Создайте роль «Клиент» с READ на «Заказ» и «Счёт» и WRITE на «Обращение»; скройте внутренние поля правом BARRED.
- Поставьте маску на реквизит «Клиент» таблицы «Заказ» со значением
[USER_ID](если клиент ссылается на пользователя) — чужие строки недоступны. - Заведите пользователей-клиентов и назначьте им роль; меню роли оставьте из двух-трёх пунктов.
- Страницу «Мои заказы» соберите HTML-шаблоном: блок с запросом «Заказы клиента», в запросе — фильтр по пользователю.
- Для заявок с сайта добавьте форму гостю (роль
guest) с записью только в «Обращение».
Подробнее: Шаблоны рабочих мест · Роли и права · Меню ролей · Права доступа
Перенос учёта из Excel в приложение
в интерфейсе
Листы становятся таблицами, повторяющиеся колонки — справочниками и ссылками, формулы — запросами и колонками-формулами; готовую первую версию можно получить автосборкой из присланной таблицы.
- Пришлите таблицу на странице автосборки: ИИ-агент строит структуру, связи, экраны и роли, оператор Интеграма проверяет результат, ссылка на приложение приходит примерно через 45 минут.
- Если собираете сами: для каждого листа создайте таблицу, у каждой колонки выберите тип (текст, число, дата, статус, файл или ссылка).
- Колонки, которые повторяются в разных листах (клиент в заказах, заказ в позициях), вынесите в справочники и ссылки либо подчинённые таблицы.
- Опишите структуру одним вызовом
_d_schemaи загрузите данные батч-импортом: в файле ссылочные поля пишутся по названиям, а не по id. - Итоговые листы и сводные превратите в запросы с группировкой, формулы расчёта — в вычисляемые колонки запроса или колонки-формулы.
- Раздайте роли: кто вносит данные, кто проверяет, кто смотрит итоги; сверьте несколько итогов с прежним Excel.
Повторный импорт тех же данных ведёт себя по правилам импорта; перед массовой загрузкой прочитайте раздел о повторной загрузке в справочнике.
Подробнее: Импорт данных · Схема одним вызовом · Универсальный импорт из Excel · Приложение из Excel
Дашборд руководителя
для разработчика
Каждый показатель — запрос, дашборд собирается из запросов; для финансовой модели есть рабочее место dash со строками по периодам, которое питают два отчёта.
- Для каждого показателя (продажи, расходы, остатки, просрочка) постройте запрос с группировкой по периоду и подразделению.
- Чтобы собрать панели, используйте дашборды на основе запросов: те же запросы питают панели и сводные таблицы.
- Для плана и факта по статьям на периодах заведите финансовую модель: Дэшборд, Лист, Панель, Строка, числа — в отдельной таблице «Значение».
- Проверьте, что отчёты
ДэшбордиДэшборд.ЗначенияЗаПериодсодержат нужные колонки периода: иначе модель молча рисуется пустой. - Роли ограничьте: каждому подразделению его срез маской, руководителю — все данные.
- Если данные лежат в Битрикс24, 1С или Google-таблицах, подтяните их в базу по расписанию и стройте те же запросы.
Подробнее: Дашборды · Отчёты · Кто вызывает запрос · Управленческий учёт: готовое решение
Бот в Telegram поверх базы
для разработчика
Бот — внешний клиент JSON API: у него свой пользователь с узкой ролью, токен $TOKEN, чтение через object/<таблица>/?JSON_OBJ и запись через _m_new; права базы действуют на бота так же, как на человека.
- Заведите в базе пользователя и роль «Бот» с минимальными правами: READ на нужные запросы и WRITE только на таблицу, куда бот пишет.
- Получите токен пользователя и храните его на стороне бота (
$TOKEN); перед записью запросите_xsrfпод тем же токеном. - Чтение: бот вызывает запрос или
object/<таблица>/?JSON_OBJс фильтрамиFR_и разбирает ответ. - Запись: бот отправляет
_m_new/<таблица>с полямиt<id реквизита>(или несколько записей одним_m_batch). - Привяжите Telegram-пользователя к записи сотрудника в таблице, чтобы бот знал, от чьего имени вносить данные.
- Если нужен ИИ вместо ручных команд, подключите MCP-сервер Интеграма: агент получает инструменты отчётов и работает с правами пользователя, от имени которого вызван.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/object/42?JSON_OBJ&FR_Статус=Новая"
Сам бот и его хостинг живут вне Интеграма: платформа даёт API, роли и права; готового пункта «подключить бота» в конструкторе нет.
Подробнее: Токен · Токен XSRF · Пакетная запись · MCP-сервер Интеграма
Письма из приложения: счета, напоминания, отчёты
для разработчика
Приложение шлёт письма через SMTP-ящик вашей компании: админ один раз вносит настройки, дальше письма отправляет вызов POST /mydb/_mail с адресатами, темой и телом.
- Создайте пароль приложения в почте (Яндекс, Mail.ru или Gmail): обычный пароль ящика не подходит.
- Откройте любой вызов
/_mailот администратора базы: служебная таблица «Почта для отправки» создастся сама. - Внесите сервер, порт, логин, пароль приложения, «От кого» и лимит в час через карточку записи
/mydb/edit_obj/<id>. - Выдайте право отправки ролям: READ или WRITE на таблицу «Почта для отправки».
- Вызывайте
_mailиз своего сценария: адресаты (до 10),subject,body; вложение — загруженный файл или файл из реквизита записи (recиreq). - Для рассылок по срокам стройте запрос «Кому напомнить» и запускайте отправку внешним планировщиком.
Лимит по умолчанию — 20 писем в час на базу; 0 запрещает отправку. Результат каждого вызова пишется в журнал почты.
Подробнее: Создать запись · Ссылки и внешний планировщик
Своя типовая база: шаблон для клиентов
для разработчика
Настроенную базу фиксируют шаблоном: сервер сохраняет данные и файлы без пользователей, паролей и токенов; после модерации шаблон выбирают при создании новой базы.
- Настройте эталонную базу: таблицы, запросы, роли, меню и рабочие места.
- В меню файлов базы откройте «Шаблон базы» и задайте имя, название и описание.
- Нажмите «Зафиксировать версию»: версия уходит на модерацию.
- После одобрения в Личном кабинете выберите шаблон при создании базы: «Мои базы данных» — «Создать БД», имя базы, шаблон, «Создать».
- Правки эталона в шаблон сами не попадают: когда готова новая версия, зафиксируйте её снова.
Шаблоны рабочих мест держите в корне папки шаблонов базы: подпапки в шаблон не входят. Базы, созданные раньше, не меняются.
Подробнее: Шаблоны решений · Файлы базы
Структура данных
Таблицы, колонки и их типы, ссылки и справочники, подчинённые таблицы, обязательность, уникальность и значения по умолчанию, порядок и удаление, шаблоны баз: как собрать и поменять модель данных приложения.
Создать таблицу
в интерфейсе
Таблица создаётся в меню «Структура»: вы вводите имя, выбираете тип первой колонки и при необходимости отмечаете её уникальной.
- Откройте меню «Структура».
- Введите имя таблицы в единственном числе: «Клиент», «Заказ», «Задача».
- Выберите тип первой колонки (для названий и номеров — короткая строка).
- Если значения первой колонки не должны повторяться, поставьте признак уникальности.
- Сохраните: таблица появится в списке, и в неё можно добавлять колонки.
Первая колонка таблицы — имя самой записи (номер заказа, название задачи), остальные колонки — её реквизиты.
Повторное создание таблицы с тем же именем и тем же типом дубль не заводит: ядро возвращает уже существующую.
Подробнее: API: создать таблицу · Конструктор информационных систем
Что делать первой колонкой таблицы
в интерфейсе
Первая колонка — собственное имя записи: номер, код, название. Ссылки на другие таблицы выносите в отдельные колонки.
- Придумайте, чем пользователь называет одну запись: «Номер платежа», «Название задачи», «Версия стратегии».
- Сделайте это значение первой колонкой при создании таблицы.
- Ссылки на проект, клиента, исполнителя добавьте отдельными колонками после неё.
- Если собственного имени у записи нет, составьте его из частей, например «Сотрудник + Месяц».
| Неправильно | Правильно |
|---|---|
| Первая колонка «Платёж» — ссылка на клиента | Первая колонка — «Номер платежа», клиент — отдельная колонка |
| Первая колонка — дата | Составное имя («Проект + Дата»): дата сама не уникальна |
| Первая колонка — галка «Да/Нет» | Текстовое имя, а галка — отдельная колонка |
Каждая запись дополнительно имеет внутренний числовой номер. Пользователи обычно работают с первой колонкой, а номер нужен аналитику и разработчику.
Подробнее: API: базовые типы
Добавить колонку в таблицу
в интерфейсе
Колонка добавляется в «Структуре»: в списке реквизитов нужной таблицы выберите существующий термин или «добавить новое» и задайте имя и тип.
- Откройте «Структура» и найдите таблицу.
- В выпадающем списке реквизитов таблицы выберите «добавить новое» (или уже существующий термин, если он подходит).
- Введите название колонки и выберите её базовый тип.
- Если колонка должна выбирать запись из другой таблицы, поставьте галку «ссылка» и выберите таблицу.
- Подтвердите: колонка появится в таблице последней, её можно передвинуть.
Колонка — это термин (имя и базовый тип), подключённый к таблице. Один и тот же термин, например «Сумма» или «Дата», можно подключить к разным таблицам.
# 1) термин колонки, 2) подключить его к таблице 641
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_new?JSON=1" -F "t=3" -F "val=ИНН"
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_req/641?JSON=1" -F "t=642"
Id колонки — поле id из ответа _d_req, а не obj: в записях значение колонки пишется ключом t<id колонки>.
Подробнее: API: добавить колонку
Какой тип выбрать для колонки
в интерфейсе
У каждой колонки один из базовых типов: короткая строка, длинная строка, текст, число, число с дробью, дата, дата и время, галка, файл и несколько служебных.
- Определите, что хранит колонка: название, число, дата, файл?
- Выберите подходящий тип по таблице ниже.
- Если значения должны выбираться из списка, а не вводиться, сделайте колонку ссылкой на справочник, а не текстом.
| Тип | Что хранит |
|---|---|
| SHORT | короткий текст: имена, коды, телефоны |
| CHARS | длинная строка: адреса, ссылки, email |
| MEMO | многострочный текст: описания, комментарии |
| NUMBER | целое число: количество, сумма |
| SIGNED | число с десятичной частью: проценты, коэффициенты |
| DATE | дата |
| DATETIME | дата и время; через API приходит как unix-время в секундах |
| BOOLEAN | галка «да / нет» |
| FILE | файл или вложение |
| PWD | пароль: хранится хешем, на экране показывается «******» |
| HTML | HTML-текст, выводится без экранирования |
| BUTTON | кнопка-действие над записью |
Длину SHORT ядро не проверяет: 127 символов — рекомендация. В списках более длинное значение показывается сокращённым с «...».
Полный список типов конкретной базы отдаёт запрос GET /mydb/basics.
Подробнее: API: базовые типы
Галка «Да / Нет» и состояние «не задано»
в интерфейсе
Колонка типа BOOLEAN хранит три состояния: «да», «нет» и «не задано». Для программ «да» — это 1, «нет» — -1, «не задано» — отсутствие значения.
- Добавьте колонку и выберите базовый тип BOOLEAN.
- В записи отметьте галку — получится «да».
- Снятая галка в интерфейсе и неотмеченное значение выглядят одинаково; различаются они только в данных и фильтрах.
| Состояние | В API при записи | При чтении |
|---|---|---|
| да | 1, true, X | 1 |
| нет | -1, 0, false | -1 |
| не задано | пусто (строка удаляется) | ключа нет |
Если читаете флаг своим кодом, считайте «да» только 1 (и X из интерфейсных шаблонов). Проверка «непусто = да» ошибается на -1.
Фильтр F_<id>=% отбирает «да», F_<id>=!% — «нет» и «не задано» вместе, F_<id>=-1 — только явное «нет».
Выпадающий список из справочника
в интерфейсе
Выпадающий список — это колонка-ссылка на таблицу-справочник: пользователь выбирает существующую запись, а не вводит текст.
- Создайте таблицу-справочник, например «Статус», с уникальной первой колонкой.
- Заполните справочник значениями.
- В «Структуре» откройте таблицу, где нужен список (например «Заказ»), и добавьте реквизит со ссылкой на «Статус».
- Откройте запись: в новой колонке появится выбор из справочника.
- Выдайте ролям доступ к справочнику, иначе список будет пустым.
По справке старого интерфейса: в списке реквизитов выберите «добавить новое», поставьте галку, что это ссылка, и укажите справочник. Если нужная таблица уже есть, найдите её среди реквизитов и создайте на ней ссылку соответствующей кнопкой.
# через API: справочник 644, ссылка на него, колонка в таблице 641
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_ref/644?JSON=1"
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_req/641?JSON=1" -F "t=645"
В _d_req передаётся тип ссылки из ответа _d_ref (поле obj), а не id самой таблицы-справочника. Значение ссылки в записи — id выбранной записи справочника.
Новая таблица не выдана ни одной роли: без доступа записи отвечают 403, а список справочника пуст.
Подробнее: API: колонка-справочник · Связанные таблицы
Создать справочник (статусы, категории, типы)
в интерфейсе
Справочник — обычная таблица с уникальной первой колонкой (название). Его значения потом выбираются в других таблицах ссылкой.
- В «Структуре» создайте таблицу с именем справочника: «Статус», «Категория», «Тип».
- При создании отметьте уникальность первой колонки.
- При необходимости добавьте колонки: «Описание» (MEMO), «Активен» (BOOLEAN).
- Заполните справочник записями.
- Подключите справочник ссылкой в нужных таблицах (см. «Выпадающий список из справочника»).
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_new?JSON=1" -F "t=3" -F "val=Статус" -F "unique=1"
Для справочников всегда включайте уникальность: иначе в нём заведутся дубли, и выбор станет неоднозначным.
Подробнее: API: создать таблицу
Две ссылки на один справочник («Заказчик» и «Плательщик»)
для разработчика
В одной таблице ссылка на конкретный справочник ровно одна: второй _d_req с тем же типом ссылки вернёт уже существующую колонку.
- Проверьте, что вторая роль действительно нужна как выбор из того же справочника.
- Если вторую сторону достаточно хранить текстом, добавьте колонку SHORT («Куда»).
- Если нужен выбор — заведите отдельный справочник под вторую роль.
- Либо ведите две записи-проводки вместо одной («списание» и «приход»).
Тип ссылки определяется таблицей-целью, а _d_req идемпотентен по типу, поэтому дубликат колонки не появится. Пары «Со склада / На склад», «Откуда / Куда», «Заказчик / Плательщик» на один справочник ссылками не выражаются.
Псевдоним (_d_alias) только переименовывает колонку в этой таблице, на количество ссылок он не влияет.
В старой справке help.integram.io описан вариант с двумя ссылками и псевдонимами; в текущем ядре _d_req и _d_schema вторую ссылку на ту же таблицу отклоняют.
Подробнее: API: колонка-справочник
Подчинённая таблица (позиции заказа, встречи клиента)
в интерфейсе
Подчинённая таблица принадлежит записи родителя целиком: позиции заказа, встречи клиента. Она создаётся как обычная таблица и подключается к родителю как реквизит.
- Создайте таблицу-родителя («Заказ») и дочернюю таблицу («Позиция заказа») с собственной первой колонкой.
- Добавьте дочерней таблице хотя бы одну колонку («Количество»): без неё она не регистрируется как табличная часть.
- В «Структуре» добавьте дочернюю таблицу реквизитом родителя — без галки «ссылка».
- Откройте запись родителя: строки дочерней таблицы вводятся внутри неё.
# 700 — Позиция, 690 — Заказ; в t передаётся id дочерней таблицы
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_req/690?JSON=1" -F "t=700"
Записи дочерней таблицы создаются с родителем up=<id записи родителя>. Строки хранятся в порядке добавления, их можно переставлять и удалять.
В метаданных такой реквизит помечен arr_id и не имеет ref. В данных он адресуется ключом t<id дочерней таблицы>.
Подробнее: API: подчинённая таблица · Связанные таблицы
Ссылка или подчинённая таблица: что выбрать
в интерфейсе
Ссылка выбирает одну существующую запись другой таблицы; подчинённая таблица хранит строки, принадлежащие только своему родителю.
- Спросите: может ли эта запись существовать сама по себе и использоваться в других местах? Да — нужна ссылка на справочник («Клиент» у заказа).
- Принадлежит ли запись только одному родителю и теряет смысл без него? Да — подчинённая таблица («Позиция заказа»).
- Реализуйте выбранный вариант; ошибка здесь самая дорогая, схему потом придётся переделывать.
| Ссылка | Подчинённая таблица | |
|---|---|---|
| Смысл | выбор одной записи справочника | строки внутри записи родителя |
| Пример | Заказчик в заказе | Позиции заказа |
t в _d_req | тип ссылки из _d_ref | id дочерней таблицы |
| В метаданных | ref и ref_id | arr_id без ref |
Подробнее: API: метаданные
Иерархия: вложенные подчинённые таблицы
в интерфейсе
Иерархия строится цепочкой подчинённых таблиц: у каждой записи есть родитель, а подчинённая таблица может сама иметь подчинённые.
- Создайте таблицы всех уровней: «Проект», «Этап», «Задача».
- Каждой нижней таблице добавьте хотя бы одну колонку.
- Подключите «Этап» реквизитом к «Проекту», а «Задачу» реквизитом к «Этапу».
- Записи нижнего уровня создавайте с
up— id записи родителя.
Одним описанием это делает _d_schema: подчинённые таблицы пишутся в children родителя, вложенность любая.
{"tables": [
{"name": "Проект", "fields": [{"name": "Бюджет", "type": "NUMBER"}],
"children": [
{"name": "Этап", "fields": [{"name": "Срок", "type": "DATE"}],
"children": [{"name": "Задача", "fields": [{"name": "Часы", "type": "NUMBER"}]}]}]}]}
Иерархия не ускоряет произвольные запросы: вынос аналитического разреза на верхний уровень выгоден только когда в группе много записей (ориентир от 10). Нужен ли он, решает разработчик по замеру.
Подробнее: API: схема одним запросом
Выбор нескольких значений из справочника (мульти-ссылка)
в интерфейсе
У колонки-ссылки включается режим множественного выбора: в одной записи можно указать несколько записей справочника.
- Создайте колонку-ссылку на справочник (см. «Выпадающий список из справочника»).
- Откройте настройки колонки и включите режим множественного выбора.
- Откройте запись и выберите нужные значения.
# включает и выключает режим на колонке 646
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_multi/646?JSON=1"
При создании колонки режим задаётся параметром multiselect у _d_req, а в _d_schema — ключом multi: true поля. В object/<таблица>/?JSON_OBJ&NAMED мульти-ссылка приходит массивом {id, val}; при записи по именам передаётся массив.
Режим предназначен для колонок-ссылок. Если нужны не просто метки, а ещё и атрибуты связи (количество, дата), делайте подчинённую таблицу.
Подробнее: API: колонка-справочник
Запретить дубли в таблице (уникальная первая колонка)
в интерфейсе
Уникальность включается у первой колонки таблицы: повторное значение не создаёт новую запись, а находит существующую.
- Откройте таблицу в «Структуре».
- Отметьте уникальность первой колонки (так же, как при создании таблицы).
- Если в таблице уже есть дубли, сначала удалите или объедините их.
- Проверьте: попытка завести запись с тем же первым значением вернёт «Запись уже существует» и id старой записи.
При загрузке из файла у таблицы с уникальной первой колонкой существующие записи обновляются, а не дублируются.
Для сквозной нумерации создайте первую колонку типа NUMBER с признаком уникальности: ядро само считает 1, 2, 3 и далее.
Уникальность включается по самому наличию параметра unique в _d_new и _d_save, значение не читается. Чтобы таблица была неуникальной, параметр не передавайте вовсе: unique=0 тоже включит уникальность. Снять — _d_save/<id> с t и val без unique.
Подробнее: API: создать таблицу
Составной ключ: уникальна комбинация колонок
для разработчика
Колонки, помеченные как «ключ», вместе образуют ключ уникальности: запись с той же комбинацией значений ядро не создаёт заново.
- Определите колонки, комбинация которых должна быть уникальной (например «Сотрудник» и «Месяц»).
- Пометьте каждую из них как часть ключа в настройках колонки.
- Проверьте создание записи с повторной комбинацией.
# переключает признак «ключ» на колонке 650
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_key/650?JSON=1"
В _d_schema признак задаётся ключом поля key: true; в метаданных он виден как field_attrs.key. Составной ключ соблюдается и при загрузке из файла.
Точное поведение при нарушении ключа в интерфейсе по доступным источникам не подтверждено; проверяйте на тестовой записи.
Подробнее: API: метаданные
Сделать поле обязательным
в интерфейсе
В Редакторе структуры у колонки есть кнопка «!»: когда она горит красным, поле обязательно для заполнения.
- Откройте «Структура» и найдите колонку.
- Нажмите кнопку «!» напротив реквизита: она загорится красным.
- Проверьте: запись без значения в этом поле не сохраняется.
- Чтобы снять обязательность, нажмите «!» ещё раз.
# переключает обязательность колонки 643
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_null/643?JSON=1"
В _d_schema — ключ поля required: true, в метаданных — field_attrs.required.
Кнопка «!» описана по справке старого интерфейса help.integram.io; как проверка выглядит в текущей форме записи, уточняйте на стенде.
Подробнее: API: обязательность и значение по умолчанию
Значение по умолчанию (сегодняшняя дата, текущий пользователь)
в интерфейсе
У колонки есть поле «Значение по умолчанию»: что в него вписано, попадёт в форму новой записи. Допустимы константа или переменные [TODAY] и [USER_ID].
- Откройте «Структура» и найдите колонку.
- Впишите значение в поле «Значение по умолчанию» (для ссылки там выпадающий список справочника).
- Создайте новую запись: колонка уже заполнена, значение можно изменить.
| Значение | Что подставится |
|---|---|
[TODAY] | сегодняшняя дата |
[USER_ID] | текущий пользователь |
| обычный текст или число | это значение |
| запись справочника | для ссылки: выбранное значение, например «Потенциальный» |
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_attrs/650?JSON=1" -F "val=[TODAY]"
Если вычисленный идентификатор не подходит типу реквизита, значение не используется и не сохраняется формой. В _d_schema ключ поля — default.
Подробнее: API: обязательность и значение по умолчанию
Проверка вводимых данных: что умеет структура
в интерфейсе
Средства проверки на уровне структуры: правильный тип колонки, обязательность, уникальность, составной ключ и выбор из справочника. Масок ввода и регулярных выражений в структуре ядро не предоставляет.
- Выберите тип, который сам отсекает лишнее: число — NUMBER или SIGNED, дата — DATE, да/нет — BOOLEAN.
- Если значение должно быть из фиксированного набора, сделайте колонку ссылкой на справочник, а не текстом.
- Обязательность задайте кнопкой «!», неповторяемость — уникальностью или ключом.
- Для более сложной проверки используйте триггеры колонок-кнопок или свой экран рабочего места.
Маски в Интеграме относятся к правам ролей (какие строки видит роль), а не к формату ввода. Длину SHORT ядро не проверяет.
Триггер колонки-кнопки срабатывает на сервере после создания, изменения или удаления записи, поэтому корректирует и дополняет данные, но не отменяет запись.
Подробнее: Триггеры: когда срабатывают · Маски в правах ролей
Редактор структуры: где смотреть и менять схему
в интерфейсе
Редактор структуры (меню «Структура») показывает таблицы в порядке связанности и позволяет создавать, менять и удалять таблицы и колонки.
- Откройте меню «Структура».
- Найдите таблицу: каждая встречается один раз, в иерархии — при первом упоминании как реквизит.
- Наведите курсор на таблицу или реквизит — стрелки покажут их связи с другими таблицами.
- Меняйте схему: добавляйте колонки, ссылки, подчинённые таблицы, переставляйте и удаляйте.
- Если пункта нет, роли не выдан доступ к редактору структуры (служебный объект
typesв правах роли).
Часть системных таблиц (Пользователь, Роль, Запрос и др.) тоже видна в редакторе: платформа во многом собрана средствами самого Интеграма.
Системные таблицы и их реквизиты удалять нельзя: система опирается на них.
Карту всей базы в машинном виде отдаёт GET /mydb/metadata?JSON=1, список таблиц — GET /mydb/dict?JSON=1.
Подробнее: API: метаданные · Права ролей
Поменять порядок колонок
в интерфейсе
Порядок реквизитов в «Структуре» определяет порядок колонок во всех таблицах и формах: колонку можно сдвинуть вверх на одну позицию или поставить на нужное место.
- Откройте «Структура» и найдите колонку.
- Нажмите «^» напротив реквизита: он сместится на одну позицию выше.
- Повторяйте, пока колонка не окажется на своём месте.
- Откройте таблицу данных: колонки идут в новом порядке.
# колонка 648 на первую позицию среди реквизитов
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_ord/648?JSON=1" -F "order=1"
# на одну позицию выше
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_up/648?JSON=1"
Первую колонку (имя записи) двигать нельзя.
Подробнее: API: переместить и удалить
Переименовать таблицу или колонку
для разработчика
Таблицу и сам тип колонки переименовывает _d_save; имя колонки только в одной таблице задаёт _d_alias (псевдоним). Для таблицы _d_alias не использовать.
- Чтобы переименовать таблицу:
_d_save/<id таблицы>с новым именемvalи базовым типом первой колонкиt. - Чтобы переименовать тип колонки во всех таблицах:
_d_save/<orig>сvalиt, гдеorig— полеorigреквизита из метаданных. - Чтобы изменить подпись колонки только в одной таблице:
_d_alias/<id колонки>с новымval. - Проверьте
metadata?JSON=1: имя изменилось там, где ожидалось.
# таблица 641: новое имя, первая колонка — SHORT (t=3)
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_save/641?JSON" -F "val=Покупатель" -F "t=3"
# подпись колонки 648 только в этой таблице
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_alias/648?JSON=1" -F "val=Исполнитель"
Для _d_save колонки берите orig из метаданных, а не id реквизита. Если вызвать _d_alias на id таблицы, имя таблицы превратится в JSON-текст; исправляется _d_save/<id таблицы>. Двоеточие в псевдониме недопустимо.
Подробнее: API: переименовать, переместить, удалить
Задать колонке своё название (псевдоним)
в интерфейсе
Псевдоним — имя колонки в конкретной таблице: тип «Дата» может называться «Дата прихода» в одной таблице и «Дата отгрузки» в другой.
- Откройте «Структура» и найдите колонку в нужной таблице.
- Задайте псевдоним в настройках колонки.
- Проверьте: в других таблицах название не изменилось.
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_alias/648?JSON=1" -F "val=Дата прихода"
В метаданных val реквизита — имя типа, а псевдоним лежит в attrs.alias и field_attrs.alias. Ищите колонку и по val, и по псевдониму.
Подробнее: API: метаданные
Удалить колонку
в интерфейсе
Колонка удаляется знаком «X» напротив реквизита в «Структуре». Если в ней есть данные, их удаление безвозвратно, поэтому сначала сохраните значения.
- Выгрузите значения колонки, если они могут понадобиться.
- Откройте «Структура» и нажмите «X» напротив реквизита.
- Если в колонке есть данные, ядро откажет и сообщит число записей; подтвердите удаление вместе с данными.
- Проверьте, что колонка исчезла из таблицы и форм.
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_del_req/643?JSON=1" -F "forced=1"
Принудительное удаление стирает значения колонки у всех записей и снимает права ролей на эту колонку. Сам термин колонки остаётся и может использоваться в других таблицах.
Подчинённую таблицу, у которой есть записи, сначала очистите: записи, затем реквизиты, затем тип. Перед необратимыми операциями делайте полный бэкап базы.
Подробнее: API: удалить колонку
Удалить таблицу
для разработчика
Таблицу можно удалить, когда нет её записей и ссылок на неё. Порядок: записи, ссылки из других таблиц, права ролей и колонки отчётов, затем сама таблица.
- Удалите записи таблицы и её подчинённых таблиц.
- Удалите колонки-ссылки на эту таблицу в других таблицах (
_d_del_req,forced=1). - Если на таблицу когда-то ссылались, удалите тип ссылки: его id — поле
referencedвGET /mydb/metadata?JSON=1(метаданные всей базы; вmetadata/<id>его нет). - Снимите права ролей на таблицу и колонки отчётов, где она использована.
- Вызовите
_d_del/<id таблицы>и проверьте, чтоobject/<id>/?JSON_METAотвечает «не найден».
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/mydb/_d_del/642?JSON=1"
Сообщение «Нельзя удалить тип при наличии экземпляров (всего: 1)» у пустой таблицы — это остаток типа ссылки: удалите его по referenced. Если тип или его реквизиты ещё используются в отчётах или ролях, ядро ответит ссылкой на них.
Сначала сделайте полный бэкап базы: удаление необратимо.
Подробнее: API: удалить таблицу
Описать всю структуру одним запросом (_d_schema)
для разработчика
_d_schema принимает описание таблиц, полей, ссылок, подчинённых таблиц, ролей и отчётов по именам и создаёт недостающее; повторный вызов того же описания ничего не дублирует.
- Опишите таблицы в JSON:
name,unique,fields[], подчинённые — вchildren[]. - В полях укажите
type, для ссылки —refс именем таблицы-цели, а такжеmulti,required,key,default. - Отправьте
POST /mydb/_d_schema?JSONполемjsonили теломapplication/json. - В ответе возьмите id таблиц и полей: это ключи
t<id>и фильтрыF_<id>. - Исправляйте описание и повторяйте вызов: существующее находится по имени.
curl -s -H "X-Authorization: $TOKEN" -H "Content-Type: application/json" "https://ideav.ru/mydb/_d_schema?JSON" -d '{"_xsrf":"'$XSRF'","tables":[
{"name":"Компания","unique":true,"fields":[{"name":"ИНН"},{"name":"Лимит","type":"NUMBER"}]},
{"name":"Заявка","fields":[{"name":"Компания","ref":"Компания","required":true}],
"children":[{"name":"Позиция заявки","fields":[{"name":"Кол-во","type":"NUMBER"}]}]}]}'
- Типы:
SHORT,CHARS,MEMO,NUMBER,SIGNED,DATE,DATETIME,BOOLEAN,FILE; допустимы синонимыSTRING,TEXT,INT,DECIMAL,FLOAT,MONEY,BOOL. - У существующего поля меняются только флаги
required,multi,key,default; тип термина и цель ссылки не меняются. - Ошибки описания проверяются до записи: ответ
400 {"ok":false,"errors":[…]}, база не меняется.
Имя термина одно на всю базу: поле «Лимит» в любой таблице — один термин с одним типом. Другой тип под тем же именем даёт ошибку 400: уберите type, задайте тип существующего термина или назовите иначе. Поле, названное как существующая таблица, станет подчинённой таблицей; для ссылки пишите ref.
Подробнее: API: схема одним запросом · ИИ-агент собирает приложение
Прочитать структуру базы (метаданные)
для разработчика
metadata описывает всю базу или одну таблицу: колонки, типы, ссылки, подчинённые таблицы и флаги field_attrs. Отсюда берутся id колонок для t<id>.
- Вызовите
GET /mydb/metadata?JSON=1для всей базы илиGET /mydb/metadata/<id или имя>?JSON=1для одной таблицы. - Для каждого
reqs[i]посмотритеid(ключt<id>),val(имя типа),type(базовый тип),orig(id типа). - Определите вид колонки: есть
refиref_id— ссылка; естьarr_idбезref— подчинённая таблица; иначе обычная колонка. - Флаги колонки читайте из
field_attrs:required,multi,key,alias,default.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/metadata/18?JSON=1"
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/dict?JSON=1" # список таблиц
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/basics" # типы базы
У пользователя с ограниченной ролью закрытые объекты в метаданных не приходят. Поле referenced есть только в метаданных всей базы.
Подробнее: API: метаданные
Заменить текстовое поле справочником
для разработчика
Колонку нельзя превратить в ссылку «на месте»: создаётся справочник, колонка заменяется ссылкой, значения переносятся.
- Сохраните значения старой колонки (выгрузка или запрос).
- Создайте справочник с уникальной первой колонкой и наполните его уникальными значениями.
- Создайте ссылку на справочник (
_d_ref) и удалите старую колонку (_d_del_req). - Добавьте колонку-ссылку (
_d_reqс типом из_d_ref) и при необходимости задайте ей имя (_d_alias). - Восстановите значения как ссылки:
_m_setсt<новая колонка>=<id записи справочника>. - Выдайте ролям READ на новый справочник.
Перед удалением колонки убедитесь, что значения сохранены: удаление безвозвратно. При записи по именам ссылку можно передавать и главным значением справочника, если запись находится однозначно.
Подробнее: API: колонка-справочник · API: изменить запись
Как спроектировать таблицу: правила и шаблоны
в интерфейсе
Первая колонка — собственное имя записи, ссылки — отдельные колонки, имена русские и в единственном числе, справочники уникальны.
- Назовите таблицу существительным в единственном числе: «Пользователь», а не «Пользователи».
- Выберите первую колонку — собственное имя записи, не ссылку.
- Вынесите связи в отдельные колонки-ссылки.
- Для списков значений заведите справочники с уникальным названием.
- Повторяющиеся строки внутри записи оформите подчинённой таблицей.
| Вид таблицы | Первая колонка | Типичные колонки |
|---|---|---|
| Справочник (Статус, Категория) | уникальное название | описание, признак «Активен» |
| Документ (Платёж, Заказ, Акт) | уникальный номер | дата, ссылка на основной объект, сумма, статус |
| Задача (Задача, Инцидент) | краткое описание | проект, исполнитель, срок, статус |
| Версия (Стратегия, Договор) | номер версии | основной объект, ссылка на файл, статус версии |
Время и расписание оформляйте колонкой DATE или DATETIME, а не текстом: такие значения доступны фильтрам по диапазону.
Подробнее: База знаний: проектирование
Системные таблицы: Пользователь, Роль и другие
в интерфейсе
В каждой базе уже есть «Пользователь», «Роль», «Запрос» и другие служебные таблицы. Их можно дополнять своими колонками, но не удалять.
- Откройте «Структура» и найдите «Пользователь» или «Роль».
- Добавьте нужную колонку так же, как в обычную таблицу (например «Должность»).
- Выдайте доступ ролям, которые будут её видеть.
- Не удаляйте штатные таблицы и их реквизиты.
Первая колонка «Пользователя» — логин, дальше роль (ссылка на «Роль»), email, телефон, имя, фото, дата регистрации и признак активности. У «Роли» первая колонка — название, затем описание.
Платформа опирается на эти таблицы. Категорически не рекомендуется удалять штатные термины или их реквизиты.
Подробнее: API: системные таблицы
Создать базу из готового шаблона
в интерфейсе
При создании базы в Личном кабинете выбирается шаблон: новая база создаётся как копия данных и файлов одобренного шаблона.
- Откройте Личный кабинет и начните создание базы.
- Задайте имя базы и выберите нужный шаблон в списке «Шаблон».
- Нажмите «Создать»: база открывается со всем содержимым шаблона.
- Откройте «Структура» и проверьте таблицы; владельцу новой базы назначается роль admin.
Шаблон — копия на момент фиксации, а не подписка: обновления шаблона в уже созданные базы не приходят.
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" "https://ideav.ru/my/_new_db/?JSON&db=newdb&template=<id шаблона>"
Подробнее: Шаблоны решений
Сделать шаблон из своей базы
для разработчика
Любая база может стать шаблоном: в меню файлов «Шаблон базы» задаётся имя шаблона и нажимается «Зафиксировать версию»; после модерации шаблон доступен в Личном кабинете.
- В меню файлов базы откройте «Шаблон базы».
- Задайте имя (латиница и цифры, от 2 до 15 символов, начинается с буквы), название и описание.
- Нажмите «Зафиксировать версию»: сервер снимает копию данных и файлов.
- Дождитесь решения модератора: версия получает статус «одобрена» или «отклонена».
- Для обновления зафиксируйте новую версию; неудачную можно снять.
- В копию не попадают пользователи, пароли и токены.
- Правки исходной базы после фиксации в шаблон не попадают.
- Файлы подпапок
templates/custom/<база>в шаблон не входят: держите шаблоны рабочих мест в корне папки. - Фиксирует версию владелец базы; системные имена — только администратор сервера.
Подробнее: Шаблоны решений
Работа с данными
Ввод и правка записей, поиск и фильтры, сортировка, файлы, выгрузка в Excel, импорт, перенос между базами, журнал изменений и очистка дублей.
Создать запись и изменить её в форме
в интерфейсе
Запись правится в модальной форме: нажмите на первую колонку строки или на карандаш в ячейке, измените поля и сохраните. Новая запись создаётся кнопкой добавления над таблицей.
- Откройте таблицу в меню «Таблицы» или на рабочем месте.
- Чтобы изменить запись, нажмите на её первую колонку (в таблице-компоненте — на иконку карандаша, она появляется при наведении на ячейку).
- Измените значения в форме: текст, число, дата, галка, значение из справочника, файл.
- Нажмите «Сохранить» — таблица обновится сама. «Отменить» закрывает форму без изменений.
- Чтобы создать запись, нажмите кнопку добавления над таблицей, заполните форму и сохраните.
Поле даты открывает календарь, поле даты-времени — календарь со временем (шаг 5 минут). В новой записи первая колонка типа дата или дата-время заполняется текущим значением; остальные даты остаются пустыми.
Пустые поля новой записи на сервер не отправляются — поэтому подставляются значения по умолчанию из структуры.
Подробнее: API: создать запись · API: изменить запись
Править значение прямо в ячейке таблицы
в интерфейсе
Наведите на ячейку, нажмите карандаш, введите значение и нажмите Enter или щёлкните вне ячейки. Tab и стрелки переходят к соседним ячейкам.
- Наведите курсор на редактируемую ячейку — появится карандаш.
- Нажмите на карандаш: ячейка станет полем ввода, списком или галкой в зависимости от типа колонки.
- Введите новое значение.
- Сохраните: Enter или щелчок вне ячейки. Escape отменяет правку.
| Клавиша | Действие |
|---|---|
| Tab / Shift+Tab | К следующей / предыдущей редактируемой ячейке, с сохранением |
| Стрелка вверх / вниз | К ячейке выше / ниже в той же колонке |
| Escape | Отменить правку |
Обязательные поля и значения по умолчанию
в интерфейсе
Обязательность и значение по умолчанию задаются у колонки в редакторе структуры; форма не даст сохранить пустое обязательное поле и подставит значение в новую запись.
- Откройте «Структура» и нужную таблицу.
- Напротив колонки нажмите кнопку со знаком «!» — она загорится красным: поле обязательное.
- В поле «Значение по умолчанию» впишите значение; у справочной колонки выберите его из списка.
- Сохраните настройку колонки кнопкой «Сохранить» или Enter.
- Создайте запись: значение по умолчанию уже стоит в форме и его можно поменять.
В «Значении по умолчанию» работают служебные слова, например [TODAY]. При сохранении с пустым обязательным полем форма выводит предупреждение и остаётся открытой.
Для API обязательность по умолчанию не проверяется: _m_new создаст запись и без обязательных полей. Чтобы получить отказ 400, добавьте в запрос strict=1.
curl -s -X POST -H "X-Authorization: $TOKEN" -d "_xsrf=$XSRF&up=1&t641=Клиент" "https://ideav.ru/mydb/_m_new/641?JSON=1&strict=1"
Подробнее: API: создать запись
Выбрать значение из справочника, найти его в длинном списке
в интерфейсе
В форме начните вводить текст в поле справочника — список отфильтруется по любой части названия. Если у вас есть право создавать записи справочника, рядом доступна кнопка «+».
- Откройте форму записи и поставьте курсор в справочное поле.
- Введите часть названия — список отфильтруется без учёта регистра.
- Выберите нужный вариант.
- Если значения нет и вам разрешено создавать записи справочника, нажмите «+» слева от списка и задайте новое значение — оно добавится при сохранении формы.
В старом интерфейсе, если в списке больше 80 записей, показываются первые 80 — тогда используйте поле поиска справа от списка и нажмите Enter. Чтобы искать по другой колонке справочника, разделяйте маски слэшем: /%red% ищет «red» во второй колонке.
Колонке с множественным выбором в API передают id записей через запятую: t648=616,617.
Подробнее: API: ссылочные поля
Скрыть лишние поля в форме записи
в интерфейсе
Шестерёнка в левом нижнем углу формы открывает список полей: снимите галки с ненужных и сохраните. Настройка действует для каждого типа записи отдельно.
- Откройте форму записи.
- Нажмите шестерёнку в нижнем левом углу формы.
- Отметьте поля, которые должны отображаться.
- Нажмите «Сохранить» — форма перерисуется без скрытых полей.
Скрытые поля не участвуют в проверке обязательности. Настройка хранится в cookies браузера (1 год), поэтому на другом компьютере или в другом браузере её придётся повторить.
Добавить записи в подчинённую таблицу (позиции, встречи, телефоны)
в интерфейсе
Подчинённые таблицы открываются вкладками в форме записи; на вкладке есть кнопка «Добавить», запись создаётся уже привязанной к родителю.
- Откройте запись-родителя (например, заказ).
- Перейдите на вкладку подчинённой таблицы — в её названии указано число записей, например «Позиции (5)».
- Нажмите «Добавить», заполните форму и сохраните.
- Чтобы изменить или удалить подчинённую запись, нажмите на её первую колонку и работайте в её форме.
Записи подчинённой таблицы хранятся в порядке добавления; в старой форме порядок меняют значком «^» (вверх на одну позицию). Если у подчинённой таблицы есть свои подчинённые, во вложенном списке показывается только число записей.
По API запись создаётся с up=<id записи-родителя>; без фильтра F_U сервер подчинённую таблицу отдаёт пустой.
Подробнее: API: чтение записей и F_U
Скопировать запись вместе с вложенными данными
в интерфейсе
Откройте запись, при необходимости поправьте поля и нажмите «Дублировать»: создастся копия со всеми реквизитами, включая подчинённые таблицы. Исходная запись не меняется.
- Откройте запись в форме редактирования.
- При необходимости измените значения, которые должны отличаться в копии.
- Нажмите «Дублировать».
- Найдите копию в таблице и проверьте её.
Копия записи в пакет _m_batch не входит; для неё используется одиночный _m_save с флагом copybtn.
Удалить запись и что делать, если не удаляется
в интерфейсе
Нажмите «Удалить» в форме записи и подтвердите. Подчинённые записи удаляются вместе с родителем; запись, на которую ссылаются другие, система удалять не даст.
- Откройте запись.
- Нажмите «Удалить» (в таблице-компоненте кнопка в форме скрыта по умолчанию — включите «Показывать кнопку Удалить» в шестерёнке формы).
- Подтвердите удаление.
- Если появилось предупреждение о ссылках, сначала переназначьте или удалите записи, которые ссылаются на эту.
По API _m_del при ссылках отвечает 409. Права на удаление настраиваются в роли: можно отдельно разрешить или запретить удаление и экспорт для структуры данных.
curl -s -X POST -H "X-Authorization: $TOKEN" -d "_xsrf=$XSRF" "https://ideav.ru/mydb/_m_del/668?JSON=1"
Подробнее: API: удалить и переместить
Удалить сразу много записей
в интерфейсе
В таблице-компоненте включите колонку чекбоксов, отметьте строки и нажмите красную кнопку «Удалить». Через API — _m_del_batch (до 10 000 id) или удаление по фильтру.
- Нажмите иконку чекбоксов рядом с иконкой настроек — слева появится колонка с галками.
- Отметьте нужные строки; галка в заголовке выбирает все строки.
- Нажмите красную кнопку «Удалить» и подтвердите.
- Если часть записей не удалилась, диалог покажет ошибки в виде «id : первая колонка : ответ».
Фильтрами заранее отберите то, что нужно удалить, и проверьте отбор глазами: удаление необратимо. Доступ к массовому удалению и экспорту настраивается в роли.
# несколько записей одной таблицы
curl -s -X POST -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "ids=668,669,670" "https://ideav.ru/mydb/_m_del_batch/641?JSON=1"
# все записи под фильтром
curl -s -X POST -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "_m_del_select=1" "https://ideav.ru/mydb/object/641/?JSON=1&F_646=650"
Подробнее: API: удалить и переместить
Галка «да / нет / не задано»
для разработчика
У поля BOOLEAN три состояния: да (1), нет (-1) и не задано (значения нет). В интерфейсе «нет» и «не задано» выглядят одинаково — галка снята.
- Чтобы поставить галку через API, передайте
t{id}=1,trueилиX. - Чтобы явно поставить «нет» —
-1,0илиfalse. - Чтобы вернуть «не задано» — пустое значение
t{id}=. - Для выборки используйте фильтры ниже.
| Фильтр | Отбирает |
|---|---|
F_{id}=% | только «да» |
F_{id}=!% | «нет» и «не задано» вместе |
F_{id}=-1 | только явное «нет» |
Читая значение, клиент получает 1, -1 или null. Поле, которого нет в запросе, не меняется.
Подробнее: API: изменить запись
Перенести подчинённую запись к другому родителю
для разработчика
Команда _m_move/{id записи} с параметром up={id нового родителя} делает запись последней у нового родителя; порядок у старого пересчитывается сам.
- Определите id переносимой записи и id новой родительской записи (не таблицы).
- Вызовите
_m_moveметодом POST с токеном и_xsrf. - Проверьте результат запросом
object/{таблица}/?JSON_OBJ&F_U={id нового родителя}.
curl -s -X POST -H "X-Authorization: $TOKEN" -d "_xsrf=$XSRF" "https://ideav.ru/mydb/_m_move/705?JSON=1&up=692"
Сервер проверяет права и на переносимую запись, и на нового родителя. Если тип родителя другой, у него должен быть реквизит этой подчинённой таблицы.
Подробнее: API: удалить и переместить
Найти записи в таблице фильтром
в интерфейсе
Поля фильтров открываются нажатием на шапку таблицы или на воронку над ней. Введите значение — фильтр применится сам; регистр букв не важен.
- Нажмите иконку воронки над таблицей (или шапку таблицы) — под названиями колонок появятся поля фильтров.
- Введите значение в поле нужной колонки; в таблице-компоненте фильтр срабатывает через полсекунды после ввода.
- Чтобы выбрать способ сравнения, нажмите иконку типа фильтра слева в поле: «начинается», «равно», «содержит» и т.д.
- Для нескольких условий заполните несколько колонок — они действуют вместе.
- Нажмите круглую кнопку с крестиком, чтобы сбросить все фильтры.
По умолчанию в старой таблице показываются первые 20 записей — для остальных используйте фильтры или листание.
Способы сравнения и служебные символы: «Служебные символы поиска» (%, !, диапазоны).
Подробнее: Язык условий фильтра
Служебные символы поиска: %, !, диапазон
в интерфейсе
Знак % означает «любое количество символов», ! в начале — отрицание, .. — диапазон. Одиночное % — «непусто», !% — «пусто».
- Откройте фильтр нужной колонки (воронка над таблицей).
- Введите условие по таблице ниже.
- Для «содержит»/«не содержит» можно выбрать способ сравнения иконкой в поле вместо символов.
| Что ввести | Что найдётся |
|---|---|
Кри% | начинается на «Кри» (найдёт «Криворучко», «кривой») |
%4041 | заканчивается на 4041 |
%подар% | содержит «подар» (подарок, подарочная…) |
Василий | точное совпадение |
!Василий | не равно |
!%подар% | не содержит, включая пустые значения |
% | значение не пустое |
!% | значение пустое |
4000..5000 | число в диапазоне, границы включены (по числам и датам) |
>100, <=20002 | больше, не больше |
IN(a,b) | одно из перечисленных значений |
Условия «пусто» и «не пусто» применяются мгновенно, без задержки, а текст в поле очищается.
Маска с % в начале строки (%Иванов) не использует индекс и на больших таблицах медленнее.
Подробнее: Язык условий фильтра
Фильтр по дате: сегодня, вчера, период
в интерфейсе
В фильтре дат можно писать дату или служебное слово в квадратных скобках: [TODAY], [YESTERDAY], [MONTH_AGO]. Период задаётся диапазоном «от и до».
- Откройте фильтр колонки с датой.
- Выберите способ сравнения («=», «≥», «≤», «...» — диапазон); для первых четырёх поле станет календарём.
- Введите дату или слово: например
[TODAY]для «сегодня». - Для периода выберите «...» и задайте обе границы.
| Слово | Значение |
|---|---|
[TODAY] | сегодня |
[NOW] | текущие дата и время |
[YESTERDAY] | вчера |
[TOMORROW] | завтра |
[MONTH_AGO] | день месяц назад |
[MONTH_PLUS] | день через месяц |
[USER], [USER_ID] | имя и id вошедшего пользователя |
Сокращённый ввод: 12 — 12-е число текущего месяца, 12.6 — 12 июня текущего года, 12.12.21 — год в текущем веке (для другого века пишите год целиком). Разделители даты — ., , или /.
Подробнее: Запросы: переменные
Фильтры и страницы в адресе запроса (F_, FR_, LIMIT)
для разработчика
Команда object/{таблица}/?JSON_OBJ принимает F_{колонка} для фильтра, FR_/TO_ для диапазона, ORDER для сортировки, LIMIT и pg для страниц.
- Определите id таблицы и колонок:
GET /{db}/metadata/{id таблицы}?JSON=1. - Добавьте фильтр
F_{id колонки}=значение; для первой колонки ключ — id самой таблицы. - Добавьте
ORDER,LIMIT— и получите страницу. - Для подсчёта вызовите с
_count=.
| Параметр | Смысл |
|---|---|
F_{id колонки}=… | фильтр; значение понимает %, !, .., IN() |
FR_{id}=…&TO_{id}=… | от и до |
F_U={id родителя} | записи подчинённой таблицы |
ORDER={id} / ORDER=-{id} | сортировка по возрастанию / убыванию |
LIMIT=100, LIMIT=100,100 | первые 100 / 100 записей, начиная со 101-й |
_count= | только число записей |
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/object/641/?JSON_OBJ&F_641=%25Ромашка%25&ORDER=-643&LIMIT=100"
Простое значение фильтра по справочной колонке сравнивается с названием записи, а не с её id; для фильтра по id используйте запись @660.
Подробнее: API: прочитать записи
Отсортировать таблицу
в интерфейсе
Нажмите на название колонки: первый клик — по возрастанию (▲), второй — по убыванию (▼), третий снимает сортировку.
- Нажмите на текст заголовка нужной колонки (не на ячейку).
- Повторный клик меняет направление, третий — отключает сортировку.
- Клик по другой колонке переключает сортировку на неё.
В запросе API сортировка — параметр ORDER={id колонки}, по убыванию ORDER=-{id}.
Подробнее: Запросы: сортировка и LIMIT
Сгруппировать записи по полям
в интерфейсе
Кнопка «Группы» слева от «Фильтры» позволяет выбрать одно или несколько полей: значения сольются в объединённые ячейки.
- Нажмите «Группы».
- Отметьте поля группировки: первое — основная группа, второе — подгруппа.
- Нажмите «Применить».
- Чтобы вернуться к обычному виду, нажмите крестик рядом с кнопкой «Группы».
В режиме группировки запрашивается до 1000 записей, а бесконечная прокрутка отключена. По полям группировки можно ставить фильтры.
Отправить коллеге ссылку на таблицу с моими фильтрами
в интерфейсе
Настройте фильтры, группировку и сортировку — слева от «Групп» появится кнопка копирования ссылки. Коллега, открыв её, увидит те же настройки.
- Задайте нужные фильтры, группировку или сортировку.
- Нажмите кнопку копирования ссылки (📋) слева от «Группы».
- Отправьте скопированный адрес коллеге.
Настройки закодированы в параметре адреса _itc; он нужен только браузеру и в запросы к API не передаётся.
Настроить вид таблицы: колонки, размер страницы, отступы
в интерфейсе
Кнопка «⚙️ Настройка» меняет отступы, размер страницы и сокращение длинных текстов; порядок, видимость и ширину колонок задают в окне колонок и перетаскиванием.
- Нажмите «⚙️ Настройка» в заголовке таблицы.
- Выберите отступы: «Просторно» или «Компактно».
- Задайте размер страницы: 10, 20, 30, 50, 100 или своё число.
- Включите или выключите сокращение значений длиннее 127 символов; полный текст открывается по ссылке «...».
- Чтобы вернуть всё как было, нажмите «Сбросить настройки».
Порядок, видимость и ширины колонок, размер страницы и режим отступов запоминаются в cookies браузера на год, то есть для каждого пользователя и браузера отдельно.
Прикрепить файл или картинку к записи
в интерфейсе
Для файлов в таблице нужна колонка базового типа FILE. В форме записи файл загружается в это поле (поддерживается перетаскивание), в таблице он показывается ссылкой.
- Убедитесь, что в структуре таблицы есть колонка типа FILE (если нет — добавьте реквизит этого типа в «Структуре»).
- Откройте форму записи и перетащите файл на поле или выберите его в диалоге выбора файла.
- Нажмите «Сохранить».
- В таблице нажмите на ссылку с именем файла, чтобы скачать или открыть его.
Файл, загруженный через форму записи, попадает в защищённую папку с зашифрованным именем (см. «Где хранятся файлы»). Картинки и документы в записях относятся к одному типу FILE.
Подробнее: Базовые типы колонок
Где хранятся загруженные файлы и как их достать
для разработчика
Файлы колонок FILE лежат в download/<база>/<папка>/<файл> с зашифрованными именами. Их видит администратор в файловом менеджере dir_admin.
- Откройте меню «Файлы» (файловый менеджер
dir_admin; нужно право на объект «Файлы»). - Выберите каталог
downloadи перейдите в папку с цифровым именем. - Зная системный идентификатор файла, найдите его визуально: имя файла — последние 3 цифры id плюс шифр из 8 символов, папка — остальные цифры id плюс шифр.
- Скачайте файл или загрузите новую версию поверх существующей.
В каждой папке не больше 1000 файлов. Имена зашифрованы с использованием имени базы.
При раздаче всё, кроме растровых картинок, отдаётся как скачивание (Content-Disposition: attachment), а html, svg, xml — ещё и в песочнице. Это защитная мера, а не ошибка.
Хранение в зашифрованных папках — только для файлов, загруженных через форму записи. Файл, загруженный администратором через меню «Файлы», лежит как есть.
Подробнее: API: файловый менеджер
Выгрузить таблицу в Excel или CSV
в интерфейсе
Кнопка экспорта (📥) в панели таблицы скачивает данные в XLSX, XLS или CSV. Выгружается всё, что подходит под текущие фильтры, а не только видимые строки.
- Установите фильтры и сортировку так, как нужно в файле.
- Скройте ненужные колонки и расставьте остальные в нужном порядке.
- Нажмите кнопку экспорта (📥) в панели управления.
- Выберите формат: XLSX, XLS (Excel 97–2003) или CSV — файл скачается.
- выгружаются все записи (до 1 000 000), а не только загруженная страница;
- применяются текущие фильтры и сортировка;
- выгружаются только видимые колонки в текущем порядке.
Нет кнопки экспорта — у роли нет права на экспорт этой таблицы: администратор настраивает его в роли.
Выгрузить таблицу вместе со структурой (BKI или JSON)
в интерфейсе
Кнопки «Экспорт BKI» и «Экспорт JSON» на панели таблицы скачивают её колонки, типы, ссылки и записи одним файлом. Применяются текущие фильтры и сортировка.
- Откройте таблицу и, если нужна часть записей, отфильтруйте её.
- Нажмите «Экспорт JSON» (читаемый файл, значения без экранирования) или «Экспорт BKI» (построчный текст).
- Сохраните скачанный файл —
data_export.jsonилиdata_export.bki.
JSON удобнее: он читается глазами, ищется и сравнивается построчно, значения с ;, :, запятыми и переводами строк едут как есть. В BKI такие значения экранируются обратной косой.
curl -s -X POST -H "X-Authorization: $TOKEN" -d "_xsrf=$XSRF" "https://ideav.ru/mydb/object/641?json_export=1" -o data_export.json
# сжатый: ?json_export=1&gzip=1
# формат BKI: ?bki=1
Подчинённые таблицы в файл не вкладываются: в JSON они только объявлены, их записи выгружаются отдельным архивом.
Подробнее: База знаний: API и JSON-экспорт
Загрузить данные из Excel или CSV в существующую таблицу
в интерфейсе
Подготовьте текстовый файл: первая строка DATA, дальше по записи на строку, поля через ; и ; в конце строки. Загрузите его кнопкой «Импорт BKI» в нужной таблице.
- Создайте таблицу с нужными колонками в «Структуре» (структура должна уже существовать).
- Подготовьте файл в UTF-8: первая строка ровно
DATA. - Дальше: значение первой колонки, затем значения реквизитов в порядке колонок таблицы, каждое с
;после него. Порядок смотрите вmetadataтаблицы. - Откройте таблицу и нажмите кнопку импорта («Импорт BKI» / «Импорт архива»), выберите файл.
- Дождитесь результата и проверьте записи.
clients.bki
DATA
АО Ромашка;7701234567;Клиент;;
ПАО Эллипс;7709876543;Лид;;
- нужны права WRITE и EXPORT на таблицу (или роль admin);
- размер файла — до 8 МБ: большие наборы делите на части, каждая со своей строкой
DATA(около 10 тысяч строк — примерно 3 МБ); - справочные колонки заполняйте названиями записей, а не id;
- даты — в формате
ДД.ММ.ГГГГ.
Данные из Excel без подготовки файла можно загрузить вставкой из буфера обмена.
Подробнее: API: загрузка файлом
Вставить данные из Excel через буфер обмена
в интерфейсе
Кнопка «Вставить данные из буфера» в панели таблицы принимает текст, разделённый табуляцией, ; или запятой, распознаёт колонки и вставляет строки.
- В Excel или Google Sheets выделите нужные ячейки и скопируйте (Ctrl+C).
- В Интеграме нажмите иконку буфера (📋) «Вставить данные из буфера» в панели таблицы.
- Вставьте текст в окно (Ctrl+V). Нажмите «Просмотр», чтобы проверить, как данные распознаны.
- Если значения справочников могут отсутствовать, отметьте «Создавать справочные значения» — найденные не будут создаваться заново, недостающие будут добавлены.
- Нажмите «Вставить».
Перед вставкой нажмите «Просмотр» и проверьте, как данные распознаны. Для больших объёмов используйте файл DATA.
Загрузить записи со ссылками на другие таблицы
в интерфейсе
В файле импорта ссылки пишут названиями целевых записей, а не id. Несколько значений мультиссылки — через запятую; недостающие значения создаются.
- В колонку-ссылку вносите значение главной колонки записи из справочника.
- Для мультиссылки перечислите названия через запятую:
имя1,имя2,имя3. - Поля разделяйте
;, значения внутри мультиссылки — запятой. - Загрузите файл и проверьте связи.
DATA
obj0007;[-0.04,-0.31];obj4003,obj0247;
obj0247;[0.11,0.02];obj0007,obj4003;
Следите за точным совпадением названий: из-за опечатки вместо связи создастся лишняя запись-заглушка. Ссылка вперёд (на запись ниже в файле) допустима.
Запятые внутри текстовых и MEMO-полей (например, JSON [1,2,3]) сохраняются как есть: по запятой разбиваются только ссылочные колонки.
Загрузить файл повторно: обновить записи или добавить новые
для разработчика
Если первая колонка таблицы уникальна (или задан составной ключ), строка файла обновляет найденную запись; иначе каждая строка добавляется новой записью.
- Определите, уникальна ли первая колонка (или есть ли реквизиты-ключи) в структуре таблицы.
- Если уникальна — повторная загрузка обновит записи с тем же названием, дублей не будет.
- Если нет — перед повторной загрузкой очистите таблицу или заведите ключ, иначе появятся дубли.
- При составном ключе различайте строки по ключевым реквизитам, а не только по названию.
При составном ключе строки с одинаковым набором ключевых реквизитов обновляют одну и ту же запись, даже если названия разные: в итоге останется название последней строки.
В числовой первой колонке нечисловое название превращается в 0.
Подробнее: API: загрузка файлом
Загрузить записи в подчинённую таблицу конкретной записи
для разработчика
В адрес импорта добавляется F_U={id записи-родителя} — конкретного заказа или клиента, а не таблицы. Остальное — как у обычного импорта.
- Найдите id записи-родителя (например, заказа).
- Подготовьте файл
DATAдля подчинённой таблицы. - Отправьте его на адрес
object/{id подчинённой таблицы}?JSON&import=1&F_U={id родителя}.
curl -s -X POST -H "X-Authorization: $TOKEN" -F "token=$TOKEN" -F "_xsrf=$XSRF" -F "bki_file=@items.bki;type=text/plain" "https://ideav.ru/mydb/object/700?JSON&import=1&F_U=691"
Не подставляйте в F_U id таблицы: это импорт в метаданные, и у родительской таблицы появится лишняя колонка с именем из данных.
Подробнее: API: загрузка файлом
Импорт не работает: строки слиплись, значение уехало в соседнюю колонку
для разработчика
Типичные причины: точка с запятой внутри значения, строка из ровно «имя + реквизиты + ;», файл больше 8 МБ, нет прав WRITE+EXPORT, обрезанный файл.
- Значение «переехало»: внутри текста была
;— разделитель колонок. Экранируйте при сборке файла:\→\\,;→\;, а переводы строк в значении схлопните. - Строки клеятся попарно: строка считается законченной, только когда в ней полей строго больше числа колонок. Добавьте в каждую строку одну лишнюю пустую колонку (ещё одну
;в конце). - Ошибка «максимальный размер файла»: разбейте файл на части по 8 МБ — у каждой своя первая строка
DATA. - Ошибка «нет прав на загрузку объектов этого типа»: выдайте роли WRITE и EXPORT на таблицу или импортируйте под admin.
- Импорт создал строки без значений реквизитов: файл выгрузки обрезан (в конец попала посторонняя страница). Выгрузите заново: файл должен заканчиваться строкой данных.
Импорт не включает сокращённый режим и ругается на структуру, если первая строка файла не равна DATA.
Подробнее: API: загрузка файлом
Загрузить архив таблицы (BKI или JSON) в базу
в интерфейсе
Одна кнопка «Импорт архива» принимает оба формата: по первому символу файла система определяет, JSON ({), данные DATA или заголовки BKI.
- Откройте таблицу, в которую нужно загрузить данные.
- Нажмите «Импорт архива» и выберите файл
.jsonили.bki. - Дождитесь окончания (предел времени — 300 секунд, размер файла — 8 МБ).
- Проверьте записи и колонки.
Нужны права WRITE и EXPORT на таблицу. Из архива создаются недостающие колонки и целевые таблицы; существующие записи обновляются по ключу уникальности.
| В записи JSON | Что произойдёт |
|---|---|
| ключа нет | колонка не трогается |
null | значение очищается |
"" | записывается пустая строка |
"val": "" | запись удаляется по ключу уникальности |
Подробнее: API: загрузка файлом
Перенести таблицу с данными в другую базу
в интерфейсе
Выгрузите таблицу «Экспортом JSON» и загрузите файл «Импортом архива» в другой базе: колонки сводятся по id, по имени и по целевой таблице, недостающие создаются.
- В исходной базе откройте таблицу и нажмите «Экспорт JSON».
- В целевой базе откройте таблицу, в которую нужно загрузить данные (при необходимости создайте пустую), и нажмите «Импорт архива».
- Выберите файл и дождитесь окончания.
- Проверьте колонки и ссылки. Подчинённые таблицы переносите отдельными архивами с
F_Uродителя.
Id в целевой базе свои, поэтому колонки ищутся по порядку: 1) id + вид + форма; 2) имя + вид + форма; 3) только целевая таблица (для ссылок). «Форма» — базовый тип или целевая таблица: Дата:DATE и Дата:DATETIME — разные колонки.
Ссылки в архиве записаны именами целевых записей, а не id, поэтому справочник переносите вместе с таблицей или заранее.
Подробнее: API: схема в JSON
Перенести всю конфигурацию базы (таблицы, запросы, меню, шаблоны) на другую базу
для разработчика
На странице «Миграция конфигурации базы» таблицы с данными, запросы, меню, пользователи и файлы выгружаются в один JSON и разворачиваются на другой базе, с возможностью отката.
- Откройте страницу миграции в исходной базе и, если нужно, измените порог служебных ID (по умолчанию 460: объекты с меньшими id считаются служебными и не переносятся).
- Отметьте, что выгружать: данные таблиц, запросы, пользователей, меню, файлы (шаблоны и скрипты).
- Для демо-копии включите «обфускацию данных» — обезличивание.
- Нажмите «Сформировать JSON», затем «Скачать .json».
- В целевой базе откройте ту же страницу, загрузите файл («Загрузить из файла») и нажмите «Развернуть на этой БД».
- Если результат не устроил, воспользуйтесь блоком «Откат последнего импорта».
- переносятся таблицы с подписями и свойствами колонок, ссылками и подчинёнными таблицами, их записи, запросы со всеми полями колонок;
- термины, которые заняты в целевой базе, получают суффикс — конфликтов имён нет;
- пароли не переносятся: импортированным пользователям нужно задать пароль;
- обфускация оставляет не более 200 записей на таблицу, суммы умножает на случайное число, тексты заменяет на «x»; справочники до 30 значений сохраняются.
Откат удаляет все объекты и записи с id, начиная с первого созданного при импорте (записи, затем колонки, затем типы). Информация о последнем импорте хранится в браузере.
Сделать резервную копию базы и восстановить из неё
для разработчика
Вызов GET /{db}/backup кладёт дамп всей базы в templates/custom/{db}/backups/{db}_<дата>.dmp.zip; восстановление делает только владелец базы, предварительно сохраняя страховочный архив.
- Откройте адрес
/{db}/backup— дамп сохранится в папкуbackupsфайлового менеджера, и вы перейдёте к этому файлу. Нужен грант EXPORT, роль admin или права владельца базы. - Скачайте архив
*.dmp.zipизdir_admin. - Для восстановления нажмите у архива значок «Восстановить из архива», прочитайте предупреждение и введите имя базы для подтверждения.
- Дождитесь ответа: в нём имя страховочного архива, сохранённого перед заливкой.
Восстановление заменяет данные базы архивом (текущие данные очищаются) и доступно только владельцу базы (пользователь с именем базы) или супер-администратору сервера. Файлы базы отдельно: для них есть code_backup и code_restore с архивами .code.zip.
Перед заливкой текущая база сохраняется в backups страховочным архивом; если сохранение не удалось, восстановление отменяется и база не тронута.
Подробнее: API: резервные копии
Узнать, кто и когда менял запись (журнал изменений)
для разработчика
У каждой базы есть два журнала: запросов (<db>_log.jsonl) и изменений данных (<db>_sql.jsonl) со значениями «до» и «после». Читает их администратор запросом GET /{db}/journal?JSON.
- Войдите под администратором базы:
admin, владелец или роль admin; остальные получат 403. - Для истории записи вызовите
journal?JSON&mode=sql&id={id записи}. - В ответе смотрите
op(insert, update, delete, import),old,new, времяtsи пользователяuser. - Чтобы увидеть всё, что сделал один запрос, отфильтруйте по
rid.
| Параметр | Что делает |
|---|---|
mode | log (по умолчанию) — запросы, sql — изменения данных |
user | логин точно; ~ai — все запросы ИИ |
id | история одной записи |
rid, op, ai_job | точное совпадение |
since, until | период по времени, включительно |
where | до 10 условий eq, ne, starts, ends, contains, notcontains |
limit, cursor | страница (до 10 000 строк) и продолжение к более старым |
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/journal?JSON&mode=sql&id=5240"
Пароли, токены и xsrf в журнал не попадают (значения ***). Файл ротируется по размеру — по умолчанию 50 МБ. SELECT не пишется. Запрос от ИИ помечается логином с суффиксом ~ai.
Массово изменить данные запросом (колонка SET)
для разработчика
К любому запросу можно добавить колонку SET с новым значением: запрос покажет, что изменится, а по ссылке «Выполнить» применит. Можно менять, создавать и удалять записи в разных таблицах.
- Создайте запрос, который отбирает нужные записи (например, клиентов с первой встречей осенью 2021).
- В колонке, которую нужно изменить, заполните поле «SET»: новое значение в кавычках, например
"Осень 2021". - Запустите запрос — он покажет отобранные данные и ничего не меняет.
- Нажмите «Выполнить»: запрос сформируется ещё раз и изменения применятся.
- Проверьте результат в самой таблице (запрос при этом показывает данные «до» изменения).
- значение SET может использовать поле «Формула» и SQL-функции, например
CONCAT()иIFNULL— чтобы дописать текст к значению, а не заменить его; - если объект встречается в отчёте несколько раз, он будет изменён один раз;
- создание подчинённых записей: условие отбора вместе с SET трактуется как «условие или пусто», поэтому при повторном запуске дубли не создаются;
- пустое значение
""в SET удаляет значение, а у записи — её и все подчинённые данные.
Удаление через SET не проверяет ссылки: можно удалить значение справочника, на которое ссылаются другие записи.
Чтобы выполнять изменение без подтверждения, передайте в POST-запросе флаг confirmed (в GET он не сработает). Параметр запроса EXECUTE выполняет запрос при вызове любым методом, GET или POST.
Подробнее: Запросы: как устроены
Найти и удалить дубликаты записей
для разработчика
Основным запросом выводят все записи, вложенным — для каждой находят минимальный id среди двойников. Записи с минимальным id оставляют, остальные удаляют колонкой SET с пустым значением.
- Создайте вложенный запрос «Оригинал»: для каждой комбинации ключевых полей (например, фильм и режиссёр) он считает минимальный id.
- Создайте основной запрос «Дубликаты»: он выводит все записи и подставляет в условие значения полей из строки основного запроса.
- Оставьте в отчёте записи, у которых id больше минимального, — это дубли (минимальный id — самый первый, потому что id выдаются по возрастанию).
- В колонке записи задайте SET с пустым значением
"", чтобы удалить дубли, и нажмите «Выполнить». - Для регулярной чистки выведите запрос в пункт меню или запускайте по расписанию POST-запросом с флагом
confirmed.
Вложенный запрос при самостоятельном запуске показывает ошибку: он не знает значения полей родительского запроса. Это нормально.
Чтобы дубли не появлялись при загрузке, сделайте первую колонку уникальной или задайте составной ключ: тогда импорт обновит запись вместо добавления.
Подробнее: Запросы: вложенные запросы
Записать много записей одним API-запросом (_m_batch)
для разработчика
POST /{db}/_m_batch выполняет до 1000 операций new, set, save, del за один запрос; запись, созданную в пакете, адресуют значением ":id".
- Соберите массив
ops: у каждой операцииop,id(запись или таблица), при создании —upиfields. - Создаваемую в пакете запись указывайте как
":id"(последняяnew) или":idN"(операцияnewс номером N с нуля). - Отправьте POST с
token,_xsrfиops. - Разберите
results: у проваленных операций"ok": falseи текст ошибки; повторите только их.
curl -s -X POST -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" --form-string 'ops=[
{"op":"new","id":690,"up":1,"fields":{"t690":"Заказ 101"}},
{"op":"new","id":700,"up":":id0","fields":{"t700":"Труба 32 мм","t702":"12"}},
{"op":"set","id":649,"fields":{"t643":"7701234569"}}
]' "https://ideav.ru/mydb/_m_batch?JSON=1"
Пакет не атомарен: упавшая операция не откатывает соседние. Предел — 1000 операций и 300 секунд. Копия записи и загрузка файлов в пакет не входят.
Поля можно задавать по именам: таблицу — именем в id, колонки — именами в fields.
Подробнее: API: пакет команд
Создать и изменить запись через API
для разработчика
Главное значение записи пишется в t{id таблицы}, а не в t3; колонки — в t{id колонки}; родитель — в up (1 — верхний уровень). Справочное поле — id записи справочника.
- Узнайте id таблицы и колонок:
GET /{db}/metadata/{id таблицы}?JSON=1. - Получите
_xsrfвызовомGET /{db}/xsrf?JSON. - Отправьте POST на
_m_new/{id таблицы}?JSON=1сup,t{id таблицы}и нужными колонками. - Для правки — POST на
_m_set/{id записи}с изменяемыми колонками; пустое значение очищает поле.
curl -s -X POST -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "up=1" -F "t641=АО Ромашка" -F "t643=7701234567" -F "t646=660" "https://ideav.ru/mydb/_m_new/641?JSON=1"
curl -s -X POST -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "t643=7701234568" "https://ideav.ru/mydb/_m_set/649?JSON=1"
_m_set в справочную колонку принимает только id записи; _m_new может принять и название. Первая колонка сохраняется теми же проверками, что и форма: права, уникальность, запрет пустого имени.
Чтение и запись по именам колонок возможны через fields={...} и ?JSON_OBJ&NAMED.
Подробнее: API: создать запись · API: изменить запись
Запросы, отчёты и дашборды
Отчёт собирается выбором колонок, а связи между таблицами ядро находит само. Один и тот же запрос отдаёт страницу отчёта, Excel, JSON и данные для панелей дашборда.
Создать отчёт
в интерфейсе
Отчёт создаётся в меню «Таблицы», пункт «Отчёт»: вы выбираете колонки из списка, а связывать таблицы вручную не нужно.
- Откройте меню «Таблицы» и перейдите в «Отчёт».
- Добавьте новый отчёт и задайте ему название, например «Встречи за текущий месяц».
- Добавьте первую колонку из выпадающего списка «Колонки отчёта» — она задаёт главную таблицу: строки отчёта будут её записями.
- Добавьте остальные колонки. После первой колонки список сокращается до колонок, связанных с её таблицей.
- При необходимости задайте фильтры, сортировку и итоги (см. соседние статьи) и откройте отчёт по названию.
Запрос хранится в той же базе, что и данные, поэтому его можно создать и командами API, и перенести между базами JSON-файлом.
Подробнее: Запросы: запрос и его колонки · API: создание запроса
Добавить в отчёт поле из связанной таблицы
в интерфейсе
Выберите в списке колонок нужный реквизит связанной таблицы, например «Клиент → Категория»: путь соединения ядро найдёт само.
- В отчёте добавьте колонку и в выпадающем списке выберите реквизит нужной таблицы.
- Промежуточные таблицы добавлять не нужно: ядро идёт по ссылке «на нас», ссылке «от нас», подчинённой таблице или родителю.
- Если до таблицы ведут несколько ссылок, добавьте в отчёт ссылочную колонку, по которой нужно идти (можно скрытую) — соединение выбирается по ней.
Подключить таблицу дважды или соединить по произвольному условию можно явным JOIN с псевдонимом.
Подробнее: Запросы: как ядро находит путь · Запросы: несколько ссылок и явный JOIN
Скрыть колонку, но оставить по ней фильтр
в интерфейсе
У колонки есть галка «Скрыть»: она не выводится и не дробит группировку, но работает в фильтре, сортировке и формулах.
- Добавьте колонку, по которой нужен отбор, например «Договор».
- Нажмите кнопку «Скрыть» (галка у колонки).
- В поле «Значение (от)» этой колонки задайте условие: например
%, чтобы отобрать только строки, где поле непусто.
Так делается условие «клиент попадает в отчёт, только если у него есть договор» без вывода самой колонки договора.
Скрытые колонки не участвуют в группировке: агрегаты и итоги считаются по видимым колонкам без функции.
Подробнее: API: поля колонки запроса
Что означают поля колонки отчёта
в интерфейсе
У каждой колонки есть источник, «Имя в отчёте», формула, фильтр (от/до), функция, скрытие, формат, сортировка и итог.
- Откройте отчёт в построителе — колонки показаны строками с перечисленными полями.
- Задайте нужные поля из таблицы ниже и сохраните.
| Поле | Что делает |
|---|---|
| Имя в отчёте | Название колонки и ключ в JSON; по нему же фильтруют снаружи FR_/TO_ |
| Формула | У колонки с источником — псевдоним (одно слово), у вычисляемой — выражение над псевдонимами |
| Значение (от) / (до) | Фильтр строк: диапазон для дат и чисел, маска для текста |
| Функция | Агрегат (SUM, COUNT, AVG, MIN, MAX, GROUP_CONCAT) или служебная, например abn_ID |
| Функция (от) / (до) | Фильтр по значению агрегата — аналог HAVING |
| Скрыть | Колонка работает в условиях и вычислениях, но не выводится |
| Формат | Вид значения: NUMBER, DATE, HTML и др. |
| Сорт. | Порядок сортировки: 1, 2, …; минус — по убыванию |
| Итог | Функция для итоговой строки: SUM, COUNT, AVG, MIN, MAX |
Подробнее: API: модель запроса
Зачем колонке «Имя в отчёте»
в интерфейсе
Снаружи фильтруются только колонки с заполненным «Именем в отчёте»; колонка без имени защищена от подмены фильтра.
- Откройте отчёт в построителе и найдите колонку, по которой нужен внешний фильтр.
- Заполните у неё «Имя в отчёте» — без пробелов.
- Передайте фильтр в адресе:
FR_{имя}— «от»,TO_{имя}— «до».
Ядро заменяет пробелы в имени на _: в ключе JSON и в фильтре пишите _. Если имя не задано, параметр молча игнорируется.
Колонке-ограничителю (например «только свои строки» с [USER_ID]) имя не давайте: с именем её фильтр становится параметром, и вызывающий сможет его подменить.
Подробнее: Запросы: фильтруемость только по имени
Вычисляемая колонка: разность, доля, условие
в интерфейсе
Колонкам-источникам задайте псевдонимы в поле «Формула», а новую колонку добавьте как «Вычисляемое» и напишите выражение над этими псевдонимами.
- У колонки-источника в поле «Формула» впишите псевдоним — одно слово, например
мест; обычно колонку скрывают. - Так же задайте псевдоним второй колонке, например
куплено. - Добавьте колонку «Вычисляемое» (последний пункт выпадающего списка) и дайте ей «Имя в отчёте».
- В её поле «Формула» напишите выражение:
ROUND(куплено/мест*100, 2).
В формуле пишите псевдоним, а не «Имя в отчёте» — иначе будет ошибка Unknown column. Псевдоним не должен совпадать со словами и функциями SQL (id, val, SUM) и с другими псевдонимами запроса.
Писать SELECT, FROM, TABLE в формулах нельзя: сумму по другой таблице делают подзапросом. Доступны функции MySQL/MariaDB.
Подробнее: API: формулы колонок · Запросы: подзапросы
Отобрать строки по условию в отчёте
в интерфейсе
Условие пишется в поля «Значение (от)» и «Значение (до)» нужной колонки; язык условий один для колонок и для внешних FR_/TO_.
- Откройте отчёт в построителе и найдите колонку, по которой отбираем.
- В «Значение (от)» впишите условие из таблицы ниже; для диапазона заполните ещё «Значение (до)».
- Если колонка нужна только для отбора, поставьте «Скрыть».
- Откройте отчёт и проверьте строки.
| Значение | Отбирает |
|---|---|
Одобрена | Равно значению; у справочной колонки — по названию записи |
%…% | Маска: подстрока в любом месте |
% / !% | Непусто / пусто |
!1 | Не равно |
IS NULL | Нет значения |
IN(1;2;3) | Вхождение в список |
~шаблон | Регулярное выражение |
1.1 и 31.12 в «до» | Диапазон от и до |
[Имя запроса] | Значение другого запроса (подзапрос) |
Индекс по значению префиксный: маска с % в начале (%Иванов) его не использует, и на больших таблицах такой фильтр перебирает строки.
Условие сложнее одного поля делают вычисляемой колонкой: логическое выражение над псевдонимами, значение 1 в «Значение (от)» и «Скрыть».
Подробнее: Запросы: что можно писать в фильтре
Передать фильтр в адресе отчёта (FR_ и TO_)
в интерфейсе
Добавьте в адрес FR_{имя}=значение для «от» и TO_{имя}=значение для «до»: страница откроется уже отфильтрованной.
- Убедитесь, что у колонки заполнено «Имя в отчёте».
- Откройте адрес отчёта и допишите
?FR_{имя}=значение(следующие параметры — через&). - Для диапазона добавьте
TO_{имя}=значение. - Скопируйте ссылку — это готовый срез, который можно отправить коллеге или поставить на кнопку.
# страница отчёта для человека
https://ideav.ru/mydb/report/951?FR_Дата=01.10.2026&TO_Дата=31.10.2026
# те же данные для кода
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/report/951?JSON_KV&FR_Статус=Новый"
- Внешние фильтры перекрывают постоянные фильтры колонки.
- Для открытого интервала по дате или числу добавьте оператор в значение (
>,<): без негоFR_— точное совпадение и даст 0 строк. - Ссылочное поле надёжнее фильтровать по id: суффикс
IDиabn_IDу колонки, напримерFR_СтатусID=9002; несколько значений —IN(9002,44895). - Параметр
F_{id колонки}работает только в таблицах (object/), в отчётах нуженFR_.
Подробнее: Запросы: фильтры FR_ и TO_ · API: фильтры запроса
Отфильтровать уже открытый отчёт
в интерфейсе
Фильтр открывается кликом по шапке отчёта или иконкой «воронка» справа вверху; отчёт перезапрашивается с сервера.
- Откройте отчёт.
- Кликните по шапке нужной колонки или по иконке «воронка» в правом верхнем углу.
- Задайте условие — отчёт обновится.
Фильтр работает только на колонках с заполненным «Именем в отчёте». Это защита: пользователь не может отменить фильтры, наложенные разработчиком отчёта.
Подробнее: Запросы: фильтруемость только по имени
Отчёт за период: диапазон дат и «за сегодня»
в интерфейсе
Задайте дату в «Значение (от)» и «Значение (до)» колонки: можно числами или встроенными датами [TODAY], [WEEK_AGO], [MONTH_AGO].
- Откройте колонку с датой в построителе.
- В «Значение (от)» впишите начало: дату или переменную, например
>=[WEEK_AGO]. - В «Значение (до)» впишите конец, например
[TODAY]. - Для года целиком:
1.1в «от» и31.12в «до» — диапазон текущего года.
Двойной клик по полю «От» или «До» открывает выпадающий список служебных слов. Значения подставляются при каждом вызове отчёта.
Чтобы пользователь менял период сам, передавайте его в адресе: FR_Дата=01.10.2026&TO_Дата=31.10.2026.
Подробнее: Запросы: встроенные переменные
Встроенные переменные: [TODAY], [USER_ID], [ROLE]
в интерфейсе
Переменные пишутся в квадратных скобках в фильтрах и формулах и подставляются при каждом вызове.
- Откройте поле «Значение (от)/(до)» или «Формула» нужной колонки.
- Впишите переменную из таблицы, например
[TODAY].
| Переменная | Значение |
|---|---|
[TODAY], [NOW], [YESTERDAY], [WEEK_AGO], [MONTH_AGO] | Относительные даты |
[USER], [USER_ID] | Текущий пользователь и его id |
[ROLE], [ROLE_ID] | Роль вызывающего |
_request_.Имя | Параметр адреса: report/950?ProjID=12 читается как _request_.ProjID |
[Имя запроса] | Значение другого запроса (подзапрос) |
[THIS] | В формуле колонки с источником — её собственное значение |
Подробнее: Запросы: встроенные переменные и _request_
Показать каждому только его строки
в интерфейсе
Добавьте скрытую колонку «Пользователь» с функцией abn_ID и фильтром [USER_ID] — и не давайте ей «Имя в отчёте».
- Добавьте в отчёт колонку «Пользователь» (или ссылку на него, например «Ответственный»).
- Поставьте у неё функцию
abn_ID: фильтр будет сравнивать id, а не название. - В «Значение (от)» впишите
[USER_ID]. - Поставьте «Скрыть» и оставьте «Имя в отчёте» пустым.
- Выдайте роли право READ на этот отчёт.
Если дать колонке имя, фильтр станет параметром и вызывающий сможет подставить в FR_ чужой id. Строки отбираются самим запросом, поэтому маски прав таблицы тут не применяются.
Подробнее: Запросы: чьи права действуют · Запросы: фильтруемость только по имени
Посчитать сумму, количество, среднее по группам
в интерфейсе
Поставьте у числовой колонки функцию (SUM, COUNT, AVG, MIN, MAX): группировка строится сама по всем видимым колонкам без функции.
- Добавьте колонки, по которым нужны группы, например «Статус».
- Добавьте колонку, которую считаем, и выберите ей в поле «Функция» агрегат:
COUNTдля количества,SUMдля суммы. - Откройте отчёт: строки сгруппированы по всем колонкам без функции.
- Если колонка нужна для условий, но не должна дробить группы, поставьте ей «Скрыть».
GROUP_CONCATсклеивает значения группы в одну строку,JSON_ARRAYAGGсобирает их в массив.- Для каждой присоединённой таблицы с агрегатом ядро строит отдельную производную таблицу со своей группировкой, поэтому «сумма заявок по компании» не размножается её договорами.
Две суммы с разных уровней цепочки (Компания ← Заявка ← Договор) в одном запросе удваиваются — такие суммы считают подзапросами.
Подробнее: Запросы: агрегаты не размножаются · API: формулы и агрегаты
Добавить итоговую строку в отчёт
в интерфейсе
В поле «Итог» колонки выберите функцию (SUM, COUNT, AVG, MIN, MAX) — отчёт добавит итоговую строку.
- В построителе откройте контекстное меню колонки и выберите «Итоги → COUNT» (или другую функцию) либо заполните поле «Итог».
- Откройте отчёт: внизу появилась итоговая строка с результатом по этой колонке.
- Достаточно функции хотя бы в одной колонке — итоговая строка выводится для всех, где она задана.
Для разового итога без правки определения передайте параметр адреса TOTALS=имя:SUM; число строк без самих строк возвращает RECORD_COUNT.
Подробнее: Запросы: сортировка, итоги и состав колонок
Отобрать группы по значению агрегата («где больше одной»)
в интерфейсе
Условие на результат агрегата задают в полях «Функция (от)» и «Функция (до)» той же колонки.
- Поставьте колонке функцию, например
COUNT. - В «Функция (от)» впишите нижнюю границу, например
>1; верхнюю — в «Функция (до)». - Откройте отчёт: останутся только группы, где агрегат попал в диапазон.
Фильтр «Значение (от/до)» срабатывает до группировки (по отдельным записям), «Функция (от/до)» — после неё. Правила записи условий те же.
Подробнее: Запросы: язык фильтров
Свести данные по месяцам
для разработчика
Скрытая колонка даты с псевдонимом и фильтром года, вычисляемая колонка с DATE_FORMAT и сумма — группы получатся по месяцам.
- Добавьте колонку даты: «Формула»
дата, «Значение (от)»1.1, «Значение (до)»31.12, «Скрыть». - Добавьте вычисляемую колонку «Месяц» с формулой
DATE_FORMAT(дата,'%Y-%m')и сортировкой 1. - Добавьте колонку суммы с функцией
SUMи итогомSUM. - Откройте отчёт: по одной строке на месяц.
Дата формула: дата от: 1.1 до: 31.12 скрыть
Месяц формула: DATE_FORMAT(дата,'%Y-%m') сорт.: 1
Выручка функция: SUM итог: SUM
# [{"Месяц":"2026-01","Выручка":"150.00"},{"Месяц":"2026-02","Выручка":"70.00"}]
Вычисляемая колонка без агрегата в отчёте с группировкой сама становится полем группировки. Псевдоним агрегированной колонки означает её значение до агрегации; сумму в формуле пишите явно: Лимит-IFNULL(SUM(Контракты),0).
Подробнее: API: формулы колонок
Сортировка отчёта
в интерфейсе
В поле «Сорт.» колонки задайте порядок 1, 2, …; отрицательное число даёт обратную сортировку.
- Откройте построитель отчёта.
- В поле «Сорт.» главной колонки поставьте
1, второй —2(например, сначала категория, затем имя). - Для убывания напишите минус:
-1. - Сортировать можно и по скрытой колонке.
В адресе параметр ORDER={id колонки} принимает id колонки, а не имя (минус перед id — по убыванию). Сортировку, от которой зависит результат (например, «последние записи» при лимите), задавайте в самом отчёте.
Подробнее: Запросы: сортировка и пагинация
Ограничить число строк и листать отчёт (LIMIT)
в интерфейсе
Параметр LIMIT=N ограничивает число строк, LIMIT=смещение,N позволяет листать; параметр можно задать в отчёте и передать в адресе.
- В параметрах отчёта задайте LIMIT — максимальное число строк.
- Или передайте в адресе
LIMIT=10: вернётся не более 10 записей. - Для страниц укажите пару через запятую:
LIMIT=15,8— 8 записей, начиная с позиции 15. - Чтобы узнать общее число строк, добавьте
RECORD_COUNT— вернётся только количество.
Количество, переданное в адресе, не может превышать лимит, заданный в самом отчёте (из соображений безопасности): больший запрошенный лимит схлопывается до заданного.
Подробнее: Запросы: сортировка, пагинация, итоги
Сделать записи в отчёте ссылками на карточки
в интерфейсе
Включите у отчёта опцию «Интерактивный»: объекты в строках станут гиперссылками на форму просмотра и редактирования.
- Откройте параметры отчёта.
- Включите опцию «Интерактивный».
- Откройте отчёт и кликните по значению — откроется карточка записи.
Для особых ссылок (переход в другой отчёт с фильтром по строке, карандаш, кнопка «создать запись») используйте колонку-действие.
Подробнее: Запросы: кнопки в таблицах
Выгрузить отчёт в Excel
в интерфейсе
Сформированный отчёт выгружается в MS Excel кнопкой выгрузки в самом отчёте.
- Откройте отчёт и при необходимости отфильтруйте его (воронка у шапки или
FR_в адресе). - Нажмите кнопку выгрузки в MS Excel.
- Откройте полученный файл.
Для выгрузки в код или другую систему вместо файла используйте JSON по тому же адресу отчёта.
Подробнее: База знаний: отчёты на той же базе
Получить данные отчёта в JSON
для разработчика
Добавьте к адресу отчёта параметр формата: JSON_KV — массив объектов, JSON_DATA — первая строка, JSON — строки плюс метаданные колонок.
- Откройте отчёт по адресу
report/{id или название}; регистр в названии не важен. - Добавьте параметр формата:
?JSON_KVдля массива объектов с ключами «Имя в отчёте». - Передайте токен заголовком
X-Authorization. - Фильтры,
LIMITи сортировку добавляйте параметрами адреса.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/report/950?JSON_KV"
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/report/Клиенты%20по%20категориям?JSON_KV&FR_Категория=Клиент"
| Формат | Что отдаёт |
|---|---|
JSON_KV | Массив объектов; ключи — «Имя в отчёте» |
JSON_DATA | Данные первой строки (скалярные выборки) |
JSON | Строки плюс метаданные: тип, формат и права каждой колонки |
Без параметра формата запрос считается переходом браузера и уходит на страницу входа — токен в заголовке не читается. Даты приходят unix-секундами; тип поля подскажет формат JSON (columns[].format). Каждый ответ помечен заголовками X-Query-Id и X-Query-Name.
Подробнее: Запросы: форматы ответа · API: вызов запроса
Использовать один отчёт внутри другого (вложенный запрос)
для разработчика
Впишите имя сохранённого запроса в квадратных скобках в формулу, фильтр, сортировку, группировку или HAVING внешнего запроса.
- Создайте внутренний запрос: первая видимая колонка — значение (обычно
SUM), плюс скрытая колонка-связь с функциейabn_IDи фильтром[Псевдоним], где псевдоним — колонка внешнего запроса. - Во внешнем запросе добавьте скрытую колонку с
abn_IDи тем же псевдонимом в «Формуле». - Добавьте вычисляемую колонку с формулой
[Имя подзапроса]. - Откройте внешний запрос и проверьте значения.
# подзапрос «Склад по артикулу»
Позиция → Артикул функция: abn_ID от: [art_id] скрыть
Партия → Остаток имя: Остаток функция: SUM
# внешний запрос
Позиция → Артикул функция: abn_ID формула: art_id скрыть
Вычисляемое имя: stock формула: [Склад по артикулу]
Подзапрос без строк возвращает пусто: оберните его в IFNULL(…, 0) или задайте запросу «Если пусто, вернуть» = 0. Запущенный отдельно, внутренний запрос показывает ошибку — он не знает значений, которые передаёт внешний.
Глубина вложенности не ограничена; вложенный запрос сам может содержать […].
Подробнее: Запросы: сохранённый запрос как подзапрос · API: подзапросы
Суммы по заявкам и договорам без удвоения
для разработчика
В одном запросе суммируйте только по самому нижнему уровню цепочки, а сумму каждого следующего уровня считайте отдельным запросом-подзапросом.
- Если суммируется одна ветка («Компания + сумма её заявок»), достаточно колонки
SUMу реквизита «Заявка → Сумма». - Для суммы второго уровня (договоры) создайте отдельный запрос и вызовите его подзапросом
[Имя]из вычисляемой колонки. - Связь подзапроса с внешним запросом делайте скрытой колонкой с
abn_IDи фильтром[Псевдоним].
Причина: в одном запросе строки всех присоединённых таблиц перемножаются — в цепочке Компания ← Заявка ← Договор сумма по заявкам повторяется столько раз, сколько у заявки договоров.
Подробнее: Запросы: агрегаты не размножаются · API: подзапросы с суммами по цепочке
Собрать дерево: все подразделения ниже данного (RECURSIVE)
для разработчика
Поставьте первой колонке функцию RECURSIVE — запрос обойдёт дерево и вернёт множество id, которое вкладывается в другие запросы.
- Создайте запрос, первая колонка которого — ссылочное поле дерева.
- Задайте ей функцию
RECURSIVE. - Укажите «засев» — корень обхода: фильтр колонки, параметр
FR_{имя колонки}или вложенный запрос[имя]в «Значении (от)». - Вызовите этот запрос подзапросом из других запросов.
- Если у таблицы ссылка на саму себя, обход идёт вверх по ссылкам к владельцам; иначе — вниз по дереву подчинённых записей того же типа.
RECBOTH=1обходит ребро в обе стороны сразу.- Объём ограничен
LIMIT(по умолчанию 80, перекрывается?LIMIT=смещение,N), глубина не ограничена.
Подробнее: Запросы: RECURSIVE
Вызвать отчёт с параметрами из кнопки или формы
для разработчика
Параметры передают в адресе: FR_{имя} и TO_{имя} для фильтров колонок, произвольное Имя=… для чтения в отчёте как _request_.Имя.
- Для отбора по колонке: убедитесь, что у неё есть «Имя в отчёте», и добавьте
FR_{имя}=значениев ссылку или запрос формы. - Для произвольного параметра: добавьте
?ProjID=12и в фильтре или формуле колонки используйте_request_.ProjID. - Для кнопки в таблице: настройте кнопку-колонку так, чтобы она вызывала отчёт с подстановками из строки (
[ID], значения колонок).
# параметр читается в отчёте как _request_.ProjID
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/report/950?JSON_KV&ProjID=12"
Внешний FR_ понимает %, !, <, >, IN( как операторы, а пустое значение снимает фильтр. Не подставляйте в него без проверки то, что ввёл посетитель.
Подробнее: Запросы: переменные и _request_ · Запросы: кнопки в таблицах · Триггеры кнопок
Колонка со ссылкой на другой отчёт или на карточку
для разработчика
Вычисляемая колонка с форматом HTML и формулой CONCAT(…) собирает ссылку; id записей берут скрытыми колонками с abn_ID.
- Добавьте скрытые колонки с id записей: функция
abn_IDи псевдоним в «Формуле». - Добавьте вычисляемую колонку, поставьте ей формат
HTML. - В «Формуле» соберите ссылку через
CONCAT; имя базы в адресе пишется как_global_.z. - У целевого отчёта у нужной колонки должно быть «Имя в отчёте» — иначе
FR_игнорируется.
# переход в отчёт 812 с фильтром по клиенту строки
CONCAT('<a href="/_global_.z/report/812?FR_КлиентID=', КлиентID, '">договоры →</a>')
# карточка записи
CONCAT('<a target="cr" href="/_global_.z/edit_obj/', СделкаID, '" title="редактировать">✏️</a>')
Псевдоним заменяется целым словом по всей формуле, в том числе внутри строковых литералов: если в тексте ссылки есть слово, совпадающее с псевдонимом, разбейте литерал на две части.
Подробнее: API: формулы колонок
Обратиться из отчёта к внешнему сайту или API
для разработчика
Задайте отчёту шаблон URL с полями в квадратных скобках, а колонке — функцию abn_URL: для каждой строки выполнится запрос и подставится ответ.
- В поле URL отчёта впишите шаблон адреса, подставив значения полей отчёта в квадратных скобках, например
[phone]и[name]. - Добавьте в отчёт колонки с этими именами — все поля шаблона должны стоять левее колонки с
abn_URL. - Добавьте колонку с функцией
abn_URL: её значение заменится ответом на запрос по полученному URL. - Чтобы сохранить ответ в базе, присвойте его значение полю в SET-запросе (в том числе с флагом
confirmed).
Колонки вычисляются последовательно, поэтому всё, что используется в шаблоне, должно быть определено левее колонки abn_URL.
Ответ в формате JSON можно разобрать: к abn_URL обращаются по именам ключей в виде CURL.{ключ}.
Подробнее: Запросы: кто вызывает запрос
Подставить значение по умолчанию в форму из отчёта
для разработчика
Впишите название отчёта в поле «Значение по умолчанию» реквизита: при создании записи отчёт запустится и его результат попадёт в поле.
- Создайте отчёт, который вычисляет нужное значение, например «ID_менеджера»: колонка «Пользователь» с фильтром
[USER]и колонка «Менеджер» с функциейabn_ID(чтобы вернуть id). - Проверьте: отчёт должен давать одну строку с id.
- В «Редакторе структуры» откройте реквизит (например, ссылку «Менеджер» у таблицы «Клиент») и в «Значении по умолчанию» впишите название отчёта.
- Создайте запись: поле заполнится результатом отчёта.
Так проставляют автора записи, подразделение пользователя и подобные поля.
Подробнее: Запросы: встроенные переменные
Изменить данные запросом (SET): массово обновить, создать, удалить
для разработчика
В колонке отчёта заполните поле «SET» — запрос покажет превью, а изменения применятся после подтверждения (confirmed=1, POST).
- Соберите отчёт, отбирающий нужные записи.
- В колонке, которую нужно изменить, заполните «SET» — выражение нового значения; можно использовать поля «Формула» и функции SQL (
CONCAT,IFNULL). - Откройте отчёт: он покажет, что и как будет изменено.
- Нажмите «Выполнить»: отчёт сформируется ещё раз, и изменения применятся.
- Для автоматического запуска вызывайте отчёт POST-запросом с
confirmed=1и_xsrf; запросу с параметромEXECUTEподтверждение не нужно.
- Объект, попавший в отчёт несколько раз, меняется один раз.
- Пустое значение
""в SET удаляет запись или значение реквизита вместе с подчинёнными записями; проверка связей при этом не выполняется. - Если в колонке с SET заданы условия отбора, они трактуются как «условие или пусто» — так не создаются дубликаты при повторном запуске.
SET меняет данные без проверки прав роли на каждую запись; запрос с EXECUTE выполняет каждый, у кого есть на него грант, поэтому гостю его не выдавайте.
Подробнее: Хранимые процедуры · Запросы: чьи права действуют
Дать роли доступ к отчёту
в интерфейсе
Роли нужен только доступ READ к самому запросу: он открывает все колонки и строки запроса, доступы к таблицам при этом не нужны.
- Откройте права нужной роли.
- Добавьте доступ READ к запросу.
- Ограничения по строкам («только свои») задайте самим запросом — скрытой колонкой с
[USER_ID].
Запрос работает как хранимая процедура: с правами того, кто его настроил. Это назначение запроса — отдать ровно то, что решил аналитик. Маски строк таблицы к запросу не применяются.
Нет READ-гранта на отчёт — ответ 403; отчёта нет — 404. Пустой массив со статусом 200 значит, что выборка действительно пуста (фильтр, определение отчёта), а не нехватку прав.
Подробнее: Запросы: чьи права действуют · API: права на запрос
Что такое дашборд и чем он отличается от отчёта
в интерфейсе
Отчёт отвечает на вопрос «какие данные выбрать», дашборд — «как показать»: листы-вкладки, а на них панели с таблицами, графиками и сводными.
- Подготовьте отчёты с нужными колонками, фильтрами и группировками.
- Создайте дашборд и добавьте лист — вкладку с отдельным срезом (продажи, задачи, финансы).
- Добавьте на лист панели и подключите к ним отчёты как источник данных.
- Выберите для каждой панели вид: таблица, график или сводная.
- Опубликуйте дашборд в меню для нужных ролей.
Панели питаются теми же запросами и правами, что и таблицы, — отдельного коннектора с кэшем нет. Дашборд открывается по адресу /{db}/dash/{id}.
Подробнее: База знаний: дашборды на тех же данных · Запросы: дашборды и ИИ-агенты
Подключить отчёт к панели дашборда
в интерфейсе
Панель берёт данные из отчёта по полю «Запрос» панели, а график настраивается по колонкам этого отчёта.
- Откройте отчёт и убедитесь, что колонки и группировка дают нужные данные, а у колонок есть «Имя в отчёте».
- В настройках панели укажите этот отчёт в поле «Запрос».
- Откройте «Варианты отображения» панели и назначьте поля графика по колонкам отчёта.
Колонка без «Имени в отчёте» или с галкой «Скрыть» в данные не попадает: панель её не увидит. Если нужной колонки нет, график или таблица остаются пустыми.
Подробнее: База знаний: дашборды
Фильтр по периоду и поиск на дашборде
в интерфейсе
В верхней панели дашборда задаются дата начала и окончания, детализация (неделя, месяц, год) и кнопка применения; поиск находит нужные строки.
- Откройте дашборд.
- Выберите дату начала, дату окончания и детализацию.
- Нажмите кнопку применения фильтра — показатели пересчитаются.
- Для поиска введите часть названия показателя в поле быстрого поиска.
Период управляет загрузкой данных на листе, поэтому одна и та же модель показывает дневной, месячный и годовой срез без пересборки отчёта. Для модели с периодами в базе должны быть записи справочника периодов (Месяц, Квартал, Год) с границами «С» и «По» на нужные годы — иначе колонок периодов не будет.
Подробнее: База знаний: дашборды
Фильтр отдельной панели
в интерфейсе
Фильтр панели применяется только к ней: можно выбрать значения, числовой диапазон или диапазон дат и сбросить фильтр.
- Нажмите иконку фильтра в шапке панели.
- Выберите одно или несколько значений либо задайте числовой диапазон или диапазон дат.
- Примените фильтр: остальные панели листа не меняются.
- Для сброса откройте окно фильтра и сбросьте условия; активный фильтр виден по состоянию иконки.
Общий фильтр периода действует на весь лист, фильтр панели — только на выбранный график или таблицу.
Подробнее: База знаний: дашборды
Выбрать тип диаграммы: линия, столбцы, круг, воронка
в интерфейсе
Панель можно показать таблицей, линейным, круговым, столбчатым графиком, диаграммой с областями, пузырьковой, воронкой или сводной таблицей.
- Откройте «Варианты отображения» панели.
- Выберите тип диаграммы по задаче из таблицы ниже.
- Назначьте поля (см. статью «Назначить поля графика») и сохраните — настройки запишутся в панель.
| Тип | Когда использовать |
|---|---|
| Таблица | Детальный просмотр значений и строк |
| Линейный график | Динамика во времени |
| Круговая диаграмма | Доли категорий в одном периоде |
| Столбчатая диаграмма | Сравнение категорий и периодов |
| Диаграмма с областями | Накопленная или сравнительная динамика |
| Пузырьковая диаграмма | Сравнение трёх числовых параметров |
| Диаграмма-воронка | Последовательные этапы процесса |
| Сводная таблица | Пересечение строк, колонок и значений |
Подробнее: База знаний: дашборды
Назначить поля графика: ось X, значение, серии
в интерфейсе
В «Вариантах отображения» назначьте колонки отчёта на роли: ось X, значение, серии, стек; для сводной — строки, колонки и значения.
- Откройте «Варианты отображения» панели и выберите тип диаграммы.
- Назначьте ось X (например, «Месяц» из отчёта) и значение (например, «Выручка»).
- При необходимости назначьте серии или стек.
- Для пузырьковой укажите X, Y и размер, для воронки — этап и значение.
Если источник — отчёт, поля выбирают из его колонок. Если источник — табличная панель, можно использовать её строки и колонки. Для динамики по месяцам удобно сделать в отчёте колонку «Месяц» и сумму.
Подробнее: Запросы: дашборды и панели
Настроить внешний вид графика: цвета, легенда, размеры
в интерфейсе
В общих настройках панели задаются высота и ширина, толщина столбцов, цветовая гамма, подписи осей, легенда и число знаков в подсказках.
- Откройте «Варианты отображения» панели и вкладку «Общие настройки».
- Задайте высоту панели и графика и ширину по сетке из 12 колонок.
- Выберите цветовую гамму и позицию легенды (или отключите её).
- Настройте размер подписей осей и поворот подписей оси X, число знаков в подсказках.
- Сохраните: настройки запишутся в панель.
Тонкие настройки поверх общих задаются JSON — см. статью про кастомные настройки диаграммы.
Подробнее: База знаний: дашборды
Тонкая настройка диаграммы JSON-ом (customOptions)
для разработчика
В «Вариантах отображения → Диаграммы» есть поле «Кастомные настройки диаграммы (JSON)» с ключами options, dataset, datasets.
- Откройте «Варианты отображения» панели, раздел «Диаграммы», нужный тип диаграммы.
- В поле «Кастомные настройки диаграммы (JSON)» вставьте объект с ключами
options,datasetи/илиdatasets. - Сохраните: если JSON некорректен, настройки игнорируются и под полем появится сообщение об ошибке.
| Ключ | Назначение |
|---|---|
options | Глубоко сливается поверх итоговых options Chart.js |
dataset | Переопределения для каждого набора данных |
datasets | Для конкретных наборов: массив по индексу или объект; -1 — последний |
Последний столбик красным (для одной серии):
{ "dataset": { "pointColors": { "-1": "#e53935" } } }
Пунктирная линия толщиной 3:
{ "dataset": { "borderWidth": 3, "borderDash": [6, 4] } }
Скрыть легенду и подписать ось Y:
{ "options": { "plugins": { "legend": { "display": false } },
"scales": { "y": { "title": { "display": true, "text": "Сумма, ₽" } } } } }
Оборвать линию в точках без данных: { "dataset": { "spanGaps": false } }.
Обрыв происходит только на значениях null; если отчёт возвращает 0 для пустых ячеек, линия пройдёт через ноль. Лимиты: строка JSON до 8000 символов, функции JavaScript не поддерживаются, настройки имеют приоритет над общими.
Подробнее: База знаний: дашборды
Расположить панели плиткой и поменять их ширину
в интерфейсе
В плиточном режиме панели выстраиваются в сетку и занимают разную ширину; сохранённые размеры сбрасываются иконкой на листе.
- Включите плиточный режим на листе.
- Задайте ширину панели по адаптивной сетке из 12 колонок.
- Для сброса сохранённых размеров нажмите иконку сброса на листе.
Плитка нужна для обзорных экранов, где сразу видны несколько показателей; обычный вертикальный режим — для последовательного анализа. Размеры, которые пользователь меняет у себя, хранятся в браузере, а устойчивые настройки панели задаёт администратор.
Подробнее: База знаний: дашборды
Расчётная строка на дашборде по формуле
в интерфейсе
Строке задают формулу со ссылками на другие строки в квадратных скобках: [Выручка]-[Себестоимость]; значения пересчитываются на экране.
- Откройте строку панели на редактирование формулы (через модальное окно).
- Впишите формулу, где другие строки названы в квадратных скобках, например
[Выручка]-[Себестоимость]. - Сохраните: связанные ячейки пересчитаются.
- Допускается и запись по id:
[648]-[652]. - Имя строки сначала ищется в своей панели, затем по всей модели — при одноимённых строках в разных панелях ссылка неоднозначна, поэтому держите имена строк уникальными.
[]— значение берётся из источника как есть;[-1],[-2]— смещения по соседним ячейкам в режимеformulas.- Вручную можно ввести значения плана, прогноза или корректировки прямо в ячейку.
Подробнее: База знаний: дашборды
Сводная таблица на дашборде
в интерфейсе
Выберите для панели вид «Сводная таблица» и назначьте поля: строки, колонки и значения.
- Подключите к панели отчёт, в котором есть нужные измерения и числа (например, «Месяц», «Департамент», «Количество»).
- Откройте «Варианты отображения» и выберите тип «Сводная таблица».
- Назначьте поля: что в строках, что в колонках, что считаем значениями.
- Сохраните настройки панели.
Сводная таблица удобна, когда нужно пересечение двух разрезов, например «Месяц × Департамент» с условными счётчиками. Библиотека сводных подгружается при первом открытии такой панели.
Подробнее: База знаний: дашборды
Добавить примечание к панели
в интерфейсе
У панели есть поле «Сноски» — текст в простом Markdown, который показывается рядом с данными.
- Откройте настройки панели.
- В поле «Сноски» напишите пояснение: методику расчёта, источник данных, инструкцию пользователю.
- Используйте списки, выделение и ссылки Markdown и сохраните.
Подробнее: База знаний: дашборды
Создать модель дашборда по API: порядок вызовов
для разработчика
Модель собирается иерархией Дэшборд → Лист → Панель → Строка плюс RG; структуру и числа рабочее место читает двумя отчётами.
- Заполните справочники: периоды (Месяц, Квартал, Год с границами «С» и «По»), «Колонка группы» («Факт»/«План»), «Строка бюджета», «Тип RG».
- Создайте дашборд, затем лист (
up— id дашборда), панель (up— id листа). - Добавьте группу колонок RG и строки панели, вычисляемым строкам задайте формулу.
- Запишите числа таблицы «Значение» по одной записи на период.
- Проверьте
report/Дэшборд?JSON_KV&FR_modelID={id}: в ответе должны быть ключиperiod,RGtype,RGcolumns— смотрите наличие ключа, а не значение.
POST /mydb/_m_new/559?JSON=1 up=1 t559=Продажи t560=01.01.2024 t561=31.12.2025 t562={id «Квартал»}
POST /mydb/_m_new/551?JSON=1 up={dashId} t551=P&L t555={id «Квартал»}
POST /mydb/_m_new/537?JSON=1 up={sheetId} t537=Финансовые результаты
Идентификаторы таблиц даны из демо-базы; в своей базе берите их из metadata. Контракт отчёта — это его «Имена в отчёте»: колонка без имени или со «Скрыть» в ответ не попадает, и модель рисуется пустой. Для RGtype берут «Код» типа RG (rg, value, col, …), а не название. Значения связываются со строкой по имени строки и «Метке».
Подробнее: База знаний: дашборды
Шаблоны, рабочие места и меню
Свои страницы и рабочие места из HTML-шаблонов с данными запросов, подключение скриптов и стилей, меню ролей, главная страница, файлы базы и их резервные копии.
Как Интеграм собирает страницу рабочего места
в интерфейсе
Рабочее место — это HTML-файл базы с блоками и точками вставки. Ядро вставляет его в оболочку main.html, заполняет блоки строками запросов и отдаёт готовую страницу.
- Адрес имеет вид
https://ideav.ru/mydb/orders/42:mydb— база,orders— имя шаблона (action),42— id объекта (необязательно). - Ядро загружает оболочку
main.html: шапку, меню роли, подключение скриптов. - Маркер
<!-- File: a -->в оболочке заменяется файломorders.html; если такого файла нет, берётсяinfo.html. - В файле находятся блоки
<!-- Begin: Имя -->…<!-- End: Имя -->; каждый блок получает строки запроса базы с тем же именем. - Блок повторяется по строкам, значения встают на места
{колонок}, готовый HTML уходит в браузер.
PHP внутри шаблона не выполняется, кеша шаблонов нет: файл читается с диска на каждый запрос, поэтому загруженная правка видна сразу.
Подробнее: Шаблонизатор: путь от адреса до страницы
Сделать своё рабочее место за три шага
в интерфейсе
Нужны три вещи: запрос с данными, HTML-файл с блоком того же имени и пункт меню роли с адресом файла.
- Сделайте в базе запрос
Ordersс колонкамиnum,client,sum. - Создайте файл
orders.html(код ниже) и загрузите его в меню «Файлы» в папку шаблонов (templates). - Добавьте роли пункт меню с адресом
orders(имя файла без.html). - Откройте
https://ideav.ru/mydb/orders; для проверки фильтра добавьте в адрес?FR_client=Иванов.
<h1>Заказы — {_global_.user}</h1>
<table>
<!-- Begin: Orders -->
<tr><td>{num}</td><td>{client}</td><td>{sum}</td></tr>
<!-- End: Orders -->
</table>
Подробнее: Шаблонизатор: рабочее место за три шага
Загрузить HTML-шаблон в базу
в интерфейсе
Шаблоны загружаются файловым менеджером dir_admin (меню «Файлы») в папку шаблонов базы; по API — с флагом templates=1.
- Откройте меню «Файлы» базы (адрес
/mydb/dir_admin). Нужно право на объект «Файлы» либо вход владельцем базы. - Выберите дерево шаблонов и загрузите файл формой «Загрузить файл»; для замены существующего поставьте «Перезаписать».
- Откройте страницу
/mydb/<имя файла без .html>и убедитесь, что блоки отрисовались.
То же по API. Кроме заголовка нужны кука idb_mydb, поля token и _xsrf; без куки сервер отвечает InvalidToken.
curl -sS -H "X-Authorization: $TOKEN" -b "idb_mydb=$TOKEN" \
-F templates=1 -F add_path= -F upload=Загрузить -F rewrite=1 \
-F "_xsrf=$XSRF" -F "token=$TOKEN" \
-F userfile=@orders.html \
"https://ideav.ru/mydb/dir_admin/"
Для файла в подпапке add_path указывайте в адресе запроса (…/dir_admin/?download=1&add_path=/css): в теле POST ядро его игнорирует, и файл молча уедет в корень. Если папки нет, менеджер тоже работает с корнем: создайте её заранее. После загрузки проверьте результат чтением gf=<имя>.
Подробнее: API: файловый менеджер · Шаблонизатор: где лежат шаблоны
Править файл шаблона в редакторе без выгрузки
в интерфейсе
В списке файлов dir_admin у каждого файла есть значки: запустить шаблон, редактировать в новом окне, скопировать имя для меню.
- Откройте «Файлы» базы и нужное дерево (шаблоны или download).
- Нажмите значок редактирования у файла: он откроется в редакторе в новом окне.
- Сохраните правку и обновите страницу рабочего места: шаблоны не кешируются и правка видна сразу.
- Значок «Запустить шаблон» открывает страницу рабочего места, «Скопировать имя шаблона» кладёт в буфер имя для пункта меню.
Для скриптов есть и второй редактор (значок рядом с файлом .js). Содержимое любого файла можно прочитать запросом …/dir_admin/?templates=1&add_path=/&gf=<имя>.
Для проверки, что файл существует, не открывайте его адрес напрямую: на несуществующий путь может прийти HTTP 200 со страницей-заглушкой. Проверяйте чтением через gf=.
Подробнее: API: файловый менеджер
Добавить рабочее место в меню роли
в интерфейсе
Пункт меню роли хранит адрес рабочего места: имя шаблона без .html. Пункт «orders» ведёт на /mydb/orders.
- Откройте любую страницу базы под администратором и нажмите значок настройки меню внизу левой панели (подсказка «Редактировать меню»).
- Выберите роль, для которой правите меню.
- Добавьте пункт: название и адрес, то есть имя шаблона без
.html(дляorders.html—orders). - Зайдите пользователем этой роли и проверьте, что пункт открывает страницу.
То же по API: меню — подчинённая таблица роли (тип 151). Название — реквизит t151, адрес — t153, иконка — t391 (HTML-тег; передавайте через --form-string, иначе curl ломает значение).
curl -s -H "X-Authorization: $TOKEN" -d "_xsrf=$XSRF" -d "up=<id роли>" \
-d "t151=Заказы" -d "t153=orders" "https://ideav.ru/mydb/_m_new/151?JSON=1"
Пользователь видит меню своей роли; доступ к данным определяют права роли, а не наличие пункта в меню.
Подробнее: Шаблонизатор: рабочее место в меню роли
Вывести таблицу из запроса на своей странице
в интерфейсе
Оберните строку таблицы в блок с именем запроса: Begin и End. Блок повторится столько раз, сколько строк вернул запрос.
- Убедитесь, что в базе есть запрос, и запомните его имя и заголовки колонок.
- В шаблоне напишите
<!-- Begin: Имя запроса -->, затем разметку строки с{колонками}, затем<!-- End: Имя запроса -->. - Имя блока должно совпадать с именем запроса символ в символ; если имя не подходит под правила, назовите блок числовым id запроса.
- Откройте страницу: сколько строк вернул запрос, столько раз повторится кусок между Begin и End.
<!-- Begin: Orders -->
<tr><td>{num}</td><td>{client}</td></tr>
<!-- End: Orders -->
- Разделители строгие:
<!--с пробелом в начале и-->с пробелом в конце; регистр словBegin/Endне важен. - В имени блока допустимы латиница, кириллица, цифры,
_и пробел; дефис, точка и буква «ё» не распознаются. - Скрытые колонки запроса в шаблон не попадают; фильтры, сортировку и права роли считает запрос.
Подробнее: Шаблонизатор: блоки · Шаблонизатор: блок равно запрос
Показать заказ и его позиции (вложенные блоки)
для разработчика
Вложите блок позиций в блок заказов и отфильтруйте запрос позиций по значению заказа через _parent_.колонка.
- Сделайте запрос
Orders(заказы) и запросOrder items(позиции) с колонкой, связывающей позицию с заказом. - В фильтре запроса
Order itemsпо этой колонке укажите значение_parent_.num(колонкаnumтекущей строки внешнего блока). - В шаблоне вложите
<!-- Begin: Order items -->…<!-- End: Order items -->внутрь блокаOrders.
<!-- Begin: Orders -->
<h3>Заказ {num} — {client}</h3>
<ul>
<!-- Begin: Order items -->
<li>{product}: {qty} шт.</li>
<!-- End: Order items -->
</ul>
<!-- End: Orders -->
Вложенный запрос выполняется заново на каждую строку внешнего блока: сто заказов — сто запросов позиций. Для длинных списков лучше один плоский запрос.
Подробнее: Шаблонизатор: запрос внутри запроса
Подставить значение на страницу: колонка, родитель, параметр
в интерфейсе
Значение вставляется записью в фигурных скобках: колонка запроса, колонка внешнего блока (_parent_), параметр адреса (_request_) или переменная сессии (_global_).
{колонка}— значение колонки текущей строки запроса этого блока (по заголовку колонки).{_parent_.колонка}— колонка текущей строки ближайшего внешнего блока, у которой она есть.{_request_.имя}— параметр адреса или формы (если пришёл и в POST, и в GET, побеждает POST).{_global_.имя}— переменная сессии и окружения; неизвестное имя даёт пустую строку.
Значения колонок экранируются, переводы строк становятся <br/>. Исключение — колонки базового типа HTML: они вставляются как есть. {_request_.имя} вставляется без экранирования, поэтому не выводите параметры адреса в разметку напрямую.
Подробнее: Шаблонизатор: плейсхолдеры
Показать на странице имя пользователя, роль и базу
в интерфейсе
Используйте переменные {_global_.user}, {_global_.role}, {_global_.z} и другие: ядро подставляет их при сборке страницы.
- Впишите нужную переменную в разметку шаблона, например
<p>Вы вошли как {_global_.user}, роль {_global_.role}</p>. - Откройте страницу под разными пользователями и убедитесь, что значения меняются.
| Переменная | Значение |
|---|---|
{_global_.z} | имя базы |
{_global_.user}, {_global_.user_id} | логин и id пользователя |
{_global_.role}, {_global_.role_id} | роль и её id |
{_global_.action}, {_global_.id} | рабочее место и id объекта из адреса |
{_global_.token}, {_global_.xsrf} | токен сессии и XSRF — для запросов из JavaScript |
{_global_.version} | версия ядра, нужна для сброса кеша ресурсов |
Подробнее: Шаблонизатор: переменные _global_
Подставить сегодняшнюю дату и вчерашнюю на страницу
в интерфейсе
Переменные {_global_.today}, now, yesterday, tomorrow, week_ago, month_ago, month_plus дают даты в формате дд.мм.гггг с учётом часового пояса.
- Впишите переменную в нужное место, например в значение поля:
<input name="FR_date" value="{_global_.today}">. - Для фильтров самих запросов используются встроенные слова
[TODAY],[NOW],[YESTERDAY],[TOMORROW],[MONTH_AGO],[MONTH_PLUS]— они пишутся в условиях запроса, а не в шаблоне.
Список переменных зависит от ядра установки: если шаблон использует переменную, которой в ядре ещё нет, плейсхолдер остаётся неподставленным и блок исчезает. Сначала обновляйте ядро, потом шаблоны.
Подробнее: Шаблонизатор: переменные _global_
Отфильтровать страницу параметром в адресе
в интерфейсе
Добавьте к адресу FR_колонка=значение: фильтр применится к запросам всех блоков страницы, у которых есть такая колонка.
- Откройте страницу и допишите к адресу
?FR_client=Иванов(FR_— «от»,TO_— «до»; пробелы в имени колонки заменяются на_). - Для сортировки и итогов доступны также
ORDER,SELECT,TOTALS,WHERE. - Чтобы дать пользователю готовую ссылку, поместите такой адрес в меню или в
<a href>шаблона.
https://ideav.ru/mydb/orders?FR_client=Иванов
Фильтр действует на ВСЕ блоки-запросы страницы, у которых есть колонка с таким именем: если две таблицы используют колонку client, сузятся обе.
Подробнее: Шаблонизатор: фильтры из адреса · Запросы
Форма поиска на странице, которая вызывает сама себя
в интерфейсе
Форма отправляется на адрес собственного рабочего места методом GET; введённые поля FR_… становятся фильтрами запроса блока.
- Добавьте на страницу
<form action="/{_global_.z}/store">, гдеstore— имя вашего шаблона. - Назовите поля формы как фильтры колонок:
FR_CODE,FR_FIRMи т. д. - Для сканера штрих-кодов задайте у поля
autofocus: после Enter или сканирования форма отправится сама. - Ниже поместите блок с запросом, у которого есть эти колонки: он покажет только подходящие строки.
<form action="/{_global_.z}/store">
<input name="FR_CODE" autofocus placeholder="Штрих-код">
</form>
<!-- Begin: Store -->
<tr><td>{CODE}</td><td>{FIRM}</td></tr>
<!-- End: Store -->
Подробнее: Шаблонизатор: фильтры из адреса
Показать кусок страницы только при условии
для разработчика
Условий if/else нет. Блок не выводится, когда у него нет строк или в строке остался неподставленный плейсхолдер: на этом строятся все приёмы.
- Чтобы показать сообщение только при наличии параметра, оберните его в локальный блок (имя начинается с
_) и поставьте в нём{_request_.имя}. - Чтобы спрятать блок при пустом запросе, держите в нём хотя бы одну колонку запроса (например,
<!--{num}-->): без строк блок не выведется. - Блок без колонок выводится всегда один раз, даже если запрос пуст: нет незаполненных точек — значит, блок показан.
<!-- Begin: _Msg -->
<div class="alert">Сохранено: {_request_.saved}</div>
<!-- End: _Msg -->
{_global_.имя} блок НЕ прячет: неизвестная глобальная переменная подставляется пустой строкой.
Подробнее: Шаблонизатор: условий нет
Блок на странице пустой или пропал: чек-лист
в интерфейсе
Чаще всего виноваты имя блока, заголовок колонки или фигурные скобки в JS. Откройте страницу с ?debug=1: неподставленные {…} останутся на ней.
- Проверьте, что имя блока совпадает с именем запроса символ в символ, без «ё», дефиса и точки.
- Проверьте, что запрос возвращает строки под этой ролью и с этими фильтрами адреса.
- Проверьте, что все
{колонки}блока есть среди заголовков колонок запроса и не скрыты. Кириллицу писать в том же регистре, что в заголовке: регистр кириллицы ядро не выравнивает (латиница без учёта регистра). - Проверьте, нет ли в блоке
{слов}из JS или CSS без пробелов вокруг (см. отдельную статью). - Проверьте, что
BeginиEndзакрыты в правильном порядке; иначе будет ошибка «Invalid blocks nesting». - Откройте страницу с
?debug=1и найдите оставшиеся{...}: опечатка в имени колонки не даёт ошибки, блок просто пустеет.
Если шаблон использует переменную, которой в ядре нет, блок исчезнет вместе с вложенными. Обновляйте ядро раньше шаблонов.
Подробнее: Шаблонизатор: если блок пустой
Скрипт или стиль на странице ломает вывод блока
для разработчика
Ядро считает плейсхолдером любые скобки, в которых только буквы, цифры, пробелы и знаки . _ - &. Такие куски в JS и CSS нужно переписать или вынести в файл.
- Найдите в шаблоне места вроде
{id},{ id },{ return }и${name}: ядро примет их за колонки, не найдёт и выбросит строку блока или весь блок. - Начинайте тело функции с новой строки после
{; безопасны скобки, где внутри есть другой знак:{ color: red; },{ a: 1 }. - Строки собирайте конкатенацией, а не шаблонными строками JS; допустимы только
{_global_.*},{_parent_.*},{_request_.*}. - Лучше всего вынесите большие скрипты и стили в файлы
downloadи подключите ссылкой: туда шаблонизатор не заглядывает.
Точки вставки обрабатываются во всём тексте файла, включая HTML-комментарии и строки. Не пишите в комментарии шаблона {слово} или пути вида templates/custom/{db}/ — пишите <база>.
Проверить, какие фрагменты ядро воспримет как точки вставки, можно регулярным выражением {([A-ZА-Я0-9\.&_ \-]*?[^ ;\r\n])} (флаги gmiu).
Подробнее: Шаблонизатор: фигурные скобки в JS и CSS
Данные в JS-строке или в разметке: кавычки и экранирование
для разработчика
Значения колонок экранируются, но внутри JS-строки в одинарных кавычках апостроф в данных может её сломать. Берите двойные кавычки или читайте данные через JSON.
- Не подставляйте колонку в JS-строку в одинарных кавычках (
'{name}'): на PHP до 8.1 апостроф в данных не экранируется. - Используйте двойные кавычки или получайте данные отдельным JSON-запросом из скрипта.
- Для вставки разметки из базы заведите колонку базового типа HTML: такие значения вставляются как есть, поэтому доверяйте только автору базы.
- Параметры адреса
{_request_.имя}не выводите в разметку напрямую; передавайте их фильтром в запрос, где ядро их экранирует.
Подробнее: Шаблонизатор: экранирование
Вставить общий кусок страницы (шапку) в несколько шаблонов
для разработчика
Маркер <!-- File: header --> вставляет файл header.html; поиск идёт сначала в папке базы, потом в общей папке шаблонов.
- Вынесите общий фрагмент в файл
header.htmlи загрузите его в шаблоны базы. - В нужных шаблонах впишите
<!-- File: header -->(имя без расширения.html). - Открывайте страницы: вставленный файл разбирается целиком, в нём работают свои блоки и вставки.
Имя a особое: <!-- File: a --> вставляет файл текущего рабочего места по адресу (на этом устроен main.html).
Подробнее: Шаблонизатор: вставка файлов
Свой шаблон для одной базы вместо общего (templates/custom)
для разработчика
Ядро ищет файл сначала в templates/custom/<база>/, потом в общей templates/: одноимённый файл базы перекрывает общий.
- Скопируйте содержимое общего шаблона (например
info.htmlилиmain.html) и сохраните под тем же именем в папку шаблонов своей базы через «Файлы». - Внесите правки; они коснутся только этой базы.
- Чтобы вернуть стандартное поведение, удалите файл из папки базы.
Файлы из подпапок templates/custom/<база> в шаблон базы (фиксацию как шаблона) не попадают: подпапки служебные (backups, logs). Держите шаблоны рабочих мест в корне.
Подробнее: Шаблонизатор: где лежат шаблоны
Изменить шапку и оформление всех страниц базы (свой main.html)
для разработчика
Оболочка main.html одна на все страницы: положите её копию в папку шаблонов базы и правьте. Файл базы перекрывает общий.
- Скопируйте стандартный
main.htmlв шаблоны своей базы. - Меняйте в нём стили, шапку и подключение скриптов. Маркер
<!-- File: a -->(место рабочего места) и блокMyRoleMenu(данные меню) не удаляйте. - Фоновый рисунок: в шаблоне есть подсказка поменять путь в
background-imageна свой файл изdownload. - Проверьте, что страница открывается под разными ролями.
Ошибка в main.html (например {слово} в комментарии) гасит все страницы базы у всех пользователей. Правьте аккуратно и проверяйте сразу.
Подробнее: Шаблонизатор: где лежат шаблоны
Подключить свой JS и CSS (папка download)
для разработчика
Скрипты и стили загружаются в дерево download базы и раздаются по адресу /download/<база>/…; подключаются в шаблоне обычными script и link.
- Загрузите файл в дерево
downloadчерез «Файлы» (по API — флагdownload=1). - Подключите в шаблоне:
<script src="/download/{_global_.z}/js/app.js?{_global_.version}.1" defer></script>и<link rel="stylesheet" href="/download/{_global_.z}/css/app.css?{_global_.version}.1">. - После каждой правки файла увеличивайте счётчик в конце версии (см. статью о кеше).
Адрес файла из download=1 — https://ideav.ru/download/mydb/<путь>. Шаблонизатор в файлы download не заглядывает, поэтому фигурные скобки там безопасны.
В download и templates выполнение серверных скриптов отключено, а список допустимых расширений ограничен. Право писать в файлы позволяет подменить код приложения, поэтому выдавайте его адресно.
Подробнее: API: файловый менеджер
Правка скрипта или стиля не видна пользователям (версия ?version)
для разработчика
Браузер кеширует js и css по адресу. Меняйте адрес при каждой правке: добавьте к ссылке ?{_global_.version}.N и увеличивайте N.
- Подключайте ресурс как
src="/download/{_global_.z}/js/app.js?{_global_.version}.N"(версия ядра, точка, ваш счётчик). - После каждой правки файла увеличьте
Nна 1 в шаблоне, где ресурс подключён; если файл подключён из нескольких шаблонов, в каждом. - Если ссылка была без счётчика (
?{_global_.version}или?0{_global_.version}), переведите её на?{_global_.version}.N, начав с.1. - Обновите страницу пользователя жёстко (Ctrl+F5) и проверьте, что скрипт новый.
Комментарий // @version внутри скрипта кеш не сбрасывает: его никто не читает при рендере. Счётчик нужен в адресе ресурса.
Подробнее: Шаблонизатор: переменные _global_
Дать скрипту страницы токен и XSRF для запросов к API
для разработчика
Положите в разметку страницы значения {_global_.z}, {_global_.xsrf}, {_global_.user} и прочитайте их скриптом; запись данных идёт командами _m_*, чтение отчётов — report/Имя?JSON_KV.
- Сделайте в шаблоне контейнер с data-атрибутами:
data-db="{_global_.z}",data-xsrf="{_global_.xsrf}",data-user="{_global_.user}". - Подключите скрипт из
download(с версией, см. статью о кеше). - В скрипте прочитайте атрибуты контейнера и отправляйте запросы с
_xsrf; изменяющие запросы — только POST.
<div id="my-app" data-db="{_global_.z}" data-xsrf="{_global_.xsrf}" data-user="{_global_.user}">
Загрузка…
</div>
<script src="/download/{_global_.z}/js/my-app.js?{_global_.version}.1" defer></script>
Токен лежит в странице и виден пользователю; не кладите в шаблон чужие токены и пароли. Права на запись по-прежнему проверяет ядро по роли.
Подробнее: Шаблонизатор: JSON-режим и JavaScript · Справочник API
Получить данные рабочего места в JSON вместо HTML
для разработчика
Любой параметр адреса, начинающийся с JSON, переключает ответ: страница считается как обычно, но вместо HTML уходят данные блоков.
- Добавьте к адресу рабочего места
?JSON=1. - Вызовите адрес с токеном: для каждого блока придёт массив значений его плейсхолдеров.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/orders?JSON=1"
Подробнее: Шаблонизатор: JSON-режим
Рабочее место-пульт на JavaScript (оператор, планшет)
для разработчика
Шаблон пульта — тонкая оболочка: контейнер с data-атрибутами, подключение css и js из download. Вся логика и данные — в скрипте через API.
- Создайте шаблон из контейнера с
data-db,data-xsrf,data-userи надписью «Загрузка…» (как в статье про токен и XSRF). - Подключите стили и скрипт пульта из
downloadс версией?{_global_.version}.N. - В скрипте читайте данные отчётами и пишите записи командами
_m_*; сам скрипт отрисует интерфейс в контейнер. - Добавьте пункт меню роли оператора с адресом шаблона и проверьте под токеном этой роли: у администратора права полные, отказов он не увидит.
- Пишите стили в
.css, скрипты в.js; инлайн оставляйте только для короткой инициализации. - Не используйте
alert,confirm,prompt: показывайте модальные окна самой страницы. - При каждой правке скрипта поднимайте счётчик версии в ссылке, иначе пульт у оператора останется старым.
Подробнее: Шаблонизатор: JSON-режим и JavaScript
Изменить главную страницу базы
в интерфейсе
Главная страница базы — шаблон info.html: он подставляется, когда в адресе нет рабочего места или файла с таким именем нет. Отредактируйте его в «Файлах».
- Откройте «Файлы» базы и найдите
info.htmlв шаблонах (если файла в папке базы нет, скопируйте общий и сохраните под тем же именем). - Откройте его в редакторе и поменяйте текст, ссылки и оформление.
- Откройте
/mydb/и проверьте результат под пользователями разных ролей.
Если у роли ровно один пункт меню, пользователь не видит меню вовсе, а с корня базы уходит прямо в этот пункт. Админский вид правило не трогает.
Подробнее: Шаблонизатор: путь от адреса до страницы
Сделать меню сверху вместо левого
для разработчика
По умолчанию меню левое. Файл _menu_layout.html в шаблонах базы со словом auto, top или left переключает раскладку.
- Создайте в шаблонах базы файл
_menu_layout.htmlчерез «Файлы» и запишите в него одно слово:auto,topилиleft. auto: у админа левое меню, у остальных разделы в шапке (подпункты выпадающими списками), пока разделов верхнего уровня не больше 7 и нет третьего уровня; иначе левое.topиleft— всегда верхнее или всегда левое. Иное содержимое файла не учитывается.- Для собственного
main.htmlраскладку задаёт атрибут<html data-menu-layout="top|left|auto">: он сильнее файла.
На экране до 900 px меню всегда в выдвижной панели. Тот, у кого есть право правки меню, видит левое меню: правка живёт там.
Подробнее: Шаблонизатор: рабочее место в меню роли
Меню роли пустое или без подписей
для разработчика
Меню строит блок MyRoleMenu в main.html по запросу MyRoleMenu базы. Пустое меню — признак запроса в старом формате колонок.
- Проверьте, что запрос
MyRoleMenuотдаёт колонки в нижнем регистре:menu_id,menu_up,name,href,icon(проверка —report/MyRoleMenu?JSON_KV). - Если колонки названы по-старому (
Name,HREF), строка блока с незаполненной точкой отбрасывается и меню пустое: приведите запрос к этому формату. - Для суперпользователя
admin(вход по хэшу пароля сервера) ядро само подставляет меню роли admin; явно переданныйFR_RoleIDне перекрывается. - Проверьте, что у пользователя назначена роль и у роли есть пункты меню.
Подробнее: Шаблонизатор: рабочее место в меню роли
Публичная страница базы для гостей без входа
для разработчика
Гость работает под пользователем guest с ролью guest. Если у роли ровно один пункт меню, сайдбар скрыт, а корень базы ведёт на этот пункт.
- Заведите пользователя
guest(таблица 18) и рольguestи назначьте пользователю эту роль. - Выдайте роли права только на нужные таблицы и отчёты.
- Добавьте роли ровно один пункт меню (таблица 151,
t153— имя шаблона страницы, напримерafisha). - Откройте корень базы без входа: страница показывается без бокового меню и кнопки «Войти».
Нет пользователя guest, у него нет роли или роль не guest — страница уводит на вход, а JSON API отвечает 401. Если пунктов больше одного, страница покажется внутри обычной оболочки с меню.
Подробнее: Шаблонизатор: рабочее место в меню роли
Как страницы выглядят на телефоне и планшете
в интерфейсе
Оболочка main.html содержит viewport; на экране до 900 px меню уходит в выдвижную панель с кнопкой-гамбургером, размер шрифта переключается пользователем.
- Откройте приложение на телефоне: меню спрятано в выдвижной панели, открыть её можно кнопкой-гамбургером в шапке.
- Размер шрифта страницы пользователь выбирает кнопками в шапке (мелкий, обычный, крупный); выбор хранится в куке браузера.
- Для своих шаблонов задайте адаптивные стили в
.cssизdownloadи проверьте страницу на узком экране.
Если у роли один пункт меню, на мобильном нет и гамбургера: пользователь сразу попадает на страницу этого пункта.
Подробнее: Шаблонизатор: путь от адреса до страницы
Печатная форма: сумма и дата прописью
для разработчика
Печатный документ — обычный шаблон с блоком по запросу; сумму и дату прописью считает вычисляемая колонка запроса с функциями abn_RUB2STR, abn_NUM2STR, abn_DATE2STR.
- В запросе, на котором строится документ, добавьте вычисляемую колонку с функцией:
abn_RUB2STR— сумма с рублями и копейками,abn_NUM2STR— число прописью,abn_DATE2STR— дата в виде «5 мая 2004 г.». - Полный список функций смотрите в меню «Таблицы» → «Функция».
- В шаблоне выведите колонку плейсхолдером внутри блока этого запроса и оформите страницу как документ.
- Распечатайте страницу средствами браузера.
Подробнее: Шаблонизатор: блок равно запрос · Запросы
Дать сотруднику доступ к файловому менеджеру
для разработчика
Доступ к файлам даёт особый объект 10 (Files) в правах роли: READ для просмотра, WRITE для загрузки. Владелец базы имеет доступ без грантов.
- Добавьте роли грант на объект
10(таблица 116:t116=10,t136— 53 для READ или 54 для WRITE). - Выдавайте WRITE адресно: он позволяет загрузить код во фронт приложения.
- Проверьте вход под токеном этой роли: без права загрузка отвечает «Недостаточно прав для загрузки файлов».
Подробнее: API: файловый менеджер
Сделать резервную копию шаблонов, скриптов и стилей
для разработчика
Адрес /<база>/code_backup кладёт архив .code.zip с шаблонами и фронтом базы в папку backups; восстанавливает его значок в dir_admin.
- Откройте
https://ideav.ru/mydb/code_backupпод владельцем базы или пользователем с правом экспорта. - Архив появится в
backupsфайлового менеджера: в нём шаблоны из корня папки базы, фронт из корняdownload(js, css, conf, json, html) и подпапкиdownloadцеликом. - Для отката нажмите у архива значок «Восстановить файлы» в
dir_adminи подтвердите вводом имени базы. Текущие файлы перед этим сохранятся страховочным архивом.
Восстановить файлы может владелец базы или супер-админ сервера. Файлы вне архива не удаляются, одноимённые перезаписываются.
Подробнее: API: файловый менеджер и резервная копия
Где лежат файлы, загруженные пользователями в поля «Файл»
для разработчика
Файлы из полей записей складываются в хэш-подкаталоги download/<база>/…; имя файла строится из системного id, поэтому по имени угадать адрес нельзя.
- Откройте «Файлы» → дерево
download: загруженные файлы лежат в подкаталогах вида<цифры+8hex>/<NNN+8hex>.<расширение>. - Имя файла — последние три цифры id плюс шифр, папка — остальные цифры id плюс шифр; шифр зависит от имени базы.
- Ссылки на такие файлы берите из значения поля записи, а не собирайте вручную.
Раздача файлов: всё, кроме растровых картинок, отдаётся как вложение (скачивание), а html, svg и xml — ещё и с Content-Security-Policy: sandbox. Статика приложения в корне download/<база> (скрипты, стили) таким правилам не подчинена.
Сохранить базу с готовыми страницами как шаблон для новых баз
для разработчика
Владелец базы фиксирует версию в dir_admin («Шаблон базы»); после модерации шаблон выбирается при создании новой базы. В копию входят данные и файлы базы, но не пользователи и пароли.
- Откройте «Файлы» базы и меню «Шаблон базы».
- Задайте имя шаблона (латиница и цифры, до 15 символов, начинается с буквы) и нажмите «Зафиксировать версию».
- Дождитесь решения модератора: после одобрения шаблон появляется в Личном кабинете в списке «Шаблон» при создании базы.
- Правки исходной базы в шаблон не попадают: чтобы обновить, фиксируйте новую версию.
Шаблоны рабочих мест держите в корне templates/custom/<база>: файлы из подпапок в копию не попадают.
Роли, права и пользователи
Кто что видит и меняет в базе: роли, права на таблицы, колонки, запросы и файлы, ограничение строк, пользователи, вход и токены, личный кабинет, совместная работа и журнал действий.
Как устроены роли и права: с чего начать
в интерфейсе
Доступ строится из трёх вещей: роль у пользователя, права роли на таблицы, колонки и запросы, и меню роли. У каждого пользователя одна роль.
- Заведите роль в таблице «Роль» (например, «Менеджер»).
- Выдайте роли права на нужные таблицы, колонки и запросы: чтение, запись или запрет.
- При необходимости добавьте маску, чтобы роль видела только часть строк, например только свои.
- Соберите меню роли: какие рабочие места она увидит.
- Создайте пользователя в таблице «Пользователь» и назначьте ему роль.
Роли, пользователи, меню и запросы — обычные системные таблицы базы. Права роли на объекты хранятся в подчинённой ей таблице «Объекты»: объект, уровень и необязательная маска.
| Таблица | id | Что в ней |
|---|---|---|
| Роль | 42 | название и описание роли |
| Пользователь | 18 | логин, роль, пароль, имя, email |
| Меню | 151 | пункты меню, подчинены роли |
| Объекты | 116 | права роли: объект, уровень, маска |
Роль admin (id 145) и технический пользователь с логином, равным имени базы, имеют полный доступ в обход прав.
Подробнее: API: системные таблицы · Права доступа из коробки
Создать роль
для разработчика
Роль — запись таблицы «Роль» (id 42): название в t42, описание в t135, родитель up=1.
- Получите токен и
_xsrf(см. «Токен API» и «Токен XSRF»). - Вызовите
_m_new/42с названием и описанием роли. - Запомните id из ответа: он нужен, чтобы выдавать права и создавать пользователей.
curl -s "https://ideav.ru/mydb/_m_new/42?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
-F "up=1" -F "t42=Менеджер" -F "t135=Ведёт клиентов и заказы"
Найти id роли по названию: object/Роль?JSON_OBJ&F_Роль=Менеджер. Роль можно создать и вместе с правами одним вызовом _d_schema, ключ roles.
Подробнее: API: создать роль · API: схема одним запросом
Добавить пользователя и назначить роль
для разработчика
Пользователь — запись таблицы «Пользователь» (id 18): логин t18, роль t115, пароль t20, имя t33, email t41.
- Создайте роль или возьмите id существующей.
- Вызовите
_m_new/18: логин, роль, пароль, имя, email. - Передайте сотруднику логин и пароль; вход — на странице базы или через
auth.
curl -s "https://ideav.ru/mydb/_m_new/18?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
-F "up=1" -F "t18=ivanov" -F "t115=900" -F "t20=Str0ng-Pass" \
-F "t33=Иван Иванов" -F "t41=ivanov@example.com"
Пароль сохраняется хешем, прочитать его обратно нельзя. Служебные поля пользователя (Activity t124, xsrf t40, счётчик неудачных входов t301) заполняет сервер, их не задавайте.
Подробнее: API: создать пользователя
Сменить роль или пароль пользователя
для разработчика
Роль и пароль меняются через _m_set с id пользователя. Смена пароля закрывает все сессии этого пользователя.
- Найдите id пользователя:
object/18/?JSON_OBJ. - Для новой роли отправьте
_m_set/<id>с полемt115. - Для нового пароля отправьте
_m_set/<id>с полемt20.
curl -s "https://ideav.ru/mydb/_m_set/910?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "t115=901"
curl -s "https://ideav.ru/mydb/_m_set/910?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "t20=N3w-Pass"
Пользователя с логином, равным имени базы, переименовать и лишить роли admin нельзя: сервер это запрещает.
Подробнее: API: пользователь, пароль, роль
Дать роли доступ к таблице: чтение или запись
для разработчика
Право — запись таблицы «Объекты» (id 116), подчинённая роли: up — роль, t116 — таблица, t136 — уровень: 53 чтение, 54 запись, 52 запрет.
- Узнайте id роли и id таблицы (
metadata?JSON=1, список объектов —grants?JSON=1). - Вызовите
_m_new/116сup=<роль>,t116=<таблица>,t136=<уровень>. - Проверьте под токеном пользователя этой роли:
object/<таблица>/?JSON_OBJ.
| t136 | Уровень |
|---|---|
| 53 | READ — чтение |
| 54 | WRITE — чтение и изменение |
| 52 | BARRED — нет доступа |
curl -s "https://ideav.ru/mydb/_m_new/116?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
-F "up=900" -F "t116=641" -F "t136=54"
Те же права можно описать по именам таблиц одним вызовом _d_schema: {"table": "Клиент", "level": "WRITE"} в grants роли. Права роли смотрите так: object/116/?JSON_OBJ&F_U=<роль>.
Подробнее: API: выдать доступ · API: схема одним запросом
Скрыть колонку от роли
для разработчика
Выдайте роли доступ к таблице, а на нужную колонку — уровень BARRED (52). Колонка не придёт роли даже в API.
- Выдайте роли доступ к таблице (READ или WRITE).
- Узнайте id колонки в
metadata?JSON=1. - Создайте право:
_m_new/116сt116=<колонка>иt136=52.
Уровень таблицы наследуют её колонки; отдельной колонке его можно понизить. То же через _d_schema:
{"table": "Клиент", "field": "ИНН", "level": "BARRED"}
Скрытая колонка просто отсутствует в ответе без всякой пометки: роль не узнает даже о её существовании. Если клиентский код ждёт эту колонку, он её не найдёт.
Подробнее: API: выдать доступ
Разрешить роли менять структуру или видеть все таблицы
для разработчика
Кроме таблиц, в право можно вписать особые объекты: 0 — редактор структуры, 1 — все таблицы, 10 — файловый менеджер.
- Определите, что нужно: менять структуру, видеть все таблицы или работать с файлами.
- Создайте право
_m_new/116сt116=0,1или10и нужным уровнем. - Для команд
_d_*роли нужен WRITE на объект0.
| t116 | Что открывает |
|---|---|
| 0 | редактор структуры (Type editor) |
| 1 | все таблицы (All objects) |
| 10 | файловый менеджер (Files) |
Право на структуру и на файлы выдавайте адресно: запись в файловый менеджер позволяет загружать файлы фронта приложения.
Подробнее: API: выдать доступ
Новая таблица или справочник недоступны: 403 и пустой выпадающий список
для разработчика
Только что созданная таблица не выдана ни одной роли. Выдайте право сразу после создания всем ролям, чьи экраны её используют.
- Определите роли, чьи рабочие места читают или пишут новую таблицу.
- Для каждой роли создайте право
_m_new/116сt116=<id новой таблицы>:t136=53для чтения,54для записи. - Проверьте матрицей
object/<id>под токеном каждой роли, а не только под владельцем базы.
Под владельцем базы (логин равен имени базы) отказа не видно: у него полный доступ в обход прав. Поэтому дефект всплывает только у обычных ролей.
Роли-владельцу справочника обычно дают WRITE, остальным потребителям — READ.
Подробнее: API: выдать доступ
Роль получает 403, 404 или не видит колонку: как разобраться
для разработчика
403 на object/<id> — у роли нет READ на таблицу. Колонки нет в ответе — на неё стоит BARRED. 404 — такой таблицы нет.
- Выполните запрос под токеном проблемной роли, а не владельца.
- Если ответ 403: выдайте роли READ или WRITE на таблицу.
- Если не хватает колонки: проверьте, нет ли у роли права BARRED на этот реквизит.
- Если 403 «нет доступа … по маске»: запись вне маски роли, проверьте маску права.
- Посмотрите права роли:
object/116/?JSON_OBJ&F_U=<роль>.
| Симптом | Причина |
|---|---|
403 с телом [{"error":…}] | нет права READ на таблицу |
| колонки нет в ответе | у роли BARRED на реквизит |
| 404 | таблицы не существует |
| пустая страница в интерфейсе | нет права на таблицу |
| 403 «нет доступа … по маске» | запись не попадает под маску роли |
Если в одной записи _m_set вместе с разрешёнными полями уходит реквизит без права, сервер отвергает весь запрос целиком, и разрешённые поля тоже не сохраняются. Выдайте роли точечное право на колонку или не отправляйте её.
Подробнее: API: выдать доступ · API: маски
Разрешить или запретить роли выгрузку и удаление
для разработчика
В праве роли есть отдельные поля: t55 разрешает выгрузку, t56 — удаление.
- Найдите право роли на нужную таблицу:
object/116/?JSON_OBJ&F_U=<роль>. - Установите в нём
t55(экспорт) и/илиt56(удаление) через_m_set. - Через
_d_schemaте же флаги называютсяexportиdelete.
Выгрузка и массовое удаление данных разрешаются или запрещаются на уровне роли для конкретного объекта.
Резервная копия базы и файлов (backup, code_backup) требует права EXPORT, роли admin или владельца базы.
Подробнее: API: выдать доступ
Показывать сотруднику только его записи
для разработчика
Поставьте на право роли маску [USER_ID] на колонку-ссылку «Ответственный»: роль увидит только записи, где ответственный — она сама.
- В таблице должна быть колонка-ссылка на «Пользователь» (например, «Ответственный»).
- Узнайте id этой колонки (
metadata?JSON=1). - Создайте право
_m_new/116:up=<роль>,t116=<id колонки>,t136=54,t49=[USER_ID]. - Выдайте также право на саму таблицу.
- Проверьте под токеном пользователя этой роли.
# менеджер видит клиентов, где он ответственный (колонка 651 ссылается на Пользователя)
curl -s "https://ideav.ru/mydb/_m_new/116?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
-F "up=900" -F "t116=651" -F "t136=54" -F "t49=[USER_ID]"
Другие переменные маски: [USER] — логин, [ROLE] и [ROLE_ID] — роль. Маска [USER] на колонку 18 оставляет пользователю в таблице «Пользователь» только его собственную запись.
Маска действует в списках, API object/, выпадающих списках, карточке записи и при правке и удалении. Запись вне маски по id не откроется и не изменится: 403 «нет доступа … по маске». Маски на одну колонку складываются по ИЛИ, на разные колонки по И: лишняя маска может расширить видимость.
Подробнее: API: маски
Ограничить роль по значению поля: статус, префикс, список id
для разработчика
Маска в t49 работает как фильтр F_ по колонке из t116: значение, условие (<20002, %ООО%) или список id @IN(21006,21014).
- Выберите колонку, по которой нужно ограничить, и узнайте её id.
- Создайте право
_m_new/116сt116=<колонка>, нужным уровнем и маской вt49. - Проверьте результат под токеном роли.
| Маска | Смысл |
|---|---|
Иванов | значение колонки равно заданному |
%ООО% | значение содержит подстроку |
<20002 | условие сравнения |
164 | на ссылочной колонке — id записи-цели |
@IN(21006,21014) | список id записей |
Маски @N, !@N и @IN(…) на таблицу сравнивают id записи, а не её значение. Создаваемую запись маска на таблицу не задерживает.
Подробнее: API: маски
Видеть записи только своей компании через цепочку ссылок
для разработчика
Маска ставится на ссылочное поле своей таблицы и берёт список id из запроса. Новое поле «Компания» в таблицу добавлять не нужно.
- Создайте запрос, который возвращает id нужных записей одной строкой через
GROUP_CONCATс фильтром по id компании. - Дайте роли READ на таблицу (например, «Договор»).
- Создайте право на ссылочное поле («Договор → Заявка») с маской
@IN([Имя запроса]). - Для каждой компании заведите свою роль и свой запрос.
Ядро при каждом обращении пользователя выполняет запрос из маски и подставляет первую ячейку первой строки. Запрос выполняется без масок роли, поэтому всё, что сужает выборку, пишется фильтром в самом запросе.
{"table": "Договор", "level": "READ"}
{"table": "Договор", "field": "Заявка", "level": "READ", "mask": "@IN([Заявки alpha])"}
Один общий запрос без фильтра по компании вернёт заявки всех компаний.
Подробнее: API: маски · API: схема одним запросом
Дать роли доступ к запросу (отчёту)
для разработчика
Отчёт — такой же объект, как таблица: выдайте роли READ (t136=53) на запрос, иначе отчёт ей не виден.
- Узнайте id запроса (таблица 22) или его имя.
- Создайте право
_m_new/116:up=<роль>,t116=<id запроса>,t136=53. - Либо через
_d_schema:{"report": "Договоры", "level": "READ"}.
Запрос выполняется с правами владельца: грант на запрос открывает все его колонки, какие бы права у роли ни были на таблицы-источники. Выдавайте роли только запросы, все строки которых ей можно видеть.
Маска в праве на объект «Запрос» (тип 22) решает, какие отчёты роль может открыть, а не какие строки в них увидит.
Подробнее: API: доступ к запросам · API: выдать доступ
Показать в отчёте только строки текущего пользователя
для разработчика
Маски роли на колонки к отчёту не применяются: фильтр «только свои» ставится в самом запросе через [USER_ID].
- Откройте запрос и добавьте колонке с ответственным фильтр
[USER_ID]. - Выдайте роли право READ на этот запрос.
- Проверьте под токеном роли, что приходят только её строки.
Запрос выполняется с правами владельца, поэтому в таблице роль может видеть только свои записи, а в отчёте и в панели дашборда на этом отчёте — все. Рабочее место, которое читает таблицу, получает отфильтрованные строки; читающее отчёт — все строки отчёта.
Для строгих требований базовые ограничения дают в роли, а действия бизнес-процесса оформляют запросами: например, выдают роли READ только на запросы с префиксом user_.
Подробнее: API: доступ к запросам · API: маски
От чьего имени и с какими правами работает кнопка
для разработчика
Действие кнопки выполняется под учёткой нажавшего или под пользователем из настройки «Выполнять от имени». Запрос, который вызывает кнопка, работает с правами владельца.
- В настройке колонки-кнопки укажите действие (ссылка, запрос, промпт ИИ или формула).
- Если действие должно идти не под нажавшим, впишите логин в «Выполнять от имени»; пусто — текущий пользователь.
- Если кнопка вызывает запрос, выдайте роли READ на этот запрос.
- Проверьте кнопку под пользователем нужной роли.
Так кнопка может точечно менять то, что роли запрещено напрямую, например статус заказа: логику фиксирует запрос, а роли выдают только право его вызвать.
При пересчёте колонки через _m_action нужны права на чтение записи. Исполнитель в настройке «Выполнять от имени» хранится как id записи «Пользователь», поэтому переименование логина не ломает кнопку.
Подробнее: Триггеры
Права на файлы и файловый менеджер
для разработчика
Доступ к файловому менеджеру dir_admin — особый объект 10 в правах роли: READ для чтения, WRITE для загрузки.
- Создайте право
_m_new/116сup=<роль>,t116=10. - Уровень
53— только чтение,54— ещё и загрузка файлов. - Раздавайте адресно, не всем ролям.
WRITE на файлы открывает загрузку файлов, то есть фактически возможность изменить фронт приложения. Не выдавайте его широко.
В _d_schema тот же объект записывается как {"object": "files", "level": "READ"}.
Подробнее: API: файловый менеджер
Открыть базу гостям без входа
для разработчика
Заведите пользователя guest и роль guest, назначьте её пользователю и выдайте роли нужные права и меню.
- Создайте роль
guestв таблице «Роль». - Создайте пользователя
guestв таблице «Пользователь» с этой ролью. - Выдайте роли только те таблицы и запросы, которые гость может видеть.
- Для страницы без оболочки дайте роли ровно один пункт меню: адрес страницы в
t153.
Что видит гость, решают права и меню роли guest. Если пользователя guest нет, у него нет роли или роль называется иначе, страница уводит на вход, а JSON API отвечает 401.
Если у роли гостя больше одного пункта меню или ни одного, публичная страница показывается внутри оболочки с боковым меню и кнопкой «Войти». Если при входе гостя появляется «Неверный токен пользователя GUEST», очистите у пользователя поле «Токен» и сохраните.
Подробнее: API: гостевой доступ
Публичная форма: гость создаёт записи, но не видит чужие
для разработчика
Гостю дают WRITE на таблицу с маской @0: он может создавать записи, а существующие ему закрыты в списке, карточке и на правку.
- Настройте гостя (см. «Открыть базу гостям»).
- Создайте право роли
guestна таблицу сt136=54и маской@0на таблицу. - Если записи нужно показывать самому автору, используйте вариант с маской
~%на первое поле, как описано ниже.
Вариант с ~%: клиент пишет первое поле как ~<случайный код>, запись видна и правится только такому гостю. Колонка-кнопка с триггером CREATE вызывает SET-запрос, который снимает ~, и запись выходит из видимости гостя.
При создании записи маска проверяет только присланные значения: гость может создать запись вовсе без маскируемого реквизита. Такая запись ничего ему не открывает, но занимает уникальный ключ; ставьте маску на главное значение таблицы, а не на реквизит.
Подробнее: API: маски · Триггеры
Настроить меню роли: какие разделы видит сотрудник
для разработчика
Пункты меню — записи таблицы «Меню» (id 151), подчинённые роли: название t151, адрес t153, иконка t391.
- Возьмите id роли.
- Создайте пункт
_m_new/151сup=<роль>, названием и адресом страницы внутри базы. - Иконку (HTML-тег
<i>) передавайте через--form-string, иначе она сломается. - Проверьте меню роли:
object/151/?JSON_OBJ&F_U=<роль>.
curl -s "https://ideav.ru/mydb/_m_new/151?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
-F "up=900" -F "t151=Клиенты" -F "t153=table/641" \
--form-string 't391=<i class="pi pi-users"></i>'
Меню лишь прячет разделы. Доступ к данным определяют права роли, поэтому выдавайте и права на таблицы, которые открывают пункты меню.
Положение меню зависит от роли: админ и тот, у кого есть право правки меню, видят левое меню; расположение меню остальных можно задать файлом _menu_layout.html базы (auto, top или left).
Подробнее: API: меню роли
Администратор базы: что он может и чего нельзя менять
в интерфейсе
В каждой базе есть технический пользователь с логином, равным имени базы, и ролью admin (145). Права на него не распространяются, а переименовать его или сменить роль нельзя.
- Не переименовывайте и не пересоздавайте этого пользователя.
- Для работы сотрудников заводите отдельных пользователей с обычными ролями.
- Если администратор повреждён, восстановите его командой
POST /<база>/restore_admin.
Администратор имеет полный доступ ко всей структуре, таблицам, шаблонам и файлам в обход прав. Сервер создаёт его при создании базы.
Подробнее: API: создать базу
Войти по логину и паролю (и из программы)
для разработчика
Команда auth проверяет логин и пароль и открывает сессию устройства; в ответе токен сессии и _xsrf.
- Отправьте
auth?JSON=1с полямиloginиpwd. - Сохраните
tokenи_xsrfиз ответа. - Передавайте токен заголовком
X-Authorizationв каждом запросе,_xsrf— в каждом POST.
curl -s "https://ideav.ru/mydb/auth?JSON=1" -F "login=manager" -F "pwd=Str0ng-Pass"
Самый простой вариант — Basic-авторизация, логин и пароль в каждом запросе: curl -u "manager:Str0ng-Pass" "https://ideav.ru/mydb/metadata?JSON=1".
Пять неверных паролей подряд блокируют вход на 15 минут: сервер отвечает 429 с заголовком Retry-After. Заголовок токена читается, только если в запросе есть параметр JSON.
Подробнее: API: вход по логину и паролю · API: токен XSRF
Постоянный токен для интеграции и скриптов
для разработчика
Заведите пользователя (например, api) с нужной ролью и впишите ему в поле «Токен» (t125) случайную строку; передавайте её заголовком X-Authorization.
- Создайте роль с минимально нужными правами.
- Создайте пользователя
apiс этой ролью и случайным токеном вt125. - Передавайте токен в каждом запросе заголовком
X-Authorization: $TOKEN. - Перед POST получите
_xsrfкомандойxsrfпод тем же токеном.
curl -s "https://ideav.ru/mydb/_m_new/18?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
-F "up=1" -F "t18=api" -F "t115=900" -F "t125=$(openssl rand -hex 32)"
Токен подходит и как Authorization: <токен>, Authorization: Bearer <токен>, кука idb_<база> (нужна, например, для dir_admin) или поле token в POST.
Ключ API не меняет вход и браузеру не отдаётся. Токен — секрет: не публикуйте его и не кладите в репозиторий.
Подробнее: API: токен API · API: создать пользователя
Выйти из базы и закрыть сессии
для разработчика
GET /<база>/exit гасит текущую сессию, exit?all=1 — все сессии пользователя. Смена и сброс пароля тоже закрывают все сессии.
- Для выхода с этого устройства откройте
/<база>/exit. - Чтобы закрыть сессии на всех устройствах, откройте
/<база>/exit?all=1. - Либо смените пользователю пароль: все его сессии закроются.
Каждый вход (логин и пароль, код с почты, QR, Яндекс или Google, кабинет my) открывает сессию отдельного устройства, не больше 30 на пользователя. Сессия гаснет через 30 дней без запросов; пока ею пользуются, пользователь заново не входит.
Выход по кнопке из браузера: POST /<база>/_logout (JSON) или GET /<база>/_logout?u=<логин>; ?all=1 — все базы браузера.
Подробнее: API: вход и выход
Короткие access- и refresh-токены для приложения
для разработчика
Для API-клиентов (мобильные приложения, интеграции) сервер может выдавать пару access и refresh. Режим включается настройкой установки AUTH_TOKENS=refresh.
- Включите режим на установке:
AUTH_TOKENS=refreshвinclude/connection.phpили переменнаяINTEGRAM_AUTH_TOKENS. По умолчанию режимsession. - Войдите через
auth?JSON: в ответ придутaccess_token,refresh_token,token_type: "Bearer"иexpires_in. - Шлите access как обычный токен (
Authorization: Bearer,X-Authorization,token=). - Когда access истёк, отправьте
POST /<база>/_refreshсrefresh_token=и сохраните новую пару.
- срок access —
ACCESS_TTL(по умолчанию 900 секунд), срок refresh —REFRESH_TTL(по умолчанию 30 дней); - refresh одноразовый: при обновлении прежний access гаснет;
- повторное использование уже использованного refresh закрывает сессию устройства, ответ
401 invalid_grant— войдите заново; - выход:
POST /<база>/_logoutсrefresh_token=или/<база>/exitс access.
Это настройка всей установки, а не одной базы. Браузер в этом режиме остаётся на обычной сессии в куке. Ключ API и Basic работают как прежде.
Подробнее: API: вход
Токен для ИИ-агента через MCP
для разработчика
MCP-токен выпускается на странице /<база>/_mcp_token с набором прав (read, write, delete, rights, schema) на срок до 90 дней.
- Откройте
/<база>/_mcp_tokenпод пользователем, чьими правами будет работать агент. - Отметьте нужные права и срок (до 90 дней).
- Передайте токен MCP-серверу ideav-mcp.
Ядро MCP-токен как вход не принимает: ideav-mcp меняет его на короткий токен ядра (живёт 10 минут). С таким токеном разрешены чтение metadata, object, edit_obj, report, xsrf и _m_*/_d_* в пределах прав токена.
Действия ИИ видны в журнале: логин записывается с суффиксом ~ai.
Подробнее: Безопасность MCP: права агента
Демо-доступ по секретному слову в ссылке
для разработчика
Если пользователю задать поле «Секрет» и передать его параметром secret в ссылке, пользователь войдёт со своей ролью.
- Создайте пользователя с нужной ролью (обычно только для чтения).
- Впишите ему в поле «Секрет» произвольное слово.
- Передайте ссылку вида
https://ideav.ru/mydb?secret=<слово>.
Секрет хранится в открытом виде, в отличие от пароля и токенов, поэтому надёжной защиты не даёт. Подходит для простого демо-доступа; не выдавайте так роли с записью и личными данными.
Подробнее: API: токены
Восстановить пароль
в интерфейсе
На странице входа нажмите «Напомнить пароль»: укажите имя пользователя и имя базы. Если базу оставить пустой, предложат сбросить пароль от личного кабинета.
- Откройте страницу входа в базу или в кабинет.
- Нажмите «Напомнить пароль».
- Введите имя пользователя и имя базы (пустое имя базы — сброс пароля кабинета).
- Следуйте подсказкам на экране.
Если вы вошли через Google, пароль для вас не создаётся, но его можно задать, чтобы входить и без Google. Администратор может сам сменить пароль любого пользователя базы (см. «Сменить роль или пароль пользователя»).
Сброс и смена пароля закрывают все сессии пользователя.
Подробнее: API: пароль пользователя
Узнать, под каким пользователем и ролью я работаю
для разработчика
Команда xsrf отдаёт _xsrf, а заодно имя пользователя, его роль и id.
- Выполните
xsrf?JSONс вашим токеном. - Посмотрите поля
user,roleиidв ответе.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/xsrf?JSON=1"
# {"_xsrf": "...", "user": "api", "role": "api", "id": "632"}
Чтобы проверить права роли, выполните нужные запросы под токеном пользователя этой роли.
Подробнее: API: токен XSRF
Создать новую базу
в интерфейсе
Базы создаются в личном кабинете /my, раздел «Базы данных». Нужны имя базы (латиница и цифры) и шаблон; в новой базе сразу есть администратор.
- Откройте личный кабинет ideav.ru/my и раздел «Базы данных».
- Задайте имя новой базы и выберите шаблон.
- Создайте базу и войдите в неё.
- В базе уже есть администратор: логин равен имени базы, роль admin.
Для автоматизации команда _new_db кабинета my: db — имя, template — шаблон, обычно RU.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/my/_new_db/?JSON=1&db=apiman&template=RU"
# {"status": "Ok", "id": 221756}
Число баз на аккаунте ограничено тарифом: кабинет не даёт создать больше трёх баз на младшем тарифе, тариф меняется в разделе «Тариф».
Подробнее: API: создать базу · API: список баз
Личный кабинет /my: что в нём есть
в интерфейсе
Личный кабинет ideav.ru/my — одно место для ваших баз, тарифа, баланса, профиля и кооперации с другими пользователями.
- Откройте ideav.ru/my и войдите.
- В левом меню выберите нужный раздел.
| Раздел | Для чего |
|---|---|
| Обзор | общая сводка |
| Базы данных | список ваших баз, создание новых |
| Кооперации | приглашения в базы и запросы доступа |
| Тариф | текущий тариф и его смена |
| Баланс | пополнение баланса |
| Бонусы | бонусы |
| Партнёрам | партнёрская программа |
| Профиль | фото, имя, телефон, email |
Кабинет хранится в базе my; список баз пользователя отдаёт отчёт 313.
Минимальная сумма пополнения баланса в кабинете — 100 рублей.
Подробнее: API: список баз
Пригласить коллегу в свою базу (кооперация)
в интерфейсе
Приглашение отправляют из личного кабинета: раздел «Кооперации», вкладка «Приглашенные мной», кнопка «Пригласить».
- Откройте ideav.ru/my, раздел «Кооперации», вкладка «Приглашенные мной».
- Нажмите «Пригласить».
- Выберите свою базу из списка.
- При желании впишите имя или email приглашаемого и описание; без имени приглашение публичное.
- Нажмите «Отправить».
Приглашённый видит приглашение на вкладке «Приглашения мне» и может принять его или отказать. Пока приглашение не принято, вы можете его отозвать. Принятое приглашение получает статус «принято», название базы становится ссылкой.
Какие права получает приглашённый внутри базы, определяет роль пользователя в самой базе: после приглашения проверьте его роль и при необходимости смените.
Подробнее: Права доступа из коробки
Запросить доступ к чужой базе и ответить на запрос
в интерфейсе
Во вкладке «Запросы» раздела «Кооперации» можно создать запрос в чужую базу по её имени, а владельцу — принять запрос или отказать.
- Откройте ideav.ru/my, «Кооперации», вкладка «Запросы».
- Для запроса к чужой базе выберите «Мои запросы к чужим базам» и нажмите «Создать запрос».
- Введите имя базы и, при желании, обоснование, затем нажмите «Отправить».
- Владелец базы выбирает «Запросы к моей базе» и нажимает «Принять» или «Отказать».
Если базы нет или владелец скрыл её, кабинет ответит «База не найдена или скрыта владельцем». Свой запрос можно отозвать, пока он не принят.
Посмотреть, кто и что менял в базе (журнал действий)
в интерфейсе
У каждой базы есть журнал: кто, когда и каким запросом обращался к базе и что менялось в данных (значение до и после). Смотреть его может только администратор.
- Откройте
/<база>/dir_adminпод администратором. - Перейдите на вкладку «Журнал».
- Отфильтруйте по пользователю, дате или условию.
- При необходимости выгрузите страницу в JSON или CSV.
То же по API: GET /<база>/journal?JSON. Режим mode=log — запросы, mode=sql — изменения. Фильтры: user, id (история одной записи), rid, op, since, until, where, limit, cursor.
# история одной записи
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/journal?JSON&mode=sql&id=5231"
- запросы ИИ записываются с логином вида
ivanov~ai, задачи ИИ-чата — по полюai_job; - пароли, токены и xsrf в журнал не попадают;
- строки одного запроса связаны общим
rid; - при росте файла журнал ротируется (по умолчанию 50 МБ).
Читать журнал могут только администратор базы: admin, владелец (логин равен имени базы) или роль admin. Остальным ответ 403. Старые .txt-журналы не читаются.
Кнопки, триггеры и автоматизация
Кнопка в таблице, действие при создании или изменении записи, запрос, который пишет данные, почта, уведомления и обновление таблиц на лету: как заставить базу работать без ручных операций.
Что такое колонка-кнопка и какие у неё бывают действия
в интерфейсе
Колонка базового типа «Кнопка» (BUTTON, тип 7) показывается в таблице кнопкой; что она делает, записано в её настройке «Действие кнопки». Действий четыре: ссылка, промпт ИИ, формула, запрос.
- Откройте шестерёнку колонок таблицы и выберите колонку (или добавьте новую в «Структуре»).
- В окне «Редактирование колонки» задайте базовый тип «Кнопка».
- В появившемся блоке «Действие кнопки» выберите тип действия: ссылка, промпт ИИ, формула или запрос.
- Заполните поля действия и сохраните.
| Действие | Что делает |
|---|---|
| Ссылка | переход по адресу, в новой вкладке или в этой же |
| Промпт ИИ | текст уходит ИИ-агенту базы и выполняется под учёткой пользователя |
| Формула | значение считается по полям строки |
| Запрос | выполняется запрос (отчёт) базы по имени, результат — первое значение первой строки |
В карточке записи выводятся только кнопки-ссылки: промпт, формула и запрос выполняются из таблицы.
Подробнее: Триггеры кнопок: основы · Четыре типа действия
Кнопка, которая открывает страницу с данными записи
в интерфейсе
Колонка-кнопка с действием «Ссылка» открывает адрес, в который подставлены [ID] (id записи) и [VAL] (значение первой колонки). Так строится рабочее место для операций над выбранной записью.
- Добавьте колонку базового типа «Кнопка» и выберите действие «Ссылка».
- В поле адреса впишите URL страницы, например
/mydb/orders-page?id=[ID]. - Выберите, открывать ли ссылку в новой вкладке (по умолчанию да), и при желании задайте подпись кнопки.
- Сохраните. Нажатие на кнопку в строке откроет адрес уже с подставленными значениями этой записи.
Страница-получатель может быть вашей html-формой или рабочим местом с отчётом: она получает идентификатор текущей записи и выводит данные по ней и по связанным таблицам.
Ссылка запускается только нажатием; запуск при создании или изменении записи для неё недоступен.
Подробнее: Тип «Ссылка» · Подстановки в шаблонах
Кнопка или колонка считает значение по формуле
в интерфейсе
Колонка-кнопка с действием «Формула» считает значение по полям строки, например ROUND({Цена} * {Количество}, 2). Поля берутся по отображаемому имени колонки в фигурных скобках.
- В окне «Редактирование колонки» выберите базовый тип «Кнопка» и действие «Формула».
- Впишите формулу, ссылаясь на колонки как
{Название колонки}. - Отметьте запуск «при показе», чтобы пустая ячейка заполнялась при показе таблицы, либо оставьте «по нажатию».
- Включите «Записывать результат в поле записи», если значение нужно сохранить в записи.
ROUND({Цена} * {Количество}, 2)
- числа (
1.5), строки в кавычках,[ID],[VAL],{Колонка}; значения вида1 250,5считаются числами; - операции
+ - * / %, склейка&, сравнения= != < <= > >=, логика&& || !, условиеa ? b : c; - функции: ROUND, FLOOR, CEIL, ABS, MIN, MAX, SUM, AVG, NUM, IF, LEN, UPPER, LOWER, TRIM, LEFT, RIGHT, CONCAT, TODAY, DAYS, ADDDAYS;
- даты пишутся как
ДД.ММ.ГГГГ.
Это выражение, а не JavaScript: доступно только перечисленное.
Подробнее: Тип «Формула» · Синтаксис формул
Кнопка запускает запрос базы
для разработчика
Действие «Запрос» вызывает отчёт базы по имени или id с параметрами; результат — первое значение первой строки. Параметры пишутся строкой вида FR_Колонка=[ID].
- Создайте запрос (отчёт), который возвращает нужное значение первой колонкой первой строки.
- В колонке-кнопке выберите действие «Запрос» и укажите имя или id запроса.
- В поле параметров впишите строку вида
FR_Заказ=[ID], чтобы передать запросу текущую запись. - Для сохранения результата включите «Записывать результат в поле записи».
Под капотом выполняется вызов report/{запрос}?JSON_KV&{параметры}. Для проверки откройте тот же вызов отдельно с теми же параметрами.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/report/МойЗапрос?JSON_KV&FR_Заказ=1234"
Если запрос не вернул ни одной строки, результата нет.
Подробнее: Тип «Запрос» · Параметры запроса
Кнопка с промптом для ИИ: заполнить поле текстом
в интерфейсе
Действие «Промпт ИИ» отправляет текст ИИ-агенту базы (тому же, что и в чате) с подстановкой полей строки. С галкой записи ответ ложится в поле записи одним значением.
- В колонке-кнопке выберите действие «Промпт ИИ».
- Напишите промпт с подстановками, например
Опиши товар {Название}. - Включите «Записывать результат в поле записи», если ответ должен сохраниться.
- При необходимости задайте «Выполнять от имени» — пользователя, под учёткой которого работает агент.
При записи к промпту добавляется требование ответить одним значением для поля; обрамление из тройных кавычек перед записью убирается. Если агент предлагает изменения на подтверждение, они подтверждаются в ИИ-чате.
Промпт-задач от триггеров — не больше 60 в час на базу. Если ИИ базы не оплачен, промпт молча пропускается.
Подробнее: Тип «Промпт ИИ» · Лимиты
Сохранить результат кнопки в поле записи
в интерфейсе
У промпта, формулы и запроса есть галка «Записывать результат в поле записи». С ней результат сохраняется в значение колонки, а в ячейке видно значение и кнопки «Пересчитать» и «Удалить результат».
- Откройте настройку колонки-кнопки с действием «Формула», «Запрос» или «Промпт ИИ».
- Включите галку «Записывать результат в поле записи» и сохраните.
- В таблице нажмите кнопку в строке: результат запишется в колонку, вместо кнопки появится значение.
- Чтобы пересчитать, нажмите «Пересчитать»; чтобы очистить, нажмите «Удалить результат».
Без галки результат показывается на месте (у промпта — в окне) и никуда не пишется. Если поменять настройку колонки, уже записанные результаты остаются как были.
Ссылка результата не создаёт, галки записи у неё нет.
Подробнее: Куда пишется результат
Когда срабатывает кнопка: нажатие, показ, создание, изменение, удаление
в интерфейсе
В настройке колонки-кнопки галки «Запуск» задают событие: по нажатию, при показе, при создании, при изменении, при удалении. Создание, изменение и удаление ловит сервер, поэтому триггер работает при любом способе записи.
- Откройте «Редактирование колонки» у колонки-кнопки.
- В блоке «Действие кнопки» отметьте нужные галки «Запуск».
- Для сервера отметьте «при создании», «при изменении» или «при удалении»; для браузера — «по нажатию» или «при показе».
- Сохраните настройку.
| Запуск | Событие | Где выполняется |
|---|---|---|
| по нажатию | PRESS | браузер (по умолчанию) |
| при показе | READ | браузер: пустая ячейка заполняется при показе таблицы |
| при создании | CREATE | сервер, после создания записи |
| при изменении | UPDATE | сервер, после изменения записи |
| при удалении | DELETE | сервер, по значениям удалённой записи |
Серверные события срабатывают при записи через таблицу, карточку, API, пакетную запись и импорт через эти команды. Колонка без запуска «по нажатию» кнопки не показывает — только значение. Смена порядка строк события не даёт.
Подробнее: События запуска · Триггеры на сервере
Автоматически заполнить поле при создании записи
в интерфейсе
Колонка-кнопка с формулой, галкой записи и запуском «при создании» заполняет своё значение сразу после создания записи.
- Добавьте колонку базового типа «Кнопка» и действие «Формула» (или «Промпт ИИ»).
- Впишите формулу, например
{Имя} & " " & {Фамилия}. - Включите «Записывать результат в поле записи».
- В «Запуск» отметьте «при создании» (при желании и «при изменении») и сохраните.
Формула выполняется на сервере уже после создания записи. Пользователю ответ приходит сразу, а запись результата идёт после ответа, поэтому значение может появиться чуть позже.
{"action":{"type":"formula","formula":"{Имя} & \" \" & {Фамилия}","write":true,"on":["CREATE"]}}
Подробнее: Триггеры на сервере · Примеры
Пересчитать поле, когда меняется другое (например, Цена)
в интерфейсе
Поставьте колонке-кнопке запуск «при изменении» и сошлитесь в формуле на нужное поле через {Цена}: действие запустится, когда изменится именно эта колонка.
- Настройте колонку-кнопку с формулой, например
ROUND({Цена} * {Количество}, 2). - Включите «Записывать результат в поле записи».
- В «Запуск» отметьте «при создании» и «при изменении».
- Сохраните. Теперь правка Цены или Количества пересчитывает значение.
Событие UPDATE срабатывает, если изменилась колонка, на которую ссылается действие ({Колонка} в формуле, промпте, параметрах или условии; [VAL] — первая колонка). Действие без ссылок срабатывает на любое изменение, кроме своей колонки.
На перенос записи к другому родителю срабатывают только действия без ссылок на колонки.
Подробнее: Когда срабатывает UPDATE
Выполнить действие при удалении записи
для разработчика
Запуск «при удалении» выполняется на сервере по значениям записи до удаления. Обычно к нему привязывают действие «Запрос», который меняет связанные данные.
- Создайте запрос, принимающий параметр, например id или значение удаляемой записи.
- В колонке-кнопке выберите действие «Запрос» и впишите параметры с
[ID]или{Колонка}. - В «Запуск» отметьте «при удалении» и сохраните.
- Удалите тестовую запись и проверьте результат запроса.
Писать результат некуда: запись уже удалена, поэтому галка записи при удалении не действует.
Подробнее: Триггеры на сервере
Запускать действие только при условии
в интерфейсе
Поле «Условие (формула)» в настройке кнопки: действие выполняется, только если формула истинна, например {Статус} = "Оплачен".
- Откройте настройку колонки-кнопки.
- В поле «Условие (формула)» впишите выражение, например
{Статус} = "Оплачен". - Сохраните. Действие будет выполняться только для строк, где условие истинно.
Условие пишется в тех же подстановках, что и формула: {Колонка}, [ID], [VAL]. Ссылки на колонки в условии учитываются при «при изменении»: триггер ловит правки этих колонок.
На сервере условие и формула проверяются сразу, при запросе пользователя; отказы приходят в warnings ответа.
Подробнее: Условие запуска
Выполнять действие кнопки от имени другого пользователя
для разработчика
Поле «Выполнять от имени» задаёт пользователя, под которым выполняются запрос, промпт и запись результата. Если пусто — выполняет текущий пользователь.
- В настройке колонки-кнопки найдите «Выполнять от имени».
- Впишите логин пользователя; при сохранении запись о нём запоминается по id.
- Сохраните настройку.
Исполнитель хранится как id записи «Пользователь», поэтому переименование логина ничего не ломает. Если исполнитель удалён или закрыт (нет роли), действие не выполняется, предупреждение идёт в ответ и журнал. Если токена нет, он выпускается, как при входе.
Выбор исполнителя ограничен только правом редактировать типы: тот, кто может добавить кнопку, владеет базой.
Подробнее: Исполнитель
Выполнить действие кнопки сразу по нескольким строкам
в интерфейсе
Включите выбор строк (чекбоксы), отметьте строки: на панели таблицы появится кнопка колонки с числом строк, она выполнит действие по отмеченным строкам по очереди.
- Включите в таблице выбор строк (чекбоксы).
- Отметьте нужные строки.
- Нажмите на панели таблицы кнопку колонки с числом строк.
- Дождитесь, пока действие выполнится по строкам по очереди.
Массовый запуск есть только у колонок с запуском «по нажатию».
Подробнее: Массовый запуск
Цепочка действий: один триггер запускает другой
для разработчика
Запись, сделанная триггером, запускает «при изменении» других колонок. Колонка не срабатывает дважды в одной цепочке, длина цепочки — не больше 3.
- Настройте колонку A: формула или запрос, запуск «при изменении», запись результата.
- Настройте колонку B с запуском «при изменении» и ссылкой на
{A}в формуле. - Измените исходное поле: A посчитается, затем сработает B.
- Для нескольких действий на одно событие помните порядок: по порядку колонок.
- каждое действие перечитывает запись и видит результаты предыдущих;
- цепочка (id колонок) общая для всех записей запроса и передаётся дальше параметром
bt_chain; - лимит глубины —
BT_MAX_DEPTH= 3; - если запрос триггера меняет другие записи той же таблицы, их триггеры идут с той же цепочкой.
Результат триггера появляется после ответа пользователю: интерфейс не должен строить ответ на нём сразу.
Подробнее: Цепочки · Порядок выполнения
Триггер не срабатывает или результат появился не сразу
для разработчика
Чаще всего причина в одном из восьми пунктов: сработал не тот запуск, нет ссылки на изменённую колонку, нет оплаты ИИ или исполнитель закрыт. Первый источник правды — журнал.
- Проверьте, что у колонки отмечен нужный «Запуск»; ссылка работает только по нажатию.
- Для «при изменении» убедитесь, что в действии и условии есть ссылки
{Колонка}на изменённое поле. - Если не сработал промпт, проверьте оплату ИИ базы и лимит 60 задач в час.
- Проверьте исполнителя: если он удалён или закрыт, назначьте живого в «Выполнять от имени».
- Откройте журналы: строки триггеров помечены
[button]в_log.jsonl, сами записи значений — в_sql.jsonl.
- в карточке записи нет кнопки с промптом, формулой или запросом — так задумано, они выполняются из таблицы;
- запрос не вернул строк — результата нет; проверьте
report/Имя?JSON_KVотдельно с теми же параметрами; - в журнале ошибка связи «запрос …: …» — сервер не достучался до себя, администратор задаёт
BUTTON_TRIGGER_BASE_URLвinclude/connection.php; - запись результата отклонена проверкой ядра (уникальность, обязательность) — отказ в журнале, запись пользователя не страдает.
Запрос, промпт и запись результата выполняются после ответа клиенту, поэтому читать результат сразу после создания записи бесполезно: показывайте «запрос принят» и обновляйте данные позже.
Подробнее: Если триггер не срабатывает · Журнал
Настроить действие кнопки через API
для разработчика
Действие хранится в модификаторе реквизита под ключом action; задаётся командой POST /{db}/_d_action/{reqId}, пустое значение снимает действие.
- Создайте реквизит базового типа 7 (
_d_req) или найдите готовый вmetadata/{tableId}. - Соберите JSON действия:
type(link, prompt, formula, query), его поля и общие ключиlabel,on,when,user,recompute. - Отправьте
POST /{db}/_d_action/{reqId}?JSONс полями_xsrfиaction. - При ошибке «Неверное описание действия кнопки» прочтите причину: не JSON, неизвестный тип или событие, пользователь не найден.
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
--form-string 'action={"type":"formula","formula":"ROUND({Цена} * {Количество}, 2)","write":true,"on":["CREATE","UPDATE"]}' \
"https://ideav.ru/mydb/_d_action/12345?JSON"
Права как у прочих _d_* (редактирование типов). Значения по умолчанию в модификатор не пишутся, строки обрезаются до 8000 символов. Запись результата из браузера: POST /{db}/_m_set/{recordId}?JSON с t{reqId}=результат. Выполнить действие на сервере от имени user: POST /{db}/_m_action/{recordId}?JSON&col={reqId}.
Подробнее: _d_action · Ключи действия · _m_action
Сменить статус по кнопке с проверкой условий
для разработчика
Статус и дату меняет запрос с колонками «Присвоить», а роли выдают на поля только чтение и READ на сам запрос. Так «согласовать» значит пройти запрос со всеми его условиями.
- Создайте запрос (
_m_new/22) и добавьте колонки (_m_new/28): параметр id заказа, Статус сt132='Согласован', Дата сt132=[TODAY]. - Добавьте скрытую колонку-ограничитель
[USER_ID]на ссылке на пользователя без «Имени в отчёте» (t107=1). - Выдайте роли «Менеджер» на поля Статус и Дата только чтение (
t136=53). - Выдайте роли READ на сам запрос: запись таблицы 116 (
t116={id запроса},t136=53). - Вызовите запрос кнопкой рабочего места: POST на
report/<запрос>сconfirmed=1и_xsrf.
Колонке-ограничителю не давайте «Имя в отчёте» (t100): с именем её фильтр становится параметром, и вызывающий подставит чужой id.
Права роли на таблицы при выполнении запроса не проверяются: вся защита в определении запроса, править который (таблицы 22 и 28) могут только администраторы базы.
Подробнее: Пример: согласование заказа · Поле только для чтения · Кто может вызвать
Запрос, который меняет данные: колонка «Присвоить» (SET)
для разработчика
У колонки запроса есть поле «Присвоить» (t132): его выражение вычисляется для каждой отобранной строки и записывается. Запрос хотя бы с одним таким выражением изменяет данные.
- Создайте запрос и выберите колонки: что отбирать (с фильтрами) и что менять.
- В колонке, которую нужно изменить, заполните «Присвоить», например
'Осень 2021'— значение в кавычках. - Запустите запрос: он покажет строки и ссылку «Выполнить».
- Нажмите «Выполнить»: изменения применятся, отчёт при этом покажет данные как до изменения.
| Выражение в «Присвоить» | Что запишется |
|---|---|
'Согласован' | строка в кавычках |
[TODAY], [NOW], [USER_ID], [USER] | дата, время, id или логин вызывающего |
[THIS] + 1 | выражение от текущего значения колонки |
CONCAT(IFNULL(Примечание, ''), ' тел.') | SQL-функции: дописать текст, не теряя старое |
| пустое значение | удаление значения; у колонки главной таблицы — удаление записи |
- если объект встречается в отчёте несколько раз, он изменится один раз;
- если у колонки заданы условия отбора и заполнено «Присвоить», условие считается как «задано или пусто» — повторный запуск не создаст дубликатов;
- удаление через пустое значение не проверяет связи: можно удалить даже справочное значение, на которое есть ссылки.
Подробнее: Колонка «Присвоить» · Повторный вызов без вреда
Применить изменяющий запрос: превью и confirmed=1
для разработчика
Без подтверждения изменяющий запрос ничего не пишет, только показывает строки. Изменения применяются POST-запросом с полем confirmed=1 и _xsrf.
- Посмотрите превью: откройте отчёт в интерфейсе или вызовите
report/<запрос>?JSON_KVбезconfirmed. - Проверьте строки под фильтром.
- Отправьте POST на тот же адрес с
confirmed=1и_xsrf; в интерфейсе это ссылка «Выполнить». - Ответ придёт со строками уже с новыми значениями.
# превью
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/report/approve_order?JSON_KV&FR_order_id=1234"
# применение
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "confirmed=1" -F "FR_order_id=1234" "https://ideav.ru/mydb/report/approve_order?JSON_KV"
Параметр confirmed должен идти POST-запросом, иначе не сработает. Без _xsrf (и при авторизации токеном тоже) сервер ответит 403 «Неверный или устаревший токен CSRF».
Подробнее: Превью · Применение
Выполнять изменения при каждом вызове: параметр EXECUTE
для разработчика
Булев реквизит запроса EXECUTE снимает подтверждение: запрос применяет изменения при любом вызове, GET или POST. Встроенный в рабочее место EXECUTE-запрос срабатывает при каждом открытии страницы.
- Откройте таблицу «Запрос» и добавьте булеву колонку
EXECUTE, если её нет (новые регистрации с апреля 2024 имеют её сразу). - Включите
EXECUTEу нужного запроса. - Встройте запрос в рабочее место или вызывайте его по адресу: изменения применятся без
confirmed.
EXECUTE пишет данные при каждом вызове, в том числе по ссылке, и не проверяет XSRF. Для изменений, которые нельзя выполнить случайно, оставляйте двухшаговый вызов с confirmed=1.
Значение реквизита включается самим его наличием, даже 0.
Подробнее: EXECUTE
Сделать массовое изменение атомарным: InTransaction
для разработчика
Булев реквизит запроса InTransaction выполняет вызов одной транзакцией: все изменения фиксируются вместе, ошибка посреди вызова откатывает записанное.
- В таблицу «Запрос» добавьте булеву колонку
InTransaction, если её нет. - Включите её у нужного изменяющего запроса.
- Вызывайте запрос с
confirmed=1или с EXECUTE: транзакция действует именно на применение изменений.
- превью и чистая выборка идут без транзакции;
- вложенный запрос внутри открытой транзакции свою не открывает;
- без галки каждая запись фиксируется сразу, упавший вызов оставляет сделанное до ошибки: тогда помогает фильтр «ещё не обработано».
Транзакция охватывает только базу: внешний HTTP-вызов из запроса не откатывается. У InTransaction значение 0 означает «выключено».
Подробнее: InTransaction
Ограничить, какие строки может изменить запрос
для разработчика
Снаружи можно подменить только фильтры колонок с заполненным «Именем в отчёте» (t100). Ограничитель делают колонкой без имени, часто скрытой.
- Колонку-ограничитель создайте без
t100, со скрытием (t107=1) и фильтром, напримерt102=[USER_ID]на ссылке на пользователя. - Параметры, которые вправе выбирать вызывающий (id заказа), делайте колонками с
t100. - Параметру без значения по умолчанию поставьте
t102=0, чтобы он не отбирал всё. - Для безопасного повтора добавьте фильтр «ещё не обработано», например
t102=!%(пусто) у колонки результата.
Значение параметра понимает синтаксис фильтров: FR_order_id=% отберёт все заказы. Поэтому охват держит ограничитель без имени. Условие WHERE из адреса только сужает выборку; строка с лишней скобкой, незакрытой кавычкой, ; или комментарием отклоняется.
| Переменная | Значение |
|---|---|
[USER_ID], [USER] | id и логин вызывающего |
[ROLE_ID], [ROLE] | id и название роли |
[TODAY], [NOW] | дата и время вызова |
Подробнее: Ограничители · Условия по пользователю и роли · Чек-лист процедуры
Удалить дубликаты записей запросом
для разработчика
Делают два запроса: основной выводит все записи, вложенный для каждой находит минимальный ID среди двойников. Записи с минимальным ID остаются, остальные удаляются пустым «Присвоить».
- Создайте вложенный запрос «Оригинал»: по каждой комбинации ключевых полей (например, фильм и режиссёр) вычисляет минимальный ID.
- Создайте основной запрос «Дубликаты»: выводит все записи и подставляет в сравнение значения полей родителя.
- Сделайте так, чтобы остались только строки, чей ID не равен минимальному, и в колонке записи задайте пустое «Присвоить» (удаление).
- Проверьте превью, затем выполните запрос с
confirmed=1.
ID выдаются по возрастанию, поэтому у самой первой записи он минимальный. Вложенный запрос при самостоятельном запуске покажет ошибку: значения полей, которые передаёт родительский запрос, ему в конструкторе неоткуда взять; это нормально.
Удаление пустым значением не проверяет связи: перед запуском убедитесь, что на дубликаты нет ссылок. Готовый отчёт можно вывести в пункт меню.
Подробнее: Колонка «Присвоить» · Применение: confirmed=1
Вызвать внешний сервис из запроса (SMS, API) и сохранить ответ
для разработчика
Задайте шаблон адреса в поле URL запроса, подставив значения колонок в квадратных скобках, и добавьте колонку с функцией abn_URL: на каждую строку уйдёт HTTP-запрос, а ответ попадёт в колонку.
- В поле URL запроса впишите шаблон, например
https://sms.example/send?phone=[phone]&name=[name]. - Добавьте колонки
phoneиnameлевее колонки с функцией: значения вычисляются последовательно. - Добавьте колонку с функцией
abn_URL: её содержимое заменится ответом внешнего сервиса. - Чтобы сохранить ответ в базе, впишите в «Присвоить» нужной колонки обращение к ключу JSON:
CURL.{ключ}, илиCURL.для всего ответа (в кавычках).
Кроме URL, у запроса есть реквизиты URL_POST и URL_HEADER. Для записи результата вызывайте запрос с confirmed=1 или используйте EXECUTE.
Транзакция внешний вызов не откатывает. Обращения к localhost из запросов запрещены.
Подробнее: Внешние вызовы из запроса · InTransaction
Запускать действие по расписанию (cron)
для разработчика
Своего планировщика внутри базы нет: изменяющий запрос запускает внешняя система по расписанию POST-запросом с confirmed=1, лучше отдельной учётной записью с доступом к одному запросу. Задачи cron сервера видны в dir_admin только на чтение.
- Создайте изменяющий запрос и проверьте его вручную: превью, затем
confirmed=1. - Заведите учётную запись с ролью, которой дан READ только на этот запрос.
- Настройте на стороне внешней системы или сервера периодический вызов
POST /{db}/report/<запрос>сconfirmed=1и_xsrf. - Чтобы увидеть, какие задачи cron есть у вашей базы, откройте в
dir_adminсекцию «Задачи cron» (она показывает расписание, команду и комментарий).
Секция «Задачи cron» только для просмотра: задачи заводит администратор сервера. Владелец базы видит лишь задачи своей базы; секреты в командах (токены, Authorization:, пароли в адресах) маскируются.
Вместо кнопки можно использовать EXECUTE-запрос: он применяет изменения при любом вызове, но пишет и при случайном открытии страницы.
Подробнее: Кто и как вызывает · EXECUTE
Подключить свой почтовый ящик для рассылки из базы
в интерфейсе
База шлёт письма через ваш SMTP-ящик. Администратор один раз вносит настройки в служебную таблицу «Почта для отправки», пароль приложения хранится зашифрованным и через API не отдаётся.
- Получите у почтовика пароль приложения (не обычный пароль): Яндекс — id.yandex.ru/security, «Пароли приложений»; Mail.ru — «Настройки», «Пароли для внешних приложений»; Gmail — при включённой двухэтапной проверке, myaccount.google.com/apppasswords.
- От имени администратора базы (владелец, admin или роль «Администратор») сделайте первый вызов
POST /{db}/_mail: служебная таблица «Почта для отправки» создастся сама. - Откройте запись по адресу
/{db}/edit_obj/{id}из текста ошибки и заполните «SMTP-сервер», «Порт» (по умолчанию 465), «Логин», «Пароль приложения», «От кого», «Лимит в час» (по умолчанию 20). - Выдайте ролям, которым разрешено слать письма, READ или WRITE на таблицу «Почта для отправки».
Чтобы сменить пароль, впишите новый; очистка поля стирает его. Маска ****** при сохранении старое значение не перезаписывает. Если ответ «пароль приложения не читается», впишите пароль заново.
Порт 465 — сразу SSL, 587 — STARTTLS обязателен. Лимит считается по успешным письмам за последний час; 0 запрещает отправку совсем.
Отправить письмо с вложением из базы и разобрать ошибки
для разработчика
Письмо уходит вызовом POST /{db}/_mail с полями to, subject, body и необязательным файлом. Ответ {"status":"ok","message_id":"…","to":N}.
- Убедитесь, что SMTP настроен и у вызывающего есть READ или WRITE на таблицу «Почта для отправки».
- Отправьте POST (multipart/form-data или JSON) с
_xsrf,to(до 10 адресатов),subject,body. - Для вложения добавьте
file(до 10 МБ) либоrecиreq— id записи и id реквизита с файлом. - Результат каждого вызова ищите в журнале
logs/<база>_mail.jsonl.
| Код | Причина и что делать |
|---|---|
| 403 | нет права на отправку или неверный _xsrf: выдайте роли доступ к «Почта для отправки» |
| 400 | не заполнены настройки или неверные параметры |
| 429 | исчерпан лимит в час: подождите или увеличьте «Лимит в час» |
| 502 | SMTP недоступен, не принял пароль приложения, отклонил адресата или нет STARTTLS: укажите порт 465 или сервер с STARTTLS |
Вложение из записи отдаётся, только если у пользователя есть READ на этот реквизит.
Показать уведомление пользователю в открытой базе
для разработчика
Команда POST /{db}/_m_notify посылает уведомление выбранным пользователям: оно всплывает на любой открытой странице базы.
- Отправьте
POST /{db}/_m_notifyс полем_xsrf. - В
toукажите логины через запятую (до 50), вmsg— текст (до 2000 символов). - При желании добавьте
link: адрес вида/…илиhttp(s)://….
curl -s -H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
-F "to=ivanov,petrov" -F "msg=Новый заказ ждёт согласования" -F "link=/mydb/orders" \
"https://ideav.ru/mydb/_m_notify"
Гостю запрещено. Уведомления доставляет демон web-socket; если он не настроен на сервере, всплывающих сообщений не будет.
Подробнее: Справочник API
Таблица обновляется сама, когда данные меняет кто-то другой
в интерфейсе
Открытая таблица подписывается на свои данные: изменённые строки подставляются на месте, новые копятся на плашке «Добавлено N — показать». Права и маски ролей действуют как обычно.
- Откройте таблицу на данных (компонент
integram-tableс источникомobject/): подписка включается сама. - Измените запись из другой сессии, триггером или через API: строка обновится без перезагрузки.
- Для новых записей нажмите на плашке «Добавлено N — показать».
- Чтобы выключить подписку, задайте компоненту опцию
live: false.
- удалённые и скрытые маской записи убираются из таблицы; id скрытых записей не сообщаются;
- массовое изменение или правка схемы дают плашки «Данные изменились — обновить» и «Структура таблицы изменилась — обновить»;
- пока ячейка в правке или новая строка не сохранена, изменения ждут;
- таблица на отчёте (
report/) не подписывается.
Работает, если администратор сервера запустил демон web-socket и задал адрес в настройках ядра.
Подписать внешнюю систему на изменения таблицы
для разработчика
Внешний клиент подключается по web-socket к /ws?db=<база> с токеном в заголовке и посылает {"op":"sub","t":<тип>,"feed":true}: ему приходят все видимые ему изменения таблицы.
- Возьмите клиент, умеющий передавать заголовки, например npm-пакет
ws: встроенный WebSocket заголовков не передаёт. - Подключитесь к
wss://ideav.ru/ws?db=mydbс заголовкомX-Authorization: $TOKEN(токен в адресе не принимается). - Отправьте
{"op":"sub","t":500,"feed":true}, где 500 — id таблицы. - Разбирайте сообщения
rows,remove,added,stale.
const WebSocket = require('ws');
const ws = new WebSocket('wss://ideav.ru/ws?db=mydb', { headers: { 'X-Authorization': TOKEN } });
ws.onmessage = (e) => console.log(JSON.parse(e.data));
ws.onopen = () => ws.send(JSON.stringify({ op: 'sub', t: 500, feed: true }));
rows— новые значения видимых записей,remove— id удалённых или скрытых,stale— данные устарели (правка схемы, массовое изменение);- значения приходят с правами и масками вашего входа;
- при отзыве входа соединение закрывается с кодом 4401: переподключаться бесполезно.
API, интеграции и ИИ
Всё, что делается в интерфейсе, доступно по API: чтение и запись записей, отчёты, загрузка файлов, события. Здесь же коннекторы к Битрикс24, 1С и Google Sheets, подключение ИИ-агентов и локальная установка.
Сделать первый вызов API
для разработчика
Команда API — это адрес вида /{база}/{команда}/{id}; чтобы получить JSON, добавьте параметр JSON, а токен передайте заголовком X-Authorization.
- Заведите пользователя с токеном API (статья «Создать пользователя с токеном для интеграции») и положите токен в переменную
TOKEN. - Отправьте запрос
metadata— он покажет все таблицы базы:curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/metadata?JSON=1". - Если пришёл JSON с таблицами и колонками, доступ работает. Дальше подставляйте нужную команду:
object,report,_m_new.
TOKEN=a3f1c9...
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/metadata?JSON=1"
Заголовок X-Authorization читается, только если в адресе или теле есть параметр JSON (JSON, JSON_KV, JSON_OBJ). Без него запрос считается переходом браузера и уходит на страницу входа.
| Префикс команды | Что делает | Метод |
|---|---|---|
_d_* | меняет структуру: таблицы и колонки | POST |
_m_* | меняет данные: записи | POST |
metadata, object, report, dict, xsrf | читает | GET |
Подробнее: API: адрес команды · API: токен
Создать пользователя с токеном для интеграции
для разработчика
Заведите в базе отдельного пользователя (например, api), впишите ему случайный токен 15-64 символа и выдайте роль с нужными правами.
- Придумайте случайную строку из 15-64 символов: это будет токен.
- Создайте пользователя в интерфейсе или командой
_m_new/18(таблица «Пользователь»): логин вt18, роль вt115, токен вt125. - Выдайте роль только на то, что нужно интеграции: ограничение прав роли действует и на API.
- Передавайте токен заголовком
X-Authorization: $TOKENв каждом запросе с параметромJSON.
curl -s "https://ideav.ru/mydb/_m_new/18?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
-F "up=1" -F "t18=api" -F "t115=900" -F "t125=случайная-строка-токена"
Вместо X-Authorization подойдёт Authorization: <токен> или Authorization: Bearer <токен>. Ещё токен можно передать кукой idb_{база} или полем формы token в POST.
В примере запрос выполняется токеном администратора; id роли (900) в вашей базе другой. Не храните настоящий токен в коде и репозитории.
Подробнее: API: токен API · API: создать пользователя
Войти по логину и паролю через API
для разработчика
Команда auth проверяет логин и пароль и возвращает токен сессии и _xsrf к нему.
- Отправьте POST на
/{база}/auth?JSON=1с полямиloginиpwd. - Из ответа возьмите
token(для заголовка X-Authorization) и_xsrf(для POST-запросов на изменение). - Для выхода вызовите
GET /{база}/exit; чтобы закрыть все сессии пользователя —exit?all=1.
curl -s "https://ideav.ru/mydb/auth?JSON=1" -F "login=manager" -F "pwd=Str0ng-Pass"
{"_xsrf": "1cb413634d074d3804ed48", "token": "s.1824537600.9e0c...", "id": "632", "msg": ""}
- Сессия гаснет через 30 дней без запросов.
- Пять неверных паролей подряд блокируют вход на 15 минут: сервер отвечает 429 с заголовком
Retry-After. - Для постоянных интеграций удобнее токен пользователя API, а не пароль.
Подробнее: API: вход по логину и паролю
Авторизоваться в API логином и паролем в каждом запросе (Basic)
для разработчика
Самый простой вариант: передавайте логин и пароль в каждом запросе по Basic — curl кодирует их сам ключом -u.
- Добавьте в запрос ключ
-u "логин:пароль". - Не забудьте параметр
JSONв адресе, иначе вместо JSON придёт страница входа.
curl -s -u "manager:Str0ng-Pass" "https://ideav.ru/mydb/metadata?JSON=1"
По RFC 7617 пара логин:пароль кодируется в Base64. Для рабочих интеграций надёжнее токен: пароль не уходит в каждом запросе.
Подробнее: API: токен API
Получить _xsrf для запросов на изменение
для разработчика
Каждый POST на изменение (_d_*, _m_*) должен нести поле _xsrf; его выдаёт команда xsrf под тем же токеном, которым вы потом пишете.
- Вызовите
GET /{база}/xsrf?JSON=1с вашим токеном в заголовке. - Возьмите из ответа поле
_xsrfи передайте его в POST полем формы-F "_xsrf=$XSRF". - Если пришла ошибка 400 про устаревший
_xsrf, запросите его заново: он привязан к токену, которым получен.
XSRF=$(curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/xsrf?JSON=1" | jq -r ._xsrf)
Заодно команда сообщает пользователя, его роль и id.
Подробнее: API: токен XSRF
Понять ошибку ответа API
для разработчика
Ошибка приходит массивом с ключом error и HTTP-статусом; статус подсказывает причину.
- Посмотрите HTTP-статус и текст в
[{"error": "..."}]. - Сверьте статус с таблицей ниже и исправьте запрос.
| Статус | Причина |
|---|---|
| 400 | неверные данные или устаревший _xsrf; неизвестное имя колонки в fields (в ответе список полей таблицы) |
| 401 | нет авторизации |
| 403 | нет доступа у роли |
| 404 | нет базы, таблицы или записи |
| 409 | на удаляемую запись есть ссылки |
| 429 | слишком много неверных паролей: ждите, смотрите Retry-After |
Успешные команды _d_* и _m_* отвечают объектом: id — созданный или изменённый элемент, obj — объект, к которому он относится, warnings — предупреждения.
Подробнее: API: ответы и ошибки
Прочитать записи таблицы через API
для разработчика
Команда object с id или именем таблицы отдаёт записи; формат JSON_OBJ — массив строк, LIMIT ограничивает выборку.
- Узнайте id или имя таблицы командой
dictилиmetadata. - Вызовите
object/{таблица}/?JSON_OBJ&LIMIT=100. - Разберите ответ:
i— id записи,u— родитель,o— порядок,r— значения колонок по порядку метаданных. - Справочные значения приходят как
id:Название, множественные —id1,id2:Название1,Название2.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/object/641/?JSON_OBJ&LIMIT=100"
[
{"i": 649, "u": 1, "o": 1, "r": ["АО Ромашка", "7701234567", "660:Клиент"]}
]
LIMIT=100,100— 100 записей, начиная со 101-й;_count=— только число записей;full=1— не обрезать длинные значения.ORDER={id колонки}— сортировка,ORDER=-{id}— по убыванию.
Подробнее: API: прочитать записи
Отфильтровать записи в запросе к API
для разработчика
Добавьте к object параметр F_{колонка}=значение; вместо id колонки можно писать её имя.
- Выберите колонку и добавьте
F_{id или имя колонки}=значениек адресуobject. - Для поиска по первой колонке используйте
F_{id таблицы}или имя таблицы. - Для диапазона используйте пару
FR_{колонка}=…&TO_{колонка}=…. - Знак
%в адресе пишите как%25.
# клиенты, в названии которых есть «Ромашка»
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/object/641/?JSON_OBJ&F_641=%25Ромашка%25"
# по именам таблицы и колонки
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/object/Клиент?JSON_OBJ&F_ИНН=7701234567"
| Условие в значении | Смысл |
|---|---|
%ООО% | содержит |
!значение | не равно |
>100, <=20002, 10..20 | сравнение и диапазон |
% / !% | непусто / пусто |
IN(a,b) | одно из значений |
@660 | ссылка на запись 660 |
Подробнее: API: прочитать записи
Работать с API по именам, а не по id
для разработчика
Таблицы, записи, колонки и запросы можно называть по именам; параметр NAMED возвращает поля ключами-именами.
- В адресе пишите имя таблицы вместо id:
object/Клиент,metadata/Клиент,_m_new/Клиент. - Для чтения добавьте
NAMED:object/Клиент?JSON_OBJ&NAMED. - Для записи передавайте
fieldsс именами колонок вместоt{id}. - Запись называйте в адресе по таблице и главному значению:
edit_obj/Клиент/АО Ромашка.
[{"id": 649, "up": 1, "ord": 1,
"Клиент": "АО Ромашка", "ИНН": "7701234567",
"Категория": {"id": 660, "val": "Клиент"}}]
- Пробел в адресе пишется как
%20; регистр имени в адресе не важен. - Неизвестное имя колонки в
fields— ошибка 400 со списком полей таблицы. - Если в базе два термина с одним именем, адрес берёт первый найденный: такие таблицы читайте по id.
Подробнее: API: имена вместо кодов
Прочитать записи подчинённой таблицы (позиции заказа и т.п.)
для разработчика
Записи подчинённой таблицы висят на родителях: без параметра F_U сервер отдаёт пустой список, даже если данные есть.
- Определите id родительской записи (например, заказа 691).
- Вызовите
object/{id подчинённой таблицы}/?JSON_OBJ&F_U=691. - Чтобы получить позиции всех заказов, перебирайте записи родителя и для каждой повторяйте запрос с её
F_U.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/object/700/?JSON_OBJ&F_U=691"
Запрос без F_U (и _count= без F_U) возвращает только записи верхнего уровня, поэтому подчинённая таблица выглядит пустой. Не делайте вывод «таблица пустая» и тем более не удаляйте из неё колонку, не прочитав данные по родителям.
Подробнее: API: прочитать записи
Создать запись через API
для разработчика
POST на _m_new с таблицей, родителем up и значениями колонок: t{id колонки}=значение или fields с именами.
- Получите
_xsrf(статья «Получить _xsrf для запросов на изменение»). - Отправьте POST на
_m_new/{таблица}:up=1для записи верхнего уровня,up={id записи}для подчинённой. - Главное значение записи пишется в
t{id таблицы}, остальные колонки — вt{id колонки}; в справочную колонку передаётся id записи справочника. - Из ответа возьмите
obj— id созданной записи.
curl -s "https://ideav.ru/mydb/_m_new/641?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" \
-F "up=1" -F "t641=АО Ромашка" -F "t643=7701234567" -F "t646=660"
То же по именам; ссылку можно задать названием записи справочника, если такая ровно одна:
curl -s "https://ideav.ru/mydb/_m_new/Клиент?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "up=1" \
--form-string 'fields={"Клиент":"ПАО Эллипс","ИНН":"7709876543","Категория":"Лид"}'
Подробнее: API: создать запись
Изменить запись через API
для разработчика
POST на _m_set с id записи и теми колонками, которые нужно изменить.
- Возьмите id записи (из
objectили из ответа_m_new) либо назовите её в адресе:_m_set/Клиент/АО Ромашка. - Передайте изменяемые колонки:
t{id колонки}=значениеилиfieldsс именами. - Для справочной колонки в
t{id}передавайте id записи справочника; для множественной — id через запятую (t648=616,617). - Проверьте ответ: удачная запись — это непустой
idиobjс id записи.
curl -s "https://ideav.ru/mydb/_m_set/649?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "t643=7701234568" -F "t646=661"
- Пустое значение очищает поле; одиночную ссылку очищает пробел (
t646=); у BOOLEAN галку снимают значением0. - Варианты для справочной колонки отдаёт
_ref_reqs/{id колонки}?JSON=1&id={запись}.
Подробнее: API: изменить запись
Удалить записи через API
для разработчика
_m_del удаляет запись вместе с подчинёнными; несколько записей — _m_del_batch, все под фильтром — object с _m_del_select.
- Отправьте POST
_m_del/{id записи}с_xsrf. - Если ответ 409 — на запись есть ссылки: сначала уберите их.
- Для пачки:
_m_del_batch/{таблица}с полемids=668,669,670(до 10 000 id). - Для всех записей под фильтром:
object/{таблица}/?JSON=1&F_...с полем_m_del_select=1.
curl -s "https://ideav.ru/mydb/_m_del/668?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF"
Перед массовым удалением сделайте резервную копию (статья «Сделать резервную копию и выгрузить таблицу через API»).
Подробнее: API: удалить и переместить
Записать много записей одним запросом (_m_batch)
для разработчика
_m_batch выполняет до 1000 команд new, set, save, del одним запросом; созданную в пакете запись адресуют как ":id" или ":idN".
- Соберите массив
ops: каждая операция —{"op":"new|set|save|del","id":...,"fields":{...}}. - Для подчинённой записи в
upукажите":id"(последняяnew) или":idN"(операцияnewс номером N, считая с нуля). - Отправьте POST на
_m_batchс полемops. - Разберите
results: повторите только операции с"ok": false.
curl -s "https://ideav.ru/mydb/_m_batch?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" --form-string 'ops=[
{"op":"new","id":690,"up":1,"fields":{"t690":"Заказ 101"}},
{"op":"new","id":700,"up":":id0","fields":{"t700":"Труба 32 мм","t702":"12"}}
]'
Пакет не атомарен: упавшая операция не откатывает соседние.
Подробнее: API: пакет команд _m_batch
Загрузить тысячи записей файлом через API
для разработчика
POST на object/{таблица} с import=1 и файлом bki_file: первая строка DATA, дальше по записи на строку, значения через точку с запятой.
- Подготовьте файл: первая строка
DATA, затем по записи на строку; поля разделены;в порядке метаданных таблицы (сначала главное значение), в конце каждой строки тоже;. - Справочные колонки задавайте названиями записей справочника.
- Отправьте файл полем
bki_file:object/{таблица}?JSON&import=1. - Большие наборы делите на части по несколько тысяч строк: у каждой своя первая строка
DATA.
DATA
АО Ромашка;7701234567;Клиент;;
ПАО Эллипс;7709876543;Лид;;
curl -s "https://ideav.ru/mydb/object/641?JSON&import=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" -F "bki_file=@clients.bki;type=text/plain"
- Файл — до 8 МБ; нужны права WRITE и EXPORT на таблицу (или роль admin).
- Если первая колонка уникальна, повторная загрузка обновляет записи по имени, иначе каждая строка добавляется новой записью.
- Для подчинённой таблицы добавьте в адрес
F_U={id родителя}.
Подробнее: API: загрузка файлом · База знаний: универсальный импорт из Excel
Сделать резервную копию и выгрузить таблицу через API
для разработчика
Команда backup создаёт архив базы в папке backups; одну таблицу выгружает object с параметром csv, bki или json_export.
- Перед массовыми изменениями структуры вызовите
backupс кукойidb_{база}. - Для выгрузки одной таблицы вызовите
object/{таблица}/?JSON=1&bki(илиcsv,json_export) и сохраните ответ в файл.
curl -s -b "idb_mydb=$TOKEN" "https://ideav.ru/mydb/backup"
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/object/641/?JSON=1&bki" -o clients.bki
Архив создаётся в папке backups файлового менеджера базы.
Подробнее: API: резервная копия · База знаний: API и JSON-выгрузка
Вызвать отчёт (запрос) из кода
для разработчика
Команда report с id или названием запроса; JSON_KV возвращает массив объектов с ключами-названиями колонок, фильтры задаются как FR_{имя} и TO_{имя}.
- В настройках запроса убедитесь, что у нужных колонок заполнено «Имя в отчёте» — без него колонку нельзя отфильтровать снаружи.
- Вызовите
report/{id или название}?JSON_KV. - Фильтры передавайте как
FR_{имя}(от) иTO_{имя}(до), пробелы в имени заменяйте на_. - Ограничить число строк можно параметром
LIMIT.
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/report/950?JSON_KV"
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/report/951?JSON_KV&FR_Дата=01.10.2026&TO_Дата=31.10.2026&LIMIT=50"
curl -s -H "X-Authorization: $TOKEN" "https://ideav.ru/mydb/report/Клиенты%20по%20категориям?JSON_KV"
| Формат | Что вернёт |
|---|---|
JSON_KV | массив объектов, все строки, ключи — имена колонок |
JSON | с описанием колонок и форматов |
Подробнее: API: выполнить запрос · Запросы: полный справочник
Отдать внешней системе только нужные данные через запрос
для разработчика
Запрос работает с правами того, кто его настроил: роли интеграции достаточно READ на сам запрос, а выдачу ограничивают фильтры внутри запроса.
- Постройте запрос, который отдаёт ровно то, что нужно внешней системе.
- Выдайте роли интеграции доступ READ к запросу (запись таблицы 116:
t116={id запроса},t136=53). - Ограничители («только свои заказы») делайте колонкой без «Имени в отчёте» и со скрытием:
FR_/TO_их не заменят. - Вызывайте запрос командой
report.
Не давайте колонке-ограничителю «Имя в отчёте»: с именем её фильтр становится параметром, и вызывающий подставит чужое значение вместо [USER_ID].
Подробнее: API: права на запрос · База знаний: запрос как хранимая процедура
Загрузить файл (шаблон, скрипт, картинку) в папку базы через API
для разработчика
Файловый менеджер dir_admin принимает файлы POST-запросом: templates=1 — шаблоны рабочих мест, download=1 — скрипты, стили и картинки.
- Получите
_xsrfпод тем же токеном и с кукойidb_{база}. - Отправьте POST на
/{база}/dir_admin/?JSON=1с полями_xsrf,token,templates=1(илиdownload=1),add_path=/,upload=Загрузитьи файлом вuserfile. - Для замены существующего файла добавьте
rewrite=1. - Файлы из
download=1раздаются по адресуhttps://ideav.ru/download/{база}/.
XSRF=$(curl -s -b "idb_mydb=$TOKEN" "https://ideav.ru/mydb/xsrf?JSON=1" | jq -r ._xsrf)
curl -s -H "X-Authorization: $TOKEN" -b "idb_mydb=$TOKEN" "https://ideav.ru/mydb/dir_admin/?JSON=1" \
-F "_xsrf=$XSRF" -F "token=$TOKEN" -F "templates=1" -F "add_path=/" -F "upload=Загрузить" -F "rewrite=1" \
-F "userfile=@clients.html"
Без куки idb_{база} сервер отвечает InvalidToken. Право записи в файловый менеджер позволяет подменить код фронтенда, поэтому выдавайте его адресно.
Подробнее: API: файловый менеджер
Создать новую базу через API
для разработчика
Команда _new_db кабинета my создаёт базу из шаблона; в новой базе уже есть администратор с логином, равным имени базы.
- Вызовите
https://ideav.ru/my/_new_db/?JSON=1&db=apiman&template=RU:db— латиница и цифры,template— шаблон, обычноRU. - Из ответа
{"status": "Ok", "id": ...}возьмите id базы. - Список баз пользователя отдаёт отчёт 313:
https://ideav.ru/my/report/313?JSON_KV=1.
В новой базе уже есть администратор: логин равен имени базы, роль admin. Переименовать его или сменить ему роль нельзя.
Подробнее: API: создать базу · API: список баз
Создать таблицы, колонки, роли и отчёты одним запросом (_d_schema)
для разработчика
_d_schema принимает описание по именам и создаёт недостающее: таблицы, поля, ссылки, подчинённые таблицы, отчёты и роли с правами.
- Опишите схему JSON:
tablesсfields(имя,type,ref,required,default). - Отправьте POST на
_d_schema?JSON=1с полемjson(через--form-string). - Проверьте результат командой
metadata.
curl -s "https://ideav.ru/mydb/_d_schema?JSON=1" \
-H "X-Authorization: $TOKEN" -F "_xsrf=$XSRF" --form-string 'json={
"tables": [
{"name": "Категория", "unique": true},
{"name": "Клиент", "fields": [
{"name": "ИНН"},
{"name": "Категория", "ref": "Категория", "required": true}]}
]
}'
Базовые типы колонок: SHORT (3), CHARS (8), MEMO (12), NUMBER (13), SIGNED (14), DATE (9), DATETIME (4), BOOLEAN (11), FILE (10).
Подробнее: API: схема одним запросом · API: базовые типы
Отправлять письма из приложения через свой SMTP-ящик
для разработчика
Админ базы один раз вносит настройки SMTP-ящика, дальше приложение шлёт письма запросом POST /{база}/_mail.
- Первым вызовом
/_mailот администратора базы создайте таблицу «Почта для отправки». - Заполните в ней SMTP-сервер, порт (по умолчанию 465), логин, пароль приложения (не обычный пароль ящика), «От кого» и лимит в час (по умолчанию 20).
- Отправьте POST на
/{база}/_mailс полями_xsrf,to(до 10 адресов),subject,bodyи, при необходимости,file. - При ошибке смотрите код: 403 — нет права или
_xsrf, 429 — превышен лимит, 502 — проблема SMTP.
- Пароль приложения хранится зашифрованным и через API не отдаётся.
- Файл вложения — до 10 МБ; либо вложение берётся из реквизита записи (
rec+req), если у пользователя есть право чтения. - Результат каждого вызова пишется в журнал
logs/{база}_mail.jsonl.
Подробнее: API: токен XSRF
Принять вебхук внешней системы в базу (заявка с сайта, платёж)
для разработчика
Отдельной «точки вебхука» нет: внешняя система (или ваш небольшой обработчик) вызывает API с токеном пользователя интеграции и создаёт запись командой _m_new.
- Создайте пользователя API с токеном и ролью, у которой есть WRITE только на нужную таблицу (например, «Заявки»).
- В отправителе (форма сайта, платёжный сервис, no-code сценарий) настройте HTTP-запрос: POST на
_m_new/{таблица}?JSON=1с заголовкомX-Authorization. - Перед записью получите
_xsrfзапросомxsrfпод тем же токеном: POST без него даст ошибку 400. - Если отправитель не умеет делать два запроса, поставьте между ними небольшой обработчик, который получает
_xsrfи пишет запись.
Токен — секрет: не вставляйте его в публичный код страницы сайта. Вызывайте API с сервера.
Подробнее: Помощь: создать запись через API · API: создать запись
Подписаться на изменения таблицы из внешней системы (web-socket)
для разработчика
Внешняя система подключается к web-socket по адресу wss://{хост}/ws?db={база} с токеном в заголовке и подписывается на таблицу, вместо опроса API по таймеру.
- Возьмите клиент web-socket, который умеет передавать заголовки (в Node — пакет
ws; встроенный WebSocket Node и браузера заголовков не передаёт). - Подключитесь к
wss://ideav.ru/ws?db=mydbс заголовкомX-Authorization: $TOKEN. - Отправьте подписку:
{"op":"sub","t":500,"feed":true}, гдеt— id таблицы. - Обрабатывайте события:
changeсopinsert, update или delete,schema— правка метаданных;bulk:trueзначит «перечитать всё».
const WebSocket = require('ws');
const ws = new WebSocket('wss://ideav.ru/ws?db=mydb', { headers: { 'X-Authorization': TOKEN } });
ws.onmessage = (e) => console.log(JSON.parse(e.data));
ws.onopen = () => ws.send(JSON.stringify({ op: 'sub', t: 500, feed: true }));
На события действуют права и маски ядра: запись, скрытая маской, не сообщается ничем. Значения демон берёт обычным листингом object с правами подписчика.
Подробнее: Триггеры
Послать пользователю уведомление из внешней системы
для разработчика
POST на _m_notify отправляет всплывающее уведомление пользователям базы, у которых открыта любая страница базы.
- Получите
_xsrfпод вашим токеном. - Отправьте POST на
/{база}/_m_notifyс полями_xsrf,to(логины через запятую, до 50),msg(текст до 2000 символов) иlink(путь/…илиhttp(s)://…).
Гостю отправка запрещена. Уведомления работают через web-socket-демон: если он не развёрнут на вашей установке, они не дойдут.
Подробнее: Помощь: подписка на события
Вызвать внешний сервис из запроса (SMS, чужой API)
для разработчика
В поле URL отчёта задаётся шаблон адреса с именами колонок в квадратных скобках; функция abn_URL подставляет в колонку результат запроса к этому адресу для каждой строки.
- В настройках запроса впишите в поле URL шаблон адреса внешнего сервиса, подставляя значения колонок в квадратных скобках, например
[phone],[name]. - Добавьте колонки запроса с этими именами.
- Для колонки с результатом выберите функцию
abn_URL: её содержимое заменится ответом внешнего сервиса. - Результат можно сохранить в базе, присвоив его полю.
Это описание из старой справки Интеграма; параметры и ограничения сверьте на своей установке. Запрос шлёт обращение на каждую строку отчёта, поэтому сначала проверьте число строк.
Подробнее: Запросы: полный справочник
Загружать данные Битрикс24 в Интеграм по расписанию
для разработчика
Универсальный коннектор b24ig читает Битрикс24 через вебхук и пишет данные в таблицы Интеграма по JSON-конфигу, полным или инкрементальным прогоном.
- Создайте в Битрикс24 входящий вебхук только на чтение (CRM, задачи, пользователи, отделы) и токен пользователя Интеграма с правами WRITE+EXPORT на целевые таблицы.
- Опишите в JSON-конфиге сущности, колонки, ключ уникальности и режим (
fullилиincremental). - Сверьте конфиг со схемой базы:
php b24ig.php --config=... --check, затем пробный прогон--dry-run. - Сделайте первую загрузку с флагом
--allow-mass-create, затем обычные запуски. - Поставьте регулярный запуск в cron (например, раз в сутки) или вызов по URL.
- Коннектор грузит файлами импорта до 7 МБ и 5000 строк, затем вторым проходом проставляет ссылки через
_m_set. - Инкремент сначала берёт новые записи, затем изменённые с прошлого успешного прогона; курсор сдвигается только после успешного файла.
- В конце делается сверка ключей: если что-то не нашлось, курсор откатывается, а запуск завершается с ошибкой.
- Нужны PHP 7.2+ и расширения curl, json, mbstring.
Подробнее: Помощь: подключить 1С
Подключить 1С через OData и перенести структуру и данные
для разработчика
Рабочее место «1С Коннектор» читает структуру ($metadata) и данные опубликованной базы 1С по стандартному OData без кода на стороне 1С и готовит их для переноса в Интеграм.
- Попросите администратора 1С опубликовать базу и включить галку OData: другого кода на стороне 1С не требуется.
- Откройте в верхнем меню базы пункт «1С Коннектор» (или
/{база}/?action=connector-1c) и введите адрес OData и логин с паролем (HTTP Basic). - Загрузите
$metadata: рабочее место покажет справочники, документы и регистры с реквизитами. - Сохраните структуру как
1c-structure.json, выберите таблицы и сохраните данные как1c-data.json(постранично,$top/$skip). - Передайте эти файлы для сопоставления типов и загрузки (например, ИИ-агенту или через импорт).
| Тип 1С (OData) | Тип Интеграма |
|---|---|
Edm.String до 127 символов | SHORT (3) |
Edm.String без длины или длиннее 127 | CHARS (8) |
Edm.Boolean | BOOLEAN (11) |
Edm.Int* | NUMBER (13) |
Edm.Single, Edm.Double, Edm.Decimal | SIGNED (14) |
Edm.Date | DATE (9) |
Edm.DateTime, Edm.DateTimeOffset | DATETIME (4) |
Edm.Binary | FILE (10) |
Рабочее место работает в браузере: пароль 1С на сервере не хранится, адрес и логин запоминаются в браузере по галке «Запомнить URL и логин». Сам коннектор b24ig тоже умеет читать 1С по OData.
Подробнее: База знаний: обёртки над 1С
Синхронизировать Google Таблицы с Интеграмом
для разработчика
Скрипт google_sheets_sync.php читает выбранные листы Google Таблицы через сервисный аккаунт, собирает файл BKI и при включённой загрузке отправляет его в таблицу Интеграма.
- Создайте сервисный аккаунт Google, положите его ключ в
include/credentials.jsonи откройте таблицу этому аккаунту по его email. - В
google_sheets_sync.config.phpукажитеspreadsheet_id, листы (sheets: имя, нужные строки и колонки, в том числе по маскам вроде01.**.202*). - В блоке
integramвключитеenabled, укажитеbase_url, токен,_xsrfиupload_endpoint(путь вида/object/{таблица}?JSON&import=1). - Проверьте без отправки:
php google_sheets_sync.php --dry-run(файл появится вoutput_file). - Отправьте:
php google_sheets_sync.php --upload; для регулярного обновления поставьте запуск в cron.
Файл credentials.json секретный и исключён из git. Если нужна разовая загрузка из Google Таблицы, проще интерфейсный импорт.
Подробнее: База знаний: умный импорт из Google
Выгрузить лиды и сделки Битрикс24 за год в CSV
для разработчика
Скрипты export_b3x*.php выгружают лиды, сделки, задачи, пользователей и отделы Битрикс24 в отдельные CSV с русскими названиями колонок, которые затем можно загрузить в таблицы.
- Задайте в config.php скрипта параметры доступа к Битрикс24 и папку для CSV.
- Укажите год выгрузки и нужные поля с русскими названиями.
- Запустите скрипт: при таймауте он перезапускается сам, с защитой от бесконечных перезапусков.
- Загрузите полученные CSV в таблицы Интеграма (импорт файла).
Для регулярного обмена вместо разовой выгрузки используйте коннектор.
Подробнее: Помощь: Битрикс24 по расписанию
Использовать базу как бэкенд для no-code фронта (Bubble и др.)
для разработчика
Конструктор вызывает API базы с сервера приложения: токен в заголовке X-Authorization, чтение через object или report в формате JSON_KV, запись через _m_new и _m_set.
- Создайте пользователя API с токеном и ролью, у которой права только на нужные таблицы.
- В конструкторе (например, в API Connector Bubble) добавьте заголовок
X-Authorizationс токеном и параметрJSONв адрес. - Для чтения списков используйте
report/{запрос}?JSON_KVилиobject/{таблица}?JSON_OBJ&NAMED: ответ — массив объектов с понятными ключами. - Для записи сначала вызовите
xsrf, затем_m_new/{таблица}с_xsrfи полямиt{id колонки}(форма,application/x-www-form-urlencoded). - Вызовы делайте с сервера приложения, а не из браузера посетителя, чтобы токен не попал в страницу.
Формат JSON_KV давно используют именно для баз под Bubble: ключи объектов — названия колонок отчёта.
В старой справке вызов с сервера приложения описан с префиксом api/ перед именем базы; для актуального адреса ориентируйтесь на описание API на этом сайте и проверьте вызов на своей установке.
Подробнее: API: токен · API: выполнить запрос
Подключить ИИ-ассистента (Claude, Cursor) к базе через MCP
для разработчика
MCP-сервер даёт ИИ-ассистенту набор действий над базой (читать, создавать, менять, строить структуру) строго в рамках прав выданного токена.
- Откройте в базе страницу выпуска токена
/{база}/_mcp_token. - Выберите права (
read,write,delete,rights,schema) — выдавайте минимально нужные — и срок (до 90 дней). - Скопируйте выданный токен вида
mcp.<срок>.<права>.<64 hex>и добавьте MCP-сервер в настройки ИИ-клиента (Claude Desktop, Claude Code, Cursor или другой с поддержкой MCP), указав адрес сервера и токен. - Попросите ассистента для начала только прочитать данные: «покажи таблицы базы».
- MCP-токен не заменяет токен API: сервер обменивает его на короткоживущий токен ядра и работает в пределах выданных прав.
- Опасные действия (удаление, права) лучше не включать без нужды: выдайте только
readдля аналитики. - Если MCP не нужен, те же операции доступны по REST API с токеном.
Адрес MCP-сервера и порядок подключения для вашей установки уточняйте у поддержки: старый npm-пакет integram-mcp и встроенный mcp-server из репозитория ядра выведены из обращения в пользу ideav-mcp.
Подробнее: База знаний: MCP-сервер простыми словами · База знаний: безопасность MCP и права агента
Спрашивать ИИ-чат прямо в базе и вносить правки по плану
в интерфейсе
Любой вошедший пользователь базы (кроме гостя) может написать в чат ИИ; агент работает с правами этого пользователя, а правки сначала предлагает планом.
- Откройте базу и панель ИИ-чата (адрес чата —
/{база}/ai/agent). - Напишите задачу обычным языком: «найди все сделки Петрова», «закрой открытые сделки».
- Если задача меняет данные, агент пришлёт план — база пока не изменена. Нажмите «Применить» или «Отменить».
- После выполнения можно нажать «Отменить»: прежние значения возвращаются в течение 24 часов, пока записи не меняли после действия агента.
- Чат учитывает, что открыто у вас на экране (запись, таблица, отчёт, рабочее место, фильтры, выделенные строки) — это можно убрать крестиком.
- Удаление, изменение структуры и прав агент делает только через план; перед структурой и правами делает
backup. - Галка «Применить автоматически» под полем ввода исполняет план сразу, пока стоит; после перезагрузки страницы она снята.
- Своего пользователя у ИИ нет: действия пишутся в журнал под логином с суффиксом
~ai. - Чат требует действующей оплаты базы.
Подробнее: База знаний: сборка приложения ИИ-агентом
Подключить собственный ИИ-сервис к чату базы
для разработчика
Чат базы шлёт POST JSON на адрес INTEGRAM_AGENT_ENDPOINT; ваш сервис отвечает синхронно текстом либо асинхронно через callback и ходит в API токеном пользователя из запроса.
- Задайте на установке
INTEGRAM_AGENT_ENDPOINT(и при необходимостиINTEGRAM_AGENT_TOKEN): без него агент не вызывается, чат отвечает заглушкой. - Примите POST: в теле
db,user,token(токен пользователя),message,conversation_id,attachments(base64, до 10 МБ на файл) иcontextс экрана пользователя. - Ходите в API базы только этим токеном и в каждом запросе передавайте параметр
client=ai. - Ответьте HTTP 200 с
{"content": "..."}(если укладываетесь в 30-60 секунд) либо 202 и затем пришлите результат наcallback_urlс заголовкомX-Agent-Secret. - Для изменений данных возвращайте поле
plan(статусpending): чат нарисует кнопки «Применить» и «Отменить».
- Права определяет CRM и токен пользователя: служебный admin-токен вместо него подставлять нельзя, иначе пользователь получит чужие права.
- Токен из запроса — секрет: не пишите в журналы и не показывайте в ответе.
- При ошибке верните 4xx/5xx с телом
{"error":{"message":"..."}}. - К
contentможно добавитьblocks(text, table, records, actions) для красивого показа.
Подробнее: Помощь: ИИ-чат в базе
Искать похожие записи по смыслу (эмбеддинги в базе)
для разработчика
Вектор хранится в обычной ячейке рядом с остальными данными, а близость по смыслу (косинус) считает штатный запрос; отдельная векторная СУБД не нужна.
- Посчитайте эмбеддинг текста внешней моделью и запишите числа в колонку записи (в проверенном прототипе вектор лежит как текст).
- Постройте запрос (отчёт), который считает косинусную близость колонки вектора к вектору запроса и сортирует по ней.
- Вызовите запрос из кода командой
reportс вектором в параметре. - Для связанных записей используйте рекурсивный запрос: движок отчётов опирается на
WITH RECURSIVE.
Это не векторная СУБД: нативного векторного индекса нет, близость считается сканом, поэтому для миллисекундного поиска на больших корпусах нужен выделенный ANN. На живом прототипе обход графа и ранжирование косинусом заняли около 0,3 секунды. Свойства базового типа VECTOR на вашей установке уточняйте в поддержке: в этой справке они не описаны.
Подробнее: База знаний: память по смыслу без векторной БД · Запросы
Установить Интеграм локально в Docker
для разработчика
Установщик scripts/install-local-docker.sh спрашивает master-пароль, создаёт .env.local и самоподписанный сертификат и запускает контейнеры; вход — https://localhost:8443.
- Установите Docker Engine с Docker Compose и освободите порты 8080 и 8443; нужен доступ к репозиторию с исходниками.
- Запустите
bash scripts/install-local-docker.sh: введите master-пароль, скрипт создаст.env.local,docker/certs/local.crtиlocal.keyи выполнитdocker compose up -d --build. - Откройте
https://localhost:8443; браузер предупредит о самоподписанном сертификате. - Войдите: база
my, логинadmin, пароль — master-пароль, введённый при установке. - Для рабочей установки замените сертификат на свой и перезапустите:
docker compose --env-file .env.local restart app.
Ручной вариант: скопируйте .env.docker.example в .env.local, заполните INTEGRAM_MASTER_PASSWORD, INTEGRAM_DB_PASSWORD, INTEGRAM_DB_ROOT_PASSWORD, INTEGRAM_SALT, создайте сертификат и выполните docker compose --env-file .env.local up -d --build.
Пароли БД из .env.local MariaDB применяет только при создании пустого тома. Если старый том есть, а .env.local новый, приложение будет перезапускаться с ошибкой 1045: верните прежний .env.local или удалите том вместе с данными (INTEGRAM_RESET_DB=1 bash scripts/install-local-docker.sh).
Подробнее: База знаний: закупка on-premise
Обновить, остановить и сохранить копию локальной установки Docker
для разработчика
Обновление — pull и up --build, остановка — down, копия базы — mariadb-dump из контейнера db; данные лежат в томах Docker и остаются при остановке.
- Обновите:
docker compose --env-file .env.local pull, затемdocker compose --env-file .env.local up -d --build. - Смотрите журнал:
docker compose --env-file .env.local logs -f app. - Остановите:
docker compose --env-file .env.local down(данные остаются в томах). - Сделайте копию:
docker compose --env-file .env.local exec db mariadb-dump -u root -p ideav > integram-local.sql. - Восстановите:
docker compose --env-file .env.local exec -T db mariadb -u root -p ideav < integram-local.sql.
Тома: integram-local_integram-db, integram-local_integram-download, integram-local_integram-templates, integram-local_integram-logs.
down -v удаляет тома вместе с данными.
Подробнее: Помощь: установка в Docker