Konektor Jira

Propojte svou instanci Jira Cloud s Brevo pro sledování issues orientovaných na zákazníky, viditelnost supportních tiketů a notifikace o projektových milnících přes Tajo.

Přehled

Funkce

• Synchronizace událostí issues – Přeposílejte události vytvoření, aktualizace a vyřešení issues do časových os kontaktů Brevo
• Sledování zákaznických tiketů – Propojte issues Jira s kontakty Brevo pro viditelnost podpory
• Upozornění na projektové milníky – Spouštějte kampaně Brevo při vydáních verzí a dokončení sprintů
• Data kapacity týmu – Synchronizujte metriky pracovní zátěže pro operační přehledy
• Události změny stavu – Sledujte přechody pracovního postupu issues jako události Brevo
• Synchronizace komentářů – Přeposílejte komentáře pro zákazníky do protokolů aktivit Brevo

Předpoklady

Než začnete, ujistěte se, že máte:

1. Instanci Jira Cloud (Jira Software, Jira Service Management nebo Jira Work Management)
2. Administrátorský přístup k vytváření OAuth aplikací nebo generování API tokenů
3. E-mail účtu Atlassian přidružený k vašemu API tokenu
4. Účet Brevo s přístupem k API
5. Účet Tajo s aktivním předplatným

Ověření

Jira Cloud podporuje více metod ověřování.

Možnost 1: OAuth 2.0 (3LO) – Doporučeno

1. Přejděte na developer.atlassian.com
2. Klikněte na Create > OAuth 2.0 integration
3. Nakonfigurujte URL zpětného volání: https://app.tajo.io/callbacks/jira
4. Přidejte tyto rozsahy:

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

Struktura URL API pro OAuth 2.0:

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

Možnost 2: API Token (Basic Auth)

1. Přejděte na id.atlassian.com/manage/api-tokens
2. Klikněte na Create API token
3. Pojmenujte ho “Tajo Integration”

# Basic Auth: e-mail jako uživatelské jméno, API token jako heslo
curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \
  -u "[email protected]:$JIRA_API_TOKEN" \
  -H "Accept: application/json"

Připojení k Tajo

# Použití OAuth 2.0
tajo connectors install jira \
  --client-id $JIRA_CLIENT_ID \
  --client-secret $JIRA_CLIENT_SECRET \
  --cloud-id $JIRA_CLOUD_ID

# Použití API tokenu
tajo connectors install jira \
  --site-url your-domain.atlassian.net \
  --email [email protected] \
  --api-token $JIRA_API_TOKEN

Konfigurace

Základní nastavení

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

Mapování polí

Mapujte pole issues a uživatelů Jira na atributy Brevo:

field_mapping:
  # Pole uživatele
  accountId: JIRA_ACCOUNT_ID
  emailAddress: email
  displayName: FIRSTNAME

  # Pole issues mapovaná na události kontaktů
  issue_key: LAST_TICKET_KEY
  issue_status: LAST_TICKET_STATUS
  issue_priority: LAST_TICKET_PRIORITY
  issue_created: LAST_TICKET_DATE
  resolution: LAST_TICKET_RESOLUTION

Koncové body API

Tajo se integruje s následujícími koncovými body Jira Cloud REST API v3:

Příklady kódu

Inicializace konektoru

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

Synchronizace supportních issues

// Synchronizace supportních issues Jira do kontaktů 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
// }

Zpracování 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');
});

Vyhledávání issues podle zákazníka

// Nalezení všech issues nahlášených konkrétním zákazníkem
const issues = await tajo.connectors.query('jira', {
  jql: 'reporter = "[email protected]" ORDER BY created DESC',
  maxResults: 20,
  fields: ['summary', 'status', 'priority', 'created']
});

Omezení rychlosti

Jira Cloud aplikuje omezení rychlosti pro zajištění stability platformy:

Jira vrací odpověď 429 Too Many Requests, když jsou překročeny limity rychlosti, s hlavičkou Retry-After určující, kdy znovu zkusit.

Řešení problémů

Časté problémy

Režim ladění

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

Test připojení

tajo connectors test jira
# ✓ Ověření API úspěšné
# ✓ Přístup k projektu ověřen
# ✓ Vyhledávání issues funkční
# ✓ Vyhledávání uživatelů dostupné
# ✓ Registrace webhooků aktivní

Osvědčené postupy

1. Používejte OAuth 2.0 pro produkci – Vyhnete se závislosti na individuálních uživatelských účtech
2. Filtrujte pomocí JQL – Synchronizujte pouze relevantní issues pro snížení volání API
3. Používejte webhooky pro real-time – Vyhněte se pollingu; registrujte webhooky pro změny issues
4. Respektujte formát ADF – Jira v3 používá Atlassian Document Format pro pole s formátovaným textem
5. Mapujte projekt na seznam – Vytvořte samostatné seznamy Brevo na projekt Jira
6. Zpracovávejte stránkování – Vždy iterujte přes všechny stránky pro úplná data

Zabezpečení

• OAuth 2.0 (3LO) – Bezpečné ověřování na základě tokenů s obnovovacími tokeny
• API Token + Basic Auth – Base64 kódované přihlašovací údaje přes HTTPS
• Pouze HTTPS – Veškerá komunikace API šifrována přes TLS 1.2+
• Rozsahový přístup – Rozsahy OAuth omezují přístup API na požadované zdroje
• Bezpečnost Atlassian Cloud – Infrastruktura certifikovaná podle SOC 2 Type II
• Šifrované úložiště – Přihlašovací údaje šifrované v klidu v Tajo

Související zdroje

• Konektor GitHub
• Konektor Linear
• Konektor Gorgias
• API kontaktů Brevo