Jira コネクタ

Jira Cloud インスタンスを Brevo に接続し、Tajo を介して顧客向け Issue トラッキング、サポートチケットの可視化、プロジェクトマイルストーン通知を実現します。

概要

機能

• Issue イベント同期 - Issue 作成、更新、解決イベントを Brevo 連絡先タイムラインに転送
• 顧客チケットのトラッキング - サポート可視化のために Jira Issue を Brevo 連絡先にリンク
• プロジェクトマイルストーンアラート - バージョンリリースやスプリント完了時に Brevo キャンペーンをトリガー
• チーム容量データ - 運用ダッシュボード用にワークロードメトリクスを同期
• ステータス変更イベント - Issue ワークフロー遷移を Brevo イベントとしてトラッキング
• コメント同期 - 顧客向けコメントを Brevo アクティビティログに転送

前提条件

開始する前に、以下を準備してください。

1. Jira Cloud インスタンス(Jira Software、Jira Service Management、または Jira Work Management)
2. OAuth アプリ作成または API トークン生成の管理者アクセス
3. API トークンに関連付けられた Atlassian アカウントのメール
4. API アクセス可能な Brevo アカウント
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

OAuth 2.0 の API URL 構造:

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: メールをユーザー名、API トークンをパスワードとして使用
curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \
  -u "[email protected]:$JIRA_API_TOKEN" \
  -H "Accept: application/json"

Tajo への接続

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

# 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"  # または "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:
  # ユーザーフィールド
  accountId: JIRA_ACCOUNT_ID
  emailAddress: email
  displayName: FIRSTNAME

  # 連絡先イベントにマッピングされた Issue フィールド
  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 を同期

// Jira のサポート Issue を Brevo 連絡先に同期
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 の処理

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 を検索

// 特定の顧客が報告したすべての Issue を検索
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 認証に成功
# ✓ プロジェクトアクセスを確認
# ✓ Issue 検索操作可能
# ✓ ユーザー検索が利用可能
# ✓ Webhook 登録有効

ベストプラクティス

1. 本番環境には OAuth 2.0 を使用する - 個々のユーザーアカウントへの依存を避ける
2. JQL でフィルタリングする - API 呼び出しを減らすため関連する Issue のみ同期
3. リアルタイムには Webhook を使用する - ポーリングを避け、Issue 変更用に Webhook を登録
4. ADF 形式を尊重する - Jira v3 はリッチテキストフィールドに Atlassian Document Format を使用
5. プロジェクトをリストにマッピングする - Jira プロジェクトごとに個別の Brevo リストを作成
6. ページネーションを処理する - 完全なデータのため常にすべてのページを反復処理

セキュリティ

• OAuth 2.0(3LO) - リフレッシュトークンを使用した安全なトークンベース認証
• API Token + Basic Auth - HTTPS 経由の Base64 エンコードされた資格情報
• HTTPS のみ - すべての API 通信は TLS 1.2 以上で暗号化
• スコープ付きアクセス - OAuth スコープが API アクセスを必要なリソースに制限
• Atlassian Cloud セキュリティ - SOC 2 Type II 認証取得済みインフラストラクチャ
• 暗号化されたストレージ - 資格情報は Tajo で保存時に暗号化

関連リソース

• GitHub コネクタ
• Linear コネクタ
• Gorgias コネクタ
• Brevo Contacts API