Коннектор Jira

Подключите ваш инстанс Jira Cloud к Brevo для отслеживания задач, ориентированных на клиентов, видимости тикетов поддержки и уведомлений о вехах проекта через Tajo.

Обзор

Возможности

• Синхронизация событий задач, пересылка событий создания, обновления и решения задач в хронологию контактов Brevo
• Отслеживание тикетов клиентов, связывание задач Jira с контактами Brevo для видимости поддержки
• Оповещения о вехах проекта, запуск кампаний Brevo при выпуске версий и завершении спринтов
• Данные о загруженности команды, синхронизация метрик рабочей нагрузки для операционных дашбордов
• События изменения статуса, отслеживание переходов рабочего процесса задач как событий Brevo
• Синхронизация комментариев, пересылка комментариев, видимых клиентам, в журналы активности Brevo

Предварительные требования

Прежде чем начать, убедитесь, что у вас есть:

1. Инстанс Jira Cloud (Jira Software, Jira Service Management или Jira Work Management)
2. Права администратора для создания OAuth-приложений или генерации API-токенов
3. Email аккаунта Atlassian, связанный с вашим API-токеном
4. Аккаунт Brevo с доступом к API
5. Аккаунт Tajo с активной подпиской

Аутентификация

Jira Cloud поддерживает несколько методов аутентификации.

Вариант 1: OAuth 2.0 (3LO), рекомендуется

1. Перейдите на developer.atlassian.com
2. Нажмите Create > OAuth 2.0 integration
3. Укажите URL обратного вызова: https://app.tajo.io/callbacks/jira
4. Добавьте следующие scope:

read:jira-work
read:jira-user
write:jira-work
read:me

Структура URL API для OAuth 2.0:

https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/{resource}

Вариант 2: API Token (Basic Auth)

1. Перейдите на id.atlassian.com/manage/api-tokens
2. Нажмите Create API token
3. Назовите токен “Tajo Integration”

# Basic Auth: email как имя пользователя, API token как пароль
curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \
  -u "[email protected]:$JIRA_API_TOKEN" \
  -H "Accept: application/json"

Подключение к Tajo

# Используя OAuth 2.0
tajo connectors install jira \
  --client-id $JIRA_CLIENT_ID \
  --client-secret $JIRA_CLIENT_SECRET \
  --cloud-id $JIRA_CLOUD_ID

# Используя API Token
tajo connectors install jira \
  --site-url your-domain.atlassian.net \
  --email [email protected] \
  --api-token $JIRA_API_TOKEN

Конфигурация

Базовая настройка

connectors:
  jira:
    enabled: true
    site_url: "your-domain.atlassian.net"
    auth_type: "oauth2"  # or "basic"

    sync:
      issues: true
      projects: true
      users: true
      comments: true
      worklogs: false

    projects:
      - key: "SUPPORT"
        sync_to_list: 22
      - key: "PRODUCT"
        sync_to_list: 23

    issue_types:
      - Bug
      - Story
      - Task
      - Support Request

Сопоставление полей

Сопоставьте поля задач и пользователей Jira с атрибутами Brevo:

field_mapping:
  # User fields
  accountId: JIRA_ACCOUNT_ID
  emailAddress: email
  displayName: FIRSTNAME

  # Issue fields mapped to contact events
  issue_key: LAST_TICKET_KEY
  issue_status: LAST_TICKET_STATUS
  issue_priority: LAST_TICKET_PRIORITY
  issue_created: LAST_TICKET_DATE
  resolution: LAST_TICKET_RESOLUTION

Эндпоинты API

Tajo интегрируется со следующими эндпоинтами Jira Cloud REST API v3:

Примеры кода

Инициализация коннектора

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('jira', {
  clientId: process.env.JIRA_CLIENT_ID,
  clientSecret: process.env.JIRA_CLIENT_SECRET,
  cloudId: process.env.JIRA_CLOUD_ID
});

Синхронизация задач поддержки

// Синхронизация задач поддержки Jira с контактами Brevo
await tajo.connectors.sync('jira', {
  type: 'incremental',
  resources: ['issues'],
  jql: 'project = SUPPORT AND updated >= -24h',
  batchSize: 50
});

const status = await tajo.connectors.status('jira');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T12:00:00Z',
//   issuesTracked: 4560,
//   projectsMonitored: 3,
//   usersLinked: 890
// }

Обработка вебхуков Jira

app.post('/webhooks/jira', async (req, res) => {
  const event = req.body;

  await tajo.connectors.handleWebhook('jira', {
    event: event.webhookEvent,
    payload: {
      issueKey: event.issue?.key,
      issueType: event.issue?.fields?.issuetype?.name,
      status: event.issue?.fields?.status?.name,
      reporter: event.issue?.fields?.reporter?.emailAddress,
      assignee: event.issue?.fields?.assignee?.emailAddress
    }
  });

  res.status(200).send('OK');
});

Поиск задач по клиенту

// Поиск всех задач, созданных конкретным клиентом
const issues = await tajo.connectors.query('jira', {
  jql: 'reporter = "[email protected]" ORDER BY created DESC',
  maxResults: 20,
  fields: ['summary', 'status', 'priority', 'created']
});

Ограничения скорости

Jira Cloud применяет ограничения запросов для обеспечения стабильности платформы:

Jira возвращает ответ 429 Too Many Requests при превышении лимитов с заголовком Retry-After, указывающим, когда повторить запрос.

Устранение неполадок

Частые проблемы

Режим отладки

connectors:
  jira:
    debug: true
    log_level: verbose
    log_api_calls: true

Проверка подключения

tajo connectors test jira
# ✓ API authentication successful
# ✓ Project access verified
# ✓ Issue search operational
# ✓ User lookup available
# ✓ Webhook registration active

Лучшие практики

1. Используйте OAuth 2.0 для production, избегает зависимости от отдельных пользовательских аккаунтов
2. Фильтруйте с помощью JQL, синхронизируйте только нужные задачи для снижения нагрузки на API
3. Используйте вебхуки для real-time, не опрашивайте API; регистрируйте вебхуки для изменений задач
4. Учитывайте формат ADF, Jira v3 использует Atlassian Document Format для полей с форматированным текстом
5. Сопоставляйте проекты с листами, создавайте отдельные листы Brevo для каждого проекта Jira
6. Обрабатывайте пагинацию, всегда перебирайте все страницы для получения полных данных

Безопасность

• OAuth 2.0 (3LO), безопасная аутентификация на основе токенов с refresh-токенами
• API Token + Basic Auth, учётные данные в кодировке Base64 через HTTPS
• Только HTTPS, все API-коммуникации зашифрованы через TLS 1.2+
• Ограниченный доступ, OAuth scope ограничивают доступ к API необходимыми ресурсами
• Безопасность Atlassian Cloud, инфраструктура с сертификацией SOC 2 Type II
• Шифрованное хранение, учётные данные зашифрованы при хранении в Tajo

Связанные ресурсы

• Коннектор GitHub
• Коннектор Linear
• Коннектор Gorgias
• Brevo Contacts API