--- title: "Connettore Jira" description: "Guida completa all'integrazione di Jira Cloud per sincronizzare issue, progetti e dati di attività del team con Brevo tramite Tajo." url: https://tajo.io/it/docs/connectors/custom/jira/ markdown: https://tajo.io/it/docs/connectors/custom/jira.md lang: it-IT robots: noindex --- Richiedi l’accesso anticipato Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo. # Connettore Jira Stato del connettore: Pianificato Non ancora realizzato. Oggi Tajo non esegue questo connettore. | Campo di origine | Campo di destinazione | Valore di esempio | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | 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 | Proprietà | Valore | | --- | --- | | **Piattaforma** | Jira Cloud | | **Categoria** | Custom | | **Complessità di setup** | Moderata | | **Integrazione ufficiale** | No | | **Dati sincronizzati** | Issue, Progetti, Utenti, Eventi | | **Tipo di API** | REST API v3 | | **Autenticazione** | OAuth 2.0 (3LO) / API Token (Basic Auth) | | **Base URL** | `https://your-domain.atlassian.net/rest/api/3/` | ## 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](https://developer.atlassian.com/console/myapps/) 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](https://id.atlassian.com/manage/api-tokens) 2. Clicca su **Create API token** 3. Nominalo “Tajo Integration” ```bash # Basic Auth: email come username, API token come password curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \ -u "email@example.com:$JIRA_API_TOKEN" \ -H "Accept: application/json" ``` Limitazioni dei token API I token API sono legati ai singoli account utente. Se l’utente viene disattivato, l’integrazione si interrompe. Usa OAuth 2.0 per i deployment in produzione. ### Connessione a Tajo ```bash # 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 admin@example.com \ --api-token $JIRA_API_TOKEN ``` ## Configurazione ### Setup di base ```yaml 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: ```yaml 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: | Endpoint | Metodo | Scopo | | --- | --- | --- | | `/rest/api/3/search` | POST | Cerca issue tramite JQL | | `/rest/api/3/issue/{issueIdOrKey}` | GET | Ottieni dettagli di una issue | | `/rest/api/3/issue` | POST | Crea una issue | | `/rest/api/3/project` | GET | Elenca tutti i progetti | | `/rest/api/3/project/{projectIdOrKey}` | GET | Ottieni dettagli progetto | | `/rest/api/3/user/search` | GET | Cerca utenti | | `/rest/api/3/myself` | GET | Ottieni l’utente corrente | | `/rest/api/3/issue/{issueIdOrKey}/comment` | GET | Ottieni i commenti di una issue | | `/rest/api/3/webhook` | POST | Registra webhook | | `/rest/api/3/status` | GET | Ottieni tutti gli stati | | `/rest/api/3/priority` | GET | Ottieni tutte le priorità | ## Esempi di codice ### Inizializzare il connettore ```javascript 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 ```javascript // 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 ```javascript 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 ```javascript // Trova tutte le issue segnalate da un cliente specifico const issues = await tajo.connectors.query('jira', { jql: 'reporter = "customer@example.com" 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: | Contesto | Rate limit | | --- | --- | | **REST API** | ~100 richieste ogni 10 secondi per utente | | **Richieste concorrenti** | 10 richieste long-running concorrenti | | **Operazioni bulk** | Variabile per endpoint | Paginazione Jira usa paginazione basata su offset con i parametri `startAt` e `maxResults`. La dimensione di pagina di default è 50, il massimo è 100. Tajo gestisce la paginazione automaticamente. 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 | Problema | Causa | Soluzione | | --- | --- | --- | | 401 Unauthorized | Token non valido o OAuth scaduto | Fai il refresh del token OAuth o rigenera il token API | | 403 Forbidden | Permessi insufficienti | Verifica che l’utente abbia accesso al progetto richiesto | | Errori JQL | Sintassi di query non valida | Valida la JQL prima nella ricerca issue di Jira | | Webhook non ricevuto | Firewall che blocca | Assicurati che l’URL del webhook sia accessibile pubblicamente | | Campi mancanti | Campo non nella risposta | Aggiungi il campo al parametro `fields` o usa `expand` | ### Modalità debug ```yaml connectors: jira: debug: true log_level: verbose log_api_calls: true ``` ### Testare la connessione ```bash 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](https://tajo.io/it/docs/connectors/custom/github) - [Connettore Linear](https://tajo.io/it/docs/connectors/custom/linear) - [Connettore Gorgias](https://tajo.io/it/docs/connectors/support/gorgias) - [Brevo Contacts API](https://tajo.io/it/docs/contact-management)