موصل 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. بريد حساب 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. أضف هذه النطاقات:

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

يتكامل 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
});

مزامنة مشاكل الدعم

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

معالجة Webhooks الخاصة بـ 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');
});

البحث عن المشاكل حسب العميل

// 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 تشير إلى وقت إعادة المحاولة.

استكشاف الأخطاء

المشكلات الشائعة

وضع التصحيح

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 للوقت الفعلي - تجنب الاستطلاع؛ سجّل webhooks لتغييرات المشاكل
4. احترم تنسيق ADF - يستخدم Jira v3 تنسيق Atlassian Document Format للحقول الغنية
5. اربط المشروع بالقائمة - أنشئ قوائم Brevo منفصلة لكل مشروع Jira
6. تعامل مع الترقيم - كرر دائمًا عبر جميع الصفحات للحصول على بيانات كاملة

الأمان

• OAuth 2.0 (3LO) - مصادقة آمنة قائمة على الرموز مع رموز تحديث
• 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