Как мы подружили 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.

1. Заводим бота в Telegram при помощи BotFather.

2. Пользователи, которые нам пишут должны проходить регистрацию через корпоративную почту. Результат – сервис может соотносить Telegram-аккаунт с учетной записью сотрудника.

3. Настраиваем взаимодействие с Jira. Результат – сервис может работать с Jira через API.

4. Настраиваем взаимодействие с Telegram для того, чтобы сервис мог отправлять пользователям сообщения и реагировать на действия пользователей.

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