Jira и Keepr: задачи приходят сами, время уходит в ворклоги
Что делает интеграция
Одна интеграция связывает Jira с одним проектом Keepr. Входящее направление: задача, созданная в Jira, становится задачей в проекте Keepr; перевод в любой статус категории Done архивирует её, выход из этой категории восстанавливает, а удаление задачи Jira архивирует задачу Keepr. Keepr смотрит на категорию статуса, а не на его название, поэтому собственные рабочие процессы не требуют настройки.
Исходящее направление: Keepr записывает отслеженное время ворклогами. Когда запись времени на задаче, связанной с задачей Jira, сохраняется впервые, Keepr создаёт ворклог в задаче; при изменении записи он обновляет этот ворклог, а при удалении — удаляет. Отправляется только время из проекта Keepr этой интеграции. Keepr отправляет точные секунды; Jira Cloud хранит ворклог в целых минутах с округлением вниз и не принимает ворклог короче минуты.
Рекомендуем для Jira Cloud: приложение Keepr для Jira
В Jira Cloud подключайте интеграцию через приложение Keepr для Jira, когда это возможно. Оно заменяет и вебхук, и API-токен: никто не вставляет секрет в администрирование Jira, не нужно выделять для Keepr отдельную учётную запись Jira, а события задач и ворклоги приложение передаёт само. Jira Data Center и Server приложение запустить не могут, поэтому для них — вебхук, как в шагах ниже.
Создайте интеграцию: Jira, Cloud и способ подключения «Приложение Keepr для Jira» — Keepr выбирает его сам — и скопируйте код подключения, который покажет Keepr. Код показывается один раз, срабатывает один раз и действует 24 часа; «Новый код подключения…» в разделе «Ключи доступа» интеграции выпускает другой.
Администратор сайта Jira устанавливает приложение Keepr для Jira (как установить — в руководстве «Настройка панели таймера Keepr в Jira») или обновляет его и принимает новые разрешения в разделе «Приложения → Управление приложениями»: среди них запись ворклогов. Затем в Jira откройте Настройки → Приложения → Keepr, вставьте код, при желании ограничьте его отдельными проектами Jira, например ABC, и нажмите «Подключить». Без ограничения задачи всех проектов сайта станут задачами в одном проекте Keepr. Раздел «Ключи доступа» интеграции после этого покажет, когда и к какому сайту подключилось приложение.
Автор ворклогов, записанных через приложение, — приложение Keepr, а в комментарии назван участник Keepr, который отследил время. Запись от имени учётной записи Jira каждого участника запланирована. Самой интеграции тариф Ultimate не нужен — он нужен только персональным токенам панели таймера. Всё остальное — три действия с задачами, сопоставление задач, что и когда отправляется — работает так, как описано ниже.
Интеграцию на вебхуке можно перевести: «Перейти на приложение…» на её странице удаляет сохранённый API-токен и показывает код подключения. Оставьте вебхук Jira, пока приложение не подключено, затем удалите его. Обратный переход отключает приложение и показывает новый секрет для вебхука Jira.
Перед началом
В Keepr нужно быть владельцем или администратором организации либо менеджером рабочего пространства, в котором лежит проект. Интеграции есть на всех тарифах: на Free одновременно работает одна, на Team — три, на Ultimate, включая пробный период, — сколько нужно.
В Jira нужны права администратора Jira: вебхуки настраиваются для всего сайта. Поддерживаются Jira Cloud и Jira Data Center или Server; редакцию выбирают при создании интеграции, потому что они по-разному подписывают доставки и по-разному входят.
Jira в собственной сети должна обращаться к по HTTPS (исходящие соединения, порт 443), а Keepr — к ней через публичный интернет, чтобы записывать время. VPN и ретрансляторы не поддерживаются.
1. Создайте интеграцию в Keepr
Откройте «Настройки организации» → «Интеграции» и нажмите «Новая интеграция». Выберите Jira и её редакцию — Cloud или Data Center, проект Keepr, в который пойдут задачи, и имя, от которого интеграция действует: в Keepr её действия выглядят, например, как «Архивировано: Jira · Сайт».
После этого Keepr один раз покажет секрет подписи вебхука. Скопируйте его, прежде чем закрыть окно: потом видны только первые символы. Если секрет потерян, смените его на странице интеграции и вставьте новый в Jira.
2. Добавьте вебхук в Jira
Jira Cloud: откройте Settings → System → WebHooks по адресу и нажмите «Create a WebHook». Вставьте адрес из раздела «Входящие вебхуки» интеграции в URL, секрет подписи — в Secret, и в Events отметьте Issue created, updated и deleted.
Вебхуки Jira охватывают весь сайт, поэтому ограничьте этот вашим проектом фильтром JQL, например . Без фильтра задачи всех проектов станут задачами одного проекта Keepr.
Data Center и Server: откройте Administration → System → WebHooks по адресу . В Jira 11.0 и новее есть поле Secret — вставьте секрет туда. Более старые версии и Server не умеют подписывать доставки, поэтому добавьте к URL и секрет. Keepr принимает такой токен только от интеграции Data Center и только для неподписанной доставки.
3. Решите, от чьего имени записывается время
Jira записывает автором каждого ворклога учётную запись, чьи данные использует Keepr, поэтому в отчётах Jira всё время команды числится за ней. В комментарии к ворклогу назван участник Keepr, который его отследил. Запись от имени учётной записи каждого участника запланирована; до тех пор используйте для Keepr отдельную учётную запись Jira, а не личную.
Этой учётной записи нужно видеть проект, записывать работу в его задачи, а также менять и удалять свои ворклоги — разрешения Browse projects, Work on issues, Edit own worklogs и Delete own worklogs. В Cloud ей, как любому пользователю, нужна лицензия Jira.
Jira Cloud входит по адресу электронной почты учётной записи и API-токену. Войдя под этой учётной записью, создайте токен в Atlassian account → Security → API tokens; с ним Keepr обращается к REST API v3.
Data Center и Server входят по персональному токену доступа. Войдя под этой учётной записью, создайте его в Profile → Personal Access Tokens по адресу ; Keepr передаёт его как Bearer-токен в REST API v2.
4. Укажите в Keepr адрес и учётные данные
На странице интеграции откройте «Ключи доступа» и нажмите «Задать…» рядом с ключом доступа Jira. Для Cloud адрес Jira — ; можно вставить любую страницу сайта, Keepr сохранит адрес сайта. Для Data Center — HTTPS-адрес вашей Jira вместе с путём контекста, если он есть, например /jira; адрес atlassian.net относится к Cloud и здесь не принимается. Для Cloud укажите и адрес электронной почты учётной записи, и API-токен; Data Center нужен только персональный токен доступа.
Keepr хранит учётные данные в зашифрованном виде и потом показывает только их первые символы. Смена редакции удаляет сохранённые учётные данные — Cloud и Data Center входят по-разному, — поэтому задайте новые в том же шаге.
Что отправляет Keepr
Запись отправляется, когда она завершена — идущий таймер ничего не отправляет, пока не остановится, — и только если её задача лежит в проекте интеграции и ссылается на задачу этой Jira: или страницу доски или бэклога с открытой задачей (), в любом регистре букв. Так связаны задачи, созданные интеграцией, и задачи, запущенные из расширения для браузера на задаче Jira.
Ворклог содержит начало записи, её длительность (в Cloud — в целых минутах с округлением вниз) и комментарий с участником; Cloud пишет комментарий в формате документов Atlassian, Data Center — простым текстом. Изменение обновляет тот же ворклог, удаление записи удаляет его, а перенос записи на другую задачу переносит туда и ворклог.
Импортированное время — это история, и оно не отправляется. Список «Недавно отправлено» на странице интеграции показывает последние записи: объект, участника, сколько времени отправил Keepr и удалась ли последняя отправка; у неудачной строки написано, почему и что делать.
Пауза, смена секрета и отзыв
Переключатель на странице интеграции выключает её без потери данных. Пока она выключена, доставки записываются, но не выполняются (Jira их не повторяет, так что изменения в Jira за это время не догоняются), а время не отправляется: запись, сохранённая во время паузы, уйдёт при следующем её изменении. Повторное включение снова занимает место в лимите тарифа.
«Заменить…» в разделе «Ключи доступа» сразу заменяет секрет вебхука, без переходного периода: доставки не проходят, пока новый секрет не окажется в Jira. «Удалить» рядом с ключом доступа Jira выключает отправку времени и не трогает входящее направление.
Отзыв окончателен. Keepr уничтожает оба секрета и больше ничего не выполняет; интеграция остаётся в списке как история, а её действия — подписанными её именем в журнале аудита и на архивных задачах. Отзовите токен и в Jira.
Если вебхук добавить нельзя
Если вебхук добавить не получается — нет администратора Jira или Jira не может достучаться до Keepr, — задачи может создавать правило Automation через REST API. Ему нужен персональный API-токен, а он входит в тариф Ultimate: создайте его в разделе API-токены с областью timers:write. В Cloud правила находятся по адресу или в Project settings → Automation проекта; в Data Center есть Automation for Jira с тем же триггером и действием.
Используйте триггер «Work item created» («Issue created» в Data Center) и действие «Send web request»: метод POST на , заголовок Authorization со значением «Bearer» и токеном и собственное тело JSON с externalKey , name , url и вашим projectId. Keepr возвращает существующую задачу или создаёт её, с опоставляя так же, как при вебхуке.
Чтобы архивировать задачу по Done, правило на «Work item transitioned» («Issue transitioned») делает тот же запрос, с отметкой «Delay execution of subsequent rule actions until we've received a response», а затем вызывает с вместо id задачи — для этого нужна область projects:write. Все поля описаны в справочнике API на api.keepr.ru/docs. Ворклогам вебхук не нужен: они работают в обоих случаях, когда заданы адрес и учётные данные.
Если что-т о пошло не так
Каждая доставка, которую получил Keepr, видна в последних доставках интеграции вместе с тем, что с ней сделано. Если там пусто, запрос Jira не дошёл: проверьте URL вебхука, в Data Center — значение ?token=, и может ли ваша Jira обратиться к . Смена статуса внутри одной категории — из To Do в In Progress — записывается и ничего не делает; архивирует или восстанавливает только вход в Done или выход из него.
В списке «Недавно отправлено» «Не заданы адрес или ключ доступа» значит, что у интеграции ещё нет адреса или ключа Jira. «Ключ доступа отклонён» — Jira не приняла API-токен или персональный токен доступа: он отозван или истёк, адрес почты в Cloud не совпадает с учётной записью токена или учётная запись потеряла доступ — в Data Center сюда же относится отсутствие разрешения Work on issues. «Задача не найдена» — задача удалена или учётная запись её не видит, «Адрес не разрешён» — адрес Jira не публичный HTTPS. «Сервис отказал» — Jira не приняла сам ворклог: учёт времени выключен, а в Cloud ещё запись короче минуты или учётная запись без разрешения Work on issues; «Сервис недоступен, повторим» проходит само, когда Jira снова отвечает.
Отправка, завершившаяся окончательной ошибкой, повторяется при следующем изменении записи.