Connecteur Jira

Connectez votre instance Jira Cloud à Brevo pour le suivi des tickets côté client, la visibilité des tickets de support et les notifications de jalons de projet via Tajo.

Vue d’ensemble

Fonctionnalités

• Synchronisation d’événements issue, Transférez les événements de création, mise à jour et résolution d’issues vers les timelines de contacts Brevo
• Suivi des tickets clients, Liez les issues Jira aux contacts Brevo pour la visibilité support
• Alertes de jalons projet, Déclenchez des campagnes Brevo lors des releases de versions et clôtures de sprints
• Données de capacité d’équipe, Synchronisez les métriques de charge pour les tableaux de bord opérationnels
• Événements de changement de statut, Suivez les transitions de workflow d’issue en tant qu’événements Brevo
• Synchronisation des commentaires, Transférez les commentaires visibles au client vers les journaux d’activité Brevo

Prérequis

Avant de commencer, assurez-vous de disposer de :

1. Une instance Jira Cloud (Jira Software, Jira Service Management ou Jira Work Management)
2. Un accès admin pour créer des applications OAuth ou générer des API tokens
3. L’adresse e-mail du compte Atlassian associée à votre API token
4. Un compte Brevo avec accès API
5. Un compte Tajo avec un abonnement actif

Authentification

Jira Cloud prend en charge plusieurs méthodes d’authentification.

Option 1 : OAuth 2.0 (3LO), recommandé

1. Rendez-vous sur developer.atlassian.com
2. Cliquez sur Create > OAuth 2.0 integration
3. Configurez l’URL de callback : https://app.tajo.io/callbacks/jira
4. Ajoutez ces scopes :

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

Structure d’URL d’API pour OAuth 2.0 :

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

Option 2 : API Token (Basic Auth)

1. Rendez-vous sur id.atlassian.com/manage/api-tokens
2. Cliquez sur Create API token
3. Nommez-le « Tajo Integration »

# Basic Auth : e-mail comme nom d'utilisateur, API token comme mot de passe
curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \
  -u "[email protected]:$JIRA_API_TOKEN" \
  -H "Accept: application/json"

Connexion à Tajo

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

# Avec API Token
tajo connectors install jira \
  --site-url your-domain.atlassian.net \
  --email [email protected] \
  --api-token $JIRA_API_TOKEN

Configuration

Configuration de base

connectors:
  jira:
    enabled: true
    site_url: "your-domain.atlassian.net"
    auth_type: "oauth2"  # ou "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

Mappage des champs

Mappez les champs issue et utilisateur Jira vers les attributs Brevo :

field_mapping:
  # Champs utilisateur
  accountId: JIRA_ACCOUNT_ID
  emailAddress: email
  displayName: FIRSTNAME

  # Champs issue mappés vers des événements de contact
  issue_key: LAST_TICKET_KEY
  issue_status: LAST_TICKET_STATUS
  issue_priority: LAST_TICKET_PRIORITY
  issue_created: LAST_TICKET_DATE
  resolution: LAST_TICKET_RESOLUTION

Endpoints API

Tajo s’intègre avec les endpoints suivants de l’API REST v3 de Jira Cloud :

Exemples de code

Initialiser le connecteur

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

Synchroniser les issues de support

// Synchroniser les issues de support Jira vers des contacts 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
// }

Gérer les 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');
});

Rechercher les issues par client

// Trouver toutes les issues signalées par un client spécifique
const issues = await tajo.connectors.query('jira', {
  jql: 'reporter = "[email protected]" ORDER BY created DESC',
  maxResults: 20,
  fields: ['summary', 'status', 'priority', 'created']
});

Limites de débit

Jira Cloud impose des limites de débit pour assurer la stabilité de la plateforme :

Jira renvoie une réponse 429 Too Many Requests lorsque les limites de débit sont dépassées, avec un en-tête Retry-After indiquant quand réessayer.

Dépannage

Problèmes courants

Mode debug

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

Tester la connexion

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

Bonnes pratiques

1. Utilisez OAuth 2.0 en production, Évite la dépendance à des comptes utilisateurs individuels
2. Filtrez avec JQL, Synchronisez uniquement les issues pertinentes pour réduire les appels API
3. Utilisez les webhooks pour le temps réel, Évitez le polling ; enregistrez des webhooks pour les changements d’issues
4. Respectez le format ADF, Jira v3 utilise Atlassian Document Format pour les champs de texte riche
5. Mappez projet-vers-liste, Créez des listes Brevo séparées par projet Jira
6. Gérez la pagination, Itérez toujours sur toutes les pages pour des données complètes

Sécurité

• OAuth 2.0 (3LO), Authentification sécurisée basée sur tokens avec tokens de rafraîchissement
• API Token + Basic Auth, Identifiants encodés en Base64 sur HTTPS
• HTTPS uniquement, Toutes les communications API chiffrées via TLS 1.2+
• Accès à portée limitée, Les scopes OAuth limitent l’accès API aux ressources requises
• Sécurité Atlassian Cloud, Infrastructure certifiée SOC 2 Type II
• Stockage chiffré, Identifiants chiffrés au repos dans Tajo

Ressources associées

• Connecteur GitHub
• Connecteur Linear
• Connecteur Gorgias
• API Contacts Brevo