Русский
Русский
English
Статистика
Реклама

Как мы обрабатываем жалобы пользователей с помощью JIRA (REST API)


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


Все жалобы пользователей должны где-то храниться, быть приоритезированы, удобно отслеживаться, и, более того, должны быть вовремя обработаны. Но не всегда есть возможность выделить достаточно ресурсов на разработку и поддержание подобной системы, ведь всегда найдется задача в бэклоге с более высоким приоритетом. Ниже я расскажу, как мы достаточно эффективно и быстро решили эту задачу в Uxcel используя JIRA REST API.


Для чего нам Report a problem?


Добавим немного контекста для чего мы предоставляем функционал жалоб и что нам нужно?
Uxcel веб-сервис для обучения UI/UX в игровой форме. Обучающим элементом у нас является Практика в большинстве случаев это 2 изображения, где одно верное, а другое нет. Что позволяет натренировать глаз находить недочеты даже в визуально идентичных элементах. Каждая практика помимо изображений имеет подсказку (hint наводку на верный ответ) и описание (description) с теорией, касающейся данной задачи.



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



Чтобы не изобретать велосипед со своими бордами, тикетами и backlog-ом, а также чтобы хранить все задачи команд в одной системе и даже в общих спринтах, было решено для этих целей использовать JIRA + REST API.


Организация тикетов в JIRA


Для каждой практики у которой есть хотя бы 1 жалоба создается BUG в JIRA в выделенном эпике Practices Reports. А сами жалобы хранятся в виде комментариев к соответствующим багам-практикам. В дополнение к этому, для разных видов практик добавляется Label (в нашем случае такие как: Course, Gym, UEye). Общая логика представлена на схеме ниже:



Таким образом, контент-команда выбирает наиболее приоритетные практики (в виде багов) для исправления в каждом спринте.


А теперь давайте взглянем на технические подробности реализации.


Интеграция с JIRA REST API


Первым делом нужно создать API token в JIRA, чтобы получить доступ к JIRA API. Для использования на продакшене рекомендую создать отдельного пользователя от имени которого и будут создаваться тикеты, иначе придется отбиваться от постоянных уведомлений, в то время как для отдельного пользователя их проще сразу все отключить.


Получение API токена:




  • Задаем имя токена -> нажимаем Create


Готово. Сохраняем куда-нибудь созданный токен, терять его нельзя.


Теперь можно выполнять API запросы к JIRA. В каждый запрос передается заголовок, содержащий емейл (пользователя для которого был создан токен) и сам токен их передаем посредством реализации HTTP basic authentication.


Пример кода (весь код на TypeScript для NodeJS):


private generateAuthHeader(): string {    // конвертируем строку email:apiToken в Base64    const basicAuthValue = Buffer.from(`${this.jiraEmail}:${this.jiraApiToken}`).toString('base64');     return `Basic ${basicAuthValue}`;}

Примечание: для хранения ключей и паролей мы используем AWS Secrets Manager. Прямо в коде такие данные хранить не безопасно. Больше информации тут.

Создание бага через API


Осталось совсем немного подготовки. Для того чтобы создать баг, нам нужно знать его Issue ID в JIRA. Один из способов его узнать вызвать GET запрос на получение информации обо всех типах:


GET https://{id}.atlassian.net/rest/api/3/issuetype 

Поскольку это разовая операция, то чтобы не писать код можно воспользоваться Postman:



Во вкладке Authorization выбираем Type: Basic Auth, вводим email и api token.


В ответе нас интересует эта часть:


{    "self": "https://{id}.atlassian.net/rest/api/3/issuetype/10004",    "id": "10001",    "description": "A problem or error.",    "iconUrl": "https://${id}.atlassian.net/secure/viewavatar?size=medium&avatarId=10303&avatarType=issuetype",    "name": "Bug",    "untranslatedName": "Bug",    "subtask": false,    "avatarId": 10303}

После того как узнали Issue Id типа BUG (10001) нам нужно узнать Project Id, к которому баг будет принадлежать. Похожим образом можем получить список всех проектов и найти id нужного.


Для этого делаем GET запрос на


GET https://{id}.atlassian.net/rest/api/3/project/search

И последний подготовительный шаг: как я выше упоминал, мы храним баги в отдельном эпике (Jira Epic). Его id знать не обязательно, достаточно скопировать его Key (расположен перед названием эпика, либо в адресной строке, например UX-1).


Все готово к созданию первого бага через API.


Я использовал npm пакет Got для создания HTTP запросов для NodeJS.

await got.post({    url: `${this.jiraApiHost}/issue`, // jiraApiHost = https://{id}.atlassian.net/rest/api/3    headers: {        Authorization: authorization, // созданный Basic Auth Header в методе generateAuthHeader        'Content-Type': 'application/json'    },    responseType: 'json',    json: {        update: {},        fields: {            issuetype: { id: this.jiraBugTypeId }, // полученный id типа BUG (пример - 10001)            project: { id: this.jiraPracticeReportProjectId }, // id проекта (пример - 10005)            parent: { key: this.jiraPracticeReportEpicKey }, // ключ Epic (пример - UX-1)            summary: practiceTicketName, // имя практики формата -  [practiceId] practiceName (#reports)            labels: [practice.label]        }    }});

API Reference


Баг создан. Далее рассмотрим остальные методы необходимые для настройки полного цикла обработки жалоб и ведения их в JIRA, такие как: Поиск, Обновление статуса, Обновление информации, Добавление комментария к багу.


Поиск бага через API


Поиск бага является первоначальной операцией в API обработки пользовательской жалобы. Необходимо убедиться, что для обжалованной практики не существует тикета, только в этом случае создаем его.


Пример кода:


// формируем JQL запрос, ищем по типу BUG в эпике где хранятся жалобы по id практики (которое есть в названии каждого бага)const jql = `issuetype = Bug AND project = CNT AND parent = ${this.jiraEpicKey} AND text ~ "${practiceId}" order by created DESC`; const response = await got.get({    url: `${this.jiraApiHost}/search?jql=${jql}`,    headers: {        Authorization: authorization    },    responseType: 'json'});const practiceJiraTicket = response.body['issues'] && response.body['issues'][0];

API Reference


В случае если для практики баг найден, нужно обновить его статус, если проблема была решена и баг находился в статусе CLOSED.


Обновление статуса бага через API


Чтобы обновить статус, воспользуемся Transitions. Но для этого нужно узнать Status ID для TODO / OPENED статуса (статус зависит от настроек JIRA).


Возвращаемся к Postman:


GET https://{id}.atlassian.net/rest/api/3/project/{projectIdOrKey}/statuses

По id проекта получаем все статусы, находим статус, который указывает на открытое состояние тикета и сохраняем его id.


Запрос на перевод бага в открытый статус:


await got.post({    url: `${this.jiraApiHost}/issue/${practiceJiraTicket.key}/transitions`, // где practiceJiraTicket - найденный объект бага    headers: {        Authorization: authorization,        'Content-Type': 'application/json'    },    responseType: 'json',    json: {        transition: {            id: this.jiraToDoStatusId // id статуса полученного выше (пример - 10006)        }    }});

API Reference


Следующий шаг после перевода найденного бага в открытое состояние обновление названия (а если нужно, то и описания либо приоритета).


Обновление названия бага через API


Названия багов должны отражать текущее состояние проблемы, помимо id и названия практики в названии бага можно хранить и статистику для более удобного поиска и просмотра открытых жалоб на борде. Под статистикой в нашем случае подразумевается количество жалоб на данную практику и процент верных ответов. Так, если у практики число верных ответов достаточно низкое либо же число жалоб больше n можно повышать приоритет.


Код вызова API для обновления бага:


await got.put({    url: `${this.jiraApiHost}/issue/${practiceJiraTicket.key}`,    headers: {        Authorization: authorization,        'Content-Type': 'application/json'    },    responseType: 'json',    json: {        update: {            summary: [{ set: newPracticeTicketName }]        }    }});

API Reference


Далее добавим детали самой жалобы в виде комментария к уже подготовленному багу.


Добавление комментария через API


Каждая жалоба пользователя хранится в виде комментария к багу-практике.


Код создания комментария:


await got.post({    url: `${this.jiraApiHost}/issue/${practiceJiraTicket.key}/comment`,    headers: {        Authorization: authorization,        'Content-Type': 'application/json'    },    responseType: 'json',    json: comment // подробности о формировании объекта ниже});

API Reference


Объект comment формируется в виде Atlassian Document Format.
На сайте так же есть Builder, который значительно упрощает генерацию объекта: просто форматируем текст под свои нужды в редакторе при этом параллельно создается итоговый JSON объект.


Готово! Теперь можно принимать, хранить, обрабатывать, закидывать в спринты и удобно искать жалобы пользователей используя JIRA.


Как у нас выглядят жалобы в виде комментариев:



Итоговый вид нашего списка багов в JIRA (название содержит id, #N число жалоб, % верных ответов):



Дальше все зависит от вашей фантазии и требований. Например, можно:


  • реализовать асинхронную обработку жалоб, чтобы пользователь не ждал пока пройдет вся цепочка запросов к JIRA (у нас реализовано средствами AWS SNS)
  • добавить поле priority для багов и менять приоритет в зависимости от числа жалоб для более удобной фильтрации в борде
  • дополнительно информировать модераторов в Slack при появлении новой жалобы со ссылкой на созданный баг (slack/webhook пакет очень прост в интеграции)
  • настроить JIRA Webhooks, чтобы при закрытии бага автоматически рассылать уведомления всем пользователям, которые жаловались на практику с благодарностью за участие в улучшении продукта
  • автоматически назначать баг на автора контента, на который поступила жалоба.

Всем спасибо за внимание! Надеюсь, статья была для вас полезной :)
С радостью отвечу на ваши вопросы!

Источник: habr.com
К списку статей
Опубликовано: 09.07.2020 08:06:27
0

Сейчас читают

Комментариев (0)
Имя
Электронная почта

Atlassian

Javascript

Node.js

Программирование

Разработка веб-сайтов

Web-разработка

Поддержка пользователей

Веб-дизайн

Nodejs

Jira

Support team

Ux/ui

Категории

Последние комментарии

© 2006-2020, personeltest.ru