Konektor Jira

Hubungkan instance Jira Cloud Anda ke Brevo untuk pelacakan issue yang menghadap pelanggan, visibilitas tiket dukungan, dan notifikasi milestone proyek melalui Tajo.

Ikhtisar

Fitur

• Sinkronisasi event issue - Teruskan event pembuatan, pembaruan, dan penyelesaian issue ke timeline kontak Brevo
• Pelacakan tiket pelanggan - Tautkan issue Jira ke kontak Brevo untuk visibilitas dukungan
• Peringatan milestone proyek - Picu kampanye Brevo saat rilis versi dan penyelesaian sprint
• Data kapasitas tim - Sinkronkan metrik beban kerja untuk dasbor operasional
• Event perubahan status - Lacak transisi alur kerja issue sebagai event Brevo
• Sinkronisasi komentar - Teruskan komentar yang menghadap pelanggan ke log aktivitas Brevo

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

1. Instance Jira Cloud (Jira Software, Jira Service Management, atau Jira Work Management)
2. Akses admin untuk membuat aplikasi OAuth atau membuat API token
3. Email akun Atlassian yang terkait dengan API token Anda
4. Akun Brevo dengan akses API
5. Akun Tajo dengan langganan aktif

Autentikasi

Jira Cloud mendukung beberapa metode autentikasi.

Opsi 1: OAuth 2.0 (3LO) - Direkomendasikan

1. Buka developer.atlassian.com
2. Klik Create > OAuth 2.0 integration
3. Konfigurasikan callback URL: https://app.tajo.io/callbacks/jira
4. Tambahkan scope berikut:

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

Struktur URL API untuk OAuth 2.0:

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

Opsi 2: API Token (Basic Auth)

1. Buka id.atlassian.com/manage/api-tokens
2. Klik Create API token
3. Beri nama “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"

Menghubungkan ke 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

Konfigurasi

Setup dasar

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

Pemetaan field

Petakan field issue dan pengguna Jira ke atribut 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

Endpoint API

Tajo terintegrasi dengan endpoint Jira Cloud REST API v3 berikut:

Contoh kode

Inisialisasi konektor

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

Menyinkronkan issue dukungan

// 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
// }

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

Mencari issue berdasarkan pelanggan

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

Batas rate

Jira Cloud menerapkan batas rate untuk menjaga stabilitas platform:

Jira mengembalikan respons 429 Too Many Requests saat batas rate terlampaui, disertai header Retry-After yang menunjukkan kapan harus mencoba lagi.

Pemecahan masalah

Masalah umum

Mode debug

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

Menguji koneksi

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

Praktik terbaik

1. Gunakan OAuth 2.0 untuk produksi - Menghindari ketergantungan pada akun pengguna individual
2. Saring dengan JQL - Sinkronkan hanya issue yang relevan untuk mengurangi panggilan API
3. Gunakan webhook untuk real-time - Hindari polling; daftarkan webhook untuk perubahan issue
4. Hormati format ADF - Jira v3 menggunakan Atlassian Document Format untuk field teks kaya
5. Petakan proyek ke list - Buat list Brevo terpisah untuk setiap proyek Jira
6. Tangani paginasi - Selalu telusuri seluruh halaman untuk data yang lengkap

Keamanan

• OAuth 2.0 (3LO) - Autentikasi berbasis token yang aman dengan refresh token
• API Token + Basic Auth - Kredensial berenkode Base64 melalui HTTPS
• Hanya HTTPS - Seluruh komunikasi API dienkripsi via TLS 1.2+
• Akses tersegmentasi - Scope OAuth membatasi akses API pada resource yang diperlukan
• Keamanan Atlassian Cloud - Infrastruktur bersertifikat SOC 2 Type II
• Penyimpanan terenkripsi - Kredensial dienkripsi saat disimpan di Tajo

Sumber daya terkait

• Konektor GitHub
• Konektor Linear
• Konektor Gorgias
• Brevo Contacts API