# Yandex Tracker Issue
Плагин отображения информации задач из Yandex Tracker в Obsidian.
---
## Обозначения
***YTI***: Yandex Tracker Issue. Сокращение обозначает собой данный плагин. Далее, YTI и Yandex Tracker Issue используются как синонимы.
---
## Быстрый старт
1. Получить *OAuth 2.0* токен. Для этого:
1. Зарегистрируйте приложение в вашем Yandex Tracker: https://yandex.ru/dev/id/doc/ru/register-client#access-note
2. Проследуйте инструкциям официального руководства: https://yandex.ru/support/tracker/ru/concepts/access#about_OAuth
3. **Нужен именно OAuth токен! На данный момент, плагин не поддерживает IAM-токен!**
2. Получить *Org-Id* вашей организации. Это можно сделать, например, на странице организации в *Yandex Tracker*.
1. **Нужен именно Org-Id. На данный момент, плагин не поддерживает Cloud-Org-Id!**
3. Открыть настройки плагина.
4. Ввести в поле *OAuth Token*, собственно, *OAuth 2.0* токен. В поле *Org ID* ввести *Org-Id*.
5. Найти какие-нибудь задачи в *Yandex Tracker*. Например, TASK-111, TASK-222.
6. В заметку в *Obsidian* добавить следующий блок кода (каждая задача с новой строки):
```
```yt-issue
TASK-111
TASK-222```
```
7. Перейти в режим просмотра.
---
## Руководство пользователя
### Сущности
Плагин **YTI** оперирует несколькими сущностями:
1. **Issue** - задача из Yandex Tracker.
2. **Board** - доска
3. **Project** - проект
4. **Queue** - очередь
5. **Sprint** - спринт
6. **User** - пользователь
### Отображение
Далее приведены названия блоков кода для отображения сущностей.
1. **yt-gantt** - отображает размещённые в нём задачи в виде диаграммы Ганта. Помещать нужно Id задач.
2. **yt-issue** - отображает размещённые в нём задачи в виде таблицы. Помещать нужно Id задач.
3. **yt-gantt-query** - отображает размещённые в нём задачи в виде диаграммы Ганта. Помещать нужно Yandex Tracker запрос: https://yandex.ru/support/tracker/ru/user/query-filter
4. **yt-issue-query** - отображает размещённые в нём задачи в виде таблицы. Помещать нужно Yandex Tracker запрос: https://yandex.ru/support/tracker/ru/user/query-filter
5. **yt-boards** - отображает размещённые в нём доски в виде таблицы. Помещать нужно Id досок.
6. **yt-queues** - отображает размещённые в нём очереди в виде таблицы. Помещать нужно Id очередей.
7. **yt-projects** - отображает размещённые в нём проекты в виде таблицы. Помещать нужно Id проектов.
8. **yt-sprints** - отображает размещённые в нём спринты в виде таблицы. Помещать нужно Id спринтов.
9. **yt-users** - отображает размещённых в нём пользователей в виде таблицы. Помещать нужно логины пользователей. Например, если пользователя зовут Иванов Василий Максимович (ФИО придумано), то его логин в Yandex Tracker, скорее всего будет *vivanov*.
Колонки таблиц и их отображение можно задавать в настройках. Подробнее в разделе *"Настройки отображения"*.
---
## Настройки
### Настройки авторизации
1. **OAuth Token** - поле для вашего *OAuth* токена.
2. **Org ID** - поле для вашего *Org-Id*.
3. **Проверка подключения** - кнопка для проверки корректности ввода *OAuth* токена и *Org ID*.
### Настройки отображения
Далее, идут поля для ввода **атрибутов** сущностей. Что такое атрибуты подробно описано в разделе *Атрибуты*.
1. **Атрибуты задач** - атрибуты для отображения задач в блоках кода *yt-issue*, *yt-gantt*, *yt-issue-query*, *yt-gantt-query*.
2. **Атрибуты досок** - атрибуты для отображения досок в блоке кода *yt-boards*.
3. **Атрибуты проектов** - атрибуты для отображения досок в блоке кода *yt-projects*.
4. **Атрибуты очередей** - атрибуты для отображения досок в блоке кода *yt-queues*.
5. **Атрибуты спринтов** - атрибуты для отображения досок в блоке кода *yt-sprints*.
6. **Атрибуты пользователей** - атрибуты для отображения досок в блоке кода *yt-users*.
Также, в данном блоке есть следующие настройки:
1. **Статусы завершённых задач** - используются в диаграммах Ганта для определения завершена задача или нет.
2. **Сбросить настройки до стандартных** - сбрасывает настройки отображения до стандартных настроек, с которыми поставляется плагин **YTI**. При этом **настройки авторизации не изменяются!**
3. **Ререндер** - перерисовывает все блоки кода данного плагина.
---
## Параметры отображения
Настройки отображения таблиц принимаю строки специального типа, которые состоят из сложных или простых атрибутов или модификаторов.
**Атрибуты** указывают какие данные отображать в таблицах.
**Модификаторы** указывают как отображать данные в таблицах.
**Аргументы модификатора** задают детальную настройку модификатора.
(На данный момент, аргументы поддерживаются только у модификатора *trim*)
### Синтаксис
Общий синтаксис параметра отображения следующий
```
атрибут:модификатор1_арг1_арг2:модификатор2_арг1: ... :модификаторn
```
Если атрибут сложный, то он поддерживает такой синтаксис:
```
атрибут.податрибут:модификатор1_арг1_арг2:модификатор2_арг1: ... :модификаторn
```
Плагин **YTI** поддерживает глубину вложенности атрибутов не более чем два.
### Атрибуты
Программный код плагина условно разделён на две части: запросы к Yandex Tracker для получения информации и отображение данной информации в виде таблиц и диаграмм.
Идея данного плагина следующая: из Yandex Tracker запрашивается (почти) вся информация о введённых сущностях, а отображается только то, что задано настройками.
Настройки отображения задаются атрибутами. Атрибуты есть у каждой сущности.
У некоторых сущностей есть сложные атрибуты. Например, у сущности **Issue** (задача) есть атрибут **assignee** (исполнитель), который сам является сущностью типа **User** (пользователь).
Для отображения таких сложных атрибутов есть атрибуты по умолчанию. Например, у пользователя - это его ФИО.
Также для каждого атрибута есть его сопоставление - читабельное название атрибута на русском языке.
Далее пойдёт перечисление всех сущностей и их атрибутов
### Issue
Атрибут по умолчанию - summary
| Атрибут | Сопоставление | Тип | Сложный? | Атрибут по умолчанию |
| -------------------- | --------------------------- | ------------------- | -------- | --------------------- |
| self | Адрес ресурса | String | Нет | |
| id | Hash-ID задачи | String | Нет | |
| key | ID задачи | String | Нет | |
| version | Версия | Number | Нет | |
| summary | Название | String | Нет | |
| aliases | Альтернативные ключи | String | Нет | |
| description | Описание | String | Нет | |
| votes | Голоса | String | Нет | |
| favorite | Избрана | String | Нет | |
| tags | Тэги | String | Нет | |
| lastCommentUpdatedAt | Дата последнего комментария | DateTime | Нет | |
| createdAt | Дата создания | DateTime | Нет | |
| updatedAt | Дата обновления | DateTime | Нет | |
| status | Статус | вспомогательный тип | Да | display |
| priority | Приоритет | вспомогательный тип | Да | display |
| previousStatus | Предыдущий статус | вспомогательный тип | Да | display |
| type | Тип | вспомогательный тип | Да | display |
| updatedBy | Последний редактор | User | Да | display |
| followers | Наблюдатели | вспомогательный тип | Да | display, display, ... |
| createdBy | Созатель | User | Да | display |
| assignee | Исполнитель | User | Да | display |
| project | Проект | Project | Да | name |
| queue | Очередь | Queue | Да | name |
| parent | Родеительская задача | Issue | Да | summary |
| sprint | Спринт | Sprint | Да | name |
### Board
Атрибут по умолчанию - name
| Атрибут | Сопоставление | Тип | Сложный? | Атрибут по умолчанию |
| ------------ | -------------------------- | ------------------- | -------- | --------------------- |
| self | Адрес ресурса | String | Нет | |
| id | ID доски | String | Нет | |
| version | Версия | String | Нет | |
| name | Название доски | String | Нет | |
| filter | Фильтр | String | Нет | |
| orderBy | Сортировка | String | Нет | |
| orderAsc | Направление сортировки | String | Нет | |
| query | Запрос | String | Нет | |
| useRanking | Возможность менять порядок | String | Нет | |
| estimateBy | Оценивание | String | Нет | |
| country | Страна | String | Нет | |
| defaultQueue | Очередь по умолчанию | String | Нет | |
| calendar | Календарь | String | Нет | |
| columns | Колонки | вспомогательный тип | Да | display, display, ... |
### Project
Атрибут по умолчанию - name
| Атрибут | Сопоставление | Тип | Сложный? | Атрибут по умолчанию |
| ----------- | -------------- | -------- | -------- | -------------------- |
| description | Описание | String | Нет | |
| key | Название | String | Нет | |
| name | Название | String | Нет | |
| self | Адрес ресурса | String | Нет | |
| status | Статус | String | Нет | |
| id | ID проекта | Number | Нет | |
| version | Версия | Number | Нет | |
| startDate | Дата начала | DateTime | Нет | |
| endDate | Дата окончания | DateTime | Нет | |
| lead | Руководитель | User | Да | display |
### Queue
Атрибут по умолчанию - name
| Атрибут | Сопоставление | Тип | Сложный? | Атрибут по умолчанию |
| ---------------- | -------------------------- | ------------------- | -------- | --------------------- |
| self | Адрес ресурса | String | Нет | |
| id | ID очереди | String | Нет | |
| key | ID очереди | String | Нет | |
| name | Название | String | Нет | |
| description | Описание | String | Нет | |
| version | Версия | Number | Нет | |
| assignAuto | Автоназначение исполнителя | Boolean | Нет | |
| denyVoting | Можно голосовать | Boolean | Нет | |
| defaultType | Тип задач по умолчанию | вспомогательный тип | Да | display |
| issueTypes | Типы задач | вспомогательный тип | Да | display, display, ... |
| workflows | Жизненные циклы | вспомогательный тип | Да | display, display, ... |
| defaultPriority | Приоритет по умолчанию | вспомогательный тип | Да | display |
| issueTypesConfig | Настройки типов задач | вспомогательный тип | Да | display, display, ... |
| lead | Руководитель | User | Да | display |
| teamUsers | Команда | вспомогательный тип | Да | display, display, ... |
### Sprint
Атрибут по умолчанию - name
| Атрибут | Сопоставление | Тип | Сложный? | Атрибут по умолчанию |
| ------------- | -------------- | -------- | -------- | -------------------- |
| self | Адрес ресурса | String | Нет | |
| name | Название | String | Нет | |
| status | Статус | String | Нет | |
| version | Версия | Number | Нет | |
| id | ID Спринта | Number | Нет | |
| archived | Архивирован | Boolean | Нет | |
| endDate | Дата окончания | DateTime | Нет | |
| endDateTime | Дата окончания | DateTime | Нет | |
| startDate | Дата начала | DateTime | Нет | |
| startDateTime | Дата начала | DateTime | Нет | |
| createdAt | Дата создания | DateTime | Нет | |
| createdBy | Создатель | User | Да | display |
| board | Доска | Board | Да | name |
### User
Атрибут по умолчанию - display
| Атрибут | Сопоставление | Тип | Сложный? | Атрибут по умолчанию |
| -------------------- | --------------------- | ------- | -------- | -------------------- |
| self | Адрес ресурса | String | Нет | |
| id | ID пользователя | String | Нет | |
| login | Логин | String | Нет | |
| cloudUid | Cloud ID | String | Нет | |
| firstName | Имя | String | Нет | |
| lastName | Фамилия | String | Нет | |
| display | Полное имя | String | Нет | |
| email | email | String | Нет | |
| firstLoginDate | Дата первого входа | String | Нет | |
| lastLoginDate | Дата последнего входа | String | Нет | |
| uid | uid | Number | Нет | |
| trackerUid | trackerUid | Number | Нет | |
| passportUid | passportUid | Number | Нет | |
| external | external | Boolean | Нет | |
| hasLicense | hasLicense | Boolean | Нет | |
| dismissed | dismissed | Boolean | Нет | |
| useNewFilters | useNewFilters | Boolean | Нет | |
| disableNotifications | disableNotifications | Boolean | Нет | |
| welcomeMailSent | welcomeMailSent | Boolean | Нет | |
### Модификаторы
1. *initials* - разбивает строку на слова, вместо слов подставляет их первые буквы с точкой и добавляет последнее слово целиком.
1. **Пример:** `Иван Иванович Иванов` => `И.И. Иванов`
2. **Пример:** `Съешь ещё этих мягких французских булок да выпей же чаю` => `С.е.э.м.ф.б.д.в.ж. чаю`
2. *trim_arg* - оставляет только первые **arg** символов строки и добавляет троеточие в конце.
1. **Пример:** `Задача очень сложная` trim_6 => `Задача...`
2. **Пример:** `Задача не очень сложная` trim_15 => `Задача не очень...`
3. *yesno* - превращает логическую истину в строку `Да`, а логическую ложь в строку `Нет`.
1. **Пример:** `true` => `Да`
2. **Пример:** `false` => `Нет`
3. **Пример:** `{"Я объект": "Всем привет"}` => `Да`
4. **Пример:** `undefined` => `Нет`
4. *link* - делает из текста ссылку HTML-элементом ``.
1. **Пример:** `https://www.minecraft.net` =>
```html
https://www.minecraft.net
```
5. *ytlink* - делает из текста ссылку HTML-элементом `` на ресурс Yandex Tracker-а
1. **Пример:** `TASK-111` =>
```html
TASK-111
```
6. *boardlink* - делает из текста ссылку HTML-элементом `` на ресурс доски Yandex Tracker-а.
1. **Пример:** `333` =>
```html
333
```
7. *projectlink* - делает из текста ссылку HTML-элементом `` на ресурс проекта Yandex Tracker-а.
1. **Пример:** `444` =>
```html
444
```
8. *log* - выводит в консоль содержимое.
9. *date* - делает из текста в формате `DateTime` текст даты без времени
1. **Пример:** `12.04.1961T09:07:00` => `12.04.1961`
10. *time* - делает из текста в формате `DateTime` текст времени без даты
1. **Пример:** `19.08.1960T11:44:00` => `11:44:00`
---
## Примеры
Далее предполагается, что плагин **YTI**
1. Установлен
2. Запущен
3. Авторизован
### Отображение задач
#### Постановка
Допустим, мы хотим отобразить задачи *TASK-111*, *TASK-112*, *TASK-113* в табличном виде.
Хотим отобразить следующие колонки: Id задачи, дата создания, исполнитель.
#### Решение
1. В настройках, в поле "Атрибуты задач" пишем строку `key createdAt assignee`
2. В произвольной заметке вставить следующий блок кода:
```
```yt-issue
TASK-111
TASK-112
TASK-113```
```
#### Результат
| ID задачи | Дата создания | Исполнитель |
| --------- | ------------------- | -------------------- |
| TASK-111 | 23.09.2025T11:32:44 | Иван Иванович Иванов |
| TASK-112 | 19.12.2025T14:12:31 | Иван Иванович Иванов |
| TASK-113 | 07.12.2025T10:49:55 | Иван Иванович Иванов |
#### Пояснение
Со столбцами `key` (ID задачи) и `createdAt` (Дата создания) сложностей нет.
Но, исполнитель имеет тип `User` и это сложный тип, у которого атрибут по умолчанию - это `display` (Полное имя).
В этом смысле, две строки в поле *"Атрибуты задач"* `key createdAt assignee` и `key createdAt assignee.display` дадут одинаковый результат.
### Улучшение отображения задач
#### Постановка
В предыдущем примере выводится лишняя информация. Более того, таблица не интерактивна.
Надо внести следующие изменения:
1. Сделать поле *"ID задачи"* кликабельной ссылкой на задачу в Yandex Tracker
2. В поле *"Дата создания"* выводить только дату создания без времени.
3. Выводить инициалы и фамилию исполнителя вместо полного ФИО.
#### Решение
1. Для создания ссылки на задачу используем модификатор `ytlink`
2. Для вывода даты без времени используем модификатор `date`
3. Для вывода инициалов используем модификатор `initials`
В итоге, сформируем такую строку: `key:ytlink createdAt:date assignee:initials` и вставим её в настройки, в поле *"Атрибуты задач"*.
#### Результат
| ID задачи | Дата создания | Исполнитель |
| --------------------- | ------------- | ----------- |
| TASK-111 | 23.09.2025 | И.И. Иванов |
| TASK-112 | 19.12.2025 | И.И. Иванов |
| TASK-113 | 07.12.2025 | И.И. Иванов |
### Используем податрибуты
#### Постановка
Хотим дополнительно отображать в таблице логин исполнителя
#### Решение
Добавим новую колонку в таблицу, которая будет содержать логин исполнителя.
Для этого, нужно ещё раз добавить атрибут `assignee` с податрибутом `login`
В итоге, сформируем такую строку:
`key:ytlink createdAt:date assignee:initials assignee.login`
и вставим её в настройки, в поле *"Атрибуты задач"*.
#### Результат
| ID задачи | Дата создания | Исполнитель | Исполнитель.Логин |
| --------------------------------------------------------- | ------------- | ----------- | ----------------- |
| TASK-111 | 23.09.2025 | И.И. Иванов | iivanov |
| TASK-112 | 19.12.2025 | И.И. Иванов | iivanov |
| TASK-113 | 07.12.2025 | И.И. Иванов | iivanov |
**Все ФИО, логины и ID задач придуманы. Все совпадения случайны.**
---
## Известные проблемы
- [ ] При отрисовки диаграммы Ганта с большим количеством задач, ссылки на задачи могут наложиться.
- [ ] При одновременном запуске плагина с нескольких устройств, может быть превышено количество запросов в Yandex Tracker.
---
## План развития
- [ ] Более гибкое масштабирование диаграмм Ганта.
- [ ] Настройки отображения диаграмм Ганта.
- [ ] Больше диаграмм.
---