Интеграция Битрикс24 с Jira

Интеграция Битрикс24 с Jira

Менеджеры ставят задачи в Битрикс24, разработчики работают в Jira. Результат предсказуем: менеджер спрашивает статус в чате, разработчик переключается в Б24 обновить задачу, забывает, менеджер видит устаревшую картину. Или наоборот — PM закрывает issue в Jira, а в Б24 задача висит открытой ещё неделю. Двойной ввод данных — это не просто неудобство, это системная потеря контроля над проектом.

Архитектура синхронизации

Интеграция работает через двунаправленный обмен по REST API обеих систем. Битрикс24 REST API отдаёт и принимает данные по задачам, Jira REST API v3 — по issues. Между ними стоит middleware, который обрабатывает события, трансформирует данные и управляет конфликтами.

Б24 Task (событие) → Webhook → Middleware → Jira REST API → Issue
Jira Issue (событие) → Jira Webhook → Middleware → Б24 REST API → Task

Middleware хранит таблицу маппинга: каждая пара «задача Б24 — issue Jira» связана по ID. При обновлении одной сущности middleware находит парную и обновляет её. Без этой таблицы синхронизация невозможна — ID в системах разные, прямой связи нет.

Маппинг полей

Поля в Б24 и Jira не совпадают по названиям и формату. Настраиваем соответствие:

Конвертация описания — отдельная задача. Б24 хранит описания в HTML, Jira v3 использует Atlassian Document Format (JSON-дерево). Middleware парсит HTML в DOM, преобразует в ADF-ноды (paragraph, text, heading, bulletList) и обратно.

Маппинг статусов

Самая тонкая часть. У каждой команды в Jira свой workflow, а в Б24 — свои стадии задач и кастомные канбан-статусы. Middleware использует конфигурируемую таблицу:

Направление «↔» означает: при изменении статуса в любой из систем парная сущность обновляется. Направление «→» — синхронизация только в одну сторону (обычно для статусов, которых нет в другой системе).

Переход статуса в Jira — это не просто запись значения. Jira требует вызова POST /rest/api/3/issue/{id}/transitions с ID конкретного перехода. Middleware сначала запрашивает доступные transitions для issue, находит нужный и выполняет переход.

Webhook-подписки

Со стороны Б24:

Регистрируем обработчики через event.bind:

• ONTASKADD — новая задача → создание issue в Jira
• ONTASKUPDATE — обновление полей → обновление issue
• ONTASKCOMMENTADD — новый комментарий → комментарий к issue
• ONTASKDELETE — удаление задачи → закрытие или удаление issue (настраивается)

Со стороны Jira:

Webhook через Settings → Webhooks или Jira App:

• jira:issue_created — новый issue → создание задачи в Б24
• jira:issue_updated — обновление полей/статуса → обновление задачи
• comment_created — комментарий → комментарий к задаче Б24

Каждый webhook содержит payload с полным набором данных. Middleware извлекает изменённые поля из changelog.items (Jira) или сравнивает со сохранённым состоянием (Б24, где changelog не предоставляется).

Предотвращение петель

Критическая проблема: Б24 обновляет задачу → middleware обновляет issue → Jira отправляет webhook → middleware обновляет задачу Б24 → бесконечный цикл.

Решение — маркировка источника обновления. Middleware при каждом обновлении записывает флаг в кастомное поле:

• В Б24: UF_SYNC_SOURCE = "jira" при обновлении из Jira
• В Jira: customfield_sync_source = "b24" при обновлении из Б24

Когда middleware получает webhook, он проверяет этот флаг. Если обновление пришло от него самого — пропускает обработку. Флаг сбрасывается через 5 секунд (задача cron).

Синхронизация комментариев

Комментарии синхронизируются в обе стороны с указанием автора:

• Из Б24 в Jira: POST /rest/api/3/issue/{id}/comment с телом {body: {type: "doc", content: [...]}}. В начало добавляется имя автора из Б24.
• Из Jira в Б24: task.commentitem.add с текстом комментария. Имя автора из Jira — в префиксе.

Вложения к комментариям: файлы скачиваются с одной стороны, загружаются на другую. Для Jira — POST /rest/api/3/issue/{id}/attachments, для Б24 — task.commentitem.add с предварительной загрузкой файла на диск.

Первоначальная миграция

Перед включением синхронизации нужно перенести существующие данные. Middleware поддерживает bulk-операции:

1. Выгрузка всех задач из выбранных проектов Б24 через tasks.task.list с пагинацией.
2. Создание issues в Jira через bulk API (POST /rest/api/3/issue/bulk).
3. Заполнение таблицы маппинга ID.
4. Обратная выгрузка issues из Jira, которых нет в Б24, и создание задач.

Миграция запускается однократно. После неё включается real-time синхронизация через webhooks.

Права и безопасность

• Jira API требует OAuth 2.0 (для Cloud) или Personal Access Token (для Server/Data Center). Middleware хранит токены зашифрованными.
• Б24 — OAuth 2.0 с scope task,user. Refresh-токен обновляется автоматически.
• Маппинг пользователей: таблица соответствий Б24 User ID ↔ Jira Account ID. Заполняется по email или вручную.
• Данные задач проходят только через ваш middleware — ни одна из систем не получает прямой доступ к другой.

Что внедряем

• Middleware для двунаправленной синхронизации задач Б24 и issues Jira
• Конфигурируемый маппинг полей, статусов и приоритетов
• Синхронизация комментариев и вложений
• Защита от петель обновления
• Первоначальная миграция существующих задач
• Маппинг пользователей между системами
• Мониторинг и логирование всех операций синхронизации