Дополнительные параметры¶

Дополнительные параметры (ДП) — это настраиваемые поля задач: текст, число, дата, выпадающий список, ссылка на другую задачу (Lookup), файл, таблица и т.д. Раздел отвечает за создание ДП, их типы и настройки, привязку к категориям, группировку в блоки на форме задачи, связи между параметрами и гибкие права доступа.

Документ описывает, где и что настраивается и как диагностировать неверную настройку.

Где настраиваются ДП¶

Настройки ДП разнесены по нескольким местам:

Что настроить	Где
Создание ДП, тип, глобальные настройки	Администрирование → Параметры (ДП) (форма `extparams`)
Привязка ДП к категории, порядок, обязательность, доступ	Настройки категории → вкладка «ДП»
Блоки и группы блоков на форме задачи	Формы `ext-param-blocks`, `extparam-blocks-groups`
Связи между ДП («ведущий-ведомый»)	Администрирование → Связи параметров (форма `extparamlinks`)
Гибкие права на задачи через ДП	Формы `ep-rights-flat` / `ep-rights-lkp` / `ep-rights-mlt`
Смарт-доступ к ДП (включая триггеры пересчёта)	Настройки категории → ДП → вкладка «Смарт-доступ»

Механизмы администрирования¶

Автоадминка (dbadmin)¶

Часть настроек ДП ведётся через формы автоадминки — стандартные карточки над таблицами БД:

Alias формы	Название	Таблица БД	Полей	Секций	Основное назначение
`ext-param-blocks`	Блоки ДП	`dbo.ExtParamBlocks`	15	1	Блоки, в которые группируются ДП на форме задачи
`extparam-blocks-groups`	Группы блоков ДП	`dbo.ExtParamBlocksGroups`	11	1	Группы блоков (верхний уровень группировки)
`custom-task-used-as-ep-block-settings`	Параметры таблицы БИ	`dbo.CustomTaskUsedAsEpBlockSettings`	24	1	Настройки отображения таблицы БИ для ДП типа `Table`
`extparam-view-personal-settings`	ДП в личных папках	`dbo.ExtParamViewPersonalSettings`	3	1	Отображение ДП в персональных папках/представлениях
`ep-rights-flat`	Flat: гибкие права	`dbo.EPRightsFlat`	5	1	Гибкий доступ к задачам через ДП `SelectUsers`
`ep-rights-lkp`	Lookup: гибкие права	`dbo.EPRightsLkp`	6	1	Гибкий доступ через цепочку `Lookup -> SelectUsers`
`ep-rights-mlt`	Multilookup: гибкие права	`dbo.EPRightsMlt`	6	1	Гибкий доступ через `Multilookup -> SelectUsers`

Отдельные SPA-страницы (в дереве администрирования)¶

Ключевые операции с ДП вынесены на отдельные страницы интерфейса администрирования:

Alias формы	Название	Url	Таблица БД	Основное назначение
`extparams`	Параметры (ДП)	`/administration/extparams-all`	`dbo.ExtParams`	Глобальная карточка ДП: тип, имя, базовые флаги
`extparamlinks`	Связи параметров	`/administration/extparamlinks`	`dbo.ExtParamLink`	Связи «ведущий-ведомый» связи между ДП

Форма extparams фигурирует и в разделе «Категории», но здесь рассматривается как часть жизненного цикла ДП.

Admin API¶

Программно ДП настраиваются через Admin API:

Базовый маршрут	Основные методы	Назначение
`/api/admin/extparams`	`POST`, `GET short`, `GET {id}/subcategories`, `GET {id}/signatures`, `DELETE {id}`	Управление глобальным ДП и анализ использования
`/api/admin/subcat/extparams`	`GET`, `POST`, `DELETE`, `reorder`, `copypermissons`, `copypermissonsstates`, `copy-ep-values`, `propagate-defaults`	Привязка ДП к категории и настройки на уровне категории. При редактировании матрицы доступа (карандаш рядом с «Доступ = Матрица доступа») система автоматически создаёт записи в `ExtParamTableSettingsInSubcat` с уникальными `Guid` — это может приводить к конфликту первичного ключа при импорте конфигурации между площадками в режиме KeepIdentity (дедупликация по составному PK `SubcatId, ExtParamId, ColumnId` в этом режиме не выполняется)
`/api/admin/extparams/settings`	`GET {extParamId}`, `POST`, `POST {extParamId}/sync-table-values`	Глобальные настройки ДП по типам
`/api/admin/subcat/extparams/blocks`	CRUD блоков, CRUD групп, links, reorder	Блоки/группы блоков ДП и их состав
`/api/admin/ext-params/links`	`POST`, `GET`, `POST {linkId}`, `DELETE {linkId}`	Связи между ДП
`/api/admin/extparam/options`	`add`, `update`, `delete`, `delete-all`	Опции для list/combobox ДП
`/api/admin/ext-params/table`	`GET template`, `PUT template`	Шаблон и отображение ДП типа `Table`

Ключевые настройки¶

1) Типы ДП (`ExtParamType`)¶

Где настраивается:

автоадминка: форма extparams;
API: POST /api/admin/extparams, POST /api/admin/extparams/settings.

Таблица БД: dbo.ExtParams.

Что важно:

тип ДП задаёт допустимый формат значения, таблицу хранения и вид поля для ввода;
изменение типа у уже используемого ДП может приводить к несовместимости старых значений;
всего 21 тип ДП.

Практически используемые типы (примерно):

Text, TextArea, TextareaWOFormat;
NumericValue, Money, Checkbox;
Date, Datetime;
Select, Combobox;
LookUpField, MultiSlctSubcatTasks;
SelectUsers, File, Table, Through, Address, URL, ExtParamAddressees, Numerator, Tree.

2) Создание и глобальная настройка ДП¶

На странице «Параметры (ДП)» отображается полный список параметров с их идентификаторами и типами. Новый параметр создаётся кнопкой «Создать ДП»: в открывшемся окне задаются имя и тип.

Страница «Список ДП» и окно создания нового параметра с выбором имени и типа

Где настраивается:

форма extparams;
API: POST /api/admin/extparams и POST /api/admin/extparams/settings.

Ключевые элементы:

имя/локализация;
тип и опции, специфичные для типа;
валидационные правила и флаги поведения.

Эффект:

глобальная часть влияет сразу на все категории, где ДП уже используется;
после смены критичных настроек может понадобиться пересчет/синхронизация данных (особенно для Table).

3) Привязка ДП к категории¶

Привязка и настройка ДП в категории выполняется на отдельной странице: слева — список параметров категории, справа — панель настроек выбранного параметра с группами «Отображение», «Правила», «Доступ и валидация».

Где настраивается:

UI: настройки категории → вкладка «ДП» (subcategory-extparam-settings)
API: /api/admin/subcat/extparams; POST /api/admin/subcategories/{subcatId}/ext-params

Таблицы БД: dbo.ExtParams, dbo.ExtParamValues, dbo.ExtParamsInSubcat (привязка), dbo.ExtParamsInSubcatToBlocks (связи с блоками)

Критичные зависимости:

права по статусам нужно пересматривать при добавлении новых статусов маршрута;
копирование прав массово перезаписывает target-настройки;
индекс полезен для поиска, но должен применяться осознанно.

Список ДП категории¶

ДП отображаются таблицей с колонками: ID, Имя ДП, Скрытый, Обязательный, Тип, Имя блока. Порядок строк определяет порядок полей на форме задачи.

Список ДП категории

Строки сгруппированы по блокам ДП. Перетаскивание строки за иконку слева меняет порядок поля на форме (SortOrder) и позволяет перенести параметр в другой блок.

Перетаскивание параметра внутри блоков ДП

При перетаскивании в другой блок система уточняет: переместить параметр или создать его дубль.

Действия при перетаскивании параметра: переместить или дублировать

Контекстное меню строки даёт операции со значением и связью: фильтр по значению, копирование, экспорт, разрыв связи, удаление.

Контекстное меню параметра в списке ДП

Индикаторы в списке:

Иконка повтора — ДП используется в нескольких блоках этой категории
Иконка шестерёнки — быстрый переход к настройкам ДП
Иконка копирования — создаёт новый ДП на основе текущего (не добавляет тот же ДП повторно)

Индикаторы и действия в списке ДП: повтор, шестерёнка, копирование

Настройки ДП в категории¶

Выбор ДП в списке открывает его настройки в правой панели — блоки «Отображение», «Правила», «Доступ и валидация».

Панель настроек выбранного ДП в категории

Для каждого ДП в категории доступны настройки:

Параметр	Описание
Имя ДП в категории	Отображаемое имя для данной категории (отличается от глобального имени ДП). Используется в таблицах, карточках, комментариях, БИ, мобильном приложении. Нельзя использовать спецсимволы `\/<>` и зарезервированные имена (Заказчик, Исполнитель, Статус, Категория, Задача). В сводных и виртуальных разделах (просроченные задачи, запрошенные подписи и т. п.) отображается глобальное имя ДП, а не имя для категории
Привязки ДП	Выбор блока ДП. Один параметр может быть в нескольких блоках, но не более одного раза внутри одного блока. Настройки привязки: порядок на форме, количество колонок, скрыт при постановке/в карточке. «Порядок на форме» синхронизируется с порядком ДП в списке (перетаскивание строки меняет его автоматически). Нельзя добавить в блок ДП «Выбор нескольких задач из категории» (Multilookup) со схемой оформления «ToDo list»
Количество занимаемых колонок	В текущем интерфейсе доступны 3 значения: «1/3 размера» (до 3 ДП в строке), «1/2 размера» (до 2 ДП в строке), «Во всю ширину» (1 ДП в строке); применяется к формам МТФ и НТФ. Варианты с 4–5 колонками удалены из интерфейса в 2026-02. Если ДП находится в блоке, применяется значение из настроек привязки к блоку, а не из этой настройки. Для Multilookup учитывается только при схеме оформления «Облако тегов»
Отображать с новой строки	Если установлен, это поле и все следующие за ним начинаются с новой визуальной строки — независимо от ширины экрана и количества колонок. Если поле со флагом скрыто, последующие поля отображаются стандартно. По умолчанию — выключено
Скрытый	ДП не отображается при постановке и в карточке
При постановке	Режим отображения ДП на форме создания задачи (НТФ): Отображать — поле показывается; Не отображать — поле скрыто при создании; Обязателен — поле отмечено `*`, и без его заполнения задачу нельзя создать. Режимы «Отображать» и «Обязателен» несовместимы с типами ДП «Сквозной» и «Нумератор». При копировании задачи в пользовательском режиме переносятся только ДП с режимом «Отображать» или «Обязателен». Если обязательный Lookup/Multilookup допускает пользователю единственное значение — оно подставляется автоматически. Для обязательной «Таблицы» при создании добавляется первая строка, а кнопка создания неактивна, пока не заполнены обязательные столбцы
Скрыть при пустом значении	На МТФ пустые значения не отображаются. Для НТФ — через CustomSetting `HideEmptyEpOnNtf=true`
Подсказка	До 1000 символов. Отображается иконкой рядом с полем. Для таблиц — в панели инструментов. Поддерживает смарт-выражения с типами: `default`, `info`, `warning`, `error`, `success` (формат: `select '{Тип}' as tooltipType, '{Текст}' as tooltip`). По умолчанию тип `default` (серая иконка); цветные типы доступны только при включённой опции «Подсказка из Смарт-выражения»
Значение по умолчанию	Фиксированное, смарт-выражение или пусто. Для таблиц — JSON: `{"rows":[{"c{colId}":"val",...},...]}`. Перекрывает глобальное значение по умолчанию ДП (`DefaultValue`). Для флажка (с v2.263 Скорпион) — всегда `false` по умолчанию (правило не действует для флажков в категориях, добавленных до v2.263). JSON для Таблицы подставляется только в редактируемые колонки — колонки ReadOnly/Invisible/Smart и виртуальные его игнорируют
Не копировать значения из задачи-источника	При создании задачи из контекста другой (БИ, Lookup, Multilookup, подзадачи) — отключает наследование значения. Если выключено — значение из источника имеет наивысший приоритет. Включать настройку нужно в категории-источнике (откуда вызывается создание), а не в целевой; по умолчанию выключена
Обязателен для завершения	Задача не завершается без заполнения. Не работает для Таблицы — используйте обязательность колонок
Требовать комментарий при изменении	При повторном изменении запрашивается комментарий. Не работает для Таблицы. Недоступен, если отключено «Сохранять историю изменений ДП»
Заполняется один раз	После первого заполнения — только для чтения. Не влияет на Администратора категории и Администратора задач
Только уникальные значения	Автоматически включает «Добавить индекс». Недоступен для: Email, Большой текст, Multilookup, Файл, Число, Таблица

Параметр, привязанный к системному блоку «Шапка задачи», отображается в верхней части карточки задачи — рядом со статусом и кнопками действий.

Параметр в системном блоке «Шапка задачи» карточки задачи

Доступ к ДП¶

Приоритет: права на категорию > права на ДП. Если нет доступа к категории — доступ к ДП не действует.

Режим	Описание
По задаче	Редактирование для пользователей с правом «Исполнять» в данной категории
Только по группам	Доступ по принадлежности к группам (редактирование или чтение)
По задаче или группам	Объединение (ИЛИ)
По задаче и группам	Пересечение (И)
По матрице доступа	Статусы × группы/роли/права → просмотр/редактирование. Иконка 👁 = просмотр, ✏️ = редактирование. При закрытом просмотре в списке задач вместо значения ДП показывается «(нет доступа)»
По SQL-функции	Скалярная (`@ExtParamId, @SubcatId, @TaskId, @UserId, @StateId, @IsOwner, @IsSubscriber, @IsPerformer, @IsResponsiblePerformer, @IsAcceptor` → `INT`: 0=нет, 1=чтение, 2=редактирование) + опциональная пакетная (`@TaskIds dbo.id_tbl_type readonly, @ExtParamId, @UserId` → `TABLE`). Пакетная необязательна: без неё работает скалярная. Если задана только пакетная — она применяется лишь при наличии контекста задачи и не работает на форме создания (НТФ), поэтому доступ на НТФ тогда не контролируется (для контроля на НТФ задайте скалярную). Если заданы обе — скалярная для одиночной задачи, пакетная для списка. При замещении функция вызывается от имени замещаемого, отдельной логики для заместителей не требуется

Режимы «По матрице доступа» и «По SQL-функции» учитываются и при быстром поиске файлов в шапке системы — в результатах видны только файлы из доступных пользователю ДП.

Просмотр не ограничивается — опция отключает проверку прав на просмотр ДП там, где требуется только право на редактирование: функции доступа (скалярная и пакетная) в таких контекстах не вызываются. Применяется с режимами «По матрице доступа» и «По SQL-функции», когда значение могут видеть все пользователи с доступом к категории, а ограничивать нужно только редактирование.

Доступ зависит от статуса — матрица видимости/редактирования по статусам маршрута. При смене видимости — полная перезагрузка страницы. Доступ на чтение = видимость: без права чтения на статусе ДП не отображается на карточке. При закрытом просмотре значение скрыто и в списке задач, но комментарии об изменении значения ДП пользователю всё равно видны.

Матрица «Доступ зависит от статуса»: чтение и редактирование по статусам маршрута

Смарт-доступ — правила доступа, рассчитываемые смарт-выражением для отдельных пользователей по условиям; подробно настройка модального окна описана в § «7а) Смарт-доступ к ДП». Скрытие смарт-доступом убирает значение из карточки и списка задач, но не скрывает комментарии об изменении ДП.

Валидация ДП¶

Значение дополнительного параметра можно проверять двумя способами.

1. Смарт-выражение (валидация по бизнес-правилу)

Смарт-выражение возвращает пустую строку (OK) или текст ошибки. Триггеры: сохранение, создание задачи, переходы, настраиваемые кнопки. При ошибке — красная рамка вокруг поля и текст ошибки под полем.

Настройка смарт-выражения проверки ДП с выбором триггеров и переходов

2. Регулярное выражение (валидация формата ввода)

Для типов «Текст», «Число», «Номер телефона», «Lookup», «Multilookup», «Select» можно задать регулярное выражение, которому должно соответствовать введённое значение. Используется для проверки формата (телефон, email, артикул, ИНН и т. п.).

Поведение при вводе:

Триггеры проверки: нажатие Enter, потеря фокуса (blur — клик в другое поле, клик за пределы формы, закрытие карточки задачи крестиком, переход в другую задачу из табличного представления или канбана). То же самое работает в модальных окнах.
Если значение не проходит проверку — поле получает красную обводку, под полем выводится текст ошибки. Алерт-модалка не открывается, стиль ошибки такой же как у смарт-валидации и смарт-отмены редактирования.
Пока значение в поле не соответствует регулярному выражению, остальные дополнительные параметры в карточке задачи остаются доступными для просмотра и редактирования. Пользователь может исправить значение в проблемном поле или очистить его.
Значение не сохраняется до тех пор, пока не пройдёт проверку.

Где настраивается: настройки дополнительного параметра → поле «Регулярное выражение». Подсказку с описанием формата для пользователя указывают в поле «Подсказка».

Шифрование ДП¶

Доступно для типов: Текст, Большой текст, Большой текст с форматированием. Требует разрешения шифрования в основных настройках категории. Необратимо — отключить нельзя. После включения — ручная денормализация. История шифруется только с момента включения. После включения настройка «Допустимая длина текста» для этого ДП обнуляется и становится недоступной для редактирования.

Синхронизация ДП¶

Значение ДП можно синхронизировать между связанными задачами:

Настройка	Описание
Синхронизировать в родительскую	При заполнении — автокопирование в родительскую задачу (одинаковые ExtParamID). Значения, заданные вручную в подзадаче, поставленной вручную, не перезаписываются
Синхронизировать в дочернюю	При изменении — автокопирование во все дочерние. Для Файла — создаются отдельные копии (рост БД)

⚠️ Синхронизация работает вне зависимости от прав доступа на категории.

Прочие настройки ДП¶

Дополнительные настройки ДП:

Параметр	Описание
Допустимая длина текста	Только для денормализованных категорий. Текст ≤ 1500 символов. При шифровании — сбрасывается. При добавлении ДП ставится ограничение по умолчанию (зависит от типа), его можно изменить вручную. Недоступно для типов: Email, Multilookup, Файл, Число, Таблица
Добавить индекс	Ускоряет загрузку списка задач. Авто-включается и блокируется для редактирования при «Только уникальные значения»
Не денормализовывать	Колонка не создаётся в `TasksInSubcatXXXDenormalized`. По умолчанию выключено (колонка создаётся)
Участвует в поиске	ДП участвует в поиске «в полях» списка задач
Сохранять историю изменений	Регистрация изменений значений. Для отображения в комментариях — нужна настройка категории «Отправлять комментарий при сохранении истории». По умолчанию выключено; если выключено — комментарии о смене значения ДП не отправляются. Для категорий-пространств включено по умолчанию для параметра «Содержимое страницы»
Пустое значение хранить как NULL	В денорм. таблице `ExtParamXXXValue` = NULL. По умолчанию = включено. Исключение: для текстовых ДП пустая строка из `ExtParamValues` сохраняется как пустая строка, а не NULL

ДП «Таблица» — дополнительные настройки блока¶

Ограничение добавления/удаления строк — смарт-фильтры для кнопок панели инструментов; отображение кнопок учитывает также право пользователя на редактирование ДП в текущем статусе. Разрешение фильтрации строк. Доступ и «Доступ зависит от статуса» — на уровне отдельных колонок, действуют только для таблиц с включённой опцией «Использовать новую таблицу». ⚠️ Ограничения колонок не действуют для Диспетчера задач (служебный пользователь).

Создание и копирование ДП¶

В категорию можно добавить уже существующий ДП или создать новый. Существующий параметр выбирают в выпадающем списке «Выберите ДП» и добавляют кнопкой «Добавить».

Добавление существующего ДП в категорию

Новый ДП создаётся кнопкой «Создать ДП»: в окне указывают имя и тип (тип неизменяем после создания). Не рекомендуется более 150 ДП в категории (каждая колонка Таблицы — 1 ДП).

Окно создания ДП в категории

Имя, тип, пример содержимого, регулярное выражение и подсказку самого ДП редактируют в его стандартной форме настроек.

Стандартная форма редактирования ДП

Копирование значений — массовое копирование из одного ДП в другой по всем задачам категории (параметр-источник → параметр-получатель). Не работает для Таблицы и Дерева.

Окно копирования значений между параметрами

UI-переход к настройкам¶

ПКМ на ДП в карточке задачи → «Настройки» → открывает список ДП с фильтром. Для Таблицы — открывает настройки параметра в системе.

Переход к настройкам ДП из карточки задачи в пользовательском режиме

Прочее по интерфейсу:

Для ДП «Большой текст с форматированием» доступен редактор Markdown.
Для ДП «Файл» в режиме «Мультифайл» поведение подсказки выровнено с остальными типами (без дублей в НТФ, доступно в режиме «только для чтения» МТФ).

4) Блоки ДП и группы блоков¶

ДП на карточке задачи можно распределить по смысловым блокам (например, «Финансовые показатели», «Контакты»): блок можно сделать сворачивающимся, задать ему цвет и порядок. Не каждый ДП обязан принадлежать блоку; один ДП может входить в несколько блоков, но в один блок — только один раз. Привязка хранится в dbo.ExtParamsInSubcatToBlocks. Для каждого блока в списке отображается значок мультиязычности (локализации).

Список блоков ДП категории

Где настраивается:

формы ext-param-blocks, extparam-blocks-groups;
API: /api/admin/subcat/extparams/blocks.

Таблицы БД:

dbo.ExtParamBlocks;
dbo.ExtParamBlocksGroups;
таблицы связей ДП-блок.

Что контролируют:

визуальная группировка ДП на карточке задачи;
порядок отображения блоков и элементов внутри блоков;
привязка одного ДП к нескольким блокам (сценарий поддерживается).

Риски мисконфигурации:

«потерявшиеся» поля при неверном порядке/связях;
дублирование отображения одного ДП в нескольких блоках без согласованной логики отображения.

Создание и настройка блока¶

Новый блок создаётся кнопкой «Создать» над списком. В форме задают наименование, порядок на форме (относительно других блоков ДП и блоков «Используется»), группу блоков (необязательно — в списке только группы текущей категории), флаги «Может ли сворачиваться» / «По умолчанию свернут» и цвет.

Форма создания блока ДП

Цвет блока отображается цветной полосой в верхней части блока на карточке задачи.

Цвет блока — цветная полоса в верхней части

Дополнительные поля формы блока:

«Блок ДП по умолчанию» (ExtParamBlocks.DefaultBlock) — помечает блок как используемый по умолчанию для категории; отдельный флаг, не путать с «По умолчанию свернут».
«Системный блок» — read-only-признак; на данный момент системным является только блок «Шапка задачи» (системные поля и переход по маршруту).
«Связь таблицы БИ с блоком ДП» — встраивает в блок одну таблицу из настроенных в категории блоков «Используется» (рядом с полями блока). ⚠️ Доступно только для БИ с видом отображения «Таблица».

Видимостью и сворачиванием блока управляют четыре смарт-фильтра: «Сворачивать»/«Скрывать» × «в карточке (МТФ)»/«при постановке (НТФ)». Смарт-выражения используют событие «Во время открытия задачи» (WhenOpenTask = 64); контекст @eventParam1: 0=Undefined, 1=Spa (веб), 2=Mobile, 3=Conference (если параметр не передан — Undefined(0); если запрос распознан как мобильный — Mobile(2)). Блок появляется в карточке только после добавления в него параметров; если параметры скрыты при постановке — блок при создании задачи тоже скрыт.

Настройки созданного блока меняются по клику на строку в списке; удалить блок можно кнопкой «Удалить» в форме или из контекстного меню строки.

Форма редактирования блока ДП

Группы блоков¶

Блоки можно объединять в группы — на карточке задачи группа отображается единым контейнером; порядок блоков внутри группы определяется их «Порядком на форме».

Группа блоков ДП на карточке задачи

Группы создаются на странице «Группы блоков ДП» (кнопка над списком блоков).

Страница «Группы блоков ДП»

Новая группа создаётся кнопкой «Создать»: указывают категорию, имя группы, порядок на форме и при необходимости флаги сворачивания/скрытия.

Форма создания группы блоков

После создания группу выбирают в настройках блока (поле «Группа блоков»).

Выбор группы в настройках блока

Переход к настройкам из интерфейса¶

Открыть настройки блоков можно из пользовательского режима: ПКМ на блоке в карточке задачи → «Настройки» (пункт доступен только администраторам).

Переход к настройкам блоков из карточки задачи

Технические детали полей (ExtParamBlocks / ExtParamBlocksGroups), системный блок «Шапка задачи» и БИ-таблица в блоке ДП — в Блоки и группы блоков. Контекст события «При открытии задачи» для смарт-фильтров блока — в Известных проблемах смарт-действий.

5) Связи между ДП (`ExtParamLink`)¶

Где настраивается:

форма extparamlinks;
API: /api/admin/ext-params/links.

Таблица БД: dbo.ExtParamLink.

Назначение:

«ведущий-ведомый» зависимости ДП;
фильтрация допустимых значений зависимого ДП на основе выбранного значения ведущего ДП.

Ключевые проверки:

исходный и зависимый ДП должны быть совместимы по типу сценария;
у ведущего ДП должны быть стабильно заполненные значения в задачах, иначе зависимый ДП будет «пустым».

6) Опции ДП (списки и выпадающие значения)¶

Где настраивается:

API: /api/admin/extparam/options;
страницы по конкретным типам в руководстве (lookup/list/file/table/through и др.).

Таблицы БД:

опции list/combobox в контуре настроек ДП;
значения задач хранятся в таблицах значений ДП.

Особенности:

delete-all для опций обнуляет справочник выбора и потенциально ломает существующие заполнения;
для File, Table, Lookup, Multilookup, Through есть специализированные настройки и отдельные риски.

7) Гибкие права на ДП / задачи¶

Где настраивается:

формы ep-rights-flat, ep-rights-lkp, ep-rights-mlt.

Таблицы БД:

dbo.EPRightsFlat;
dbo.EPRightsLkp;
dbo.EPRightsMlt.

Режимы:

Flat: доступ определяется значением ДП SelectUsers в этой же категории;
Lookup: доступ в категории A через lookup на категорию B, где хранится SelectUsers;
Multilookup: то же через множественную ссылку.

Ключевой инвариант:

в SelectUsers для этих сценариев не используется выбор орг.единиц, если модель прав строится только на пользователях/группах.

7а) Смарт-доступ к ДП (модалка в карточке ДП)¶

Отдельная система разграничения доступа: смарт-выражение возвращает список пользователей, которым применяются права CanRead / CanWrite на конкретный ДП в категории. Архитектура и таблицы — см. permissions-model.md § «Система 3: SmartAccessForExtParamsInSubcat».

Где настраивается: настройки категории → вкладка «ДП» → у конкретного ДП открыть модалку «Смарт-доступ» (administration-ext-params-settings-smart-access-info). Точка входа также упомянута в § «Где настраиваются ДП» выше.

Поля строки правила:

Поле	Описание
Смарт-выражение	Выражение, возвращающее список ID пользователей, на которых действует правило. ID извлекается из `value`/`id` объекта дропдауна или из «сырого» числового значения.
Доступ на чтение	Пользователи из выражения видят ДП.
Доступ на запись	Пользователи из выражения могут редактировать ДП.
Пересчёт при смене ДП	Список ДП-триггеров. При изменении значений этих ДП в задаче материализованный результат пересчитывается.
Пересчёт при добавлении пользователя в группу	Список групп-триггеров. При изменении состава этих групп материализованный результат пересчитывается.

Сохранение правил:

Каждое правило сохраняется независимо кнопкой «Добавить параметр» в модальном окне — сохранять всю форму настроек ДП не нужно.
После сохранения: уведомление «Смарт доступ сохранён», форма очищается для следующего правила, правило сразу появляется в списке.
Действует защита от дублирования при повторных кликах на кнопку сохранения.
Закрытие модального окна не требует отдельного сохранения — добавленные правила уже сохранены на сервере.

С 2.268.350 сохранение модалки работает корректно: до этого POST /api/admin/subcat/extparams/{id} падал с 400 (фронт читал id смарт-выражения из несуществующего поля, при редактировании затирались имя/группы, новые строки с временным id=0 правились не те), и ни смарт-выражение, ни права не сохранялись. Связано с бэк-фиксом #2095796 (тег 2.268.346) — без обоих изменений работает только половина связки: бэк ждёт триггеры массивом INamedEntity[], фронт умеет такой массив отдавать.

8) Таблица БИ для ДП `Table`¶

Где настраивается:

форма custom-task-used-as-ep-block-settings;
API: /api/admin/ext-params/table, POST .../extparams/settings/{id}/sync-table-values.

Таблица БД: dbo.CustomTaskUsedAsEpBlockSettings.

Что контролируется:

шаблон отображения таблицы;
параметры вывода колонок/строк;
синхронизация HTML-представления по существующим задачам.

Риски:

изменение шаблона без синхронизации приводит к «старому» отображению в части задач;
крупные перезапуски синхронизации нужно планировать по нагрузке.

9) Валидация значений: регулярное выражение и маска¶

Где задаётся:

автоадминка ДП → вкладка «Основные настройки» → поля «Регулярное выражение» и «Пояснение к полю»;
API: POST /api/admin/extparams/settings — поля в корне тела запроса: regExp (шаблон), regExpErrorMessage (текст ошибки). Не путать с маской ввода textSettings.mask (см. §«Справочник body-форматов» → Text/MaskedText).

Поведение:

значение, не прошедшее проверку, подсвечивается; под полем выводится текст из «Пояснение». Если пояснение пустое — стандартный текст ошибки.
если «Регулярное выражение» не задано, текст «Пояснение» используется как обычная подсказка под ДП.
для типа Text при одновременно заполненных mask (маска ввода) и regExp — приоритет у регулярного выражения.
опция «сохранять unmasked-значение» в textSettings.mask поддерживается в двух форматах: корневом saveUnmaskedValue: true и вложенном extParamSettings: { saveUnmaskedValue: true }. До 2.268.360 (#2097173, коммит 08b19ce35c) работал только корневой формат, вложенный игнорировался; в той же сборке исправлено пропадание значения в поле на 300 мс после потери фокуса (Tab) при включённой маске. Подробности поведения для пользователя — в types-reference.md § «ДП "Текст" (Text)".

⚠️ Регулярные выражения не работают для типов:

Checkbox (Галочка),
Tree (Дерево),
TextArea (Большой текст с форматированием),
SelectUsers (Выбор пользователей).

⚠️ Также не применяется для Text с активной опцией «Отображать ДП текст как телефон» — в этом случае вшита фиксированная маска +X (XXX) XXX-XXXX.

Часто используемые шаблоны:

Что проверяется	Регулярное выражение	Комментарий
ФИО (рус.)	`^[А-ЯЁа-яё]+(?:-[А-ЯЁа-яё]+)* [А-ЯЁа-яё]+(?: [А-ЯЁа-яё]+)?$`	Учитывает двойные фамилии и составные имена. Без цифр, латиницы и спецсимволов кроме дефиса и пробела
Серия и номер паспорта РФ	`^\d{4} \d{6}$`	4 цифры серии, пробел, 6 цифр номера
ИНН (юр. лицо)	`^\d{10}$`	10 цифр
ИНН (физ. лицо)	`^\d{12}$`	12 цифр
БИК	`^\d{9}$`	9 цифр
Мобильный телефон РФ	`^\+7 $\d{3}$ \d{3}-\d{2}-\d{2}$`	Формат `+7 (xxx) xxx-xx-xx`
Дата `ДД.ММ.ГГГГ` (формат)	`^(0[1-9]\\|[12][0-9]\\|3[01])\.(0[1-9]\\|1[0-2])\.\d{4}$`	Только формат, без проверки корректности дня в месяце и високосного года
E-mail	`^[\w.+-]+@[\w-]+(\.[\w-]+)*\.[a-zA-Z]{2,}$`	Стандартный формат

Примеры — общеупотребимые варианты. Один и тот же контракт может быть выражен разными regex; при необходимости подбирать под фактический формат ввода клиента.

10) Тип ДП «Дерево» (Tree) — узкие настройки¶

Назначение: хранение значения, выбираемого из внутренней иерархии узлов, которую администратор формирует вручную в настройках ДП. Это собственное дерево значений ДП, не иерархия категорий и не Lookup в иерархическом режиме.

Хранение: ExtParamValues.ExtParamValue (текст узла) + DataSourceItemID (ID узла). Денормализация — varchar/nvarchar(1000).

Настройка узлов в админке:

Ввести название в поле «Текст создаваемого узла» → кнопка «Создать узел» → новый узел добавляется на первый уровень.
Чтобы добавить дочерний узел: предварительно нажать на родительский узел, затем создать.
Иерархия меняется перетаскиванием узлов мышью.
Редактирование названия и удаление узла — кнопки справа от названия в дереве.

API: body для POST /api/admin/extparams/settings использует treeSettings; см. таблицу маппинга в §«Справочник body-форматов».

Ограничения:

регулярные выражения для Tree не работают (см. §9);
изменение типа ДП после создания невозможно.

11) Тип ДП «Выпадающий список» (Select / Combobox) — узкие настройки¶

Различие двух типов:

Параметр	`Select`	`Combobox`
Произвольный текст	нельзя — только выбор из списка	можно ввести своё значение (сохраняется в задачу, но не в источник)
Радиокнопки	поддерживаются	не поддерживаются
Максимальная длина значения	200 символов	200 символов

Источник данных: задаётся в selectSettings.dataSource / comboboxSettings.dataSource.

Источник	Когда использовать	Быстрые подсказки
Набор элементов	Фиксированный перечень, редко меняется	Поддерживаются (3 последних выбранных значения в категории)
Из таблицы (БД / SQL-view)	Динамический список из таблицы	Не поддерживаются

Поля при «Набор элементов»:

задаются массивом selectSettings.elements / comboboxSettings.elements (см. §«Справочник body-форматов» → Select/Combobox);
каждый элемент: value, isDefault, локализованное значение;
при обновлении передаётся полный список — перезатирает предыдущие.

Поля при «Из таблицы»:

Параметр	Описание
Имя таблицы	Название таблицы БД или SQL-view
Колонка значения	Уникальный ID, сохраняется в `DataSourceItemID`
Колонка текста	Отображается пользователю, сохраняется в `ExtParamValue`
Колонка сортировки	По какой колонке сортировать. При активном «Автоматически сортировать по алфавиту» приоритет у автосортировки
Колонка контекст текущей задачи	TaskID; если заполнена — список фильтруется по совпадению значения колонки с ID текущей задачи

⚠️ Поля «Колонка значения» и «Колонка текста» не должны содержать пустых значений в источнике.

Радиокнопки (только Select):

«Использовать отображение в виде радиокнопок» — ДП отображается блоком радиокнопок;
«Отображать радиокнопки в ряд» — горизонтальное расположение (иначе вертикальное);
⚠️ для радиокнопок нет возможности отменить выбор — применять только для обязательных ДП и обязательно задавать значение по умолчанию.

⚠️ Важно о производительности для «Из таблицы»: при таком источнике система (включая мобильное приложение и форму создания задачи НТФ) передаёт все значения списка целиком. Для таблиц с большим количеством записей это перегружает клиент — фильтруйте на уровне источника или переходите на LookUpField (там источник — категория с постраничной загрузкой и смарт-фильтром).

12) Выбор между Multilookup, Таблицей и БИ («Используется»)¶

При проектировании связанной информации внутри задачи возникает выбор между тремя инструментами. Критерии:

Инструмент	Когда использовать	Когда не использовать
Multilookup (`MultiSlctSubcatTasks`)	Важен только признак «выбран / не выбран» элемента; никакие другие атрибуты не отслеживаются (пример: сегменты рынка, отрасли клиента)	Нужны атрибуты у выбранного элемента в контексте этой задачи
Таблица (`Table`)	У каждого выбранного элемента есть дополнительные характеристики, которые наполняются именно в этой задаче (пример: позиции заказа с количеством и ценой; опыт работы по специальности в карточке соискателя)	У элементов есть собственный жизненный цикл и статусы
БИ (блок «Используется») на категорию-источник	(1) у элементов собственный жизненный цикл и смена статусов с автоматизациями (пример: участники мероприятия — «Приглашён → Принял → Оплатил»); (2) нужно разделение доступа к элементам (для строк `Table` и содержимого ДП смарт-доступ невозможен — только для задач); (3) элементы должны быть видны в нескольких частях системы через перекрёстные ссылки (карточка мероприятия ↔ карточка клиента)	Достаточно простого отбора без жизненного цикла

Один процесс может комбинировать все три инструмента: Multilookup на этапе сбора заявок (отбор магазинов), Lookup + блок «Используется» после согласования (отдельные задачи на каждый магазин), Table внутри каждой задачи для атрибутов выполнения.

См. также бизнес-описание ДП и категорию как сущность с жизненным циклом.

CustomSettings — глобальные ключи поведения ДП¶

Задаются на странице «Настройки приложения» → «Пользовательские ключи». Источник: dbo.SettingsCustom.

Ключ	Тип / По умолчанию	Назначение
`DecodeBigTextEp`	bool / `false`	Отображение эмодзи в ДП «Большой текст без/с форматированием». Исключения — список ID в `DecodeBigTextEpExcept`
`DecodeBigTextEpExcept`	array	ID ДП, к которым `DecodeBigTextEp` не применяется
`ExtParamTableLookUpTextLength`	int	Максимум символов для значения Lookup-колонки ДП «Таблица». При превышении — обрезка
`ExtParamExtraSettings`	JSON	Перевод ДП «Файл» в режим «только сканирование» (в интерфейсе остаётся только кнопка «Сканировать», без вложений)
`ExperimentalMultilookupEpIds`	array	ID ДП Multilookup с поддержкой выбора элементов развёрнутых/неразвёрнутых групп при активной опции «Чекбоксы для групп в мультилукапе». ⚠️ Экспериментальная функция
`TableEpIdsOldUI`	array	ID ДП «Таблица» в старом представлении (с выключенной опцией «Использовать новую таблицу»), которые при открытии задачи сразу разворачиваются в режим редактирования. Остальные старые таблицы открываются в режиме чтения
`UseNewExtParamsAndTaskUsed`	JSON	Включает новые ДП и блок «Используется» для пользователей в указанных категориях/группах. Формат: `[{"subcats":[ids],"groups":[ids]}]`
`CustomTaskUsedAsEpBlocksExtSettings`	JSON	Не закрывать модальное окно создания задачи из БИ — позволяет последовательно добавлять несколько записей
`EveryTagExtParams`	array	ID ДП «Файл», для которых при скачивании/просмотре отправляется метка времени в файловый провайдер EveryTag
`EveryTagSubcats`	array	То же, что `EveryTagExtParams`, но на уровне категорий

Типичные ошибки настройки¶

На PostgreSQL в полях SQL-функций доступа при настройке дополнительного параметра нельзя использовать квадратные скобки в имени функции. Указывайте имя в формате schema.function_name. Ограничение действует для полей AccessFunc и AccessFuncBatch; на MSSQL это ограничение не применяется.

Симптом	Вероятная причина	Где проверить	SQL-диагностика
ДП не отображается в категории	ДП не добавлен в `ExtParamsInSubcat` или скрыт настройкой на уровне категории	Категория → список ДП (`subcategory-extparam-settings`)	см. Q1
ДП отображается, но в «неправильном» месте	Некорректный порядок в категории или в блоке	Блоки ДП + порядок ДП	см. Q2
Подчинённый lookup пустой	Ошибка в `ExtParamLink` или несогласованные значения ведущего ДП	`extparamlinks` + карточки задач	см. Q3
Пользователь видит/не видит задачи не по ожиданию (гибкие права)	Ошибка в `EPRightsFlat/Lkp/Mlt` или в исходном ДП `SelectUsers`	Формы `ep-rights-*`	см. Q4
После изменения шаблона `Table` часть задач в старом виде	Не выполнена синхронизация `sync-table-values`	Настройки table + API лог	см. Q5
Копирование прав на все ДП испортило точечные настройки	Вызван `copypermissons`/`copypermissonsstates` без сегментации	Операции на уровне категории	см. Q6
Массовое копирование значений дало неожиданный результат	Несовместимые типы источника и приёмника	`copy-ep-values` + типы ДП	см. Q7
Нельзя удалить глобальный ДП	ДП используется в категориях или подписях	`GET {id}/subcategories` + `GET {id}/signatures`	см. Q8
ДП отображается некорректно по ширине	Устаревшее значение колонок (4 или 5) в `ExtParamsInSubcat`	Настройки ДП категории	см. Q9

SQL-диагностика (Q1-Q9)¶

Ниже приведены диагностические запросы (Q1–Q9) для проверки конфигурации дополнительных параметров на уровне базы данных.

-- Q1: есть ли привязка ДП к категории
select
        eisc.SubcatID,
        eisc.ExtParamID,
        eisc.SubcatOrder,
        eisc.IsRequired,
        eisc.Hidden
from dbo.ExtParamsInSubcat eisc with (nolock)
where eisc.SubcatID = @subcat_id and
      eisc.ExtParamID = @ext_param_id;

-- Q2: порядок ДП в категории и в блоках
select
        eisc.SubcatID,
        eisc.ExtParamID,
        eisc.SubcatOrder as extparam_order,
        eisc.BlockId
from dbo.ExtParamsInSubcat eisc with (nolock)
where eisc.SubcatID = @subcat_id
order by eisc.SubcatOrder, eisc.BlockId;

-- Q3: связи ДП master-slave
select
        l.MasterExtParamID,
        l.ChildExtParamID,
        l.MasterColumnName,
        l.ChildIDColumnName,
        l.ChildNameColumnName,
        l.ChildSource,
        l.HardLink
from dbo.ExtParamLink l with (nolock)
where l.MasterExtParamID = @master_ep_id or
      l.ChildExtParamID = @child_ep_id;

-- Q4: настройки гибких прав по категории
select top (200) *
from dbo.EPRightsFlat with (nolock);

select top (200) *
from dbo.EPRightsLkp with (nolock);

select top (200) *
from dbo.EPRightsMlt with (nolock);

-- Q5: значения табличного ДП и следы синхронизации
select top (200)
        tv.TaskID,
        tv.ColumnID,
        tv.RowID,
        tv.Value
from dbo.ExtParamTableValues tv with (nolock)
where tv.ExtParamID = @ext_param_id
order by tv.TaskID desc, tv.RowID, tv.ColumnID;

-- Q6: права по статусам для ДП категории
select
        esv.SubcatID,
        esv.ExtParamID,
        esv.StateID,
        esv.CanRead,
        esv.CanEdit
from dbo.ExtParamStateView esv with (nolock)
where esv.SubcatID = @subcat_id
order by esv.ExtParamID, esv.StateID;

-- Q7: совместимость типов source/target перед copy-ep-values
select
        ep.ExtParamID,
        ep.ExtParamName,
        ep.ExtParamType
from dbo.ExtParams ep with (nolock)
where ep.ExtParamID in (@ext_param_from_id, @ext_param_to_id);

-- Q8: использование ДП в категориях и подписях
select
        eisc.SubcatID,
        eisc.ExtParamID
from dbo.ExtParamsInSubcat eisc with (nolock)
where eisc.ExtParamID = @ext_param_id;

select
        s.SignatureID,
        s.ExtParamID,
        s.Description
from dbo.Signatures s with (nolock)
where s.ExtParamID = @ext_param_id;

-- Q9: проверка настроек ширины ДП в категории
select
        eisc.SubcatID,
        eisc.ExtParamID,
        ep.ExtParamName,
        eisc.ColumnCount,
        case eisc.ColumnCount
            when 1 then '1/3 размера'
            when 2 then '1/2 размера'
            when 3 then 'Во всю ширину'
            when 4 then 'Устаревшее значение (4 колонки)'
            when 5 then 'Устаревшее значение (5 колонок)'
            else 'Неизвестное значение'
        end as DisplayName
from dbo.ExtParamsInSubcat eisc with (nolock)
join dbo.ExtParams ep with (nolock) on ep.ExtParamID = eisc.ExtParamID
where eisc.SubcatID = @subcat_id
order by eisc.SubcatOrder;

-- Поиск категорий с устаревшими значениями ширины колонок
select
        eisc.SubcatID,
        sc.SubcatName,
        count(*) as ExtParamsWithOldValues
from dbo.ExtParamsInSubcat eisc with (nolock)
join dbo.Subcategories sc with (nolock) on sc.SubcatID = eisc.SubcatID
where eisc.ColumnCount in (4, 5)
group by eisc.SubcatID, sc.SubcatName
order by ExtParamsWithOldValues desc;

Справочник body-форматов для `POST /api/admin/extparams/settings`¶

Метод обновляет глобальные настройки ДП, специфичные для его типа. Каждый тип ДП требует свойство с конкретным именем в теле запроса. Поле с настройками типа не должно быть пустым (null) — иначе сохранение завершится ошибкой.

Важно: имена полей нечувствительны к регистру, значения перечислений передаются строками ("Default", а не 0).

Корневые поля (общие для всех типов)¶

Тело запроса всегда содержит корневые поля, общие для любого типа ДП; поле с настройками конкретного типа добавляется к ним.

{
  "id": 125290,
  "name": "TM_Lookup",
  "type": "LookUpField",
  "toolTip": "",
  "regExp": "",
  "regExpErrorMessage": "",
  "localizable": false,
  "<typeSettings>": { ... }
}

type — строковое значение из перечисления ExtParamType: Text (0), TextArea (1), Checkbox (2), Date (3), Datetime (4), Select (5), Combobox (6), File (7), Numerator (8), MultiSlctSubcatTasks (10), LookUpField (11), TextareaWOFormat (12), Money (13), URL (14), Through (15), Table (16), SelectUsers (17), NumericValue (18), Tree (19), ExtParamAddressees (20), Address (21).

Соответствие типа ДП и поля настроек¶

Для каждого типа ДП настройки передаются в своём именованном поле тела запроса:

`type`	Поле в body
`LookUpField`	`lookUpFieldSettings`
`Text`	`textSettings`
`Select`	`selectSettings`
`Combobox`	`comboboxSettings`
`MultiSlctSubcatTasks`	`selectSubcatTasksSettings`
`TextArea`	`textAreaSettings`
`Date`	`dateSettings`
`Datetime`	`dateTimeSettings`
`File`	`fileSettings`
`NumericValue`	`numericSettings`
`Money`	`moneySettings`
`SelectUsers`	`selectUsersSettings`
`Tree`	`treeSettings`
`Address`	`addressesSettings`
`Numerator`	`numeratorSettings`
`Through`	`throughSettings`
`Table`	`tableSettings`
`Checkbox`	`checkboxSettings`
`URL`, `TextareaWOFormat`	— (нет отдельных настроек)

Примеры рабочих body (верифицированы на dev 2026-02-27)¶

Каждый пример ниже представляет собой полный body запроса POST /api/admin/extparams/settings для соответствующего типа ДП.

LookUp (`lookUpFieldSettings`)¶

ДП типа «Лукап» позволяет выбрать задачу из категории-источника; источник задаётся полем subcatId.

{
  "id": 125290,
  "name": "TM_Lookup",
  "type": "LookUpField",
  "toolTip": "",
  "regExp": "",
  "regExpErrorMessage": "",
  "localizable": false,
  "lookUpFieldSettings": {
    "subcatId": 70400,
    "states": [],
    "isHierarchical": false,
    "disableFolderSelection": false,
    "displayFilteredParts": false,
    "isLayoutPlan": false,
    "isDropdownLookup": false,
    "groupsCollapsed": false,
    "gridVirtualPageSize": 0,
    "viewPageSize": 0,
    "viewAsText": false,
    "isTooltipVisible": true,
    "displayAsRadioButtons": false,
    "skin": "Default"
  }
}

Важные нюансы:

states обязательно передавать (хотя бы []). Если null — сохранение завершится ошибкой.
skin — строка ("Default"), не число.
subcatId — ID категории-источника (не lookupSubcategoryId, не subcategory.id).
При пустом states: [] сервер автоматически подставляет все состояния категории-источника.

MultiLookup (`selectSubcatTasksSettings`)¶

ДП типа «Мультилукап» позволяет выбирать несколько задач из категории-источника; источник указывается вложенным объектом subcategory.

{
  "id": 125300,
  "name": "TM_MultiLookup",
  "type": "MultiSlctSubcatTasks",
  "toolTip": "",
  "regExp": "",
  "regExpErrorMessage": "",
  "localizable": false,
  "selectSubcatTasksSettings": {
    "subcategory": {"id": 70400},
    "checkPermissionToShowTasks": false,
    "viewAsText": false,
    "isTooltipVisible": true,
    "isHierarchical": false,
    "isLayoutPlan": false,
    "isDropdownLookup": false,
    "skin": "Default",
    "groupsCollapsed": false
  }
}

Важные нюансы:

Источник указывается как "subcategory": {"id": N} (вложенный объект), не "subcatId": N.

Select (`selectSettings`)¶

ДП типа «Список» хранит фиксированный набор вариантов; все варианты передаются массивом elements в поле selectSettings.

{
  "id": 125370,
  "name": "TM_Select",
  "type": "Select",
  "toolTip": "",
  "regExp": "",
  "regExpErrorMessage": "",
  "localizable": false,
  "selectSettings": {
    "elements": [
      {"value": "Опция 1", "isDefault": true},
      {"value": "Опция 2", "isDefault": false},
      {"value": "Опция 3", "isDefault": false}
    ],
    "autoSortByAlphabet": false,
    "dataSource": 0
  }
}

Combobox (`comboboxSettings`)¶

ДП типа «Комбобокс» аналогичен «Списку», но допускает ручной ввод значения; варианты задаются массивом elements в поле comboboxSettings.

{
  "id": 125380,
  "name": "TM_Combobox",
  "type": "Combobox",
  "toolTip": "",
  "regExp": "",
  "regExpErrorMessage": "",
  "localizable": false,
  "comboboxSettings": {
    "elements": [
      {"value": "Вариант A", "isDefault": true},
      {"value": "Вариант B", "isDefault": false},
      {"value": "Вариант C", "isDefault": false}
    ],
    "autoSortByAlphabet": false,
    "dataSource": 0
  }
}

Важные нюансы для Select/Combobox:

Опции задаются массивом elements внутри поля настроек типа, НЕ через POST /api/admin/extparam/options/{epId}/add.
dataSource: 0 = «Набор элементов».
При обновлении — передавать полный список elements (перезатирает предыдущие).

Text / MaskedText (`textSettings`)¶

ДП типа «Строка» может включать маску ввода и регулярное выражение для валидации; оба поля задаются в корне запроса, а не внутри textSettings.

{
  "id": 125480,
  "name": "TM_MaskedText",
  "type": "Text",
  "toolTip": "Format: XXX-XX-XXXX",
  "regExp": "^\\d{3}-\\d{2}-\\d{4}$",
  "regExpErrorMessage": "Формат: 123-45-6789",
  "localizable": false,
  "textSettings": {
    "mask": "",
    "phoneOption": false,
    "suggestType": 0
  }
}

Важные нюансы:

textSettings обязательно передавать (даже пустое). Если null — сохранение завершится ошибкой.
regExp и regExpErrorMessage — в корне тела запроса (не внутри textSettings).
mask — маска ввода (формат типа ###-##-####), не регулярное выражение. Проверка по регулярному выражению — через корневой regExp.
suggestType: 0 = без автоподсказок.

GET настроек ДП¶

GET /api/admin/extparams/settings/{extParamId} (path param, не query string).

Ответ: настройки, специфичные для типа, в едином поле settings (не в отдельных полях по типам, как в запросе).

{
  "data": {
    "id": 125290,
    "name": "TM_Lookup",
    "type": "LookUpField",
    "settings": {
      "subcatId": 70400,
      "states": [1, 2, 3, 4],
      "isHierarchical": false,
      "skin": "Default",
      ...
    }
  }
}

Связь с колонками списка задач¶

Для отображения колонок ДП в списке задач категории — отдельный запрос:

POST /api-core/datasource/settings/save

{
  "entityId": 70400,
  "type": "subcat",
  "isAdmin": true,
  "clientSettings": {
    "columnState": [
      {"colId": "task", "width": 160, "hide": false, ...},
      {"colId": "ExtParam125220", "width": 160, "hide": false, ...}
    ],
    "columnGroupState": null,
    "filterState": {},
    "tasksState": null,
    "myTasks": null
  }
}

isAdmin: true — admin-level (видно всем, UserId=null в БД). Без isAdmin — user-level (только для текущего пользователя).
colId для EP: "ExtParam" + ExtParamID (конкатенация строки).

Заполнение ДП через API¶

Для программного заполнения ДП используется endpoint POST /api/extParams/update; значение передаётся в формате строки #n{epId}#v{value}, несколько ДП разделяются ::.

POST("/api/extParams/update", [{
    "extParamStr": "#n{epId}#v{value}",  # несколько ДП через ::
    "taskId": N,
    "userId": N,
    "writeComment": False
}])

TextArea: значение — HTML (<p>текст</p>). Не начинать с заголовка — у ДП уже есть название.

Admin API — создание ДП¶

POST /api/admin/extparams?name=ИмяДП&type=Text — тип и имя передаются в URL, body пустой {}.

Типы ДП в API¶

Имя типа в API не всегда совпадает с интуитивно ожидаемым — используйте точные значения из таблицы:

Интуитивно	API type	Примечание
Строка	`Text`
Число	`NumericValue`	Не `Number`, не `Integer`
Галочка	`Checkbox`	Не `Bool`, не `Boolean`
Лукап	`LookUpField`	Не `Lookup`
Мультифайл	`File`	Тот же тип что File, разница в настройках

Добавление значений (Options)¶

POST /api/admin/extparam/options/{id}/add принимает массив [{Value, IsDefault}], не одиночный объект.

Table EP — настройка колонок¶

Добавление колонок в ДП типа «Таблица» выполняется в два шага: сначала получить текущие настройки, затем отправить обновлённый объект целиком.

# 1. GET текущие настройки
settings = GET(f"/api/admin/extparams/settings/{epId}")

# 2. Добавить колонки в settings.extParamTableSettings
settings["extParamTableSettings"].append({
    "id": 0,  # 0 = новая колонка
    "name": "Колонка",
    "type": 0  # 0=Текст, 1=Большой текст, 5=Дата-время
})

# 3. POST полный объект настроек
POST("/api/admin/extparams/settings", settings)

LookUpField — требует настройки после создания¶

ДП типа «Лукап» сразу после создания не работает — его нужно донастроить:

POST /api/admin/extparams/settings — указать subcatId источника
Настроить колонки списка

Без настройки лукап остаётся пустым.

Table и MultiSlctSubcatTasks — опасность¶

Создание ДП этих типов без настройки колонок/источника ломает отображение всей панели ДП на форме задачи. Создавайте такой ДП в отдельной категории и настраивайте через POST /api/admin/extparams/settings сразу после создания.

Связанные документы¶

Смежные разделы документации:

Дополнительные параметры¶

Где настраиваются ДП¶

Механизмы администрирования¶

Автоадминка (dbadmin)¶

Отдельные SPA-страницы (в дереве администрирования)¶

Admin API¶

Ключевые настройки¶

1) Типы ДП (ExtParamType)¶

2) Создание и глобальная настройка ДП¶

3) Привязка ДП к категории¶

Список ДП категории¶

Настройки ДП в категории¶

Доступ к ДП¶

Валидация ДП¶

Шифрование ДП¶

Синхронизация ДП¶

Прочие настройки ДП¶

ДП «Таблица» — дополнительные настройки блока¶

Создание и копирование ДП¶

UI-переход к настройкам¶

4) Блоки ДП и группы блоков¶

Создание и настройка блока¶

Группы блоков¶

Переход к настройкам из интерфейса¶

5) Связи между ДП (ExtParamLink)¶

6) Опции ДП (списки и выпадающие значения)¶

7) Гибкие права на ДП / задачи¶

7а) Смарт-доступ к ДП (модалка в карточке ДП)¶

8) Таблица БИ для ДП Table¶

9) Валидация значений: регулярное выражение и маска¶

10) Тип ДП «Дерево» (Tree) — узкие настройки¶

11) Тип ДП «Выпадающий список» (Select / Combobox) — узкие настройки¶

12) Выбор между Multilookup, Таблицей и БИ («Используется»)¶

CustomSettings — глобальные ключи поведения ДП¶

Типичные ошибки настройки¶

SQL-диагностика (Q1-Q9)¶

Справочник body-форматов для POST /api/admin/extparams/settings¶

Корневые поля (общие для всех типов)¶

Соответствие типа ДП и поля настроек¶

Примеры рабочих body (верифицированы на dev 2026-02-27)¶

LookUp (lookUpFieldSettings)¶

MultiLookup (selectSubcatTasksSettings)¶

Select (selectSettings)¶

Combobox (comboboxSettings)¶

Text / MaskedText (textSettings)¶

GET настроек ДП¶

Связь с колонками списка задач¶

Заполнение ДП через API¶

Admin API — создание ДП¶

Типы ДП в API¶

Добавление значений (Options)¶

Table EP — настройка колонок¶

LookUpField — требует настройки после создания¶

Table и MultiSlctSubcatTasks — опасность¶

Связанные документы¶

1) Типы ДП (`ExtParamType`)¶

5) Связи между ДП (`ExtParamLink`)¶

8) Таблица БИ для ДП `Table`¶

Справочник body-форматов для `POST /api/admin/extparams/settings`¶

LookUp (`lookUpFieldSettings`)¶

MultiLookup (`selectSubcatTasksSettings`)¶

Select (`selectSettings`)¶

Combobox (`comboboxSettings`)¶

Text / MaskedText (`textSettings`)¶