Інтеграція Bitrix24 та Jira
Менеджери ставлять задачи в Bitrix24, розробники працюють у Jira. Результат передбачуваний: менеджер запитує статус у чаті, розробник переходить у B24 оновити задачу, забуває, менеджер бачить застарілу картину. Або навпаки — PM закриває issue у Jira, а в B24 задача висить відкритою ще тиждень. Подвійний облік даних — це не просто незручність, це системна втрата контролю над проектом.
Архітектура синхронізації
Інтеграція працює через двонаправлений обмін за REST API обох систем. Bitrix24 REST API видає та приймає дані про задачі, Jira REST API v3 — про issues. Між ними стоїть middleware, який обробляє події, трансформує дані та управляє конфліктами.
B24 Task (подія) → Webhook → Middleware → Jira REST API → Issue
Jira Issue (подія) → Jira Webhook → Middleware → B24 REST API → Task
Middleware зберігає таблицю маппінгу: кожна пара «задача B24 — issue Jira» пов'язана за ID. При оновленні однієї сутності middleware знаходить парну та оновлює її. Без цієї таблиці синхронізація неможлива — ID у системах різні, прямої зв'язку немає.
Маппінг полів
Поля в B24 та Jira не збігаються за назвами та форматом. Налаштовуємо відповідність:
| Поле B24 (tasks.task) | Поле Jira (issue) | Примітка |
|---|---|---|
| TITLE | summary | Пряма відповідність |
| DESCRIPTION | description | B24 — HTML, Jira — ADF (Atlassian Document Format). Middleware конвертує |
| RESPONSIBLE_ID | assignee (accountId) | Через таблицю маппінгу користувачів |
| CREATED_BY | reporter | Аналогічно |
| DEADLINE | duedate | Формат дати: B24 — ISO 8601, Jira — YYYY-MM-DD |
| PRIORITY | priority.id | Маппінг значень: 1→Highest, 2→High, 3→Medium |
| STATUS | status.id | Окрема таблиця відповідностей (див. нижче) |
| GROUP_ID (проект) | project.key | Проект B24 → проект Jira |
| UF_* (кастомні поля) | customfield_* | Налаштовується індивідуально |
Конвертація опису — окрема завдання. B24 зберігає описи в HTML, Jira v3 використовує Atlassian Document Format (JSON-дерево). Middleware парсить HTML у DOM, трансформує у ADF-ноди (paragraph, text, heading, bulletList) та назад.
Маппінг статусів
Найтонша частина. У кожної команди в Jira свій workflow, а в B24 — свої стадії задач та кастомні kanban-статуси. Middleware використовує конфігуровану таблицю:
| Статус B24 | Статус Jira | Направлення |
|---|---|---|
| Нова (2) | To Do | ↔ |
| Виконується (3) | In Progress | ↔ |
| Чекає контролю (4) | In Review | B24 → Jira |
| На паузі (6) | On Hold | ↔ |
| Завершена (5) | Done | ↔ |
| — | QA Testing | Jira → B24 (кастомне поле) |
Направлення «↔» означає: при зміні статусу в будь-якій з систем парна сутність оновлюється. Направлення «→» — синхронізація тільки в один бік (зазвичай для статусів, яких немає в іншій системі).
Переход статусу у Jira — це не просто запис значення. Jira вимагає виклику POST /rest/api/3/issue/{id}/transitions з ID конкретного переходу. Middleware спочатку запитує доступні transitions для issue, знаходить потрібний та виконує переход.
Webhook-підписки
З боку B24:
Реєструємо обробники через event.bind:
-
ONTASKADD— нова задача → створення issue у Jira -
ONTASKUPDATE— оновлення полів → оновлення issue -
ONTASKCOMMENTADD— новий коментар → коментар до issue -
ONTASKDELETE— видалення задачи → закриття або видалення issue (налаштовується)
З боку Jira:
Webhook через Settings → Webhooks або Jira App:
-
jira:issue_created— новий issue → створення задачи в B24 -
jira:issue_updated— оновлення полів/статусу → оновлення задачи -
comment_created— коментар → коментар до задачи B24
Кожен webhook містить payload з повним набором даних. Middleware витягує змінені поля з changelog.items (Jira) або порівнює зі збереженим станом (B24, де changelog не надається).
Запобігання петлям
Критична проблема: B24 оновлює задачу → middleware оновлює issue → Jira відправляє webhook → middleware оновлює задачу B24 → нескінченний цикл.
Рішення — маркування джерела оновлення. Middleware при кожному оновленні записує прапор у кастомне поле:
- У B24:
UF_SYNC_SOURCE = "jira"при оновленні з Jira - У Jira:
customfield_sync_source = "b24"при оновленні з B24
Коли middleware отримує webhook, він перевіряє цей прапор. Якщо оновлення прийшло від нього самого — пропускає обробку. Прапор скидається через 5 секунд (задача cron).
Синхронізація коментарів
Коментарі синхронізуються в обидва боки з зазначенням автора:
- З B24 у Jira:
POST /rest/api/3/issue/{id}/commentз тілом{body: {type: "doc", content: [...]}}. На початок додається ім'я автора з B24. - З Jira у B24:
task.commentitem.addз текстом коментаря. Ім'я автора з Jira — у префіксі.
Вкладення до коментарів: файли скачуються з одного боку, завантажуються на інший. Для Jira — POST /rest/api/3/issue/{id}/attachments, для B24 — task.commentitem.add з попередньою завантаженням файлу на диск.
Початкова міграція
Перед включенням синхронізації необхідно перенести існуючі дані. Middleware підтримує bulk-операції:
- Вивантаження всіх задач з вибраних проектів B24 через
tasks.task.listз пагінацією. - Створення issues у Jira через bulk API (
POST /rest/api/3/issue/bulk). - Заповнення таблиці маппінгу ID.
- Зворотна вивантаження issues з Jira, яких немає в B24, та створення задач.
Міграція запускається однократно. Після цього включається real-time синхронізація через webhooks.
Права та безпека
- Jira API вимагає OAuth 2.0 (для Cloud) або Personal Access Token (для Server/Data Center). Middleware зберігає токени зашифрованими.
- B24 — OAuth 2.0 з scope
task,user. Refresh-токен оновлюється автоматично. - Маппінг користувачів: таблиця відповідностей B24 User ID ↔ Jira Account ID. Заповняється за email або вручну.
- Дані задач проходять тільки через ваш middleware — жодна з систем не отримує прямого доступу до іншої.
Що впроваджуємо
- Middleware для двонаправленої синхронізації задач B24 та issues Jira
- Конфігуровану маппінг полів, статусів та пріоритетів
- Синхронізацію коментарів та вкладень
- Захист від петель оновлення
- Початкову міграцію існуючих задач
- Маппінг користувачів між системами
- Моніторинг та логування всіх операцій синхронізації