Перейти к основному содержимому

Jira

Интеграция Jira с Time позволяет пользователям связывать свои учетные записи Jira с Time, получать уведомления о событиях в Jira и управлять задачами Jira непосредственно из интерфейса Time.

Настройка​

  1. Зайдите на страницу настройки плагина Jira в системной консоли и настройте параметры Jira следующим образом:
    • Создайте Webhook Secret, выбрав Regenerate
    • Установите API токен администратора: Admin API Token, подробнее в Jira
  2. Выполните команду /jira setup для запуска настройки плагина.

Для настройки вручную выполните следующие действия.

Настройка через переменные окружения​

Плагин Jira можно включить и настроить с помощью переменных окружения. Для включения плагина используйте переменную TIME_PLUGINSETTINGS_PLUGINSTATES_JIRA_ENABLE="true".

Параметры плагина Jira​

Переменная окруженияЗначение по умолчаниюОписание
TIME_PLUGINSETTINGS_PLUGINS_JIRA_DISPLAYSUBSCRIPTIONNAMEINNOTIFICATIONS"false"Отображать имя подписки в сообщении, когда подписка публикует сообщение в канал. Установите true, чтобы скрыть имя подписки.
TIME_PLUGINSETTINGS_PLUGINS_JIRA_ENABLEAUTOCOMPLETE"true"Включение автозаполнения. Помогает пользователям освоиться с доступными командами /jira.
TIME_PLUGINSETTINGS_PLUGINS_JIRA_ENABLEWEBHOOKEVENTLOGGING"false"Включение логирования событий веб-хука.
TIME_PLUGINSETTINGS_PLUGINS_JIRA_GROUPSALLOWEDTOEDITJIRASUBSCRIPTIONS""Список названий групп, разделённых запятыми. Укажите группы пользователей Jira, которые могут создавать подписки. Если группы не указаны, любой пользователь Jira может создать подписку. Ограничения по группам Jira применяются только для устаревших экземпляров, установленных на Jira 2.4 или ранее.
TIME_PLUGINSETTINGS_PLUGINS_JIRA_HIDEDECRIPTIONCOMMENT"false"Скрывать подробные описания задач и комментарии в сообщениях подписки и веб-хуков.
TIME_PLUGINSETTINGS_PLUGINS_JIRA_JIRAADMINADDITIONALHELPTEXT""Дополнительный текст справки, который будет отображаться пользователю вместе с результатом команды /jira help.
TIME_PLUGINSETTINGS_PLUGINS_JIRA_MAXATTACHMENTSIZE""Максимальный размер вложения, который можно загрузить в Jira. Может быть числом, за которым следует одна из единиц измерения [b, kb, mb, gb, tb].
TIME_PLUGINSETTINGS_PLUGINS_JIRA_ROLESALLOWEDTOEDITJIRASUBSCRIPTIONS"system_admin"Роли TIME, которые могут подписываться на каналы задач Jira. Возможные варианты: users (все пользователи), channel_admin (роль, которая может управлять настройками канала), team_admin (роль, которая может управлять настройками команды), system_admin (системный администратор системы).
TIME_PLUGINSETTINGS_PLUGINS_JIRA_SECURITYLEVELEMPTYFORJIRASUBSCRIPTIONS"true"Подписки будут включать только те задачи, у которых назначен уровень безопасности, если соответствующий уровень безопасности включён в качестве фильтра.
TIME_PLUGINSETTINGS_PLUGINS_JIRA_ENABLEJIRAUI"true"Включение пользовательского интерфейса Jira.
TIME_PLUGINSETTINGS_PLUGINS_JIRA_SECRET""Секрет, используемый для аутентификации веб-хука в TIME.

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

  • Для экземпляров Jira Server или Data Center выполните команду /jira instance install server <YOUR-JIRA-URL>.

    Далее следуйте инструкциям, опубликованным в канале. Для удаления экземпляра Jira Server или Data Center выполните команду /jira instance uninstall server <YOUR-JIRA-URL>.

  • Для Jira Cloud выполните команду /jira instance install cloud-oauth <YOUR-JIRA-URL>.

    Далее следуйте инструкциям, опубликованным в канале для завершения настройки. Для удаления экземпляра Jira Cloud выполните команду /jira instance uninstall cloud-oauth <YOUR-JIRA-URL>.

Настройка веб-хуков в Jira​

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

  1. В канале Time выполните команду /jira webhook <YOUR-JIRA-URL>, чтобы получить URL веб-хука.
  2. В Jira перейдите в Jira Settings → System → Webhooks (для более старых версий Jira выберите значок шестеренки в левом нижнем углу, затем перейдите в Advanced → Webhooks).
  3. Выберите Create a WebHook.
  4. Введите название Name для вашего веб-хука и добавьте URL-адрес веб-хука Jira, который был получен выше, в Time.
  5. Укажите события, которые будут отправляться на каналы в Time из списка:
    • Comments: created, updated, deleted.
    • Issue: created, updated, deleted.
  6. Нажмите Save.

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

В модальном окне «Подписка на канал» администраторы каналов Time могут легко настроить уведомления, которые они хотят получать для каждого канала. В любом канале выполните команду /jira subscribe и настройте следующие параметры:

  • Настройте, какие уведомления Jira отправляются на текущий канал
  • Укажите фильтры, в том числе: affects versions, epic link, fix versions, labels, and priority.
  • Укажите настраиваемые поля, включая: checkboxes, labels, radio buttons, and select list.
  • Просмотрите примерный сгенерированный вывод JQL. Это не обязательно валидный JQL, он показан только для того, чтобы вы могли представить, как может выглядеть запрос при преобразовании в JQL.

Выполните команду /jira subscribe list, чтобы отобразить все правила подписки, настроенные для всех каналов и команд в вашем экземпляре Time.

Устаревшие веб-хуки Jira​

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

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

  2. Как системный администратор Jira, перейдите в Jira Settings → System → WebHooks. Для более старых версий Jira выберите значок шестеренки в левом нижнем углу, затем перейдите в Advanced → WebHooks.

  3. Выберите Create a WebHook, чтобы создать новый веб-хук. Введите название Name для вашего веб-хука и добавьте URL-адрес веб-хука Jira: https://TIME-SITE-URL/plugins/jira/webhook?secret=TIME-WEBHOOK-SECRET&team=TIME-TEAM-URL&channel=TIME-CHANNEL-URL (для Jira 2.1) в качестве URL-адреса.

    • TIME-TEAM-URL и TIME-CHANNEL-URL - URL-адреса команды и канала Time, на который вы хотите отправлять события Jira, используя строчные буквы.
    • TIME-SITE-URL - URL-адрес вашего экземпляра Time.
    • TIME-WEBHOOK-SECRET - секретный ключ веб-хука, полученный при настройке плагина Jira: Системная консоль → Плагины → Jira.

  4. (Необязательно) Задайте описание и пользовательский запрос JQL, чтобы определить, какие задачи запускают события.

    Информацию о запросах JQL см. в справочной документации Atlassian.

  5. Выберите, при каких событиях в системе отправлять сообщения на каналы Time, затем нажмите Save.

    Поддерживаются следующие события в системе: issues created, issues deleted и issues updated (включая reopened или resolved при смене assignee).

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

  • update_all=1 - все события
  • updated_comments=1 - все события с комментариями
  • updated_description=1 - все события с изменением описания
  • updated_labels=1 - все события с изменением меток
  • updated_priority=1 - все события с изменением приоритета
  • updated_rank=1 - все события с изменением ранга
  • updated_status=1 - все события с изменением статуса
  • updated_summary=1 - изменение названия задачи
  • updated_sprint=1 - все события с изменением спринта

Пример веб-хука, настроенного на получение событий с изменением комментариев: https://example.time-messenger.ru/plugins/jira/webhook?secret=MYSECRET&team=developers&channel=general&updated_comments=1

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

Уведомления Jira — это сообщения, отправляемые на канал Time при возникновении определённого события в Jira. Их можно настроить как подписки на каналы в Time или как веб-хуки в Jira.

Когда из Jira поступает какое-либо событие веб-хука, соответствующее правилу уведомления, оно отправляет уведомление на канал. Если нет совпадений с подпиской, событие веб-хука пропускается.

Дополнительные возможности для системных администраторов Time​

Системные администраторы Time могут использовать следующие команды для управления интеграцией с Jira:

  • /jira instance alias [URL] [ALIAS-NAME] — присвоить псевдоним экземпляру Jira.
  • /jira instance unalias [ALIAS-NAME] — удалить псевдоним у экземпляра Jira.
  • /jira instance list — вывести список всех установленных экземпляров Jira.
  • /jira instance v2 <YOUR-JIRA-URL> — установить экземпляр Jira для обработки устаревших вебхуков и подписок версии "v2".
  • /jira stats — отобразить статистику использования.
  • /jira webhook [--instance=<YOUR-JIRA-URL>] — отобразить вебхук Time.
  • /jira v2revert — вернуть устаревшую модель данных интеграции Jira версии V2.

Использование​

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

Подключение учетной записи Jira к Time​

  1. В Time выполните команду /jira connect в любом канале, чтобы связать свою учетную запись Time с учетной записью Jira.
  2. Перейдите по ссылке в ваш экземпляр Jira и нажмите Allow.
  3. После подключения выполните команду /jira help, чтобы узнать доступные возможности.
подсказка

Отключить учетные записи можно с помощью команды /jira disconnect.

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

Вот некоторые распространенные команды, с которых можно начать:

  • /jira info — отобразить информацию о текущем пользователе и интеграции с Jira.
  • /jira connect [jiraURL] — подключить вашу учетную запись Time к вашей учетной записи Jira.
  • /jira disconnect [jiraURL] — отключить вашу учетную запись Time от вашей учетной записи Jira.
  • /jira issue assign [issue-key] [assignee] — изменить исполнителя задачи Jira.
  • /jira issue create [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​

Используйте команду /jira issue create, чтобы создать задачу в Jira, не покидая Time. Вы можете предварительно заполнить заголовок задачи, выполнив /jira issue create Это заголовок моей задачи.

Изменение состояния задач Jira​

Изменяйте состояние задач, используя команду /jira transition <issue-key> <state>.

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

примечание

Состояния задач зависят от конфигурации рабочего процесса вашего проекта Jira.

Назначение задач Jira​

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

Например, выполнение команды /jira assign EXT-20 john назначит задачу EXT-20 пользователю John.

примечание

Поддерживаются частичные совпадения по именам пользователей.