Как мы подружили Jira и Telegram
Привет, Хабр! Я — Артем, ведущий специалист в дирекции эксплуатации и развития автоматизированных рабочих мест в Страховом Доме ВСК. Сегодня я вам расскажу о том, как мы подружили Jira и Telegram в нашем проекте «Telegram Bot «Поддержка ВСК».
План повествования:
Введение в работу поддержки и Jira SD
Что такое Telegram‑боты и как с ними работать
Идентификация пользователей
Основы взаимодействия с API Jira
Итоги
ВВЕДЕНИЕ В РАБОТУ ПОДДЕРЖКИ И JIRA SD
Говоря о поддержке, я имею в виду внутреннюю техническую поддержку Страхового Дома ВСК, которая обрабатывает запросы наших сотрудников. Все вопросы, связанные с ИТ продуктами и техническим оборудованием, решаются специалистами техподдержки.
Запросы в поддержку всегда должны где-то храниться. Так их удобнее отслеживать и обрабатывать. В нашей компании для хранения и обработки запросов используется Jira ServiceDesk (далее Jira, Jira SD).
Когда пользователь (далее будем называть его инициатором) обращается в поддержку, его обращение фиксируется в виде заявки. В нашей компании для создания заявок предусмотрено несколько каналов:
Пользовательский портал
Почтовый ящик
Горячая линия поддержки
Используя любой из этих каналов, инициатор может создать заявку и ожидать её решения.
Важно отметить, что все три канала позволяют однозначно идентифицировать инициатора: за счет этого, инициатор всегда может получить актуальные данные по своим заявкам, а исполнители могут связаться с инициатором.
Постановка проблемы
Создать заявку, проверить её статус, получить уведомления — весь этот функционал доступен только с рабочего места сотрудника. Как только сотрудник ушёл домой или потеря доступ к рабочему компьютеру — связь с поддержкой теряется (не считая горячей линии, которая не занимается уведомлениями).
Особенно эти ограничения сказываются на сотрудниках, работающих в разных часовых поясах. Например, когда сотрудник из Хабаровска заканчивает рабочий день, поддержка из Москвы только выходит на работу. Поэтому обо всех изменениях в своих заявках сотрудник из Хабаровска узнает только на следующий день, когда придёт на работу.
Для решения этой проблемы мы создали сервис, позволяющий создавать заявки, отслеживать их статусы, добавлять комментарии и получать уведомления через Telegram. Используя этот сервис, инициаторы могут оперативно узнать о решении своего запроса или о том, что специалисту поддержки требуется дополнительная информация.
ЧТО ТАКОЕ TELEGRAM-БОТЫ И КАК С НИМИ РАБОТАТЬ
Для решения нашей задачи отлично подошли Telegram-боты!
Разница между аккантом обычного пользователя и бота заключается в том, что боты не могут существовать отдельно от пользователей. И пользовательские аккаунты взаимодействуют с Telegram через Telegram API, а аккаунты ботов — через Telegram Bot API.
Для создания ботов используется главный бот BotFather. Он создаёт аккаунт бота и передаёт токен авторизации пользователю-владельцу. Программу бота обычно размещают на сервере, где он крутится 24/7, выполняя заложенный в него функционал.
Для примера работы бота расскажу про два основных процесса: отправка сообщения от имени бота пользователю Telegram и получение информации о каком-либо действии пользователя в чате.
Отправка сообщения
Для отправки сообщения нужны следующие данные:
Запрос к Bot API выглядит следующим образом:
https://api.telegram.org/bot{token}/sendMessage? chat_id={chat_id}text={text}
А схема процесса выглядит так:
Под «дополнительными данными» я имею в виду клавиатуры, форматирование текста, форматирование ссылок и прочее.
Отслеживание действий в чате
Когда пользователь совершает какое-либо действие в Telegram, регистрируется событие. На эти события могут реагировать участники чата (в том числе и боты). Например, подписка на канал — это событие. Отправка сообщения — тоже событие. Нажатие кнопки — событие. И так далее.
Информация о событиях хранится на серверах Telegram. Для того, чтобы бот мог реагировать на эти события — нужно запросить их и своевременно обновлять. Для этого существуют два инструмента: Webhook и Polling.
Webhook (далее вебхук) требуется развернуть на сервере отдельно от бота. У Telegram есть определенные требования к конфигурации таких серверов, нужно это учитывать. После развертывания, вебхук нужно зарегистрировать. После этого Telegram будет обращаться к нашему вебхуку при возникновении событий, которые нас интересуют (например, событий в чате с нашим ботом).
Polling — метод попроще. Это процесс, при котором наш сервис сам будет опрашивать Telegram, чтобы узнать о наличии новых событий. Например, раз в 2 секунды приходит в Telegram и запрашивать изменения за последнее время, после его самостоятельно их разбирать.
В любом случае, получив информацию об определенном событии, бот может как-либо отреагировать (например, отправить сообщение в ответ или запустить какой-то внутренний процесс).
Схема будет выглядеть вот так:
Подробнее о создании ботов и взаимодействии с ними можно узнать на бесплатных ресурсах, например на Stepik: https://stepik.org/course/120924/syllabus в курсе Михаила Крыжановского или на GitHub пользователя MasterGroosha: https://github.com/MasterGroosha/aiogram-2-guide
Это не единственные источники, но на мой взгляд — самые удобные для начинающих администратором Telegram-ботов.
ИДЕНТИФИКАЦИЯ ПОЛЬЗОВАТЕЛЕЙ
Как я писал выше, при создании заявок в Jira SD всегда однозначно идентифицируется инициатор. Заявка связывается с учетной записью сотрудника компании. Поэтому специалистам доступна расширенная информация об инициаторе (например, специалист может узнать, в каком филиале работает сотрудник, увидеть адрес его почты или корпоративный номер телефона для связи).
Если мы хотим создать дополнительный канал создания и мониторинга заявок через Telegram, то нам нужно научиться определять, кто именно нам пишет. Telegram беспокоится об анонимности своих пользователей, поэтому встроенными методами узнать о том, кому принадлежит аккаунт нельзя. Но, для создания заявок, нам обязательно нужно быть на 100% уверенными, что человек, находящийся по ту сторону экрана — сотрудник компании.
Для решения этой задачи мы введи систему регистрации. Наш бот общается только с зарегистрированными пользователями.
Для регистрации бот отправляет код авторизации на корпоративную почту сотрудника. Если пользователь возвращает код боту, то мы создаём у себя связь между Telegram-аккаунтом пользователя и учетной записью сотрудника. Разумеется, эта информация доступна только нашему сервису и нигде не публикуется.
Пример: есть человек (пусть его будут звать Алмазов Артём). У него есть Telegram-аккаунт Abrikos_2022. Кроме того, Артём работает в Страховом Доме ВСК под логином AlmazovA. После прохождения регистрации, на сервере будет сохранена связь: TelegramID аккаунта Abrikos_2022 → ID учетной записи AlmazovA. И всегда, когда пользователь Abrikos_2022 будет делать что-то в боте, мы будем считать, что эти действия делает сотрудник под логином AlmazovA.
Схема выглядит вот так:
ОСНОВЫ ВЗАИМОДЕЙСТВИЯ С API JIRA
Для создания заявок и получений информации по ним нам требуется настроить взаимодействие между нашим сервисом и Jira SD. Самый простой и удобный способ для этого — работа API.
Информацию о методах работы с Jira доступна на странице https://docs.atlassian.com/.
Для работы с Jira через API требуется пройти авторизацию. Для этого нам завели отдельного пользователя (специально под нашу систему) и наделили его нужными правами.
Получив все доступы, можно отправлять запросы на создание заявок/получение информации о заявке. Шаблон запроса выглядит вот так:
https://jira.vsk.ru/rest/api/2/{method_name}
Используя запросы через API можно:
Создать заявку (в том числе и от имени какого-либо пользователя)
Добавить комментарий
Изменить статус заявки
Выгрузить информацию о заявке
ИТОГИ
Соберем воедино всё, что было описано выше. Цель — пользователи могут взаимодействовать с Jira SD через Telegram.
Заводим бота в Telegram при помощи BotFather.
Пользователи, которые нам пишут должны проходить регистрацию через корпоративную почту. Результат — сервис может соотносить Telegram-аккаунт с учетной записью сотрудника.
Настраиваем взаимодействие с Jira. Результат — сервис может работать с Jira через API.
Настраиваем взаимодействие с Telegram для того, чтобы сервис мог отправлять пользователям сообщения и реагировать на действия пользователей.
Общий результат следующий: мы создали сервис, при помощи которого сотрудники могут создавать заявки, проверять их статус, писать комментарии, а также получать уведомления. Сотрудникам обеспечена оперативная и качественная поддержка, а специалисту поддержки легче получить дополнительную информацию и работать!