Jira Konektor

Povežite svoju Jira Cloud instancu s Brevom za praćenje problema prema klijentima, vidljivost tiketa podrške i obavijesti o projektnim prekretnicama putem Taja.

Pregled

Značajke

• Sinkronizacija događaja problema - Prosljeđujte događaje stvaranja, ažuriranja i rješavanja problema na Brevo vremenske linije kontakata
• Praćenje tiketa klijenata - Povežite Jira probleme s Brevo kontaktima radi vidljivosti podrške
• Upozorenja o projektnim prekretnicama - Pokrećite Brevo kampanje pri objavama verzija i dovršetku sprintova
• Podaci o kapacitetu tima - Sinkronizirajte metrike radnog opterećenja za operativne nadzorne ploče
• Događaji promjene statusa - Pratite prijelaze radnog toka problema kao Brevo događaje
• Sinkronizacija komentara - Prosljeđujte komentare prema klijentima u Brevo zapisnike aktivnosti

Preduvjeti

Prije nego što počnete, osigurajte da imate:

1. Jira Cloud instancu (Jira Software, Jira Service Management ili Jira Work Management)
2. Administratorski pristup za stvaranje OAuth aplikacija ili generiranje API tokena
3. E-mail Atlassian računa povezan s vašim API tokenom
4. Brevo račun s API pristupom
5. Tajo račun s aktivnom pretplatom

Autentifikacija

Jira Cloud podržava više metoda autentifikacije.

Opcija 1: OAuth 2.0 (3LO) - Preporučeno

1. Idite na developer.atlassian.com
2. Kliknite Create > OAuth 2.0 integration
3. Konfigurirajte callback URL: https://app.tajo.io/callbacks/jira
4. Dodajte ove opsege:

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

Struktura API URL-a za OAuth 2.0:

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

Opcija 2: API Token (Basic Auth)

1. Idite na id.atlassian.com/manage/api-tokens
2. Kliknite Create API token
3. Nazovite ga “Tajo Integration”

# Basic Auth: e-mail kao korisničko ime, API token kao lozinka
curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \
  -u "[email protected]:$JIRA_API_TOKEN" \
  -H "Accept: application/json"

Povezivanje s Tajom

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

# Korištenjem API Tokena
tajo connectors install jira \
  --site-url your-domain.atlassian.net \
  --email [email protected] \
  --api-token $JIRA_API_TOKEN

Konfiguracija

Osnovna konfiguracija

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

Mapiranje polja

Mapirajte Jira probleme i korisnička polja na Brevo atribute:

field_mapping:
  # Korisnička polja
  accountId: JIRA_ACCOUNT_ID
  emailAddress: email
  displayName: FIRSTNAME

  # Polja problema mapirana na kontaktne događaje
  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 krajnje točke

Tajo se integrira sa sljedećim Jira Cloud REST API v3 krajnjim točkama:

Primjeri koda

Inicijalizacija konektora

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

Sinkronizacija tiketa podrške

// Sinkronizacija Jira tiketa podrške s Brevo kontaktima
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
// }

Rukovanje Jira Webhooksima

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

Pretraživanje problema po klijentu

// Pronalazak svih problema koje je prijavio određeni klijent
const issues = await tajo.connectors.query('jira', {
  jql: 'reporter = "[email protected]" ORDER BY created DESC',
  maxResults: 20,
  fields: ['summary', 'status', 'priority', 'created']
});

Ograničenja brzine

Jira Cloud primjenjuje ograničenja brzine radi osiguravanja stabilnosti platforme:

Jira vraća odgovor 429 Too Many Requests kada su prekoračena ograničenja brzine, sa zaglavljem Retry-After koje označava kada ponovo pokušati.

Rješavanje problema

Uobičajeni problemi

Način otklanjanja grešaka

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

Testiranje veze

tajo connectors test jira
# ✓ API autentifikacija uspješna
# ✓ Pristup projektu potvrđen
# ✓ Pretraživanje problema operativno
# ✓ Traženje korisnika dostupno
# ✓ Registracija webhookova aktivna

Preporučene prakse

1. Koristite OAuth 2.0 za produkciju - Izbjegava ovisnost o pojedinačnim korisničkim računima
2. Filtrirajte JQL-om - Sinkronizirajte samo relevantne probleme za smanjenje API poziva
3. Koristite webhookove za sinkronizaciju u stvarnom vremenu - Izbjegavajte anketiranje; registrirajte webhookove za promjene problema
4. Poštujte ADF format - Jira v3 koristi Atlassian Document Format za polja obogaćenog teksta
5. Mapirajte projekt-na-popis - Stvorite zasebne Brevo popise po Jira projektu
6. Rukujte paginacijom - Uvijek iterirajte kroz sve stranice za potpune podatke

Sigurnost

• OAuth 2.0 (3LO) - Sigurna autentifikacija temeljena na tokenima s tokenima za osvježavanje
• API Token + Basic Auth - Base64-kodirane vjerodajnice putem HTTPS-a
• Samo HTTPS - Sva API komunikacija šifrirana putem TLS 1.2+
• Opsežni pristup - OAuth opsezi ograničavaju API pristup na potrebne resurse
• Atlassian Cloud sigurnost - SOC 2 Type II certificirana infrastruktura
• Šifrirano pohranjivanje - Vjerodajnice šifrirane u mirovanju u Taju

Povezani resursi

• GitHub Konektor
• Linear Konektor
• Gorgias Konektor
• Brevo API kontakata