Налаштування інтеграції Bitrix24 з YouTrack
Розробка вести задачі в YouTrack, коммерчний відділ — в Bitrix24. Клієнт прислав баг-репорт, менеджер створив задачу в Б24, потім йде в YouTrack та створює дублюючий issue. Коли розробник закриває issue, менеджер про це не знає — клієнт отримує відповідь «ще працюємо» на вже виправленну проблему. Два трекери без зв'язки — це подвійна робота та постійне відставання інформації.
Архітектура синхронізації
Інтеграція працює через YouTrack REST API та Б24 REST API. YouTrack надає повнофункціональний API для роботи з issues, проектами, agile-досками та записами часу. Middleware забезпечує двунаправлений обмін.
Б24 (подія задачі) → Webhook → Middleware → YouTrack REST API → Issue
YouTrack (workflow/webhook) → Middleware → Б24 REST API → Задача
YouTrack підтримує два механізми сповіщення зовнішніх систем: Webhooks (Settings → Webhooks) та Workflows (серверні скрипти на JavaScript). Webhooks простіші, але workflows дають більше контролю — можна фільтрувати події за полями, проектами та типами issues.
Маппінг полів
| Поле Б24 (tasks.task) | Поле YouTrack (issue) | Примітка |
|---|---|---|
| TITLE | summary | Пряме відповідання |
| DESCRIPTION | description | Б24 HTML → YouTrack Markdown |
| RESPONSIBLE_ID | Assignee | Через таблицю маппінга користувачів |
| CREATED_BY | Reporter | Аналогічно |
| DEADLINE | Due Date | ISO 8601 у обох системах |
| PRIORITY | Priority | Маппінг значень (див. нижче) |
| STATUS | State | Окрема конфігурація |
| GROUP_ID | Project (shortName) | Таблиця відповідностей |
| UF_* (кастомні) | Custom fields | Індивідуально |
Конвертація описання: Б24 зберігає HTML, YouTrack використовує Markdown (з розширеннями). Middleware конвертує через проміжне AST-подання.
Маппінг статусів
YouTrack використовує state machine — кожен проект має свій набір станів. Middleware підтримує конфігурований маппінг:
| Статус Б24 | State YouTrack | Напрямок |
|---|---|---|
| Нова (2) | Open | ↔ |
| Виконується (3) | In Progress | ↔ |
| Чекає контролю (4) | To Verify | ↔ |
| Завершена (5) | Fixed / Done | ↔ |
| На паузі (6) | Wait | ↔ |
| — | Duplicate | YT → Б24 (коментар) |
| — | Won't Fix | YT → Б24 (закриття + коментар) |
Стани, яких немає в Б24, обробляються особливим чином: middleware додає коментар з поясненням та закриває або приставляє задачу.
Синхронізація учету часу
YouTrack та Б24 обидва ведуть учет затраченого часу. Middleware об'єднує записи:
-
З YouTrack в Б24: При додаванні work item у YouTrack (подія
issue.updated, полеworkItems) middleware створює запис про затрачений час у задачі Б24 черезtask.elapseditem.add. Указує тривалість, дату та коментар. -
З Б24 в YouTrack: При додаванні запису про час в Б24 (подія
ONTASKELAPSEDTIMEADD) middleware створює work item у YouTrack черезPOST /api/issues/{id}/timeTracking/workItems.
Важливо: middleware веде таблицю маппінга записів часу, щоб уникнути дублювання при двусторонній синхронізації. Кожна запис отримує унікальний sync_id.
Інтеграція agile-досок
YouTrack Agile Board відображає issues на kanban/scrum-дошці. Б24 має свій Канбан. Middleware не синхронізує візуальне розташування, але забезпечує:
- Переміщення issue на дошці YouTrack (зміна State) → оновлення статусу задачі в Б24 Канбан.
- Зміна стадії на Канбан-дошці Б24 → оновлення State issue в YouTrack.
- Спринти YouTrack → групи задач або теги в Б24 (через кастомне поле
UF_SPRINT).
Запобігання петлям
Той же принцип, що й в інших інтеграціях: middleware маркує джерело оновлення в кастомному полі обох систем. При отриманні webhook перевіряється маркер — якщо оновлення ініційовано middleware, обробка пропускається.
Аутентифікація
- YouTrack: Permanent Token (Profile → Authentication → New Token). Для Cloud та Server — однаковий механізм. Scope задається через права користувача, від імені якого виданий токен.
-
Б24: OAuth 2.0 з scope
task,user. - Дані проходять тільки через middleware — прямого доступу між системами немає.
Що впроваджуємо
- Middleware для двунаправленої синхронізації задач Б24 та issues YouTrack
- Конфігурований маппінг полів, статусів та пріоритетів
- Синхронізацію учету робочого часу між системами
- Інтеграцію agile-досок YouTrack з Канбан Б24
- Захист від петель оновлення
- Маппінг користувачів та проектів між системами