Jira Service Management Bi-Directional Sync

Bi-directional synchronization between Incidents and Jira Service Management enables real-time incident updates across both systems. Changes made in either system automatically propagate to the other within seconds.

Overview#

The bi-directional sync provides:

• Real-time Updates: Changes sync within 5 seconds
• Field Ownership: Control which system owns each field
• Conflict Resolution: Automatic handling of simultaneous edits
• Drift Detection: Periodic reconciliation to catch missed updates

Prerequisites#

• Jira Cloud or Data Center instance
• API token with project admin permissions
• Network connectivity between systems
• Webhook endpoint accessible from Jira

Configuration#

Step 1: Create Integration#

Use the CLI to create a new Jira integration:

im integration configure \
  --name "Production Jira SM" \
  --type jira \
  --org acme-corp \
  --base-url "https://your-instance.atlassian.net" \
  --direction bidirectional \
  --email "api-user@example.com" \
  --api-key "your_api_token"

Or use the API:

curl -X POST http://localhost:8080/api/v1/integrations \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "acme-corp",
    "integration_type": "jira",
    "name": "Production Jira SM",
    "base_url": "https://your-instance.atlassian.net",
    "credentials": {
      "email": "api-user@example.com",
      "api_key": "your_api_token"
    },
    "sync_direction": "bidirectional",
    "enabled": true
  }'

Step 2: Configure Webhook in Jira#

1. Navigate to Settings > System > WebHooks in Jira

2. Click Create a WebHook

3. Configure:

   • Name: Incidents Platform Sync
   • URL: https://your-incidents-server/api/v1/webhooks/{integration_id}
   • Events: Issue created, Issue updated, Issue deleted
   • JQL Filter (optional): project = INCIDENT

4. Save and note the webhook secret for signature validation

Step 3: Configure Project Mapping#

Map Jira projects to your organization:

# Set the default project for new incidents
im integration configure prod-jira --project-key INCIDENT

# Map issue types
im integration configure prod-jira --issue-type "Incident"

Step 4: Configure Field Ownership#

Set up field ownership rules:

# Platform owns severity and priority
im integration field-ownership set prod-jira severity --owner platform --priority 10
im integration field-ownership set prod-jira priority --owner platform --priority 10

# Jira owns assignee and comments
im integration field-ownership set prod-jira assignee --owner external --priority 5
im integration field-ownership set prod-jira comments --owner external --priority 5

Field Mapping#

Priority Mapping#

Status Mapping#

Conflict Resolution#

When simultaneous edits occur within 5 seconds:

Last-Write-Wins (Default)#

im integration configure prod-jira --conflict-strategy last-write-wins

Ownership-Priority#

im integration configure prod-jira --conflict-strategy ownership-priority

Manual Review#

im integration configure prod-jira --conflict-strategy manual-review

# View and resolve conflicts
im conflict list --integration prod-jira
im conflict resolve conflict-123 --use-external

Drift Detection#

On-Demand Reconciliation#

# Check for drift
im integration reconcile prod-jira --dry-run

# Fix drift automatically
im integration reconcile prod-jira --auto-heal

Scheduled Reconciliation#

curl -X POST http://localhost:8080/api/v1/integrations/{id}/reconcile/schedule \
  -d '{"interval": "1h", "auto_heal": true}'

Custom Field Mapping#

Map custom Jira fields to Incidents:

# Map a custom field
im integration field-mapping add prod-jira \
  --incidents-field "impact" \
  --jira-field "customfield_10001"

ADF Description Support#

Jira uses Atlassian Document Format (ADF) for rich text descriptions. The sync automatically converts between plain text and ADF.

Monitoring#

# Check integration health
im integration sync-status prod-jira

# View sync metrics
im integration sync-status prod-jira --format json

Testing#

Test the integration:

im integration test prod-jira

Troubleshooting#

JWT Validation Errors#

Ensure your webhook secret matches what’s configured in Jira. JWT tokens must be signed with HS256.

Rate Limiting#

Jira Cloud has rate limits. The sync automatically handles backoff:

• 100 requests per minute for standard tier
• Enable rate limiting in the integration config

Field Sync Issues#

1. Check field ownership configuration
2. Verify custom field IDs match your Jira instance
3. Ensure API user has field edit permissions