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` считывает и записывает значения из текущей строки.

Пример:

```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()`.

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

![](images/fieldMappingExample.png)

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

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

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

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

![](images/statisticsExample.png)