---
title: "Jira Integration"
description: "Complete guide to integrating TracerTM with Jira for bidirectional sync, issue import, and real-time updates"
---

# Jira Integration

Integrate TracerTM with Jira to synchronize requirements, test cases, and traceability data between both systems. This guide covers one-time imports, bidirectional sync, and webhook-based real-time updates.

## Overview

TracerTM's Jira integration enables you to:

- **Import Jira issues** as TracerTM items with full metadata preservation
- **Maintain bidirectional sync** between Jira and TracerTM
- **Map custom fields** from Jira to TracerTM properties
- **Preserve issue links** and relationships during import
- **Enable real-time updates** via webhooks
- **Track sync status** and resolve conflicts automatically

### Integration Architecture

```
┌─────────────┐                    ┌──────────────┐
│    Jira     │◄──── Webhooks ────►│   TracerTM   │
│             │                    │              │
│  - Issues   │◄──── REST API ────►│  - Items     │
│  - Links    │                    │  - Links     │
│  - Metadata │◄──── Sync Svc ────►│  - Metadata  │
└─────────────┘                    └──────────────┘
```

## Prerequisites

Before integrating with Jira, ensure you have:

### 1. Jira Access

- **Jira Cloud** or **Jira Server** instance
- **Admin permissions** or **API access** enabled
- **Project access** for the projects you want to import

### 2. TracerTM Setup

```bash
# Verify TracerTM installation
rtm --version

# Initialize database
rtm init

# Check configuration
rtm config show
```

### 3. Authentication Credentials

You'll need one of the following:

- **API Token** (Jira Cloud) - Recommended
- **Personal Access Token** (Jira Server/Data Center)
- **Username + Password** (Legacy, not recommended)

## Authentication Configuration

### Step 1: Create Jira API Token

For **Jira Cloud**:

1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API Token**
3. Give it a label (e.g., "TracerTM Integration")
4. Copy the token immediately (you won't see it again)

For **Jira Server/Data Center**:

1. Go to Jira → Settings → Personal Access Tokens
2. Click **Create token**
3. Set permissions and expiration
4. Copy the token

### Step 2: Configure TracerTM

Store your Jira credentials securely:

```bash
# Set Jira credentials via environment variables (recommended)
export JIRA_URL="https://your-company.atlassian.net"
export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your-api-token-here"

# Or store in TracerTM config
rtm config set jira.url "https://your-company.atlassian.net"
rtm config set jira.email "your-email@company.com"
rtm config set jira.api_token "your-api-token-here"
```

### Step 3: Test Connection

```bash
# Verify Jira connection
rtm integration test jira

# Expected output:
# ✓ Successfully connected to Jira
# ✓ Authenticated as: your-email@company.com
# ✓ API version: 3
```

## Importing Issues from Jira

### One-Time Import

#### Option 1: Import via Jira REST API

```bash
# Import all issues from a specific Jira project
rtm import jira \
  --project "PROJ" \
  --target-project "My TracerTM Project"

# Import with filters (JQL)
rtm import jira \
  --project "PROJ" \
  --jql "status != Done AND created >= -30d" \
  --target-project "Recent Issues"

# Import specific issue types
rtm import jira \
  --project "PROJ" \
  --issue-types "Story,Bug,Task" \
  --target-project "Development Items"
```

#### Option 2: Import from JSON Export

First, export from Jira:

```bash
# Using Jira REST API
curl -u "your-email@company.com:your-api-token" \
  "https://your-company.atlassian.net/rest/api/3/search?jql=project=PROJ&maxResults=1000" \
  > jira-export.json

# Or export via Jira UI:
# 1. Go to Issues → Search
# 2. Apply filters
# 3. Export → JSON
```

Then import to TracerTM:

```bash
# Validate export before importing
rtm import jira jira-export.json --validate-only

# Import the file
rtm import jira jira-export.json \
  --project "Imported Project" \
  --dry-run  # Preview changes first

# Perform actual import
rtm import jira jira-export.json \
  --project "Imported Project"
```

### Import with Advanced Options

```bash
# Import with custom field mapping
rtm import jira jira-export.json \
  --project "My Project" \
  --map "customfield_10001:priority" \
  --map "customfield_10002:severity" \
  --preserve-ids  # Keep original Jira IDs in metadata

# Import to specific view
rtm import jira jira-export.json \
  --project "My Project" \
  --default-view "FEATURE" \
  --story-view "FEATURE" \
  --bug-view "TEST" \
  --task-view "CODE"

# Skip specific issue types
rtm import jira jira-export.json \
  --project "My Project" \
  --exclude-types "Sub-task,Epic"
```

## Field Mapping

### Default Mappings

TracerTM automatically maps Jira fields to TracerTM properties:

#### Issue Type Mapping

| Jira Type  | TracerTM Type | Default View |
|------------|---------------|--------------|
| Epic       | epic          | FEATURE      |
| Story      | story         | FEATURE      |
| Task       | task          | CODE         |
| Bug        | bug           | TEST         |
| Sub-task   | subtask       | CODE         |
| Requirement| requirement   | FEATURE      |

#### Status Mapping

| Jira Status    | TracerTM Status |
|----------------|-----------------|
| To Do          | todo            |
| In Progress    | in_progress     |
| In Review      | in_progress     |
| In Testing     | in_progress     |
| Done           | complete        |
| Closed         | complete        |
| Cancelled      | cancelled       |

#### Link Type Mapping

| Jira Link Type      | TracerTM Link Type |
|---------------------|-------------------|
| relates to          | relates_to        |
| blocks              | blocks            |
| is blocked by       | blocked_by        |
| duplicates          | duplicates        |
| is duplicated by    | duplicated_by     |
| implements          | implements        |
| is implemented by   | implemented_by    |
| tests               | tests             |
| is tested by        | tested_by         |
| causes              | causes            |
| is caused by        | caused_by         |

### Custom Field Mapping

Create a mapping configuration file:

```yaml
# jira-mapping.yaml
field_mappings:
  # Map Jira custom fields to TracerTM metadata
  customfield_10001:
    target: priority
    type: string

  customfield_10002:
    target: severity
    type: string
    values:
      Critical: critical
      High: high
      Medium: medium
      Low: low

  customfield_10003:
    target: estimated_hours
    type: number

  customfield_10004:
    target: tags
    type: array

# Custom status mapping
status_mappings:
  "Awaiting Approval": in_progress
  "Ready for QA": in_progress
  "QA Complete": complete

# Custom type mapping
type_mappings:
  "Technical Debt": task
  "Spike": task
  "Investigation": task
```

Use the mapping file:

```bash
rtm import jira jira-export.json \
  --project "My Project" \
  --mapping-file jira-mapping.yaml
```

## Bidirectional Synchronization

### Enable Continuous Sync

Set up automatic bidirectional synchronization:

```bash
# Register Jira integration
rtm integration register \
  --name "production-jira" \
  --type jira \
  --url "https://your-company.atlassian.net" \
  --project "PROJ"

# Enable bidirectional sync
rtm integration sync enable production-jira \
  --direction bidirectional \
  --interval 300  # Sync every 5 minutes

# Start sync service
rtm integration sync start production-jira
```

### Sync Configuration

```bash
# Configure sync behavior
rtm integration sync config production-jira \
  --conflict-strategy last_write_wins \
  --sync-comments true \
  --sync-attachments false \
  --sync-watchers false

# Available conflict strategies:
# - last_write_wins: Most recent change wins (default)
# - local_wins: TracerTM changes take precedence
# - remote_wins: Jira changes take precedence
# - manual: Prompt for resolution
```

### Manual Sync Operations

```bash
# One-time sync from Jira to TracerTM
rtm integration sync pull production-jira

# One-time sync from TracerTM to Jira
rtm integration sync push production-jira

# Full bidirectional sync
rtm integration sync both production-jira

# Check sync status
rtm integration sync status production-jira
```

### Monitoring Sync

```bash
# View sync history
rtm integration sync history production-jira

# View sync conflicts
rtm integration sync conflicts production-jira

# Resolve specific conflict
rtm integration sync resolve-conflict \
  --conflict-id abc123 \
  --strategy local_wins

# View sync statistics
rtm integration sync stats production-jira
```

## Webhook Configuration

Enable real-time updates from Jira using webhooks:

### Step 1: Create Webhook Endpoint

```bash
# Start TracerTM webhook receiver
rtm integration webhook start \
  --port 8080 \
  --path /webhooks/jira

# With authentication
rtm integration webhook start \
  --port 8080 \
  --path /webhooks/jira \
  --secret "your-webhook-secret"

# Output:
# ✓ Webhook receiver started
# URL: https://your-server.com:8080/webhooks/jira
# Secret: your-webhook-secret
```

### Step 2: Configure Jira Webhook

In Jira:

1. Go to **Settings → System → WebHooks**
2. Click **Create a WebHook**
3. Configure:

```
Name: TracerTM Integration
Status: Enabled
URL: https://your-server.com:8080/webhooks/jira
Description: Real-time sync with TracerTM

Events to trigger:
☑ Issue Created
☑ Issue Updated
☑ Issue Deleted
☑ Comment Created
☑ Comment Updated
☑ Comment Deleted

JQL Filter: project = PROJ

Authentication:
Header Name: X-Webhook-Secret
Header Value: your-webhook-secret
```

4. Click **Create**

### Step 3: Test Webhook

```bash
# Test webhook connection
rtm integration webhook test production-jira

# Monitor webhook events
rtm integration webhook logs \
  --integration production-jira \
  --follow

# Webhook event statistics
rtm integration webhook stats production-jira
```

### Webhook Event Handling

TracerTM processes these Jira webhook events:

| Jira Event        | TracerTM Action              |
|-------------------|------------------------------|
| issue_created     | Create new item              |
| issue_updated     | Update existing item         |
| issue_deleted     | Delete item (or mark deleted)|
| comment_created   | Add comment to item          |
| comment_updated   | Update item comment          |
| comment_deleted   | Remove comment               |
| worklog_updated   | Update time tracking         |

## CLI Commands Reference

### Import Commands

```bash
# Import from Jira API
rtm import jira --project PROJ [options]

# Import from JSON file
rtm import jira <file.json> [options]

# Validate import
rtm import jira <file.json> --validate-only

# Dry run
rtm import jira <file.json> --dry-run
```

### Integration Management

```bash
# Register integration
rtm integration register --name <name> --type jira [options]

# List integrations
rtm integration list

# Get integration details
rtm integration info <name>

# Update integration config
rtm integration update <name> [options]

# Remove integration
rtm integration remove <name>

# Test integration
rtm integration test <name>
```

### Sync Commands

```bash
# Enable/disable sync
rtm integration sync enable <name>
rtm integration sync disable <name>

# Start/stop sync service
rtm integration sync start <name>
rtm integration sync stop <name>

# Manual sync operations
rtm integration sync pull <name>
rtm integration sync push <name>
rtm integration sync both <name>

# Sync status and history
rtm integration sync status <name>
rtm integration sync history <name>
rtm integration sync conflicts <name>
```

### Webhook Commands

```bash
# Start webhook receiver
rtm integration webhook start [options]

# Stop webhook receiver
rtm integration webhook stop

# Test webhook
rtm integration webhook test <name>

# View webhook logs
rtm integration webhook logs <name>

# Webhook statistics
rtm integration webhook stats <name>
```

## Troubleshooting

### Issue: Authentication Failed

**Symptoms:**
```
Error: Failed to authenticate with Jira
Status: 401 Unauthorized
```

**Solutions:**

1. Verify API token:
```bash
# Test token manually
curl -u "email@example.com:api-token" \
  "https://your-company.atlassian.net/rest/api/3/myself"
```

2. Check token permissions:
   - Ensure API token has not expired
   - Verify token has read/write access to the project

3. Update credentials:
```bash
rtm config set jira.api_token "new-token"
rtm integration test jira
```

### Issue: Import Validation Errors

**Symptoms:**
```
Error: Validation failed
- Missing 'issues' field
- Issue 5 missing 'key' field
```

**Solutions:**

1. Validate JSON structure:
```bash
python -m json.tool jira-export.json > validated.json
rtm import jira validated.json --validate-only
```

2. Check export format:
```json
{
  "issues": [
    {
      "id": "10001",
      "key": "PROJ-123",
      "fields": {
        "summary": "Issue title",
        "description": "Issue description",
        "status": {"name": "To Do"},
        "issuetype": {"name": "Story"}
      }
    }
  ]
}
```

### Issue: Sync Conflicts

**Symptoms:**
```
Warning: Sync conflict detected
Item: PROJ-123
Local modified: 2025-01-15 10:30:00
Remote modified: 2025-01-15 10:35:00
```

**Solutions:**

1. View conflicts:
```bash
rtm integration sync conflicts production-jira
```

2. Resolve manually:
```bash
# Choose local version
rtm integration sync resolve-conflict \
  --conflict-id abc123 \
  --strategy local_wins

# Choose remote version
rtm integration sync resolve-conflict \
  --conflict-id abc123 \
  --strategy remote_wins
```

3. Prevent conflicts:
```bash
# Set default strategy
rtm integration sync config production-jira \
  --conflict-strategy last_write_wins
```

### Issue: Webhook Not Receiving Events

**Symptoms:**
- Jira webhook shows errors
- TracerTM not updating in real-time

**Solutions:**

1. Check webhook receiver status:
```bash
rtm integration webhook status
```

2. Verify webhook URL is accessible:
```bash
curl -X POST https://your-server.com:8080/webhooks/jira \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-secret" \
  -d '{"webhookEvent":"jira:issue_created"}'
```

3. Check firewall/network:
   - Ensure port is open
   - Verify HTTPS certificate is valid
   - Check reverse proxy configuration

4. Review webhook logs:
```bash
rtm integration webhook logs production-jira --follow
```

### Issue: Rate Limiting

**Symptoms:**
```
Error: Rate limit exceeded
Retry after: 60 seconds
```

**Solutions:**

1. Reduce sync frequency:
```bash
rtm integration sync config production-jira \
  --interval 600  # 10 minutes instead of 5
```

2. Use batching:
```bash
rtm integration sync config production-jira \
  --batch-size 50 \
  --batch-delay 2  # 2 seconds between batches
```

3. Check Jira rate limits:
   - Jira Cloud: 10 requests/second per user
   - Jira Server: Varies by configuration

## Best Practices

### 1. Initial Import Strategy

```bash
# Start with validation
rtm import jira export.json --validate-only

# Do a dry run
rtm import jira export.json --dry-run --project "Test Import"

# Import to test project first
rtm import jira export.json --project "Test Import"

# Review and verify
rtm project switch "Test Import"
rtm item list
rtm link list

# Import to production
rtm import jira export.json --project "Production"
```

### 2. Incremental Sync

Instead of full imports, use incremental sync:

```bash
# Import initial data
rtm import jira --project PROJ --target-project "My Project"

# Enable sync for updates only
rtm integration sync enable production-jira \
  --mode incremental \
  --since "2025-01-01"
```

### 3. Field Mapping

Create comprehensive mapping files:

```yaml
# comprehensive-mapping.yaml
field_mappings:
  # Standard fields
  summary: title
  description: description
  status: status
  issuetype: item_type
  priority: priority

  # Custom fields with transformations
  customfield_10001:
    target: business_value
    type: number
    transform: "lambda x: int(x) if x else 0"

  customfield_10002:
    target: acceptance_criteria
    type: text
    preserve_formatting: true

  # Array fields
  labels:
    target: tags
    type: array

  components:
    target: components
    type: array
    extract: name
```

### 4. Monitoring and Alerts

Set up monitoring for integration health:

```bash
# Configure alerts
rtm integration alert production-jira \
  --on-failure email \
  --email "team@company.com" \
  --on-conflict slack \
  --webhook "https://hooks.slack.com/..."

# Health check endpoint
rtm integration health production-jira --format json

# Schedule health checks (cron)
*/15 * * * * rtm integration health production-jira || \
  echo "Jira integration unhealthy" | mail -s "Alert" team@company.com
```

### 5. Backup Before Sync

```bash
# Backup before major sync operations
rtm backup create --name "pre-jira-sync-$(date +%Y%m%d)"

# Perform sync
rtm integration sync both production-jira

# Verify sync
rtm integration sync status production-jira

# Restore if needed
rtm backup restore "pre-jira-sync-20250115"
```

### 6. Performance Optimization

```bash
# For large imports, use batching
rtm import jira export.json \
  --project "My Project" \
  --batch-size 100 \
  --parallel 4 \
  --no-validate  # Skip validation for trusted exports

# Use connection pooling for sync
rtm integration sync config production-jira \
  --pool-size 5 \
  --pool-timeout 30
```

## Next Steps

- [Configure additional integrations](/docs/wiki/concepts/integrations)
- [Set up GitHub integration](/docs/wiki/examples/github-integration)
- [Learn about webhooks](/docs/wiki/concepts/webhooks)
- [Explore API endpoints](/api)

## Additional Resources

- [Jira REST API Documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/)
- [TracerTM Integration Guide](/docs/developer/integrations)
- [Webhook Security Best Practices](/docs/developer/security/webhooks)
- [Field Mapping Reference](/docs/developer/field-mapping)
