Коннектор требований

Коннектор связывает пространство с проектом во внешнем трекере: загружает оттуда требования, пишет обратно в тикет ID связанных проверок и вычисленный статус покрытия, принимает события об изменении требований. Один коннектор на пространство.

Какие трекеры подходят

Источником требований может быть один из шести сервисов:

Источник	Что становится требованием	Обратная связь в источнике	Вебхук
Jira Server	задачи проекта	кастомные поля ID проверок и статуса покрытия либо статус workflow	настраивается вручную в Jira
YouTrack	задачи проекта	кастомные поля ID проверок и статуса покрытия	workflow-правило со скриптом из DoQA
Yandex Tracker	задачи очереди	локальные поля очереди, DoQA может создать их сама	триггер, DoQA создаёт его сама
Kaiten	карточки доски	внешние ссылки на проверки и свойство статуса покрытия	настраивается вручную в Kaiten
Яга	задачи проекта	текстовое поле ссылок на проверки, покрытие через статус задачи	нет, только ручное обновление
Confluence Data Center	страницы пространства или раздела	блок «Покрытие DOQA» на странице	нет, только ручное обновление

Jira Cloud, Bitrix24, Redmine и GitLab источником требований быть не могут и в списке «Трекер» не появятся. Если такой трекер всё же попадёт в коннектор, DoQA откажется его сохранить: «Этот трекер не поддерживается модулем требований».

Коннектор не хранит логин и токен: он ссылается на уже существующую интеграцию. Сначала администратор подключает трекер в разделе интеграций: Jira Server, YouTrack, Yandex Tracker, Kaiten, Яга или Confluence Data Center. Только после этого трекер появится в списке коннектора. Подсказка в интерфейсе так и говорит: «Из уже подключённых интеграций-трекеров DoQA».

В списке предлагается по одной интеграции на тип трекера. Если в DoQA заведено несколько подключений к одному трекеру, например к Jira Server, коннектор возьмёт первое из них.

Что нужно подготовить на стороне источника до настройки коннектора, описано на странице каждой интеграции, в разделе «… как источник требований».

Где настраивается

Пространство → «Настройки» в боковом меню → вкладка «Коннектор требований». Страница настроек открывается при правах на редактирование проекта или пространств либо при правах на редактирование тест-кейсов, чек-листов или прогонов в этом пространстве. Из пустого списка требований туда же ведёт кнопка «Настроить коннектор».

Рядом с заголовком «Коннектор требований» — состояние подключения:

Значок	Что означает
«Не настроено»	Коннектор ещё не сохранён.
«Подключено»	Последний обмен с трекером прошёл без ошибок.
«Поле не найдено»	Указанного кастомного поля в трекере нет (трекер ответил HTTP 400). Исправьте поле и сохраните заново.
«Трекер недоступен»	Подключиться к трекеру не удалось; DoQA показывает данные из кэша.

Настройка

Трекер и проект-источник

1. «Трекер» — выберите подключённую интеграцию. Пока трекер не выбран, остальные настройки не показываются: набор полей зависит от интеграции.
2. Откуда брать требования. DoQA подтягивает список из трекера сама, а название поля зависит от трекера:
   • «Проект-источник» — для Jira Server и YouTrack;
   • «Очередь-источник» — для Yandex Tracker;
   • «Доска-источник» — для Kaiten: требованиями станут карточки этой доски;
   • для Confluence — «Пространство Confluence» и «Корневой раздел», см. Особенности Confluence.
3. Запрос-фильтр под списком — «JQL-запрос» для Jira Server, «Запрос YouTrack» для YouTrack, «Запрос Яндекс Трекера» для Yandex Tracker. Работает как дополнительный фильтр внутри выбранного проекта или очереди: например, status = Open. Требования, не попавшие под фильтр, в пространство не загружаются, а уже загруженные уходят в «Архивные записи». У Kaiten и Confluence фильтра нет: загружается всё содержимое доски или раздела.

Если трекер не умеет отдавать схему полей, DoQA переключается в ручной режим и просит ввести ключ проекта и идентификаторы полей строками (появится сообщение «Трекер не поддерживает выбор полей — введите значения вручную»).

Поле для ID кейсов

Кастомное поле трекера, в которое DoQA списком пишет ID связанных проверок. Именно оно делает связь двусторонней: открыв тикет, аналитик видит, какие проверки его покрывают.

Для YouTrack рекомендуемый тип поля — «текст» (одиночное значение). Для Yandex Tracker рекомендуется многозначное строковое поле: тогда каждый ID отображается отдельно.

У Kaiten этой настройки нет: ссылки на связанные проверки DoQA добавляет в карточку как внешние ссылки. У Confluence её тоже нет, ссылки попадают в блок покрытия на странице.

Для Yandex Tracker поле можно не выбирать, а создать: переключатель «Создать автоматически», подробнее — в разделе Особенности Yandex Tracker.

Статус покрытия

DoQA вычисляет состояние покрытия и отражает его в трекере. Настройка «Куда писать статус покрытия» определяет способ:

• «Кастомное поле» (рекомендуется) — статус пишется в отдельное select-поле трекера. Не требует настройки workflow.
• «Системный статус (workflow)» — DoQA двигает тикет по статусам/переходам проекта. Подходит, если в проекте трекера уже настроены нужные статусы и переходы.

Переключатель показывается, только если трекер поддерживает оба варианта, то есть только для Jira Server. YouTrack, Yandex Tracker и Kaiten пишут статус только в кастомное поле. Рекомендуемый тип поля в YouTrack — «перечисление» (одиночное значение), в Kaiten — свойство типа «список» с одиночным выбором. У Confluence секции «Статус покрытия» нет: статус показывается в блоке на самой странице.

При выборе «Кастомное поле» задайте «Поле статуса покрытия» — это отдельное поле, не то же самое, что «Поле для ID кейсов». Без него коннектор не сохранится.

Маппинг статусов покрытия

Таблица сопоставляет пять состояний покрытия DoQA со значениями в трекере. Что подставлять в правую колонку, зависит от выбранной цели. При «Кастомном поле» это опция выбранного поля, при «Системном статусе» — статус или переход workflow. Состояние без сопоставления («— не задано —») в трекер не пишется.

Четыре состояния DoQA пишет в трекер: «Нет тестов», «Все прошли», «Не все прошли», «Не прогонялись». У них в таблице стрелка вправо.

Состояние «Требуется актуализация» — единственное, которое DoQA читает из трекера. У него стрелка влево и подсказка «Этот статус выставляет аналитик в трекере — DoQA слушает его и снимает пометку». Как только значение в трекере совпадает с этим маппингом, DoQA помечает все связанные проверки требования и замораживает запись статуса в трекер до подтверждения актуализации. Подробнее — цикл актуализации.

Если маппинг пуст

Без маппинга «Требуется актуализация» цикл актуализации не запустится: DoQA не поймёт, какой статус в трекере означает «требование изменилось».

Особенности источников

Особенности Yandex Tracker

Поля в задачах Yandex Tracker для загрузки требований не обязательны. Без них ID связанных проверок и статус покрытия останутся только в DoQA, а триггер на изменения создать не получится.

У «Поля для ID кейсов» и «Поля статуса покрытия» есть переключатель «Существующее» / «Создать автоматически». При «Создать автоматически» DoQA после сохранения коннектора сама заводит локальные поля в очереди-источнике, в категории полей DOQA:

• «Связанные кейсы DOQA» — многозначное строковое поле для ID проверок;
• «Статус покрытия DOQA» — поле со списком значений «Нет тестов», «Все прошли», «Не все прошли», «Не прогонялись», «Требуется актуализация». Маппинг статусов покрытия при этом заполняется автоматически.

Пока поля создаются, над формой висит «Создаём поля в трекере», синхронизация станет доступна после завершения. Если создать поля не удалось («Не удалось создать поля»), чаще всего у владельца токена нет прав на категории полей или локальные поля очереди. Выдайте права и нажмите «Повторить».

Особенности Kaiten

• Требования — карточки «Доски-источника». В списке доски показаны в виде «Пространство / Доска».
• Поля для ID кейсов нет. Связанные проверки DoQA добавляет в карточку внешними ссылками с описанием DOQA linked test и убирает ссылку, когда связь снята. Ссылки, добавленные в карточку вручную, DoQA не трогает.
• Статус покрытия пишется в кастомное свойство компании типа «список» с одиночным выбором. Свойство создаётся в Kaiten заранее, см. Kaiten как источник требований.

Особенности Яги

• Требования — задачи «Проекта-источника» Яги. Загрузку можно ограничить фильтром на языке запросов JAWL в поле «Фильтр импорта (JAWL)», например taskStatus = "Сделать".
• Ссылки на связанные проверки DoQA публикует в текстовое поле (тип TEXT с одним значением). Поле необязательно: без него требования загружаются, а ссылки остаются только в DoQA. При «Создать автоматически» DoQA создаёт поле или использует уже созданное и добавляет его во все типы задач проекта.
• Статус покрытия публикуется только через статус задачи Яги по маппингу «Статус задачи Яги». Без соответствия статус задачи не меняется.
• Вебхука нет: изменения загружаются кнопкой «Обновить из трекера».

Подробнее — в разделе Яга как источник требований.

Особенности Confluence

Confluence Data Center — источник требований, а не трекер: требованием становится страница.

1. «Пространство Confluence» — пространство, в котором лежат требования.
2. «Корневой раздел» — всё пространство целиком или страница-раздел. Для раздела требованиями станут все дочерние страницы на любой глубине, сам раздел не импортируется.

Обратная связь устроена иначе, чем у трекеров. Полей ID и статуса покрытия, маппинга и вебхука нет. Вместо них DoQA публикует на каждой странице-требовании управляемый блок «Покрытие DOQA»: статус покрытия («НЕТ ПРОВЕРОК», «НЕ ЗАПУСКАЛИСЬ», «ПРОЙДЕНО», «НЕ ВСЕ ПРОЙДЕНЫ», «ТРЕБУЕТСЯ АКТУАЛИЗАЦИЯ»), число кейсов и чек-листов, ссылки на них (первые 50), ссылки на требование и матрицу покрытия в DoQA. В форме об этом напоминает плашка «Обратная синхронизация включена».

Блок правится только из DoQA: если удалить или изменить его вручную, при следующей публикации DoQA его восстановит. Правка блока не считается изменением требования. Для публикации у владельца токена должно быть право на редактирование страниц.

Изменения страниц DoQA замечает по номеру версии при ручном обновлении.

Вебхуки

Вебхук доставляет в DoQA события «требование изменилось» из трекера, не дожидаясь ручного обновления. Тумблер «Принимать вебхуки» включает приём.

Тумблер выключает коннектор целиком

Несмотря на название, «Принимать вебхуки» — это выключатель всего коннектора, а не только приёма событий. Пока он выключен, DoQA не загружает требования по кнопке «Обновить из трекера», не пишет в трекер ID проверок и статус покрытия и не даёт генерировать тесты по требованию. В «Ленте операций» пропущенные операции будут помечены причиной «Коннектор выключен».

Настраивается вебхук на стороне трекера, и у каждого трекера это делается по-своему. Confluence вебхуки не поддерживает: требования из него обновляются только кнопкой «Обновить из трекера».

Jira Server

DoQA даёт готовый URL вебхука с секретом внутри. Секрет на экране скрыт. Кнопка «Скопировать» кладёт в буфер полный URL вместе с ним. Кнопка «Перевыпустить» выдаёт новый секрет; старый URL сразу перестаёт работать.

Подсказка со шагами открывается кнопкой «?» рядом с полем «Вебхук». В самой Jira: Администрирование → Система → Веб-перехватчики (WebHooks) → Создать.

1. Имя — любое; Статус — Включён.
2. URL — вставьте скопированный из DoQA.
3. События → Проблема: отметьте «обновлено» (и «удалено», если нужно архивировать требования).
4. Не ставьте галочку «Исключить основу»: DoQA принимает JSON-тело.
5. Сохраните.

Внимание

URL содержит секрет. Не публикуйте его. Адрес DoQA должен быть доступен с сервера Jira: для внешней Jira нужен публичный домен или туннель, localhost не подойдёт.

YouTrack

У YouTrack нативных вебхуков нет. Вместо них ставится workflow-правило. Кнопка «Настройка вебхука YouTrack» открывает окно с готовым скриптом: URL, секрет и имя поля статуса покрытия в него уже подставлены. Секрет в URL не передаётся: скрипт отправляет его заголовком.

Кнопка доступна только после сохранения коннектора: до этого DoQA ещё не выдала URL и секрет.

1. Откройте Administration → Workflows.
2. Нажмите New workflow (или выберите существующий) и привяжите его к проекту-источнику требований.
3. Создайте правило (rule) и вставьте скопированный скрипт.
4. Сохраните workflow и убедитесь, что правило включено для нужного проекта.
5. Нажмите «Обновить из трекера» в DoQA, чтобы загрузить текущие требования.

Если поле статуса покрытия не выбрано, скрипт не будет отслеживать изменение покрытия. Окно об этом предупредит.

Без workflow-правила модуль остаётся рабочим: данные синхронизируются по кнопке «Обновить из трекера», вебхук лишь ускоряет обновление.

Yandex Tracker

Вебхук для Yandex Tracker DoQA настраивает сама: после сохранения коннектора она создаёт в очереди-источнике триггер «DoQA requirements sync». Он срабатывает на изменение значения поля статуса покрытия. Поэтому без поля статуса покрытия триггер не создаётся.

Рядом с полем «Вебхук» виден «Статус настройки»: «Ожидает настройки», «Зарегистрирован в трекере», «Активен», «Требуется ручная настройка» или «Ошибка настройки». После ошибки настройку можно повторить кнопкой «Повторить».

Статус «Требуется ручная настройка» означает, что у токена интеграции нет права «Настройки очереди». Тогда триггер создаётся вручную. Форма показывает URL, секрет и готовое тело запроса; кнопка «Создать триггер в очереди» открывает нужную страницу Яндекс Трекера.

1. Название триггера — «DoQA requirements sync».
2. «При условии» — поле статуса покрытия, операция «Значение поля изменилось». Других условий не нужно.
3. «Выполнить действие» — одно действие «HTTP запрос».
4. Метод POST, в «Адрес» — URL из DoQA, авторизация NoAuth.
5. «Тело запроса» — application/json, JSON из DoQA без изменений.
6. «Заголовки» — заголовок X-Webhook-Secret со скопированным секретом. DoQA проверяет его даже при NoAuth.
7. Нажмите «Создать триггер».

Секрет показывается один раз. Если он потерян, нажмите «Получить новый секрет» и обновите заголовок в триггере.

Kaiten

Вебхук Kaiten настраивается вручную, как в Jira Server: DoQA даёт URL с секретом внутри, кнопка «Скопировать» копирует его целиком, «Перевыпустить» выдаёт новый, и старый URL перестаёт работать. Кнопка «Открыть настройку вебхука в Kaiten» ведёт в раздел внешних вебхуков вашей компании.

1. В Kaiten: настройки пространства → «Внешние вебхуки».
2. Создайте вебхук со скопированным из DoQA URL.
3. Отметьте пространства, доски которых служат источниками требований.
4. Добавьте фильтр по событию «Изменение карточки».

DoQA обрабатывает события создания, изменения и удаления карточек. События с других досок пространства приходят, но пропускаются.

Confluence Data Center

Вебхуков у Confluence нет: в Confluence Data Center они регистрируются на весь сервер, а не на пространство. Блока «Вебхук» в коннекторе нет. Под кнопкой обновления написано: «Источник не присылает события об изменениях — требования обновляются только этой кнопкой».

Ручное обновление

Кнопка «Обновить из трекера» в блоке «Ручное обновление» перечитывает требования по фильтру коннектора. Во время работы виден прогресс («Прочитано N из M»), по завершении — сколько требований обновлено. Рядом показывается время последнего обновления или число загруженных требований.

Та же кнопка есть в шапке списка требований.

Лента операций

Под формой коннектора — «Лента операций»: что DoQA отправляла в трекер и что получала оттуда. Индикатор справа показывает «синк в норме» либо число ошибок.

Записи фильтруются по «Статусу» («Все», «OK», «Ошибки», «Пропущено») и «Операции»:

• «Получение» — «Получение требования» (загрузка требований из трекера);
• «Отправка» — «Отправка ID проверок в тикет» и «Отправка статуса покрытия»;
• «Вебхук» — «Принят вебхук об изменении».

Отдельным цветом выделены записи «Актуализация».

Строки со статусом «Пропущено» объясняют, почему DoQA ничего не сделала:

Причина	Что это значит
«Коннектор не настроен»	В пространстве нет коннектора.
«Коннектор выключен»	Приём вебхуков выключен тумблером.
«Заморожено до актуализации»	Требование ждёт подтверждения актуализации. Статус покрытия в трекер не пишется.
«Статус не сопоставлен или переход недоступен»	В маппинге нет значения для этого состояния либо трекер не даёт нужный переход.
«Повторное событие»	Вебхук с тем же событием уже обработан.

Очистка данных требований

Внизу вкладки — «Очистка данных требований». Кнопка «Очистить данные» безвозвратно удаляет из базы все загруженные в это пространство требования и все связи тест-кейсов и чек-листов с ними.

Действие необратимо

Восстановить связи после очистки нельзя. Их придётся расставлять заново вручную. В трекер DoQA при этом ничего не пишет: очистка убирает локальные данные, а не отвязывает проверки в тикетах.

Не удаляются: настройки коннектора, сама интеграция и сами тест-кейсы и чек-листы. После очистки можно синхронизироваться заново.

Кнопка доступна только администраторам проекта, остальным она заблокирована с подсказкой «Действие доступно только администраторам». В диалоге подтверждения кнопка «Удалить» разблокируется через несколько секунд. По завершении DoQA сообщит, сколько требований и связей удалено.

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