Jira Connector

Connect your Jira Cloud instance to Brevo for customer-facing issue tracking, support ticket visibility, and project milestone notifications through Tajo.

Overview

Features

• Issue event sync - Forward issue create, update, and resolve events to Brevo contact timelines
• Customer ticket tracking - Link Jira issues to Brevo contacts for support visibility
• Project milestone alerts - Trigger Brevo campaigns on version releases and sprint completions
• Team capacity data - Sync workload metrics for operational dashboards
• Status change events - Track issue workflow transitions as Brevo events
• Comment sync - Forward customer-facing comments to Brevo activity logs

Prerequisites

Before you begin, ensure you have:

1. A Jira Cloud instance (Jira Software, Jira Service Management, or Jira Work Management)
2. Admin access to create OAuth apps or generate API tokens
3. The Atlassian account email associated with your API token
4. A Brevo account with API access
5. A Tajo account with an active subscription

Authentication

Jira Cloud supports multiple authentication methods.

Option 1: OAuth 2.0 (3LO) - Recommended

1. Go to developer.atlassian.com
2. Click Create > OAuth 2.0 integration
3. Configure callback URL: https://app.tajo.io/callbacks/jira
4. Add these scopes:

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

The API URL structure for OAuth 2.0:

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

Option 2: API Token (Basic Auth)

1. Go to id.atlassian.com/manage/api-tokens
2. Click Create API token
3. Name it “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"

Connecting to 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

Configuration

Basic Setup

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

Field Mapping

Map Jira issue and user fields to Brevo attributes:

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 Endpoints

Tajo integrates with the following Jira Cloud REST API v3 endpoints:

Code Examples

Initialize Connector

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

Sync Support Issues

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

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

Search Issues by Customer

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

Rate Limits

Jira Cloud enforces rate limits to ensure platform stability:

Jira returns a 429 Too Many Requests response when rate limits are exceeded, with a Retry-After header indicating when to retry.

Troubleshooting

Common Issues

Debug Mode

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

Test Connection

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

Best Practices

1. Use OAuth 2.0 for production - Avoids dependency on individual user accounts
2. Filter with JQL - Only sync relevant issues to reduce API calls
3. Use webhooks for real-time - Avoid polling; register webhooks for issue changes
4. Respect ADF format - Jira v3 uses Atlassian Document Format for rich text fields
5. Map project-to-list - Create separate Brevo lists per Jira project
6. Handle pagination - Always iterate through all pages for complete data

Security

• OAuth 2.0 (3LO) - Secure token-based authentication with refresh tokens
• API Token + Basic Auth - Base64-encoded credentials over HTTPS
• HTTPS Only - All API communication encrypted via TLS 1.2+
• Scoped Access - OAuth scopes limit API access to required resources
• Atlassian Cloud Security - SOC 2 Type II certified infrastructure
• Encrypted Storage - Credentials encrypted at rest in Tajo

Related Resources

• GitHub Connector
• Linear Connector
• Gorgias Connector
• Brevo Contacts API

Open-Source Implementation Map

No official open-source repository was found in the current Tajo connector catalog for Jira. Keep this page focused on the verified public API contract and vendor documentation until an official schema, SDK, MCP server, or public integration repository is available.

Tajo Revamp Checklist

• Verify authentication and scope requirements against the vendor documentation before each connector release.
• Document primary sync objects, external IDs, pagination strategy, and rate limits explicitly.
• Add smoke tests from public API examples rather than undocumented behavior.
• Capture webhook signature verification and replay protection when the vendor supports webhooks.
• Record gaps where no official public repository or schema exists so future maintainers know what still needs source-backed validation.