Смарт-фильтры — Администрирование¶
Смарт-выражения (SmartExpressions) — универсальный механизм условий и вычислений в 1Форме: фильтры в гридах и виджетах, условия правил в smart-actions, вычисления параметров. Раздел описывает интерфейсы администрирования (SPA-страницы и Admin API), справочник синтаксиса и типичные ошибки настройки.
Обзор¶
Раздел охватывает создание и редактирование смарт-выражений (SmartExpressions) — универсального механизма условий и вычислений в 1Форме. Смарт-выражения используются как:
- Фильтры (
IsFilter = 1) — условия отбора в гридах, виджетах, отчётах - Условия правил (
IsFilter = 0) — триггерные условия в smart-actions - Вычисления — значения параметров в пакетах действий
- Смарт-доступ — динамические права (см.
smart-actions/admin.md)
Администрирование использует:
- Отдельные SPA-страницы — 3 формы (SmartExpressions, SmartQueries) — зарегистрированы в дереве автоадминки, но открывают собственные SPA-страницы
- Admin API — 6 контроллеров (редактор, конструктор, тест-кейсы)
Механизмы администрирования¶
Отдельные SPA-страницы (в дереве администрирования)¶
Ключевые операции вынесены на отдельные страницы интерфейса администрирования:
| Alias формы | Название | Url | Таблица БД | Папка |
|---|---|---|---|---|
general-smart |
Общие смарты | /administration/smart-packs |
dbo.SmartExpressions | Общая бизнес-логика |
all-smart |
Все смарты | /administration/smart-packs?globalEventsOnly=false |
dbo.SmartExpressions | Общая бизнес-логика |
rebus-queues |
Очереди шины сообщений | /administration/rebus-queues |
dbo.SmartQueries | Системные настройки |
Формы general-smart и all-smart разделяются с доменом smart-actions (обе работают с dbo.SmartExpressions). Smart-filters отвечает за создание/редактирование выражений, smart-actions — за привязку к событиям и пакетам.
Admin API контроллеры¶
Редактор выражений, запросы и конструктор¶
Методы API редактора выражений:
| Маршрут | Методы | Назначение |
|---|---|---|
/api/admin/smart/expressions |
GET, POST, DELETE | CRUD смарт-выражений, список, фильтрация |
/api/admin/smart/expression-editor |
GET, POST | Загрузка/сохранение выражения в визуальном редакторе |
/api/admin/smart/expression-constructor |
GET, POST | QueryBuilder-конструктор (визуальное дерево условий) |
/api/admin/smart/expression-test-cases |
GET, POST, DELETE | CRUD тест-кейсов для отладки выражений |
Методы API запросов и конструктора условий (в составе раздела редактора):
| Маршрут | Методы | Назначение |
|---|---|---|
/api/admin/smart/query |
GET, POST | SmartQueries — конфигурации выборок для виджетов |
/api/admin/smart/query-constructor |
GET, POST | Конструктор TSQL-запросов |
Ключевые настройки¶
Создание и редактирование выражений¶
Где настраивается: Admin API (/api/admin/smart/expression-editor, /api/admin/smart/expressions)
Таблица БД: dbo.SmartExpressions
Два способа создания:
- Визуальный редактор — через дерево свойств сущностей и панель операторов и функций
- TSQL-режим — прямой ввод SQL-кода в
TSqlContent
Лукап-колонки ДП «Таблица» в дереве свойств. Если ДП «Таблица» содержит колонку типа «Лукап» (ссылка на задачи другой категории), при выборе такой колонки в дереве свойств визуального редактора раскрываются сущности связанной категории — параметры задач (номер, текст, срок, исполнитель, ДП целевой категории), а не технические поля строки таблицы (ColumnID, RowID, Value). Так условия строятся по свойствам выбранных задач, а не по идентификаторам строк.
Поля SmartExpressions (16 в форме general-smart):
| Поле | Тип | Что контролирует |
|---|---|---|
Content |
nvarchar(max) | XML-формула визуального конструктора |
TSqlContent |
nvarchar(max) | TSQL-код (ручной ввод, приоритет над Content) |
Name |
nvarchar | Название выражения |
SubcatID |
int | Привязка к категории (NULL = глобальное) |
IsFilter |
bit | Тип: фильтр (true) или условие правила (false) |
EventID |
int | Событие-триггер (только для условий правил) |
ParameterValue |
nvarchar | Уточнение параметра события |
NoContextMode |
int | Режим без контекста задачи |
AvailAsSmartSearch |
bit | Доступно как смарт-поиск в гридах |
Public |
bit | Публичное (видимо другим администраторам) |
OwnerUserId |
int | Владелец выражения |
QueryBuilderState |
nvarchar(max) | Состояние QueryBuilder (JSON) |
OriginID |
int | Контекст использования (Origin enum) |
IsDeleted |
bit | Мягкое удаление |
GUID |
uniqueidentifier | Уникальный ID для миграции |
ID |
int | Primary key |
Приоритет выполнения:
TSqlContent(если задан) — прямой TSQLTSqlCompiled(скомпилированное выражение)Content(формула визуального конструктора)
Origin — контекст использования¶
Где настраивается: атрибут originId при создании выражения через API
| Значение | Имя | Контекст |
|---|---|---|
| 0 | Почтовые ящики | |
| 1 | CustomPages | Кастомные страницы, виджеты, подписи, отчёты |
| 2 | Subcat | Подкатегории задач (дефолт) |
| 3 | Queue | Очереди |
| 4 | EdocumentLink | Э-документы |
| 5 | EdocumentSbisLink | Э-документы СБИС |
Правило валидации: если задан SubcatId — origin обязан быть Subcat (2). Исключение: старые контролы (прежняя админка) могли создавать выражения с SubcatId и origin=1 (CustomPages) — такие записи существуют в БД, но при пересохранении через SPA origin будет приведён к 2.
SmartQueries (выборки для виджетов/отчётов)¶
Где настраивается: SPA-страница /administration/rebus-queues (пункт rebus-queues в дереве автоадминки) / Admin API (/api/admin/smart/query)
Таблица БД: dbo.SmartQueries
| Поле | Что контролирует |
|---|---|
Name |
Название выборки |
SmartFilterID |
Смарт-выражение для фильтрации |
RecordsLimit |
Лимит записей |
SubcatID |
Привязка к категории |
XAxisExpressionID |
Выражение для оси X (графики) |
YAxisExpressionID |
Выражение для оси Y |
AggregationTypeID |
Тип агрегации |
SortByXAxis |
Сортировка по X |
SortAsc |
Направление сортировки |
EventID |
Событие (для контекста) |
SmartQueries — связующее звено между смарт-выражениями и UI-виджетами. Каждый SmartQuery ссылается на один или несколько SmartExpressions через SmartFilterID, XAxisExpressionID, YAxisExpressionID.
Редактор выражений¶
Где настраивается: Admin API (/api/admin/smart/expression-editor)
Визуальный редактор — ключевой инструмент администратора. Состоит из:
- Дерево свойств — свойства сущностей (Задача, Пользователь, Комментарий…), из которых строится выражение
- Панель операторов — операторы и функции
- Визуальное представление формулы
Основные методы редактора:
| HTTP | Маршрут | Назначение |
|---|---|---|
| GET | {id}/editor |
Загрузить выражение в редактор |
| POST | editor |
Сохранить выражение |
| POST | editor/execute |
Выполнить и проверить выражение |
| POST | editor/tree/reload |
Перестроить дерево свойств |
| POST | editor/tree/expand |
Развернуть узел дерева |
| GET | editor/toolbar/objects |
Список доступных операторов и функций |
Тестирование выражений через execute и тест-кейсы¶
Endpoint: POST /api/admin/smart/expressions/editor/execute
Выполняет SE и возвращает результат + execution plan. Работает из Admin UI (кнопка «Тест» в редакторе выражений) и через curl.
URL Admin UI: /spa/noframe/administration/smart-expressions?SubcatId={subcatId}&ID={seId}&EventID={eventId}&ActionsPackID={packId}
Ключевые параметры payload:
| Параметр | Тип | Назначение |
|---|---|---|
expression |
object | Полный объект SE (id, tSql, pgSql, subcatId, isFilter и т.д.) |
context.eventId |
string | Событийный контекст: "AfterTaskCreate", "BeforeTaskChange" и т.д. Позволяет тестировать событийно-зависимые SE |
context.subcatId |
int | Категория контекста |
context.isFilter |
bool | Тип: фильтр или условие |
params.contextId |
int/null | ID задачи-контекста. null → используется фиктивный ID (-1) |
generateDummyParams |
bool | Автоподстановка фиктивных параметров (@ContextId = -1 и т.д.) |
getExecutionPlan |
bool | Вернуть план выполнения (EXPLAIN ANALYZE для PG) |
runOnSmartPgConnection |
bool | Ключевой флаг. true → выполняет pgSql на PG через SmartPgConnectionString. false/отсутствует → выполняет tSql на MSSQL |
Ответ (data):
| Поле | Описание |
|---|---|
filterResult |
Результат фильтра (bool) |
objectResult |
Результат для non-filter SE |
tSql |
Итоговый SQL (tSql или pgSql в зависимости от runOnSmartPgConnection) |
executionPlan.executionPlanMsSql |
MSSQL plan (если запрашивался, требует SHOWPLAN permission) |
executionPlan.executionPlanPostgreSql |
PG EXPLAIN ANALYZE JSON (если runOnSmartPgConnection: true) |
matchExpectedResult |
Совпадение с ожидаемым типом |
actualResultType |
Фактический тип результата |
Пример curl (PG):
curl -s -H "1F-Pat: $PAT" -H "Content-Type: application/json" \
-X POST "https://{host}/api/admin/smart/expressions/editor/execute" \
-d '{"expression":{...},"context":{"eventId":"AfterTaskCreate","subcatId":5574,"isFilter":true,...},"params":{"contextId":null,"eventParameters":[]},"getExecutionPlan":true,"generateDummyParams":true,"runOnSmartPgConnection":true}'
Известные ограничения:
generateDummyParams: trueподставляет@ContextId = -1— выражения с JOIN на контекстную задачу вернут пустой результат, но синтаксическая проверка пройдёт- Execution plan для MSSQL требует SHOWPLAN permission на БД (у PAT-пользователя может не быть)
Позволяет создавать тестовые наборы данных для отладки смарт-выражений. Тест-кейс = набор входных параметров + ожидаемый результат.
Контрол выбора смарт-выражения (dropdown) принимает параметры:
| Параметр | Дефолт | Влияние |
|---|---|---|
originId |
2 (Subcat) | Контекст: какие свойства доступны в дереве |
subcatId |
null | Привязка к категории (фильтрует выборку) |
isFilter |
true | Тип: фильтр или условие |
eventId |
null | Событие (для условий правил) |
smartExpressionId |
null | Текущее выбранное выражение |
Справочник синтаксиса — дополнения к read-data.md¶
Базовый справочник операторов и функций для чтения данных — в read-data.md: числовые/строковые/датовые/логические/агрегатные функции, операторы сравнения, работа со всеми типами ДП (включая Lookup, Multilookup, Таблицу, Файл, Выбор пользователей), реквизиты задачи, ресурсы, FileStorage. Ниже — то, что в нём явно не описано.
Математические функции¶
Математические функции выражений:
| Функция | Параметры | Возвращает | Пример / описание |
|---|---|---|---|
ПоМодулю(N) |
Число | Число | Абсолютное значение (модуль) |
Степень(N, M) |
Число (основание N), Число (показатель M) | Число | N в степени M |
УрезатьДоЗнаков(N, Знаков) |
Число, Число (макс. знаков после запятой) | Число | УрезатьДоЗнаков(123.456, 2) = 123.45; УрезатьДоЗнаков(123, 2) = 123 |
СлучЗнач(N) |
Число (seed) | Число | Случайное десятичное от 0 до 1, рассчитанное на основе указанного числа |
ЗнакЧисла(N) |
Число | Целое | 1 для положительных, -1 для отрицательных, 0 для нуля |
Корень(N) |
Число | Число | Квадратный корень |
Базовая арифметика (
+,-,*,/, сравнения),Округлить,МинЦелоеНеМеньше,МаксЦелоеНеБольше,IsNullDecimal,ВСтроку,ВЦелоеЧисло,ВДробноеЧисло— см.read-data.md§ Числовые ДП.
Строковые функции — дополнение¶
Дополнительные строковые функции:
| Функция | Параметры | Возвращает | Назначение |
|---|---|---|---|
DateConvert(Дата, СтильЧисло) |
Дата, Целое (стиль формата MS SQL CAST/CONVERT) |
Строка | Преобразование даты в строку по указанному стилю (см. справочник стилей MS SQL date-and-time-styles) |
ПовторитьСтроку(Строка, N) |
Строка, Целое | Строка | Повторяет строку N раз |
Конкатенация(Строка1, Строка2) |
Строка, Строка | Строка | Соединяет две строки (функциональная альтернатива оператору +) |
Остальные строковые функции (
СтрокаСодержит,НачинаетсяС,ЗаканчиваетсяНа,Подстрока,ВернутьСлева/Справа,ВВерхРегистр/ВНижРегистр,ЗаменитьВСтроке,БезПробелов,ДлинаСтроки,IsNullString,ПоискВСтроке,ПоискПоШаблону), а также оператор+для конкатенации — см.read-data.md§ Строковые ДП.
Объект «Текущий пользователь» (раздел дерева «Прочее»)¶
В дереве сущностей редактора раздел «Прочее» содержит объект «Текущий пользователь» — пользователя, под которым выполняется смарт-выражение. Через него доступен полный набор параметров 1F.User (ID, логин, ФИО, email, группы, орг.единица — см. read-data.md § Пользователь (User)).
Применяется для проверки принадлежности к группе/орг.единице, подстановки имени в выражение, отбора задач по исполнителю/заказчику = текущий пользователь. При редактировании глобальных смартов (форма general-smart, без контекста категории/события) обращение к объектам системы возможно только через раздел «Прочее» — это единственный путь к данным пользователя в таком контексте.
Блок «Используется» — параметры события «Во время открытия задач軶
Для отбора задач в блоке «Используется» категории (вкладка, отображающая задачи, ссылающиеся на текущую через Lookup/Multilookup) применяются смарт-фильтры. Особенности дерева сущностей такого фильтра:
- Параметры основной задачи (в карточке которой открыт блок) — через папку «Параметры события "Во время открытия задачи"» в дереве.
- Параметры задач, отображаемых в блоке (ссылающихся) — через объекты вне контекста события, ниже в дереве сущностей.
- ДП основной и зависимых задач — через объекты «Значения ДП».
Ограничения языка смарт-выражений¶
Что нужно учитывать при написании выражений:
ORDER BYзапрещён в скрипте смарт-фильтра, доступного в смарт-поиске (отбор в табличном представлении категории).- Тип возвращаемого результата должен соответствовать контексту использования: для записи в поле «Дата» —
DateTime; для поля единичного объекта — единичный объект, не список; для смарт-фильтра —Boolean(тип выставляется системой автоматически и не редактируется). - Конвертация TSQL → SMART не предусмотрена. Из режима SMART можно перейти в TSQL (
Конвертировать в режим TSQL), обратный путь отсутствует — кнопка не отображается, если выражение в TSQL. - Список значений в смарт-выражении записывается через фигурные скобки:
{ААА, ВВВ, ССС}. Чтобы единичный объект воспринимался как коллекция, он тоже заключается в{}. - Запись (модификация) ДП через смарт-выражения использует отдельный синтаксис (JSON для SelectUsers/Email, разделители
+/-/=/#/|и]||[для Таблицы и Выбора нескольких задач) — описан в../smart-actions/admin.md. Smart-filters отвечают только за чтение и фильтрацию.
Типичные ошибки настройки¶
Частые проблемы и где их искать:
| Симптом | Причина | Где проверить | SQL-диагностика |
|---|---|---|---|
| Выражение возвращает пусто | Неверный SubcatID / OriginID | Форма general-smart |
select ID, Name, SubcatID, OriginID, IsFilter from dbo.SmartExpressions where ID = {id} |
| Редактор не показывает свойства | Неверный Origin (не тот контекст) | Origin-audit.md → таблица | select ID, Name, OriginID from dbo.SmartExpressions where Name like '%{name}%' |
| «Выражение удалено» но используется | IsDeleted = 1, но ссылки остались | Поиск по FK | select * from dbo.SmartExpressions where IsDeleted = 1 and ID in (select SmartFilterID from dbo.CustomQueueActions) |
| TSql-выражение не работает, визуальное — да | TSqlContent имеет приоритет, но содержит ошибку | Поле TSqlContent | select ID, Name, left(TSqlContent, 200) from dbo.SmartExpressions where TSqlContent is not null and ID = {id} |
| SmartQuery виджет пустой | SmartFilterID ссылается на несуществующее выражение | Форма rebus-queues |
select sq.*, se.Name as FilterName, se.IsDeleted from dbo.SmartQueries sq left join dbo.SmartExpressions se on sq.SmartFilterID = se.ID where sq.ID = {id} |
| Дерево свойств в редакторе неполное | Внутренняя ошибка построения дерева свойств | — | Обновить дерево («Перестроить»); если не помогает — обратиться в поддержку 1Ф |
Связанные документы:
- Справочник чтения данных — операторы и функции выражений
- Смарт-действия — администрирование — привязка правил к событиям, смарт-доступ