Jira Connector

เชื่อมต่อ Jira Cloud instance กับ Brevo สำหรับการติดตามปัญหาที่หันหน้าสู่ลูกค้า การมองเห็นตั๋วสนับสนุน และการแจ้งเตือนเหตุการณ์สำคัญของโปรเจกต์ผ่าน Tajo

ภาพรวม

ฟีเจอร์

• การซิงค์เหตุการณ์ปัญหา - ส่งต่อเหตุการณ์สร้าง อัปเดต และแก้ไขปัญหาไปยังไทม์ไลน์ผู้ติดต่อ Brevo
• การติดตามตั๋วลูกค้า - เชื่อมโยงปัญหา Jira กับผู้ติดต่อ Brevo สำหรับการมองเห็นการสนับสนุน
• การแจ้งเตือนเหตุการณ์สำคัญโปรเจกต์ - ทริกเกอร์แคมเปญ Brevo เมื่อ version releases และ sprint completions
• ข้อมูลความสามารถทีม - ซิงค์ตัวชี้วัดปริมาณงานสำหรับ dashboards ปฏิบัติการ
• เหตุการณ์การเปลี่ยนสถานะ - ติดตามการเปลี่ยนผ่านเวิร์กโฟลว์ปัญหาเป็นเหตุการณ์ Brevo
• การซิงค์ความคิดเห็น - ส่งต่อความคิดเห็นที่หันหน้าสู่ลูกค้าไปยัง activity logs ของ Brevo

ข้อกำหนดเบื้องต้น

ก่อนเริ่มต้น ตรวจสอบให้แน่ใจว่าคุณมี:

1. Jira Cloud instance (Jira Software, Jira Service Management หรือ Jira Work Management)
2. สิทธิ์ผู้ดูแลระบบในการสร้าง OAuth apps หรือสร้าง API tokens
3. อีเมลบัญชี Atlassian ที่เกี่ยวข้องกับ API token ของคุณ
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. เพิ่ม scopes เหล่านี้:

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 กับแอตทริบิวต์ 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 Endpoints

Tajo ผสานรวมกับ Jira Cloud REST API v3 endpoints ต่อไปนี้:

ตัวอย่างโค้ด

เริ่มต้น Connector

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

ซิงค์ปัญหาการสนับสนุน

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

ค้นหาปัญหาตามลูกค้า

// 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 เมื่อเกินขีดจำกัดอัตรา พร้อม header 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 - ซิงค์เฉพาะปัญหาที่เกี่ยวข้องเพื่อลดการเรียก API
3. ใช้ webhooks สำหรับแบบเรียลไทม์ - หลีกเลี่ยงการ polling ลงทะเบียน webhooks สำหรับการเปลี่ยนแปลงปัญหา
4. เคารพรูปแบบ ADF - Jira v3 ใช้ Atlassian Document Format สำหรับฟิลด์ rich text
5. แมปโปรเจกต์กับรายการ - สร้างรายการ Brevo แยกต่างหากต่อโปรเจกต์ Jira
6. จัดการ pagination - วนซ้ำผ่านทุกหน้าเสมอสำหรับข้อมูลที่สมบูรณ์

ความปลอดภัย

• OAuth 2.0 (3LO) - การยืนยันตัวตนตาม token ที่ปลอดภัยพร้อม refresh tokens
• API Token + Basic Auth - ข้อมูลรับรอง Base64-encoded ผ่าน HTTPS
• HTTPS เท่านั้น - การสื่อสาร API ทั้งหมดเข้ารหัสผ่าน TLS 1.2+
• การเข้าถึงแบบกำหนดขอบเขต - OAuth scopes จำกัดการเข้าถึง API กับทรัพยากรที่จำเป็น
• Atlassian Cloud Security - โครงสร้างพื้นฐานที่ได้รับการรับรอง SOC 2 Type II
• การจัดเก็บที่เข้ารหัส - ข้อมูลรับรองเข้ารหัสที่เก็บใน Tajo

แหล่งข้อมูลที่เกี่ยวข้อง

• GitHub Connector
• Linear Connector
• Gorgias Connector
• Brevo Contacts API