Jira konektor

Poveži svoju Jira Cloud instancu sa Brevo za praćenje problema okrenuto ka kupcima, vidljivost tiketa podrške i obaveštenja o prekretnicama projekta putem Tajo.

Pregled

Karakteristike

• Sinhronizacija događaja problema - Prosleđivanje događaja kreiranja, ažuriranja i rešavanja problema na Brevo vremenske linije kontakata
• Praćenje tiketa kupaca - Povezivanje Jira problema sa Brevo kontaktima za vidljivost podrške
• Upozorenja o prekretnicama projekta - Pokretanje Brevo kampanja pri objavljivanju verzija i završetku sprintova
• Podaci o kapacitetu tima - Sinhronizacija metrika radnog opterećenja za operativne dashboard-ove
• Događaji promena statusa - Praćenje prelaza toka problema kao Brevo događaja
• Sinhronizacija komentara - Prosleđivanje komentara okrenuto ka kupcima u Brevo logove aktivnosti

Preduslovi

Pre nego što započneš, proveri da imaš:

1. Jira Cloud instancu (Jira Software, Jira Service Management ili Jira Work Management)
2. Admin pristup za kreiranje OAuth aplikacija ili generisanje API tokena
3. Atlassian email naloga povezan sa tvojim API tokenom
4. Brevo nalog sa API pristupom
5. Tajo nalog sa aktivnom pretplatom

Autentifikacija

Jira Cloud podržava više metoda autentifikacije.

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

1. Idi na developer.atlassian.com
2. Klikni Create > OAuth 2.0 integration
3. Konfiguriši callback URL: https://app.tajo.io/callbacks/jira
4. Dodaj ove skopove:

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. Idi na id.atlassian.com/manage/api-tokens
2. Klikni Create API token
3. Nazovi ga “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"

Povezivanje sa 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

Konfiguracija

Osnovno podešavanje

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

Mapiranje polja

Mapiranje Jira polja problema i korisnika na Brevo atribute:

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

API endpointi

Tajo se integriše sa sledećim Jira Cloud REST API v3 endpointima:

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

Sinhronizacija tiketa podrške

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

Obrada Jira webhook-ova

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

Pretraga problema po kupcu

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

Ograničenja brzine

Jira Cloud primenjuje ograničenja brzine za osiguranje stabilnosti platforme:

Jira vraća 429 Too Many Requests odgovor kada se prekorače limiti brzine, sa Retry-After headerom koji označava kada pokušati ponovo.

Rešavanje problema

Česti problemi

Debug režim

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

Testiraj vezu

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

Najbolje prakse

1. Koristi OAuth 2.0 za produkciju - Izbegava zavisnost od individualnih korisničkih naloga
2. Filtriraj sa JQL - Sinhronizuj samo relevantne probleme da smanjiš API pozive
3. Koristi webhook-ove za real-time - Izbegavaj ispitivanje; registruj webhook-ove za promene problema
4. Poštuj ADF format - Jira v3 koristi Atlassian Document Format za polja sa bogatim tekstom
5. Mapiraj projekat na listu - Kreiraj posebne Brevo liste po Jira projektu
6. Obradi paginaciju - Uvek iteriraj kroz sve stranice za kompletne podatke

Bezbednost

• OAuth 2.0 (3LO) - Bezbedna autentifikacija zasnovana na tokenu sa refresh tokenima
• API Token + Basic Auth - Base64-kodovani akreditivi putem HTTPS
• Samo HTTPS - Sva API komunikacija enkriptovana putem TLS 1.2+
• Skopovani pristup - OAuth skopovi ograničavaju API pristup potrebnim resursima
• Atlassian Cloud bezbednost - SOC 2 Type II sertifikovana infrastruktura
• Enkriptovano skladištenje - Akreditivi enkriptovani u mirovanju u Tajo

Povezani resursi

• GitHub konektor
• Linear konektor
• Gorgias konektor
• Brevo Contacts API