Jira-kobling

Koble Jira Cloud-instansen din til Brevo for kundevendt issue-sporing, synlighet av supportsaker og varslinger om prosjektmilepæler gjennom Tajo.

Oversikt

Funksjoner

• Synkronisering av issue-hendelser - Videresend hendelser for opprettelse, oppdatering og løsning av issues til Brevo-kontakttidslinjer
• Sporing av kundesaker - Koble Jira-issues til Brevo-kontakter for supportoversikt
• Varsler om prosjektmilepæler - Utløs Brevo-kampanjer ved versjonsreleaser og sprintfullføringer
• Data om teamkapasitet - Synkroniser arbeidsmengdemålinger for operasjonelle dashbord
• Statusendringshendelser - Spor arbeidsflytoverganger for issues som Brevo-hendelser
• Kommentar-synkronisering - Videresend kundevendte kommentarer til Brevo-aktivitetslogger

Forutsetninger

Før du begynner, sørg for at du har:

1. En Jira Cloud-instans (Jira Software, Jira Service Management eller Jira Work Management)
2. Administratortilgang for å opprette OAuth-apper eller generere API-tokens
3. Atlassian-kontoens e-postadresse knyttet til API-tokenet ditt
4. En Brevo-konto med API-tilgang
5. En Tajo-konto med aktivt abonnement

Autentisering

Jira Cloud støtter flere autentiseringsmetoder.

Alternativ 1: OAuth 2.0 (3LO) - Anbefalt

1. Gå til developer.atlassian.com
2. Klikk Create > OAuth 2.0 integration
3. Konfigurer callback-URL: https://app.tajo.io/callbacks/jira
4. Legg til disse scopene:

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

API-URL-strukturen for OAuth 2.0:

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

Alternativ 2: API-token (Basic Auth)

1. Gå til id.atlassian.com/manage/api-tokens
2. Klikk Create API token
3. Gi det navnet “Tajo Integration”

# Basic Auth: e-post som brukernavn, API-token som passord
curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \
  -u "[email protected]:$JIRA_API_TOKEN" \
  -H "Accept: application/json"

Koble til Tajo

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

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

Konfigurasjon

Grunnleggende oppsett

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

Feltmapping

Mapp Jira-issue- og brukerfelt til Brevo-attributter:

field_mapping:
  # Brukerfelt
  accountId: JIRA_ACCOUNT_ID
  emailAddress: email
  displayName: FIRSTNAME

  # Issue-felt mappet til kontakthendelser
  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-endepunkter

Tajo integrerer med følgende Jira Cloud REST API v3-endepunkter:

Kodeeksempler

Initialiser kobling

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

Synkroniser supportsaker

// Synkroniser Jira-supportsaker til Brevo-kontakter
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
// }

Håndter Jira-webhooks

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

Søk etter issues per kunde

// Finn alle issues rapportert av en bestemt kunde
const issues = await tajo.connectors.query('jira', {
  jql: 'reporter = "[email protected]" ORDER BY created DESC',
  maxResults: 20,
  fields: ['summary', 'status', 'priority', 'created']
});

Ratebegrensninger

Jira Cloud håndhever ratebegrensninger for å sikre plattformstabilitet:

Jira returnerer en 429 Too Many Requests-respons når ratebegrensninger overskrides, med en Retry-After-header som angir når du skal prøve igjen.

Feilsøking

Vanlige problemer

Feilsøkingsmodus

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

Test tilkobling

tajo connectors test jira
# ✓ API-autentisering vellykket
# ✓ Prosjekttilgang bekreftet
# ✓ Issue-søk operativt
# ✓ Brukeroppslag tilgjengelig
# ✓ Webhook-registrering aktiv

Beste praksis

1. Bruk OAuth 2.0 i produksjon - Unngår avhengighet av individuelle brukerkontoer
2. Filtrer med JQL - Synkroniser kun relevante issues for å redusere API-kall
3. Bruk webhooks for sanntid - Unngå polling; registrer webhooks for issue-endringer
4. Respekter ADF-format - Jira v3 bruker Atlassian Document Format for rike tekstfelt
5. Mapp prosjekt til liste - Opprett separate Brevo-lister per Jira-prosjekt
6. Håndter paginering - Iterer alltid gjennom alle sider for komplette data

Sikkerhet

• OAuth 2.0 (3LO) - Sikker token-basert autentisering med oppfriskningstokens
• API-token + Basic Auth - Base64-kodede påloggingsdetaljer over HTTPS
• Kun HTTPS - All API-kommunikasjon kryptert via TLS 1.2+
• Avgrenset tilgang - OAuth-scopes begrenser API-tilgang til nødvendige ressurser
• Atlassian Cloud-sikkerhet - SOC 2 Type II-sertifisert infrastruktur
• Kryptert lagring - Påloggingsdetaljer kryptert i hvilemodus i Tajo

Relaterte ressurser

• GitHub-kobling
• Linear-kobling
• Gorgias-kobling
• Brevo Contacts API