mirror of
https://github.com/alamion/obsidian-jira-sync.git
synced 2026-07-22 05:43:04 +00:00
ad06c8f4d8
- `jira-sync-block-start-` docs fix - custom fields functions correct load on startup - jira values highlight rollback due to contributor dropped feature full realization. (In current state it's too buggy to release)
142 lines
12 KiB
Markdown
142 lines
12 KiB
Markdown
Функционал плагина можно разделить на несколько частей.
|
||
|
||
### Базовый функционал
|
||
|
||
Для него достаточно указать креды 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` считывает и записывает значения из текущей строки.
|
||
|
||
Пример:
|
||
|
||
```md
|
||
Ответственным за эту задачу является `jira-sync-line-assignee` Боб.
|
||
Описание: `jira-sync-line-description` Некоторое описание.
|
||
```
|
||
|
||
- `section` считывает значения из нескольких строк после индикатора, останавливаясь только на любом другом индикаторе или заголовке.
|
||
|
||
Пример:
|
||
|
||
```md
|
||
### Ответственный `jira-sync-section-assignee`
|
||
|
||
Боб
|
||
|
||
### Описание `jira-sync-section-description`
|
||
|
||
Некоторое описание
|
||
`jira-sync-section-customfield_10842`...
|
||
```
|
||
|
||
- `inline` позволяет размещать индикатор начала и окончания в любом месте текста. Должна быть конечная часть индикатора (`jira-sync-end`).
|
||
|
||
Пример:
|
||
|
||
```md
|
||
Ответственным за эту задачу является `jira-sync-inline-start-assignee`Боб`jira-sync-end`, а описание — `jira-sync-inline-start-description`Некоторое описание`jira-sync-end`.
|
||
```
|
||
|
||
- `block` в основном аналогичен `inline`, но с разрывом строки перед и после индикаторов.
|
||
|
||
Пример:
|
||
|
||
```md
|
||
Ответственным за эту задачу является `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.
|
||
|
||
Выглядит табличка так:
|
||
|
||
|