Conector Jira

Conectați instanța dvs. Jira Cloud la Brevo pentru urmărirea problemelor vizibile clienților, vizibilitatea tichetelor de suport și notificările privind etapele proiectului prin Tajo.

Prezentare generală

Funcționalități

• Sincronizare evenimente de probleme - Transmiteți evenimentele de creare, actualizare și rezolvare a problemelor în cronologiile de contact Brevo
• Urmărire tichete clienți - Legați problemele Jira de contactele Brevo pentru vizibilitate suport
• Alerte etape proiect - Declanșați campanii Brevo la lansări de versiuni și completări de sprint
• Date capacitate echipă - Sincronizați valorile de încărcare pentru tablouri de bord operaționale
• Evenimente de schimbare status - Urmăriți tranzițiile de flux de lucru ale problemelor ca evenimente Brevo
• Sincronizare comentarii - Transmiteți comentariile vizibile clienților în jurnalele de activitate Brevo

Cerințe preliminare

Înainte de a începe, asigurați-vă că aveți:

1. O instanță Jira Cloud (Jira Software, Jira Service Management sau Jira Work Management)
2. Acces de administrator pentru a crea aplicații OAuth sau a genera tokeni API
3. E-mailul contului Atlassian asociat cu tokenul API
4. Un cont Brevo cu acces API
5. Un cont Tajo cu abonament activ

Autentificare

Jira Cloud suportă mai multe metode de autentificare.

Opțiunea 1: OAuth 2.0 (3LO) - Recomandat

1. Accesați developer.atlassian.com
2. Faceți clic pe Create > OAuth 2.0 integration
3. Configurați URL-ul de callback: https://app.tajo.io/callbacks/jira
4. Adăugați aceste scopuri:

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

Structura URL-ului API pentru OAuth 2.0:

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

Opțiunea 2: Token API (Basic Auth)

1. Accesați id.atlassian.com/manage/api-tokens
2. Faceți clic pe Create API token
3. Denumiți-l “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"

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

Configurare

Configurare de bază

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

Mapare câmpuri

Mapați câmpurile problemelor și utilizatorilor Jira la atributele 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

Puncte finale API

Tajo se integrează cu următoarele puncte finale ale API-ului REST v3 Jira Cloud:

Exemple de cod

Inițializare conector

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

Sincronizare probleme de suport

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

Gestionare webhook-uri 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');
});

Căutare probleme după client

// 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']
});

Limite de rată

Jira Cloud aplică limite de rată pentru a asigura stabilitatea platformei:

Jira returnează un răspuns 429 Too Many Requests când limitele de rată sunt depășite, cu un antet Retry-After indicând când să reîncercați.

Depanare

Probleme frecvente

Modul de depanare

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

Testare conexiune

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

Bune practici

1. Utilizați OAuth 2.0 pentru producție - Evitați dependența de conturi de utilizatori individuali
2. Filtrați cu JQL - Sincronizați doar problemele relevante pentru a reduce apelurile API
3. Utilizați webhook-uri pentru timp real - Evitați interogarea; înregistrați webhook-uri pentru modificările problemelor
4. Respectați formatul ADF - Jira v3 utilizează Atlassian Document Format pentru câmpuri cu text îmbogățit
5. Mapați proiectul la listă - Creați liste Brevo separate per proiect Jira
6. Gestionați paginarea - Iterați întotdeauna prin toate paginile pentru date complete

Securitate

• OAuth 2.0 (3LO) - Autentificare bazată pe token securizat cu tokeni de reîmprospătare
• Token API + Basic Auth - Credențiale codificate Base64 prin HTTPS
• Numai HTTPS - Toată comunicarea API criptată prin TLS 1.2+
• Acces cu scop limitat - Scopurile OAuth limitează accesul API la resursele necesare
• Securitate Atlassian Cloud - Infrastructură certificată SOC 2 Tip II
• Stocare criptată - Credențiale criptate în repaus în Tajo

Resurse conexe

• Conector GitHub
• Conector Linear
• Conector Gorgias
• API Contacte Brevo