Connettore Jira

Collega la tua istanza Jira Cloud a Brevo per un tracciamento delle issue rivolto al cliente, la visibilità sui ticket di supporto e le notifiche sulle milestone di progetto tramite Tajo.

Panoramica

Funzionalità

• Sync eventi issue - Inoltra eventi di creazione, aggiornamento e risoluzione issue sulle timeline dei contatti Brevo
• Tracciamento ticket del cliente - Collega le issue Jira ai contatti Brevo per la visibilità sul supporto
• Alert sulle milestone di progetto - Attiva campagne Brevo sui rilasci di versione e sul completamento degli sprint
• Dati di capacità del team - Sincronizza le metriche di carico di lavoro per dashboard operative
• Eventi di cambio stato - Traccia le transizioni di workflow delle issue come eventi Brevo
• Sync dei commenti - Inoltra i commenti visibili al cliente sui log attività di Brevo

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un’istanza Jira Cloud (Jira Software, Jira Service Management o Jira Work Management)
2. Accesso admin per creare app OAuth o generare token API
3. L’email Atlassian associata al tuo token API
4. Un account Brevo con accesso API
5. Un account Tajo con abbonamento attivo

Autenticazione

Jira Cloud supporta diversi metodi di autenticazione.

Opzione 1: OAuth 2.0 (3LO) - consigliata

1. Vai su developer.atlassian.com
2. Clicca su Create > OAuth 2.0 integration
3. Configura l’URL di callback: https://app.tajo.io/callbacks/jira
4. Aggiungi questi scope:

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

La struttura URL dell’API per OAuth 2.0:

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

Opzione 2: API Token (Basic Auth)

1. Vai su id.atlassian.com/manage/api-tokens
2. Clicca su Create API token
3. Nominalo “Tajo Integration”

# Basic Auth: email come username, API token come password
curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \
  -u "[email protected]:$JIRA_API_TOKEN" \
  -H "Accept: application/json"

Connessione a Tajo

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

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

Configurazione

Setup di base

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

Mapping dei campi

Mappa i campi issue e utente Jira sugli attributi Brevo:

field_mapping:
  # Campi utente
  accountId: JIRA_ACCOUNT_ID
  emailAddress: email
  displayName: FIRSTNAME

  # Campi issue mappati su eventi di contatto
  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 si integra con i seguenti endpoint della REST API v3 di Jira Cloud:

Esempi di codice

Inizializzare il connettore

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

Sincronizzare le issue di supporto

// Sincronizza le issue di supporto Jira sui contatti 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
// }

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

Cercare issue per cliente

// Trova tutte le issue segnalate da un cliente specifico
const issues = await tajo.connectors.query('jira', {
  jql: 'reporter = "[email protected]" ORDER BY created DESC',
  maxResults: 20,
  fields: ['summary', 'status', 'priority', 'created']
});

Limiti di rate

Jira Cloud applica limiti di rate per garantire la stabilità della piattaforma:

Jira restituisce una risposta 429 Too Many Requests quando i limiti di rate vengono superati, con un header Retry-After che indica quando riprovare.

Risoluzione dei problemi

Problemi comuni

Modalità debug

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

Testare la connessione

tajo connectors test jira
# ✓ Autenticazione API riuscita
# ✓ Accesso al progetto verificato
# ✓ Ricerca issue operativa
# ✓ Lookup utente disponibile
# ✓ Registrazione webhook attiva

Best practice

1. Usa OAuth 2.0 in produzione - Evita la dipendenza dai singoli account utente
2. Filtra con JQL - Sincronizza solo le issue rilevanti per ridurre le chiamate API
3. Usa i webhook per il real-time - Evita il polling; registra webhook per i cambi sulle issue
4. Rispetta il formato ADF - Jira v3 usa Atlassian Document Format per i campi di testo ricco
5. Mappa progetto-lista - Crea liste Brevo separate per ogni progetto Jira
6. Gestisci la paginazione - Itera sempre su tutte le pagine per avere dati completi

Sicurezza

• OAuth 2.0 (3LO) - Autenticazione basata su token sicuri con refresh token
• API Token + Basic Auth - Credenziali codificate in Base64 su HTTPS
• Solo HTTPS - Tutte le comunicazioni API cifrate tramite TLS 1.2+
• Accesso con scope - Gli scope OAuth limitano l’accesso API alle risorse necessarie
• Sicurezza Atlassian Cloud - Infrastruttura certificata SOC 2 Type II
• Archiviazione cifrata - Credenziali cifrate a riposo in Tajo

Risorse correlate

• Connettore GitHub
• Connettore Linear
• Connettore Gorgias
• Brevo Contacts API