alamion_obsidian-jira-sync/docs/how_to_ru.md

Функционал плагина можно разделить на несколько частей.

Базовый функционал

Для него достаточно указать креды Jira и папку с создаваемыми задачами.

Методы аутентификации Плагин поддерживает три метода аутентификации:

• Bearer Token (PAT) - аутентификация по персональному токену доступа
• Basic Auth (Username + PAT) - имя пользователя с персональным токеном доступа
• Session Cookie (Username + Password) - традиционная аутентификация по имени пользователя и паролю

Важное замечание для ключей аутентификации: При использовании аутентификации по персональному токену доступа, области write:jira-work и read:jira-work являются обязательными для корректной работы плагина.

При запуске Get issue from Jira with custom key команда будет скачивать актуальные задачи из Jira и сохранять их в указанной папке.

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

Шаблон

Шаблон можно составить из нескольких разных частей:

Frontmatter

Оно же метаинформация сверху экрана. При указании ключей для него и любом варианте Get issues from Jira они будут заполняться соответствующими полями из ответных данных.

Body

Основное содержание страницы. При использовании индикаторов типа jira-sync-"type"-* они будут заполняться соответствующими полями из сырых данных задачи.

Разница между этими параметрами заключается в следующем:

• line считывает и записывает значения из текущей строки.

Пример:

Ответственным за эту задачу является `jira-sync-line-assignee` Боб.
Описание: `jira-sync-line-description` Некоторое описание.

• section считывает значения из нескольких строк после индикатора, останавливаясь только на любом другом индикаторе или заголовке.

Пример:

### Ответственный `jira-sync-section-assignee`

Боб

### Описание `jira-sync-section-description`

Некоторое описание
`jira-sync-section-customfield_10842`...

• inline позволяет размещать индикатор начала и окончания в любом месте текста. Должна быть конечная часть индикатора (jira-sync-end).

Пример:

Ответственным за эту задачу является `jira-sync-inline-start-assignee`Боб`jira-sync-end`, а описание — `jira-sync-inline-start-description`Некоторое описание`jira-sync-end`.

• block в основном аналогичен inline, но с разрывом строки перед и после индикаторов.

Пример:

Ответственным за эту задачу является `jira-sync-block-start-assignee`
Bob
`jira-sync-end`, а описание — `jira-sync-block-start-description`
Некоторое описание
`jira-sync-end`.

Пример можно найти в docs/template_example.

Настоятельно рекомендуется указать следующие базовые значения в форматере шаблона: key — ID задачи Jira, используемый для обновлений, summary — название задачи Jira и status — текущий статус задачи в Jira.

Форматировщик имеет приоритет и перезаписывает значения содержимого файла при обновлении задачи в Jira, если значение поля присутствует в обоих, поскольку форматировщик сохраняет исходный формат значения, а при помещении его в тело мы преобразуем его в строку.

Не все поля являются предопределенными, и некоторые из них могут потребовать дополнительной настройки. Чтобы добавить любые нестандартные поля, узнать об особенностях их представления в формате .md и о том, как обновлять их информацию в Jira, обратитесь к разделу "Продвинутое использование" ниже.

Команды

На текущий момент плагин предоставляет следующие команды:

• Get issue from Jira with custom key - позволяет создать в папке, указанной в настройках, файл, импортирующий информацию из Jira по указанному вручную id.
• Batch Fetch Issues by JQL - позволяет получить задачи по JQL и создать/обновить все соответствующие заметки.
• Get current issue from Jira - позволяет обновить активный файл, если в его formatter указан key - id задачи Jira.
• Update issue in Jira - позволяет обновить информацию из файла в Jira по указанному в formatter ключу. Ряд системных полей (например, status, таким образом изменить нельзя. Для них созданы отдельные команды)
• Create issue in Jira - позволяет создать в Jira новую задачу. В formatter обязательно нужно указать summary - название задачи и, опционально, project и issuetype (последние два можно выбрать из существующих при создании)
• Update work log in Jira manually - позволяет вести учёт потраченного на задачу времени вручную. В данный момент он никак не отображается в файле, это будет в ближайших обновлениях.
• Update work log in Jira by batch - позволяет вести учёт потраченного на задачу времени батчем. Если в файле в formatter есть jira_worklog_batch, то вместо ручного заполнения будет послан батч данных из jira_worklog_batch с обновлением каждой из представленных сущностей.
• Update issue status in Jira - позволяет обновить статус задачи, выбрав один из возможных вариантов.
• Add comment to Jira - позволяет добавить комментарий в выбранную задачу.

Продвинутое использование

Маппинг полей

В настройках можно задать кастомный маппинг дл любых дополнительных полей, приходящих из запроса. Для этого нужно:

• Настроить в каком виде информация отправляется в Jira (например при функции null поле будет игнорироваться)
• В каком виде получается из Jira (например issue.fields.creator.name позволит получать соответственное имя создателя запроса, а не весь объект с информацией о нём в целом.)

Таким же образом можно настроить показанный в примере progressPercentage - такого поля в запросе не существует, но его можно 'собрать' из существующего progress: issue.fields.progress.total ? 100 * issue.fields.progress.progress / issue.fields.progress.total : 0. Как понятно из синтаксиса, для маппинга используется обрезанный TypeScript

Кроме того, вы можете использовать некоторые встроенные функции:

• jiraToMarkdown - преобразует разметку Jira в Markdown. (Jira API v2)
• markdownToJira - преобразует Markdown в разметку Jira. (Jira API v2)
• markdownToAdf - преобразует Markdown в ADF. (Jira API v3)
• adfToMarkdown - преобразует ADF в Markdown. (Jira API v3)
• JSON.parse - преобразует строку JSON в объект.
• JSON.stringify - преобразует объект в строку JSON.

и модули: (исходный синтаксис JavaScript)

• Math - предоставляет доступ к математическим функциям, таким как Math.round().
• Date - предоставляет доступ к функциям даты, таким как Date.now().
• String - предоставляет доступ к функциям строки, таким как String.fromCharCode().
• Number - предоставляет доступ к числовым функциям, таким как Number.isNaN().
• Boolean - предоставляет доступ к булевым функциям, таким как Boolean(true).
• Array - предоставляет доступ к массивным функциям, таким как Array.isArray().
• Object - предоставляет доступ к объектным функциям, таким как Object.keys().

Секция маппинга может выглядеть так:

Статистика ведения журнала работы

Статистика доступна через настройки плагина в секции "Timekeep work log statistics" ("Статистика ведения журнала работы через Timekeep"). Эта функция предоставляет динамически генерируемую таблицу (или ряд таблиц), показывающую статистику работы и позволяющую отправлять журналы работ в Jira. Там же можно удобно выбирать временные промежутки для которых проводится расчёт и передавать информацию ведения журнала работы в Jira.

Поддерживаются форматы временных записей: timekeep и simple-time-tracker.

Выглядит табличка так: