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

Board

Атрибут по умолчанию - name

Project

Атрибут по умолчанию - name

Queue

Атрибут по умолчанию - name

Sprint

Атрибут по умолчанию - name

User

Атрибут по умолчанию - display

Модификаторы

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-элементом <a/>.
   1. Пример: https://www.minecraft.net =>

<a href="https://www.minecraft.net"> https://www.minecraft.net </a>

5. ytlink - делает из текста ссылку HTML-элементом <a/> на ресурс Yandex Tracker-а
   1. Пример: TASK-111 =>

 <a href="https://tracker.yandex.ru/TASK-111"> TASK-111 </a>

6. boardlink - делает из текста ссылку HTML-элементом <a/> на ресурс доски Yandex Tracker-а.
   1. Пример: 333 =>

 <a href="https://tracker.yandex.ru/pages/projects/333/board"> 333 </a>

7. projectlink - делает из текста ссылку HTML-элементом <a/> на ресурс проекта Yandex Tracker-а.
   1. Пример: 444 =>

 <a href="https://tracker.yandex.ru/pages/projects/444"> 444 </a>

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``` 

Результат

Пояснение

Со столбцами 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 и вставим её в настройки, в поле "Атрибуты задач".

Результат

Используем податрибуты

Постановка

Хотим дополнительно отображать в таблице логин исполнителя

Решение

Добавим новую колонку в таблицу, которая будет содержать логин исполнителя.

Для этого, нужно ещё раз добавить атрибут assignee с податрибутом login

В итоге, сформируем такую строку: key:ytlink createdAt:date assignee:initials assignee.login и вставим её в настройки, в поле "Атрибуты задач".

Результат

Все ФИО, логины и ID задач придуманы. Все совпадения случайны.

Известные проблемы

• При отрисовки диаграммы Ганта с большим количеством задач, ссылки на задачи могут наложиться.
• При одновременном запуске плагина с нескольких устройств, может быть превышено количество запросов в Yandex Tracker.

План развития

• Более гибкое масштабирование диаграмм Ганта.
• Настройки отображения диаграмм Ганта.
• Больше диаграмм.