Конектор Jira

Свържете вашата Jira Cloud инстанция с Brevo за проследяване на issue-та, видими за клиентите, видимост на тикети за поддръжка и известия за етапи на проекта чрез Tajo.

Преглед

Функции

• Синхронизация на събития за issue-та – Препращайте събития за създаване, обновяване и разрешаване на issue-та към времевите линии на контактите в Brevo
• Проследяване на клиентски тикети – Свързвайте Jira issue-тата с контакти в Brevo за видимост на поддръжката
• Сигнали за етапи на проекта – Задействайте кампании в Brevo при release-и на версии и завършване на спринтове
• Данни за капацитета на екипа – Синхронизирайте метрики за натовареност за оперативни dashboards
• Събития за промяна на статус – Проследявайте преходите в работния процес на issue-тата като събития в Brevo
• Синхронизация на коментари – Препращайте видимите за клиентите коментари към логове за активност в Brevo

Предварителни условия

Преди да започнете, уверете се, че имате:

1. Jira Cloud инстанция (Jira Software, Jira Service Management или Jira Work Management)
2. Администраторски достъп за създаване на OAuth приложения или генериране на API токени
3. Имейл на 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. Конфигурирайте callback URL: https://app.tajo.io/callbacks/jira
4. Добавете следните обхвати:

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

Структура на API URL за 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 as username, API token as password
curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \
  -u "[email protected]:$JIRA_API_TOKEN" \
  -H "Accept: application/json"

Свързване към Tajo

# Using OAuth 2.0
tajo connectors install jira \
  --client-id $JIRA_CLIENT_ID \
  --client-secret $JIRA_CLIENT_SECRET \
  --cloud-id $JIRA_CLOUD_ID

# Using 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 issue-та и потребители към атрибути в 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
});

Синхронизация на issue-та за поддръжка

// Sync Jira support issues to Brevo contacts
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 webhooks

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');
});

Търсене на issue-та по клиент

// Find all issues reported by a specific customer
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, указващ кога да се опита повторно.

Отстраняване на проблеми

Често срещани проблеми

Debug режим

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 за продукция – Избягва зависимост от индивидуални потребителски акаунти
2. Филтрирайте с JQL – Синхронизирайте само релевантни issue-та, за да намалите API повикванията
3. Използвайте webhooks за реално време – Избягвайте допитване; регистрирайте webhooks за промени в issue-тата
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 обхватите ограничават API достъпа до необходимите ресурси
• Сигурност на Atlassian Cloud – SOC 2 Type II сертифицирана инфраструктура
• Криптирано съхранение – Идентификационните данни са криптирани в покой в Tajo

Свързани ресурси

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