Функции
Ключевые функции
- Получение для проекта Jira всех типов запросов (issue type) и связанных с ними статусов (status) запросов.
- Выборка измененных запросов из Jira с отбором по проекту, периоду, с ограничением на кол-во отбираемых записей и используя шаблон JQL запроса.
- Получение списка пользователей Jira исходя из полей запроса (assignee, reporter, creator), полей worklog-а (autor, update autor) и полей комментариев (autor, update autor) и отображение имени пользователя и представления пользователя при выборе пользователя при редактировании полей запроса и полей записи о работе.
- Чтение и запись ключевых полей запроса (issue) Jira: Наименование (summary), Описание (description), Тип запроса (issue type), Родитель подзадачи (parent), Ссылка на epic (epic link), Приоритет (priority), Исполнитель (assignee), Автор (reporter), Создатель (creator), Срок исполнения (due date), Дата создания (created), Дата обновления (updated), Компоненты проекта Jira (components), Метки (labels), Первоначальная оценка (original estimate), Оставшееся время (remaining estimate), Всего затраты (time spent).
- Чтение и установка нового статуса запроса (status). Получение допустимых транзакции (transitions) Jira для перехода к новому статусу и осуществление перехода используя подходящую транзакцию.
- Чтение записей о работах (worklog) для запроса Jira. Добавление, Изменение и Удаление записей о работе.
- Чтение комментариев к запросу Jira. Формирование ссылки для перехода в Jira непосредственно к выбранному комментарию.
Дополнительные возможности
- В случае ошибки в момент выполнения http запроса к Jira, программа выдает диагностическое сообщение с кодом состояния и открывает для просмотра в виде текста файл с ответом от Jira.
- Программа отдельно контролирует список изменившихся полей запроса и при записи запроса передает в Jira только изменения.
- Основные значения сохраняются между сеансами работы с обработкой (параметры подключения к Jira, типы и статусы запросов, настройки отбора выборки запросов, список пользователей, последние выбранные значения полей запроса).
- Реквизиты и элементы формы для сохраняемых полей создаются программно.
Источники и ссылки
- Спецификация по работе с JIRA с использованием REST: http://docs.atlassian.com/jira/REST/latest/
- Спецификация REST API для JIRA SERVER: https://docs.atlassian.com/jira/REST/server/
- Примеры REST запросов к JIRA: https://developer.atlassian.com/server/jira/platform/jira-rest-api-examples/
- Продвинутый поиск в Jira используя Jira Query Language (JQL): https://confluence.atlassian.com/jirasoftwareserver073/advanced-searching-861256227.html
- Онлайн просмотр .json: jsonviewer.stack.hu
Особенности и ограничения
- Данная обработка предназначена для работы с серверной версией Jira.
- Для подключения к Jira используется обычная проверка подлинности (Basic authentication).
- При изменении статуса запроса (status) выполняется дополнительный запрос для определения подходящей транзакций перехода от текущего к выбранному статусу. В определенных случаях (например для "подзадачи") переход к выбранному статусу может оказаться невозможным. В таком случае программа выдаст диагностическое сообщение "Не удалось определить ""ID транзакции"" для статуса ...".
- При создании в Jira записи о работах (work log) в качестве автора запись всегда устанавливается пользователи под которым выполнено подключение к Jira (указать другого автора нельзя).
- При определенных настройках Jira, в момент перехода к новому статусу, также может изменится исполнитель (assignee) на пользователя от имени которого выполнено подключение к Jira.
- Используя REST невозможно изменить тип запроса "подзадача" на другой тип запроса. При попытке выполнить такое изменение Jira вернет код ошибки и описание ошибки в файле с ответом.
- Для комментариев к запросу реализовано только чтения списка комментариев и непосредственный переход к комментарию в браузере. Создание, изменение и удаление комментариев не поддерживается (при необходимости может быть легко реализовано по аналогии как это сделано для записей о работах (worklog).
Варианты использования
Короткий ролик с демонстрацией основных возможностей обработки (~ 7 мин, только текстовые комментарии, без голосового сопровождения)
Подключение к серверу Jira
На закладке "Параметры" указываются параметры для подключения к Jira:
- Адрес сервера для подключения.
- Ссылка по которой доступен REST API.
- Ключ проекта Jira который будет использоваться.
- Пользователь и пароль для подключения к Jira. Подключение к Jira выполняется используя простой (незащищённый) способ аутентификации (подробнее по ссылке: Basic authentication).
Получение Типов и статусов запросов для проекта Jira
- На закладке "Параметры" по кнопке "Заполнить типы и статусы из Jira" выполняется запрос к Jira, который возвращает .json файл с информацией о типах и статусах запросов используемых для указанного проекта. (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/project-getAllStatuses)
- Данные из таблицы используются в дальнейшем для заполнения списков выбора полей "Типа запроса" и "Статус запроса" в карточке запроса на закладке "Запрос".
- Информация из таблицы используется для определения "подзадач" и "id" типа запроса. Эти данные требуется для обращения к Jira при редактирования и создания запросов.
- Список типов и статусов автоматически сохраняется между сеансами работы в данных формы.
Выборка запросов используя JQL запрос к Jira
- На закладке "Выборка запросов" по команде "Прочитать из Jira" выполняется запрос к Jira по результатам которого заполняется список запросов (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/search-searchUsingSearchRequest)
- Запросы из Jira отбираются согласно JQL запроса.
- Итоговый JQL запрос формируется путем подстановки параметров в строку "Шаблон запрос JQL для выборки данных".
- Данные выбираются в количестве не более "Всего выбрать" заданными порциями.
- Из списка запросов по ссылке "Browse link" можно перейти к запросу в браузере.
- Из списка запросов по кнопкам "Добавить", "Изменить" можно перейти к созданию или редактированию запроса. При этом будет активирована закладка "Запрос" (в случае операции "Изменить" будет выполнено обращение к Jira и заполнены все предусмотренные для редактирования поля, а также получены все комментарии и записи о работах для выбранного запроса).
Список пользователей Jira для выбора
- Список на закладке "Пользователи" является основой для содержимого списков выбора при выборе участников запроса.
- Пользователи в список добавляются автоматически при "Выборке запросов" или при чтения данных конкретного запроса (с учетом записей о работах и комментариев).
- При необходимости пользователей в список можно добавить "вручную".
- Список пользователей автоматически сохраняется между сеансами работы в данных формы.
Чтение запроса из Jira
- На закладке "Запрос" выполняются основные операции по просмотру и редактированию полей запроса.
- Если выбрана операция "Изменить запрос" и заполнен "Ключ запроса" (Key) доступна команда "Прочитать из Jira".
- При нажатии "Прочитать из Jira" выполняется запрос к Jira и заполняются поля запроса, записи о работах и комментарии.
- Если заполнен "Ключ запроса" тогда отображается "ссылка для перехода к запросу в браузере".
- По ссылке "JSON" выполняется переход в браузере к файлу .json с данными запроса.
- Для чтения значений полей выполняется запрос к Jira (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-getIssue).
- В случае успешной операции чтения из Jira, все поля запроса отмечаются как "не изменявшиеся".
- Значения полей, количество записей о работах и количество комментариев (кроме самих записей о работах и комментариев) сохраняются между сеансами работы в данных формы.
Изменение полей запроса и запись в Jira
- Программа отдельно хранит все предыдущие значения полей запроса.
- Каждый раз при чтении запроса из Jira текущие и предыдущие значения полей синхронизируются.
- При изменение какого-либо из полей запроса, сравнивается новое значение и предыдущее.
- Если новое значение отличается от предыдущего, поле отмечается как "измененное" и выделяется на форме с помощью фона и цвета текста заголовка.
- При записи в Jira передаются только измененные поля (для которых новое значение отличается от предыдущего).
- Для записи выполняется запрос к Jira (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-editIssue)
- Предыдущие значения реквизитов сохраняются между сеансами работы в данных формы.
- Для "обнуления" измененных реквизитов можно либо "Прочитать из Jira" или "Записать в Jira" (после успешной записи автоматически выполняется "Прочитать из Jira".
Создание нового запроса в Jira
- Для создания нового запроса на закладке "Запрос" необходимо выбрать операцию "Создать запрос".
- Пока запрос не создан, недоступны ссылки для перехода к запросу, комментариям и списку записей о работах.
- Для создания запроса выполняется запрос к Jira (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-createIssue)
- После создания запроса в Jira, автоматически выполняется чтение запроса и активация операции "Изменить запрос".
Изменение статуса запроса в Jira
- Если изменяется статус запроса, программа показывает информационную надпись вида "При записи статус изменится с "В работе" -> "Выполнен".
- Изменение статуса происходит при нажатии "Записать в Jira".
- Сначала выполняется запрос по записи измененных полей запроса, а затем изменяется статус запроса.
- Изменение статуса запроса происходит в несколько этапов:
- Сначала выполняется дополнительный запрос для получения списка всех допустимых транзакция для текущего запроса (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-getTransitions)
- Из списка допустимых транзакция определяется подходящая транзакция, для которой конечный статус равен выбранному в запросе.
- Выполняется отдельный запрос для выполнения транзакции перехода (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-doTransition)
- После изменения статуса запроса, автоматически выполняется чтение запроса из Jira.
Чтение, Добавление и Удаление записей о работах в Jira
- В карточке запроса на закладке "Записи о работах" отображается список записей о работах запроса.
- По кнопке "Прочитать work log" выполняется запрос к Jira и заполняется список записей о работах для запроса (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-getIssueWorklog).
- По кнопке "Добавить" появляется форма для создания новой записи о работе. По кнопке "Сохранить запись" выполняется запрос к Jira для добавления новой записи о работе (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-addWorklog).
- По кнопке "Изменить" появляется форма для редактирования выбранной записи о работе. По кнопке "Записать изменения" выполняется запрос к Jira для обновления данных существующей записи о работе (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-updateWorklog).
- По кнопке "Удалить запись" выполняется запрос к Jira для удаления записи о работах (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-deleteWorklog)
Чтение комментариев и переход по ссылке к конкретному комментарию в Jira
- В карточке запроса на закладке "Комментарии" отображается список всех комментариев для запроса.
- По кнопке "Прочитать комментарии" выполняется запрос к Jira и заполняется список комментариев для запроса (см. https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#api/2/issue-getComments).
- По ссылке "Ссылка на комментарий" можно непосредственно перейти к комментарию в Jira.