Conector Jira

Conecte sua instância Jira Cloud ao Brevo para rastreamento de issues voltado ao cliente, visibilidade de tickets de suporte e notificações de marcos de projeto através do Tajo.

Visão geral

Recursos

• Sincronização de eventos de issue - Encaminhe eventos de criação, atualização e resolução de issues para as timelines de contato do Brevo
• Rastreamento de tickets de clientes - Vincule issues do Jira a contatos do Brevo para visibilidade de suporte
• Alertas de marcos de projeto - Dispare campanhas do Brevo em releases de versão e conclusões de sprint
• Dados de capacidade da equipe - Sincronize métricas de carga de trabalho para dashboards operacionais
• Eventos de mudança de status - Acompanhe transições de workflow de issue como eventos do Brevo
• Sincronização de comentários - Encaminhe comentários voltados ao cliente para logs de atividade do Brevo

Pré-requisitos

Antes de começar, certifique-se de que você tem:

1. Uma instância Jira Cloud (Jira Software, Jira Service Management ou Jira Work Management)
2. Acesso de administrador para criar apps OAuth ou gerar tokens de API
3. O e-mail da conta Atlassian associado ao seu token de API
4. Uma conta Brevo com acesso à API
5. Uma conta Tajo com assinatura ativa

Autenticação

O Jira Cloud suporta vários métodos de autenticação.

Opção 1: OAuth 2.0 (3LO) - Recomendado

1. Acesse developer.atlassian.com
2. Clique em Create > OAuth 2.0 integration
3. Configure a URL de callback: https://app.tajo.io/callbacks/jira
4. Adicione estes escopos:

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

A estrutura de URL da API para OAuth 2.0:

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

Opção 2: API Token (Basic Auth)

1. Acesse id.atlassian.com/manage/api-tokens
2. Clique em Create API token
3. Nomeie como “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"

Conectando ao 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

Configuração

Configuração básica

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

Mapeamento de campos

Mapeie campos de issue e usuário do Jira para atributos do 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

Endpoints da API

O Tajo integra-se com os seguintes endpoints da REST API v3 do Jira Cloud:

Exemplos de código

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

Sincronizar issues de suporte

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

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

Buscar issues por cliente

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

Limites de taxa

O Jira Cloud aplica limites de taxa para garantir a estabilidade da plataforma:

O Jira retorna uma resposta 429 Too Many Requests quando os limites de taxa são excedidos, com um cabeçalho Retry-After indicando quando tentar novamente.

Solução de problemas

Problemas comuns

Modo de depuração

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

Testar conexão

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

Melhores práticas

1. Use OAuth 2.0 para produção - Evita dependência de contas de usuário individuais
2. Filtre com JQL - Sincronize apenas issues relevantes para reduzir chamadas de API
3. Use webhooks para tempo real - Evite polling; registre webhooks para mudanças de issue
4. Respeite o formato ADF - O Jira v3 usa Atlassian Document Format para campos de texto rico
5. Mapeie projeto-para-lista - Crie listas separadas do Brevo por projeto do Jira
6. Trate a paginação - Sempre itere por todas as páginas para dados completos

Segurança

• OAuth 2.0 (3LO) - Autenticação segura baseada em token com refresh tokens
• API Token + Basic Auth - Credenciais codificadas em Base64 sobre HTTPS
• Somente HTTPS - Toda comunicação com a API é criptografada via TLS 1.2+
• Acesso com escopo - Escopos OAuth limitam o acesso à API aos recursos necessários
• Segurança do Atlassian Cloud - Infraestrutura certificada SOC 2 Type II
• Armazenamento criptografado - Credenciais criptografadas em repouso no Tajo

Recursos relacionados

• Conector GitHub
• Conector Linear
• Conector Gorgias
• API de contatos do Brevo