Руководство Jira

Этот плагин поддерживает двустороннюю интеграцию между Loop и Jira. Поддерживаются продукты Jira Core и Jira Software, серверные, для центров обработки данных и облачных платформ. Плагин протестирован с версиями 7 и 8.

Краткое описание характеристик

Уведомления от Jira до Loop

Подписки на каналы

Уведомляйте команду о последних обновлениях, отправляя уведомления из проектов Jira в каналы Loop. Вы можете указать, какие события вызывают уведомление, и отфильтровать определенные типы уведомлений, чтобы снизить уровень шума.

Персональные уведомления: JiraBot

Каждый пользователь Loop связан со своим личным аккаунтом Jira, и уведомления о проблемах, в которых кто-то упоминается или назначен на проблему, отправляются вашим личным ботом уведомлений Jira, чтобы помочь каждому оставаться в курсе назначенных ему проблем.

Управление проблемами Jira в Loop

Создание проблем Jira

• Создавайте проблемы Jira с нуля или на основе сообщений Loop

• Не выходя из пользовательского интерфейса Loop, можно быстро выбрать проект, тип проблемы и ввести другие поля для создания проблемы.

Прикрепление сообщений к вопросам Jira

Сохраняйте всю информацию в одном месте, прикрепляя части бесед Loop к вопросам Jira в виде комментариев. Затем в появившемся диалоговом окне выберите проблему Jira, к которой вы хотите прикрепить сообщение. Вы можете искать вопросы, содержащие определенный текст.

Переход вопросов Jira

Переход между заданиями осуществляется без необходимости переключения на проект Jira. Для перехода к другой задаче используйте команду /jira transition [issue-key] /[state/]

Например, команда /jira transition EXT-20 done переводит ключ задания EXT-20 в состояние Done

Назначение проблем Jira

Назначение проблем другим пользователям Jira без необходимости переключения на свой проект Jira. Чтобы назначить задание, используйте команду /jira assign

Например, /jira assign EXT-20 Петр передает ключ задания EXT-20 Петру.

Руководство для администраторов

Необходимые условия

• Для Jira 2.1 требуется Loop Server v5.14+ (стали доступны некоторые API плагинов)

• Для Jira 2.0 требуется Loop Server v5.12+

Установка

1. Для установки плагина напишите нам на support@loop.ru, укажите название команды и название плагина, который хотите установить

2. После добавления плагина в команду, необходимо включить его в Системной консоли > Плагины > Jira

3. Настроить плагин с помощью команды /jira setup

к сведению

Если вам необходима помощь в подключении и настройке плагина, напишите нам на support@loop.ru вместе с сообщением о подключении плагина или позже.

Конфигурация

Шаг 1: Настройка плагина в Loop

1. В верхней части страницы Плагины > Jira Системной консоли установите для параметра Включить плагин значение Да.

2. Выберите Сохранить, чтобы включить плагин Jira. Выполните команду /jira setup, чтобы начать настройку плагина.

Шаг 2: Установите плагин как приложение в Jira

Для того, чтобы пользователи могли создавать и управлять проблемами Jira в каналах Loop, установите плагин в качестве приложения в свой экземпляр Jira. Для экземпляров Jira Server или Data Center опубликуйте команду /jira instance install server <your-jira-url> на канале Loop в качестве Системного Администратора Loop и следуйте шагам, опубликованным на канале. Для Jira Cloud опубликуйте сообщение /jira instance install cloud <ваш-jira-url>

Шаг 3: Настройте webhook’и на сервере Jira

Начиная с версии Jira 2.1, необходимо настроить один webhook для всех возможных триггеров событий, которые вы хотите передавать в Loop. Это называется firehose; плагин получает поток событий с сервера Jira через webhook, настроенный ниже. Функция Channel Subscription плагина обрабатывает поток данных и затем направляет события в каналы, основанные на ваших подписках.

Используйте команду /jira webhook, чтобы получить URL-адрес webhook’а для копирования в Jira.

Для управления подписками на канал Loop, используйте команду /jira subscribe в канале, на который вы хотите получать подписки. Затем выберите проект и триггеры событий, которые будут публиковаться в канале. Для управления всеми подписками на канал с правами Администратора см. раздел Управление уведомлениями.

1. Для получения соответствующего URL-адреса webhook’а, отправьте команду /jira webhook <ваш-jira-url> в канал Loop в качестве Системного Администратора Loop.

2. В качестве Системного Администратора Jira перейдите в раздел Настройки Jira > Система > WebHooks.

• Для старых версий Jira выберите иконку шестеренки в левом нижнем углу, затем перейдите в раздел Advanced > WebHooks.

3. Выберите Создать webhook, чтобы создать новый webhook.

4. Введите имя для webhook’а и добавьте в качестве URL-адреса URL-адрес webhook’а Jira, полученный выше.

5. Наконец, установите, какие события проблемы отправляют сообщения в каналы Loop, и выберите все из перечисленных ниже:

• Комментарий

• создано

• обновлено

• удалено

• Задача

• создана

• обновлена

• удалена

6. Выберите Сохранить

Ранее настроенные webhook’и, указывающие на определенные каналы, по-прежнему поддерживаются и будут работать

Обновление плагина

Если вы хотите обновить версию плагина Jira, то напишите нам на support@loop.ru

Slash-команды Администратора

Slash-команды Администратора используются для выполнения функций системного уровня, требующих доступ Администратора

Установка экземпляров Jira

• /jira instance install cloud [jiraURL] - подключение Loop к экземпляру Jira Cloud, расположенному по адресу <jiraURL>

• /'jira instance install server [jiraURL] - подключение Loop к серверу Jira Server или центру обработки данных, расположенному по адресу <jiraURL>

Деинсталляция экземпляров Jira

• /jira instance uninstall cloud [jiraURL] - Отключить Loop от экземпляра Jira Cloud, расположенного по адресу <jiraURL>

• /jira instance uninstall server [jiraURL] - отключить Loop от экземпляра Jira Server или Data Center, расположенного по адресу <jiraURL>

Управление подписками на канал

• /jira subscribe - настройка уведомлений Jira, отправляемых на этот канал. Как настроить доступ пользователей к команде subscribe, смотрите на странице Управление уведомлениями

• /jira subscribe list - отображение всех правил подписки, установленных для всех каналов и команд на вашем экземпляре Loop. Эта команда доступна только Системным Администраторам Loop

Другие

• /jira instance alias [URL] [alias-name] - Назначить псевдоним экземпляру

• /jira instance unalias [alias-name] - Удалить псевдоним из экземпляра

• /jira instance list - Список установленных экземпляров Jira

• /jira instance v2 <jiraURL> - Установить экземпляр Jira для обработки webhook'ов и подписок "v2" (без префикса идентификатора экземпляра)

• /jira stats - отображение статистики использования

• /jira webhook [--instance=<jiraURL>] - Показать webhook Loop для получения JQL-запросов

• /jira v2revert - Возврат к модели данных плагина V2 jira

Управление уведомлениями

Что такое уведомления?

Уведомления Jira - это сообщения, отправляемые на канал Loop при наступлении определенного события в Jira. На них можно подписаться из канала с помощью команды /jira subscribe (управляется в Mattermost). Webhook может быть вручную настроен из Jira для отправки сообщения на определенный канал в Loop (управляется через Jira).

Уведомления и webhook’и можно использовать вместе или выбрать один из них.

При получении любого события webhook’а от Jira плагин просматривает все подписки на уведомления. Если оно соответствует какому-либо правилу, то уведомление будет опубликовано в канале. Если подписки не совпадают, то событие webhook’а отбрасывается.

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

Что такое подписка на уведомления?

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

Когда пользователь настраивает подписку на уведомления, он будет видеть только те проекты и типы заданий, к которым у него есть доступ в Jira. Если проект не виден в Jira, он не будет отображаться в качестве опции для данного пользователя при попытке настроить подписку в Loop.

Также выводится примерный JQL-запрос. Не гарантируется, что это правильный JQL, и он приводится только в качестве ссылки на то, как может выглядеть запрос, если его преобразовать в JQL.

Кто может устанавливать подписку на уведомления для канала?

В конфигурации плагина можно указать, кто может устанавливать подписку на уведомления. Сначала установите, каким ролям пользователей Loop разрешен доступ к функционалу подписки:

Вы также можете указать список групп Jira, разделенных запятыми, в которых должен состоять пользователь, чтобы иметь возможность создавать/редактировать подписки. Пользователь, редактирующий подписку, должен быть членом только одной из перечисленных групп. Если этот параметр оставить пустым, то ограничений на группы Jira не будет.

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

Как я могу увидеть все подписки на уведомления, настроенные в Loop?

Войдя в систему в качестве Системного Администратора, введите /jira subscribe list в канале Loop.

Какие события уведомлений поддерживаются?

Поддерживаются следующие уведомления о событиях Jira:

• Создан вопрос

• Обновление определенных полей задачи, настраиваемое для каждой подписки

• Вопрос вновь открыт или решен

• Вопрос удален, если он еще не решен

• Создание, обновление или удаление комментариев

Если вы хотите видеть поддержку дополнительных событий, сообщите нам об этом

Настройка webhook’а в Jira

Для того чтобы Jira могла отправлять события в ваш экземпляр Loop, необходимо настроить webhook в Jira. Пожалуйста, ознакомьтесь с инструкциями по настройке webhooks на сервере Jira

Устаревшие webhook’и

Если инфраструктура вашей организации устроена таким образом, что экземпляр Loop не может подключиться к экземпляру Jira, вы не сможете воспользоваться функцией Channel Subscriptions. Вместо этого необходимо использовать функцию Legacy Webhooks (первая итерация функции Webhooks, поддерживаемая плагином Jira)

Для того, чтобы сгенерировать URL-адрес webhook’а для конкретного канала, выполните команду /jira webhook и используйте URL-адрес, выведенный в разделе "Legacy Webhooks"

1. Под ролью Системного Администратора Jira, перейдите в раздел Настройки Jira > Система > Webhooks

• Для старых версий Jira выберите значок шестеренки в левом нижнем углу, затем перейдите в раздел Advanced > Webhooks

2. Выберите Создать Webhook, чтобы создать новый webhook. Введите имя для webhook’а и добавьте в качестве URL-адреса URL webhook’а Jira https://SITEURL/plugins/jira/webhook?secret=WEBHOOKSECRET&team=TEAMURL&channel=CHANNELURL (для Jira 2.1)

• Замените TEAMURL и CHANNELURL на URL команды Loop и URL канала, в которые вы хотите отправлять события Jira. Значения должны быть в нижнем регистре

• Замените SITEURL на URL сайта вашего экземпляра Loop, а WEBHOOKSECRET - на секрет, созданный в Loop через Системной консоли > Плагины > Jira

Например, если URL команды - contributors, URL канала - town-square, URL сайта - https://community.mattermost.com, а сгенерированный секрет webhook - MYSECRET, то окончательный URL webhook будет таким:

https://community.mattermost.com/plugins/jira/webhook?secret=MYSECRET&team=contributors&channel=town-square

3. (Необязательно) Задайте описание и пользовательский JQL-запрос для определения того, какие билеты вызывают события. Для получения дополнительной информации о запросах JQL обратитесь к справочной документации Atlassian

4. Наконец, задайте, какие события проблемы отправляют сообщения в каналы Loop, и выберите Сохранить. Поддерживаются следующие события:

• Создание задачи

• Удаление задачи

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

По умолчанию, унаследованная интеграция webhook публикует уведомления о событиях создания, разрешения, снятия, повторного открытия и назначения задачи. Для публикации большего количества событий, используйте следующие дополнительные параметры с разделителем &:

• updated_all=1: все события

• updated_comments=1: все события с комментариями

• updated_description=1: обновленное описание выпуска

• updated_labels=1: обновленные метки задания

• updated_prioity=1: обновленный приоритет задания

• updated_rank=1: присвоение заданию более высокого или более низкого ранга

• updated_sprint=1: назначение задания на другой спринт

• updated_status=1: перевести задание в другой статус, например, Done, In Progress

• updated_summary=1: переименование задания

Вот пример webhook’а, настроенного на создание поста для событий, связанных с комментариями:

https://community.mattermost.com/plugins/jira/webhook?secret=MYSECRET&team=contributors&channel=town-square&updated_comments=1

Разрешения

Можно ли запретить пользователям создавать или прикреплять сообщения Loop к проблемам Jira?

Да, существует настройка плагина для отключения этой функциональности

Как Loop узнает, какие проблемы может видеть пользователь?

Loop отображает только статические сообщения в канале и не применяет разрешения Jira для зрителей в канале.

Любые сообщения в канале могут быть видны всем пользователям этого канала. Подписки на задачи Jira должны осуществляться с осторожностью, чтобы избежать непроизвольного раскрытия конфиденциальных задач Jira, например, в публичном канале. Информация, размещенная в канале, ограничена. Для перехода или переназначения проблемы пользователю необходимо иметь соответствующие права в Jira.

Почему каждый пользователь должен аутентифицироваться в Jira?

Аутентификация в Jira позволяет JiraBot предоставлять персональные уведомления для каждого пользователя Loop/Jira, когда он упоминается в задаче, комментирует задачу или когда ему назначается задача. Кроме того, плагин использует информацию об аутентификации пользователя для выполнения действий от его имени. Такие задачи, как поиск, просмотр, создание, назначение и перенос проблем, выполняются в соответствии с правами, предоставленными пользователю в Jira.

Устранение неполадок

Если у вас возникли проблемы с взаимодействием пользователей с Jira в Loop, например, с созданием проблем, отключите эти функции, установив значение Allow users to connect their Mattermost accounts to Jira to false в Системной консоли> Плагины > Jira. Данная настройка не влияет на уведомления Jira. Затем снова включите этот плагин в Системной консоли > Плагины > Управление плагинами, чтобы сбросить состояние плагина для всех пользователей.

Иногда плагин может аварийно завершить работу, и вы можете заметить ответ в виде красного текста под окном чата, в котором отображается slash-команда с триггером /(название) not found. Если проверить файл журнала, то можно найти сообщения, относящиеся к плагинам и ошибкам проверки работоспособности, ExecuteCommand и т.д.

Если вы столкнулись с подобными проблемами, то в настройках config.json можно установить LogSettings.FileLevel в значение DEBUG. Это позволит включить отладочную регистрацию и получить более подробные события об ошибках в системном журнале. Затем попробуйте снова включить плагин в Cистемной консоли. Эти результаты могут быть запрошены другими участниками форума или нашей службой поддержки.

Примечание: Если у вас есть сайт с высокой активностью, то данная настройка может привести к значительному увеличению файлов журнала и негативно повлиять на производительность сервера. Следите за журналами своего сервера или включайте эту настройку только в средах разработки.

Подключение пользователей Jira/Loop

Подключение учетной записи между Loop и Jira является ключевой частью процесса установки и требует от конечного пользователя аутентификации в Jira и разрешения доступа к своей учетной записи Jira. Все операции по созданию, просмотру, назначению и переходу выполняются с использованием маркера доступа Jira вошедшего пользователя.

• Вы должны быть авторизованы в Loop в том же браузере, который вы используете для входа в Jira во время подключения.

• Домен, с которым конечные пользователи входят в Loop в этом браузере, должен совпадать с SiteURL в файле config.json

Руководство пользователя

Начало работы

Приступить к работе с коннектором Jira/Loop очень просто. Сначала необходимо связать учетную запись Jira с учетной записью Loop, чтобы система могла выполнять такие действия, как поиск, просмотр и создание проблем Jira от вашего имени

1. Зайдите в любой канал Loop и введите /jira connect

2. Перейдите по появившейся ссылке - она приведет вас на ваш сервер Jira

3. Выберите Разрешить

Вы можете заметить, что при вводе / появляется меню - это так называемые slash-команды, которые предоставляют функциональность Jira (и других интеграций) под рукой

Проблемы аутентификации в Jira Cloud

При подключении к облачному экземпляру Jira необходимо временно разрешить сторонние файлы cookie в браузере во время процесса аутентификации в Jira. Если вы используете Google Chrome, это можно сделать, зайдя в настройки cookie-файлов браузера и выбрав Разрешить все cookie. Для доступа к этим настройкам можно вставить в адресную строку chrome://settings/cookies. После подключения учетной записи Jira отключите в браузере настройку сторонних файлов cookie

Использование команд /jira

Доступные команды перечислены ниже:

• /jira help - Запуск синтаксиса справки командной строки плагина Jira.

• /jira info - отображение информации о текущем пользователе и плагине Jira

• /jira connect [jiraURL] - Подключить учетную запись Loop к учетной записи Jira.

• /jira disconnect [jiraURL] - Отключить учетную запись Loop от учетной записи Jira.

• /jira issue assign [issue-key] [assignee] - изменить назначенного человека в задании Jira.

• /jira issue create [text] - Создание нового задания с вставкой text в поле описания.

• /jira issue transition [issue-key] /[state/] - изменение состояния задания Jira.

• /jira issue unassign [issue-key] - Отменить назначение задания Jira.

• /jira issue view [issue-key] - Просмотр деталей конкретного задания Jira

• /jira instance settings - Просмотр настроек пользователя

• /jira instance settings [setting] [value] - обновление настроек пользователя

к сведению

Для команды /jira instance settings параметр setting может быть уведомлением, а value - включением или выключением

Аутентификация в Jira

Для управления соединением между учетной записью Loop и учетной записью Jira используйте команды /jira connect и /jira disconnect

Создание проблемы в Jira

Используйте команду /jira issue create для создания проблемы Jira в Loop. Появится форма, позволяющая заполнить вопрос. Вы можете предварительно заполнить краткое описание проблемы с помощью команды:

/jira issue create Это резюме моего задания

Переход между задачами Jira

Переход между задачами осуществляется без необходимости переключения на проект Jira. Для переноса задачи используйте команду /jira transition [issue-key] /[state/]

Например, команда /jira transition EXT-20 done переводит ключ задания EXT-20 в состояние Done

к сведению

• Состояния и переходы задач зависят от конфигурации рабочего процесса проекта Jira. Если введено недопустимое состояние, возвращается эфемерное сообщение о том, что состояние не найдено.

• Частичные совпадения работают. Например, при вводе команды /jira transition EXT-20 произойдет переход в состояние In Progress. Однако если есть состояния In Review, In Progress, бот плагина попросит вас уточнить и покажет частичные совпадения

Назначение проблем Jira

Назначайте проблемы другим пользователям Jira без необходимости переключения на ваш проект Jira. Чтобы назначить проблему, используйте команду /jira assign. Например, /jira assign EXT-20 Петр передает ключ задания EXT-20 Петру.

к сведению

Частичные совпадения работают с именами пользователей и именами и фамилиями

Часто задаваемые вопросы (FAQ)

Почему плагин Jira не публикует сообщения в Loop?

Попробуйте выполнить следующие действия по устранению неполадок:

Если в настройках webhook’а Jira указан JQL-запрос, вставьте его в Jira issue search и убедитесь, что он возвращает результаты. Если результатов нет, возможно, запрос некорректен. Обратитесь за помощью к документации Atlassian. Обратите внимание, что включать JQL-запрос при настройке webhook не нужно

Если вы используете Legacy webhook’и:

1. Убедитесь, что URL команды и URL канала, указанные в URL webhook’а Jira, совпадают с путем, отображаемым в браузере при посещении канала.

2. Поддерживаются только события, описанные в документации Legacy Webhooks.

3. С помощью команды curl выполните POST-запрос к URL webhook’у. Если команда curl завершает запрос с ответом 200 OK, значит, плагин настроен правильно. Например, можно выполнить следующую команду:

curl -X POST -v "https://<your-mattermost-url>/plugins/jira/webhook?secret=<your-secret>&team=<your-team>&channel=<your-channel>&user_id=admin&user_key=admin" --data '{"event":"some_jira_event"}

Поля <your-mattermost-url>, <your-secret>, <your-team-url> и <your-channel-url> зависят от ваших настроек при конфигурировании плагина Jira. Команда curl не приведет к появлению реального сообщения в вашем канале

Если у вас все еще возникают проблемы с настройкой, пожалуйста, напишите нам на почту support@loop.ru, и мы будем рады помочь вам в решении проблем, возникающих при настройке.

Как отключить плагин?

Вы можете отключить плагин Jira в любое время из Loop через Системную консоль > Плагины > Управление. После отключения плагина все запросы webhook’ов, поступающие от Jira, будут игнорироваться. Кроме того, пользователи не смогут создавать проблемы Jira из Loop.

Если вы хотите отключить только взаимодействие пользователей Loop с Jira, например, создание проблем, вы можете отключить эти функции, установив значение Allow users to connect their Mattermost accounts to Jira в false в Системной консоли > Плагины > Jira. После этого необходимо перезапустить плагин в Системной консоли > Плагины > Jira, чтобы обновить пользовательский интерфейс для пользователей, вошедших в Loop, или они могут обновить его, чтобы увидеть изменения. Эта настройка не влияет на уведомления webhook’ов Jira.

Почему возникает ошибка Webhooks могут использовать только стандартные порты http и https (80 или 443)?

Jira позволяет webhook’ам подключаться только к стандартным портам 80 и 443. Если вы используете нестандартный порт, вам необходимо настроить прокси между Jira и вашим экземпляром Loop, чтобы Jira обменивалась данными через порт 443.

Как обрабатывать ротацию учетных данных для вебхука Jira?

Сгенерируйте новый секрет в Системной консоли > Плагины > Jira, затем вставьте новый URL webhook в конфигурацию Jira webhook.

Что изменилось в конфигурации webhook’ов Jira 2.1?

В Jira 2.1 появилось модальное окно для Подписки на канал на задачи в Jira. Для этого необходимо отправить webhook из Jira в Loop, а плагин Jira затем "перенаправляет" или "сбрасывает" события в определенные каналы. Модальное окно Channel Subscription (доступ к которой можно получить, перейдя на определенный канал и набрав jira /subscribe) предоставляет Администраторам каналов Loop удобный доступ к настройке уведомлений, которые они хотят получать по каждому из каналов.

Если инфраструктура вашей организации устроена таким образом, что ваш экземпляр Loop не может подключиться к вашему экземпляру Jira, функция Channel Subscriptions будет недоступна. Вместо этого необходимо использовать функцию Legacy Webhooks, поддерживаемую плагином Jira, которая позволяет отправлять webhook’и Jira на определенный канал.

Лицензия

Данный репозиторий лицензируется в соответствии с лицензией Apache 2.0, за исключением каталога server/enterprise, который лицензируется в соответствии с лицензией Mattermost Source Available License. Более подробная информация приведена в разделе Лицензия Mattermost Source Available License.

Разработка

Ознакомьтесь с документацией по разработке данного проекта, а также с документацией Developer Workflow и Developer Setup для получения дополнительной информации о разработке и расширении плагинов.

Окружение

Данный плагин поддерживает как сервер Jira Server (самостоятельное размещение), так и облачные экземпляры Jira Cloud. В поведении этих двух систем могут быть небольшие различия, поэтому при внедрении новой логики webhook’ов или добавлении нового вызова API Jira лучше протестировать обе системы по отдельности.

Для тестирования изменений на локальном экземпляре Jira Server необходимо установить Docker, после чего можно использовать файл docker-compose.yml в этом репозитории для создания экземпляра Jira. Просто запустите docker-compose в директории репозитория, и новый сервер Jira запустится и будет доступен по адресу http://localhost:8080. Запуск может занять несколько минут из-за процессов запуска сервера Jira. Если контейнер не запускается с кодом выхода 137, возможно, необходимо увеличить объем оперативной памяти, которую разрешено использовать docker.

Чтобы протестировать свои изменения на экземпляре Jira Cloud, мы рекомендуем начать 14-дневную пробную версию, если у вас нет проекта Jira для тестирования. Более подробную информацию можно найти здесь: https://www.atlassian.com/software/jira/try.