Jira Bağlayıcısı

Müşteriye yönelik sorun takibi, destek bileti görünürlüğü ve proje kilometre taşı bildirimleri için Jira Cloud örneğini Tajo aracılığıyla Brevo’ya bağla.

Genel Bakış

Özellikler

• Sorun olayı senkronizasyonu - Sorun oluşturma, güncelleme ve çözme olaylarını Brevo kişi zaman çizelgelerine ilet
• Müşteri bileti takibi - Destek görünürlüğü için Jira sorunlarını Brevo kişilerine bağla
• Proje kilometre taşı uyarıları - Sürüm yayınları ve sprint tamamlamalarında Brevo kampanyalarını tetikle
• Takım kapasitesi verisi - İş yükü metriklerini operasyonel gösterge panoları için senkronize et
• Durum değişikliği olayları - Sorun iş akışı geçişlerini Brevo olayları olarak takip et
• Yorum senkronizasyonu - Müşteriye yönelik yorumları Brevo etkinlik kayıtlarına ilet

Ön Koşullar

Başlamadan önce sahip olman gerekenler:

1. Bir Jira Cloud örneği (Jira Software, Jira Service Management veya Jira Work Management)
2. OAuth uygulamaları oluşturmak veya API token üretmek için yönetici erişimi
3. API token ile ilişkili Atlassian hesabı e-posta adresi
4. API erişimi olan bir Brevo hesabı
5. Aktif aboneliği olan bir Tajo hesabı

Kimlik Doğrulama

Jira Cloud birden fazla kimlik doğrulama yöntemini destekler.

Seçenek 1: OAuth 2.0 (3LO) - Önerilen

1. developer.atlassian.com adresine git
2. Create > OAuth 2.0 integration seçeneğine tıkla
3. Callback URL’sini yapılandır: https://app.tajo.io/callbacks/jira
4. Bu kapsamları ekle:

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

OAuth 2.0 için API URL yapısı:

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

Seçenek 2: API Token (Basic Auth)

1. id.atlassian.com/manage/api-tokens adresine git
2. Create API token seçeneğine tıkla
3. “Tajo Integration” olarak adlandır

# 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’ya Bağlanma

# 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

Yapılandırma

Temel Kurulum

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

Alan Eşlemesi

Jira sorun ve kullanıcı alanlarını Brevo özniteliklerine eşle:

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 Endpoint’leri

Tajo, aşağıdaki Jira Cloud REST API v3 endpoint’leri ile entegre olur:

Kod Örnekleri

Bağlayıcıyı Başlat

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

Destek Sorunlarını Senkronize Et

// 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 Webhook’larını Yönet

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

Müşteriye Göre Sorun Ara

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

Hız Limitleri

Jira Cloud, platform kararlılığını sağlamak için hız limitleri uygular:

Hız limitleri aşıldığında Jira, ne zaman yeniden deneneceğini belirten bir Retry-After başlığı ile 429 Too Many Requests yanıtı döndürür.

Sorun Giderme

Yaygın Sorunlar

Hata Ayıklama Modu

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

Bağlantıyı Test Et

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

En İyi Uygulamalar

1. Üretim için OAuth 2.0 kullan - Bireysel kullanıcı hesaplarına bağımlılığı önler
2. JQL ile filtrele - API çağrılarını azaltmak için yalnızca ilgili sorunları senkronize et
3. Gerçek zamanlı için webhook kullan - Polling’den kaçın; sorun değişiklikleri için webhook kaydet
4. ADF biçimine saygı göster - Jira v3 zengin metin alanları için Atlassian Document Format kullanır
5. Projeyi listeye eşle - Her Jira projesi için ayrı Brevo listeleri oluştur
6. Sayfalamayı yönet - Tam veri için her zaman tüm sayfaları yinele

Güvenlik

• OAuth 2.0 (3LO) - Yenileme token’ları ile güvenli token tabanlı kimlik doğrulama
• API Token + Basic Auth - HTTPS üzerinden Base64 kodlu kimlik bilgileri
• Yalnızca HTTPS - Tüm API iletişimi TLS 1.2+ ile şifrelenir
• Kapsamlı Erişim - OAuth kapsamları API erişimini gerekli kaynaklarla sınırlar
• Atlassian Cloud Güvenliği - SOC 2 Type II sertifikalı altyapı
• Şifrelenmiş Depolama - Kimlik bilgileri Tajo’da bekleme sırasında şifrelenir

İlgili Kaynaklar

• GitHub Bağlayıcısı
• Linear Bağlayıcısı
• Gorgias Bağlayıcısı
• Brevo Contacts API