Канбан — Администрирование

Документ описывает администрирование канбан-представлений платформы: включение канбана в категории, настройку шаблона карточки, группировок, агрегаций и сортировки, а также альтернативные режимы (Lookup, публикации). Для администраторов категорий и инженеров внедрения.

Что настраивается и типовой канбан категории

Админ-контур канбана состоит из трех блоков:

1. включение канбана как представления категории;
2. настройка карточки и поведения доски через шаблон задач;
3. ~~настройка пользовательского канбана через публикации~~ (устарело, не поддерживается).

Канбан категории доступен по URL:

• ~/spa/tasks/subcat/{subcatId}/kanban
• устаревший формат: ~/spa/kanban/subcat/{subcatId}

Что контролируется настройками категории:

• доступность представления "Канбан";
• маршрут и статусы, из которых строятся колонки — порядок колонок по статусам не настраивается, его рассчитывает система по графу переходов;
• права на принудительную смену статуса;
• параметры, доступные для фильтрации/группировки.

2. Шаблон карточки канбана

Шаблон настраивается через "Шаблоны задач" (динамический шаблон, контекст kanban).

Ключевые параметры:

• templateClass: "kanban" — тип шаблона;
• showHeaderColors — включение/выключение цветных заголовков статусов;
• leftBorder — цветовая левая обводка карточки;
• groupings — список доступных группировок и признак группировки по умолчанию;
• aggregations — агрегаты по числовым/денежным ДП (sum/avg/max/min).

В карточке настраиваются блоки:

• header и footer — предопределенные блоки;
• body — динамический вывод ДП и системных полей.

2.1 Элементы блоков header и footer

Каждый элемент блока описывается JSON:

{ "type": "mainParam"|"extparam", "dataKey": "..."|123, "alias": "...", "viewMode": "...", "settings": {} }

• type — mainParam (системный параметр) или extparam (ДП);
• dataKey — для mainParam ключ системного поля; для extparam — ID ДП;
• alias — роль элемента в блоке (см. таблицы ниже);
• hideIfEmpty — корневой ключ элемента (на одном уровне с type, dataKey и alias, не внутри settings): false — показывать элемент даже без значения, true или отсутствие ключа — скрыть. Действует в карточках только для чтения: галерея, канбан, карточка масштаба «Расписание» в календаре, ресурсная карточка и всплывающая подсказка, предпросмотр шаблона в администрировании. Карточка задачи, форма создания и лента задач читают свои шаблоны другими компонентами и на этот ключ не реагируют.

Пустые элементы карточки скрываются по умолчанию: числовой параметр со значением 0 и признак со значением «нет» пустыми не считаются и показываются как обычно.

Alias для header:

Alias	Описание	Ключевые settings
title	Заголовок — текст задачи (dataKey: "taskText")	—
headerCounter	Индикатор с количеством задач	color, emphasis
subtitle	Подзаголовок, вторая строка	—
mainTag	Главный тег	color
tags	Теги задачи (из viewTags)	—
headerDate	Срок задачи	—
cover	Обложка карточки	ratioWH, устаревший showEmptyCover
cardIdentifier	Номер задачи (dataKey: "taskId")	prefix

Теги задачи (alias tags). Набор тегов берётся из настройки тегов категории (Дополнительно → Наборы тегов). Цвет каждого тега — из его настройки: тег, привязанный к мультилукап-параметру, показывается отдельным бейджем на каждое выбранное значение, а при цвете «из значения» каждый бейдж окрашивается в цвет своей задачи-значения. Тег без заданного цвета выводится серым. Теги статуса и приоритета в карточку не попадают: статус показывают колонки доски, приоритет — цветовая обводка слева. Набор, порядок и цвета тегов одинаковы для карточки без шаблона и для элемента mainParam/tags в header; тот же конструктор карточки используют галерея, календарь, «Ресурсы» и превью шаблона в администрировании.

Alias для footer:

Alias	Описание	Ключевые особенности
avatar	Аватар карточки (из ДП-файла)	dataKey = ID ДП с типом «Файл»
priority	Приоритет	valueMapper для пользовательских подписей
users	Пользователи (исполнители, ДП-выбор пользователей)	viewMode: "table" обязателен
cardIdentifier	Номер задачи	settings.prefix добавляет префикс (напр. #)
totalSubtasks	Общее количество подзадач	Поддерживает extparam с типом «Число»
activeSubtasks	Количество активных подзадач	Аналогично totalSubtasks

totalSubtasks и activeSubtasks также поддерживают значения из ДП с типом «Число»: "type": "extparam", "dataKey": {ID ДП}, alias остаётся без изменений.

Бейдж подзадач на карточке канбана виден по умолчанию: если в шаблоне нет элемента подзадач, счётчики totalSubtasks/activeSubtasks подставляются из задачи (у задач без подзадач — 0/0). Чтобы скрыть бейдж, у элемента подзадач задают settings.showInFooter: false (флаг срабатывает и при нулевом счётчике). В представлении «Галерея» и в админ-превью бейдж показывается только при счётчике больше нуля.

Параметры settings для элемента headerCounter:

Параметр	Значения	Описание
color	primary accent info success warning fav danger error default blackWhite	Цвет индикатора
emphasis	accent container	Акцент индикатора

Параметры settings для элемента cover:

Параметр	Тип	Описание
ratioWH	string	Соотношение сторон обложки строкой W:H, где W и H — положительные числа, например 1:1, 16:9, 2:3, 9:21. Значение произвольное, закрытого перечня нет. Если ключ не задан или значение не разобрано, используется 16:9
showEmptyCover	bool	Устаревший частный ключ обложки: true — показывать пустую обложку. Читается только тогда, когда у элемента не задан корневой hideIfEmpty. Для новых шаблонов используйте hideIfEmpty

Порядок чтения для обложки: сначала корневой hideIfEmpty; если он не задан — showEmptyCover; если не задан ни один ключ, пустой слот обложки скрыт, как и у любого другого пустого элемента. Шаблон с обоими ключами подчиняется hideIfEmpty.

Параметры settings для элемента priority (footer):

valueMapper позволяет задать пользовательские подписи для уровней приоритета:

"settings": {
  "valueMapper": { "0": "low", "3": "high" }
}

2.2 Элементы блока body

Блок body — динамический: отображаются только те ДП, в которых есть значение. Для каждого элемента обязателен параметр viewMode.

Значения viewMode:

Значение	Описание
normal	Названия параметров строкой выше значений
compact	Названия слева от значений (по умолчанию)
valueOnly	Только значения, без названий
one	Параметры не отображаются
table	Табличный вид (для пользователей; в settings: showUserStatus: true для статуса «как в ленте»)
icon	Иконка слева вместо названия (требует settings.icon)
iconSet	Для Multilookup — иконки задач вместо текста; showColor: true окрашивает по цвету задачи
tags	Lookup/Multilookup в виде тегов; showIcon и showColor управляют иконкой/цветом задачи

Параметры settings для элементов body:

Параметр	Тип	Описание
icon	string	Иконка при viewMode: icon (из /spa/content-icons)
truncate	bool	Обрезка текста троеточием (true — по умолчанию)
showUserStatus	bool	Статус пользователя при viewMode: table
showIcon	bool	Иконка задачи в тегах при viewMode: tags
showColor	bool	Цвет задачи в тегах при viewMode: tags; при использовании в leftBorder — автоматическое определение цвета
style	string	secondary — второстепенный стиль: уменьшенный шрифт и серый цвет текста. Применяется к подписи поля и к текстовому значению; на теги, иконки и списки пользователей не влияет. По умолчанию (primary или параметр не задан) — обычный вид

2.3 Секция settings шаблона

В settings внутри contexts[] задаются глобальные настройки карточки канбана:

• leftBorder — левая обводка;
• showHeaderColors — цветные заголовки статусов;
• groupings — группировки;
• aggregations — агрегаты по числовым/денежным ДП;
• sortings — сортировка карточек внутри колонки.
• readonly — режим «только просмотр»: перетаскивание карточек и перестановка колонок отключены для всех (с версии 2.268).
• readonly — режим «только просмотр»: перетаскивание карточек и перестановка колонок отключены для всех (с версии 2.268).

showHeaderColors, leftBorder и groupings

showHeaderColors. По умолчанию true (цвета статусов из настроек маршрута). Завершающие статусы всегда зелёные, отклоняющие — красные; изменение цвета для них недоступно. false — все статусы серые.

leftBorder. Настраивается как элемент с source/mainParam. Два режима:

1. Ручной — через dynamicSettings со значениями и цветами:

   "leftBorder": {
     "type": "mainParam", "dataKey": "priority", "alias": "leftBorder",
     "dynamicSettings": {
       "0": { "color": "var(--base-info)" },
       "3": { "color": "var(--base-danger)" }
     }
   }
   

2. Автоматический — через "settings": { "showColor": true }:

3. для dataKey: "priority" — все 5 уровней приоритета;
4. для Lookup-полей — цвет значения (taskColor);
5. dynamicSettings в этом режиме игнорируется.

Минимальная настройка:

"leftBorder": {
  "type": "mainParam", "dataKey": "priority",
  "alias": "leftBorder",
  "settings": { "showColor": true }
}

groupings. Список доступных группировок. Элемент с "settings": { "isDefault": true } — группировка по умолчанию при открытии канбана.

Если groupings не задан, в выпадающем списке по умолчанию доступны: Исполнители, Заказчик, Срок, Дата создания, Дата изменения.

Пример:

"groupings": [
  {
    "type": "mainParam", "dataKey": "performer",
    "name": "Исполнители",
    "settings": { "isDefault": true }
  }
]

aggregations

Сумма, среднее, максимум, минимум по числовым/денежным ДП. Параметры:

Параметр	Описание
column	ID ДП в формате ExtParam{ID}
name	Отображаемое имя
operation	sum avg max min
postfix	Текст после значения
separator	Разделитель между агрегациями

Пример:

"aggregations": [
  { "column": "ExtParam12872", "name": "Efforts(сумма)", "operation": "sum", "postfix": "сум", "separator": "/" },
  { "column": "ExtParam12872", "name": "Efforts(среднее)", "operation": "avg", "postfix": "ср" }
]

sortings (v2.259+)

Сортировка карточек внутри колонки. Задаётся на уровне конфигурации канбана, без пользовательского переключателя. Поддерживает множественные правила — второе правило применяется к карточкам, равным по первому, и т.д.

Параметры элемента сортировки:

Параметр	Описание
type	mainParam или extParam
dataKey	Ключ системного поля или ID ДП
name	Отображаемое имя
settings.direction	asc (по возрастанию) или desc (по убыванию)
settings.isDefault	Признак сортировки по умолчанию (может быть несколько — все применяются последовательно)

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

• сортировка действует внутри колонки, порядок колонок не меняется;
• если сортировка не задана — используется порядок от источника данных;
• при настроенной сортировке перетаскивание карточек внутри колонки отключено (карточка возвращается на исходную позицию);
• параметр сортировки не должен передаваться в запрос получения данных, если настройка не выбрана.

Пример:

"sortings": [
  {
    "type": "mainParam", "dataKey": "order",
    "name": "Порядок", "settings": { "direction": "desc" }
  },
  {
    "type": "extParam", "dataKey": 76690,
    "name": "Фича", "settings": { "isDefault": true, "direction": "desc" }
  }
]

readonly (v2.268+)

Режим «только просмотр» доски. Задаётся в секции settings контекста kanban, рядом с группировками и сортировками.

Ключ	Тип	По умолчанию	Значение
readonly	boolean	отсутствует (равносильно false)	true — перетаскивание карточек и перестановка колонок отключены для всех пользователей

Что отключается при true:

• перетаскивание карточек между колонками и внутри колонки — и на канбане по статусам, и на канбане по дополнительному параметру, на любом срезе;
• пункт «Режим принудительной смены статуса» в меню «Прочее»: настройка сильнее этого режима и действует независимо от прав, включая администратора категории и администратора задач;
• перестановка колонок перетаскиванием заголовков на канбане по дополнительному параметру.

Ключ не влияет на остальные действия доски: создание задачи в колонке, отметки в списке задач на карточке и контекстное меню карточки работают как прежде, а статус по-прежнему можно сменить в карточке задачи. Настройка действует только в интерфейсе: переход, выполненный напрямую через API, проверяется сервером по обычным правилам. Если ключ отсутствует или его значение отлично от true, доска ведёт себя как раньше.

Пример:

"settings": {
  "templateClass": "kanban",
  "readonly": true
}

Отдельного флажка в редакторе шаблонов нет: ключ задаётся в JSON шаблона (кнопка «JSON» в редакторе динамического шаблона).

readonly (v2.268+)

Режим «только просмотр» доски. Задаётся в секции settings контекста kanban, рядом с группировками и сортировками.

Ключ	Тип	По умолчанию	Значение
readonly	boolean	отсутствует (равносильно false)	true — перетаскивание карточек и перестановка колонок отключены для всех пользователей

Что отключается при true:

• перетаскивание карточек между колонками и внутри колонки — и на канбане по статусам, и на канбане по дополнительному параметру, на любом срезе;
• пункт «Режим принудительной смены статуса» в меню «Прочее»: настройка сильнее этого режима и действует независимо от прав, включая администратора категории и администратора задач;
• перестановка колонок перетаскиванием заголовков на канбане по дополнительному параметру.

Ключ не влияет на остальные действия доски: создание задачи в колонке, отметки в списке задач на карточке и контекстное меню карточки работают как прежде, а статус по-прежнему можно сменить в карточке задачи. Настройка действует только в интерфейсе: переход, выполненный напрямую через API, проверяется сервером по обычным правилам. Если ключ отсутствует или его значение отлично от true, доска ведёт себя как раньше.

Пример:

"settings": {
  "templateClass": "kanban",
  "readonly": true
}

Отдельного флажка в редакторе шаблонов нет: ключ задаётся в JSON шаблона (кнопка «JSON» в редакторе динамического шаблона).

Добавление ДП из карточки канбана

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

Меню вызывается по клику на карточке (в Канбане правого клика на карточках нет — используется кликовое меню доски). В меню есть пункт «Добавить ДП» с подменю типов дополнительных параметров.

Пункт виден в двух случаях:

• пользователь — администратор площадки;
• в категории у пользователя есть право «Администратор категории» — тогда пункт открыт и без прав администратора площадки.

Если ни одного из этих прав нет, пункт в меню не показывается.

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

После успешного создания доска пересчитывается автоматически — новое поле появляется на карточках без перезагрузки страницы.

Ограничения быстрого создания:

• параметр создаётся с настройками по умолчанию;
• тип-специфичные настройки (флаг форматирования для «Большого текста», режим отображения времени для «Даты» и «Даты и времени», выбор справочника и первых значений для «Лукапа» и «Мультилукапа») в окне не задаются — их настраивают потом на странице настроек ДП категории;
• типы «Таблица» и «Выбор нескольких задач из категории» (Мультилукап) без настройки колонок и источника ломают отображение всей панели ДП на форме задачи. Быстрое создание их допускает, но сразу после создания параметр нужно донастроить.

Дальнейшая настройка ДП — на странице настроек ДП категории, см. Настройка ДП.

Когда шаблон не применяется к канбану

Шаблон доходит до доски, только если правило его назначения подходит запросу. Если правило не отобралось, канбан рисует карточку и меню сортировок по умолчанию — там остаётся стандартный набор, а секция sortings шаблона не применяется, хотя её содержимое верное.

Что проверить в назначении шаблона:

• категория правила совпадает с категорией доски;
• тип клиента правила подходит запросу: значение «Все» действует для любого клиента, иначе нужен «Веб». Значение может храниться и именем, и числовым кодом — отбор принимает оба вида;
• шаблон содержит контекст kanban, а в его настройках у templateClass стоит значение kanban;
• секция sortings лежит в настройках именно канбан-контекста;
• у правила включён признак размещения, соответствующий представлению карточки.

Альтернативные режимы канбана: Lookup и публикации

Канбан по Lookup-полю. Админ может переключить построение канбана с маршрута на конкретный Lookup-параметр.

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

• порядок колонок задается настройкой Lookup "Колонка сортировки";
• если «Колонка сортировки» не задана, колонки идут в ручном порядке задач категории-источника; администратор этой категории или администратор задач в ней может переставлять колонки, перетаскивая заголовки на доске;
• при переносе карточки меняется значение Lookup;
• появляется колонка "Не заполнено" для пустых значений.

Пользовательский канбан на публикациях (устаревший способ).

⚠️ Устарело. Настройка через публикации больше не поддерживается. Пользовательский канбан настраивается через шаблон задач (см. раздел 2).

Канбан вызывается по URL:

• ~/spa/kanban/{publicationAlias}

Нужно настроить 3 публикации:

1. публикация структуры (columns, rows, templates, ссылки на data/move);
2. публикация данных;
3. публикация перемещения карточки между колонками/строками.

Ключевые элементы структуры:

• columns — колонки с movableFrom/movableTo, template, showArrow;
• rows — строки доски, опционально с movableFrom/movableTo;
• dataSet — URL публикации данных;
• moveWebRequest — URL публикации перемещения.

Важно:

• права на публикации должны быть настроены отдельно;
• ограничение прав на move можно сделать через доступ к публикации перемещения.

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

Частые ошибки настройки канбана:

1. Канбан не отображается в категории:

2. не включено представление "Канбан" в настройках категории;

3. у пользователя нет прав на категорию.

4. Колонки не соответствуют ожиданиям:

5. основной маршрут не настроен или настроен не тот;

6. выбран режим канбана по Lookup, а не по маршруту.

7. Перетаскивание не работает:

8. в шаблоне задач контекста kanban задано settings.readonly: true — тогда перетаскивание отключено для всех, независимо от маршрута и прав.

9. Перетаскивание не работает:

10. в шаблоне задач контекста kanban задано settings.readonly: true — тогда перетаскивание отключено для всех, независимо от маршрута и прав.

11. Карточка выглядит "по-старому":

12. шаблон задач не привязан в шаблонизации категории;

13. контекст шаблона задан не как kanban.

14. Перетаскивание не работает:

15. в пользовательском канбане не задан moveWebRequest;

16. нет прав на публикацию перемещения;
17. в типовом канбане переход запрещен маршрутом/правами.

Связанные контуры

Карточка масштаба «Расписание»

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

Галерея и мобильный дашборд

Шаблон карточки галереи. Представление категории «Галерея» использует конструктор шаблона, аналогичный канбан-шаблону: те же блоки header/body/footer, элементы, viewMode, settings. Отличия:

• context: "gallery" (вместо "kanban");
• templateClass: "gallery";
• уникальный параметр bootstrapSize (sm/md/lg), влияющий на минимальное количество элементов в строке и размер карточек (sm — до 6 элементов в ряду).

Галерея использует тот же конструктор карточки, что и канбан, отличаясь только контекстом (gallery) и размером bootstrap-сетки.

Подробнее о представлениях списков задач — в администрировании списков.

Мобильный дашборд (Dashboard-контейнер). Функциональность мобильного дашборда (AllDashboards, Dashboard-контейнер с плитками/баннерами/стеками, Избранное в дашборде) не относится к домену kanban. Это сквозная функциональность мобильного клиента, администрируемая через контейнеры мобильного приложения.