Incidents

Jira Service Management

Overview

The Jira Service Management connector enables bi-directional synchronization between the incident management platform and Jira Service Management, providing seamless integration with your existing ITSM processes.

Key Benefits:

  • Unified incident tracking across both platforms
  • Leverage existing Jira workflows and approvals
  • Rich metadata support with custom fields
  • Real-time synchronization via webhooks
  • Intelligent conflict resolution

Features

✅ Bi-directional Sync: Create, update, and sync incidents between both systems
✅ Field Mapping: Configurable field mappings for status, priority, and severity
✅ Webhook Support: Real-time updates from Jira SM to incident management platform
✅ Conflict Resolution: Intelligent handling of field conflicts between systems
✅ Rich Metadata: Supports Jira-specific fields like issue types, projects, and components
✅ Custom Fields: Synchronize custom fields and labels
✅ Attachment Sync: File attachments synchronized between platforms

Prerequisites

Before setting up the integration:

  1. Jira Cloud instance with Service Management enabled
  2. API Token from Atlassian Account Settings
  3. Appropriate Permissions in your Jira project
  4. Project Key where incidents will be created (e.g., ITSM, INCIDENT)
  5. Issue Type ID for incident issues (typically Service Request or Incident)

Required Permissions

  • Create issues in the target project
  • Edit issues in the target project
  • Add comments to issues
  • Transition issues through workflow states
  • View project and Browse users (for assignments)

Quick Setup

Step 1: Generate Jira API Token

  1. Go to Atlassian Account Settings: https://id.atlassian.com/manage/api-tokens
  2. Click “Create API token”
  3. Enter label: “Incident Management Integration”
  4. Copy the token (shown only once)

Step 2: Add Jira Connector

Interactive Configuration 

# Add connector with interactive prompts
./im connector add jira my-jira-instance

# You'll be prompted for:
# - Jira instance URL (e.g., https://yourcompany.atlassian.net)
# - Email address (your Atlassian account email)
# - API Token (from Step 1)
# - Project Key (e.g., ITSM)
# - Sync Direction (bidirectional recommended)

JSON Configuration 

./im connector add jira my-jira-instance --config '{
  "base_url": "https://yourcompany.atlassian.net",
  "username": "your-email@company.com",
  "api_key": "your-api-token",
  "sync_direction": "bidirectional",
  "sync_interval": "5m",
  "enable_webhook": true,
  "custom": {
    "project_key": "ITSM",
    "issue_type": "10004",
    "default_assignee": "incident-manager"
  }
}'

Step 3: Test the Connection 

./im connector test my-jira-instance

# Output:
✓ Connected to Jira instance
✓ Project ITSM accessible
✓ Issue type 10004 (Service Request) found
✓ User permissions verified
✓ Webhook endpoint configured

Configuration Parameters

Required Settings

Parameter Description Example
base_url Jira instance URL https://yourcompany.atlassian.net
username Atlassian account email admin@company.com
api_key API token from Atlassian ATATT3xFfGF0...
custom.project_key Jira project key ITSM

Optional Settings

Parameter Description Default
sync_direction Sync mode outbound
sync_interval Sync frequency 5m
enable_webhook Real-time updates true
custom.issue_type Issue type ID 10004
custom.default_assignee Default assignee -

Advanced Configuration 

{
  "base_url": "https://yourcompany.atlassian.net",
  "username": "admin@company.com",
  "api_key": "your-api-token",
  "sync_direction": "bidirectional",
  "sync_interval": "3m",
  "enable_webhook": true,
  "custom": {
    "project_key": "ITSM",
    "issue_type": "10004",
    "default_assignee": "incident-manager",
    "priority_mapping": {
      "SEV-1": "1",
      "SEV-2": "2",
      "SEV-3": "3",
      "SEV-4": "4"
    },
    "status_mapping": {
      "open": "To Do",
      "mitigated": "In Progress",
      "resolved": "Done",
      "closed": "Done"
    },
    "custom_fields": {
      "severity": "customfield_10001",
      "service": "customfield_10002",
      "impact": "customfield_10003"
    },
    "sync_attachments": true,
    "sync_comments": true,
    "auto_transition": true
  }
}

Field Mappings

Status Synchronization

IM Status Jira Status Transition Description
open To Do Create New incident reported
mitigated In Progress Start Progress Someone is working on it
resolved Done Complete Issue is fixed
closed Done Complete Final closure

Priority/Severity Mapping

IM Severity Jira Priority Priority ID Description
SEV-1 Highest 1 Critical system outage
SEV-2 High 2 Major functionality impact
SEV-3 Medium 3 Minor functionality impact
SEV-4 Low 4 Informational or planned

Core Field Mappings

IM Field Jira Field Format Notes
Title Summary Text Direct mapping
Description Description ADF/Wiki Converted to Atlassian Document Format
Service Labels Array Prefixed with service-
Severity Labels/Custom Array/Select Configurable via custom fields
Assignee Assignee User Based on email or username
Created Created DateTime System managed
Updated Updated DateTime System managed

Custom Field Support 

{
  "custom_fields": {
    "severity": "customfield_10001",
    "impact": "customfield_10002",
    "urgency": "customfield_10003",
    "service_category": "customfield_10004",
    "customer_impact": "customfield_10005"
  }
}

Usage Examples

Basic Operations

List Connectors 

./im connector list

# Output:
Name              Type    Status    Direction     Last Sync
my-jira-instance  jira    active    bidirectional 1m ago
prod-pagerduty    pagerduty active  bidirectional 2m ago

View Connector Details 

./im connector status my-jira-instance

# Output:
Connector: my-jira-instance (jira)
Status: Active
Direction: Bidirectional
Project: ITSM
Issue Type: Service Request (10004)
Last Sync: 2025-08-23 15:45:00
Issues Synced: 23 (last 24h)
Sync Errors: 0
Webhook: Enabled

Manual Synchronization 

# Force immediate sync
./im connector sync my-jira-instance

# Sync specific incident
./im connector sync my-jira-instance --incident INC-12345

# Sync from Jira to IM platform
./im connector sync my-jira-instance --direction inbound

Incident Workflows

Creating Incidents

When you create an incident in the platform, it automatically creates a Jira issue:

# Create incident
./im declare --sev SEV-2 --title "Database performance degradation" \
  --service database --description "Query response times increased 300%"

# Jira issue created with:
# - Summary: "Database performance degradation"
# - Priority: High (SEV-2 mapping)
# - Labels: ["severity-sev2", "service-database"]
# - Description: Formatted description with incident metadata

Updating Incidents 

# Add timeline update
./im update --incident INC-12345 --note "Applied database index optimization"

# Automatically adds comment to Jira issue:
# - Comment author: System or user who made the update
# - Comment body: "Applied database index optimization"
# - Timestamp: Synchronized between systems

Status Transitions 

# Acknowledge incident
./im ack --incident INC-12345 --note "Investigating database performance"

# Jira issue transitions:
# - Status: To Do → In Progress
# - Assignee: Set to acknowledging user
# - Comment: "Investigating database performance"

Webhook Configuration

Configure Jira Webhooks

  1. Go to Jira Administration:

    • Settings → System → WebHooks

  2. Create Webhook:

    • Name: Incident Management Integration
    • URL: https://your-domain.com/connectors/my-jira-instance/webhook
    • Events: Select relevant events: 
      ☑ Issue created
☑ Issue updated
☑ Issue deleted
☑ Issue commented
☑ Issue transitioned

  3. JQL Filter (Optional):

    project = ITSM AND issuetype = "Service Request"

  4. Test Webhook:

    ./im connector webhook my-jira-instance --test

# Creates test issue in Jira to verify webhook delivery

Supported Webhook Events

Jira Event Trigger IM Platform Action
issue_created New issue created Create corresponding incident
issue_updated Issue fields changed Update incident fields
issue_commented Comment added Add timeline event
issue_transitioned Status changed Update incident status
issue_assigned Assignee changed Update incident assignee
issue_deleted Issue deleted Archive incident (configurable)

Webhook Security 

# Configure webhook authentication
./im connector config my-jira-instance --webhook-secret "shared-secret"

# Jira webhook configuration includes:
# - Secret token for request validation
# - IP whitelisting for Atlassian IPs
# - HTTPS requirement for webhook endpoints

Advanced Features

Project & Issue Type Mapping

Handle multiple projects or issue types:

{
  "project_mappings": {
    "api": "API", // API incidents → API project
    "database": "DATA", // DB incidents → DATA project
    "web": "WEB", // Web incidents → WEB project
    "default": "ITSM" // Default project for unmapped services
  },
  "issue_type_mappings": {
    "SEV-1": "10001", // Critical → Incident type
    "SEV-2": "10001", // Major → Incident type
    "SEV-3": "10004", // Minor → Service Request type
    "SEV-4": "10004" // Info → Service Request type
  }
}

Custom Field Synchronization

Sync custom fields between platforms:

# Configure custom field mapping
./im connector config my-jira-instance --custom-fields '{
  "impact_assessment": "customfield_10010",
  "customer_count": "customfield_10011",
  "business_impact": "customfield_10012",
  "resolution_category": "customfield_10013"
}'

# Custom fields are synchronized bidirectionally
# Values are validated against Jira field types

Attachment Synchronization

Enable file attachment sync between platforms:

{
  "sync_attachments": true,
  "attachment_settings": {
    "max_size": "10MB",
    "allowed_types": [".jpg", ".png", ".pdf", ".txt", ".log"],
    "sync_direction": "bidirectional"
  }
}

Comment Synchronization

Control how comments and timeline events are synced:

{
  "sync_comments": true,
  "comment_settings": {
    "sync_direction": "bidirectional",
    "prefix_system_comments": true,
    "exclude_automation": false,
    "mention_mapping": {
      "john.doe@company.com": "jdoe"
    }
  }
}

Conflict Resolution

Handling Field Conflicts

When the same field is modified in both systems:

Last Writer Wins (Default) 

{
  "conflict_resolution": "last_writer_wins",
  "conflict_settings": {
    "grace_period": "5m", // Allow 5 minutes for manual resolution
    "notify_conflicts": true,
    "log_conflicts": true
  }
}

Field-Specific Rules 

{
  "conflict_resolution": "field_specific",
  "field_rules": {
    "status": "jira_wins", // Jira status changes take precedence
    "assignee": "im_wins", // IM platform assignment wins
    "priority": "highest_wins", // Highest priority wins
    "description": "merge" // Attempt to merge descriptions
  }
}

Manual Resolution 

# View conflicts requiring manual resolution
./im connector conflicts my-jira-instance

# Resolve specific conflict
./im connector resolve-conflict my-jira-instance --incident INC-12345 \
  --field priority --source jira --reason "Business decision"

Workflow Integration

Jira Workflow Configuration

Ensure your Jira project workflow supports the required transitions:

Required Transitions

  1. Create → To Do (automatic on issue creation)
  2. To Do → In Progress (when incident acknowledged)
  3. In Progress → Done (when incident resolved)
  4. Done → In Progress (if incident reopened)

Workflow Validation 

# Validate workflow compatibility
./im connector validate-workflow my-jira-instance

# Output:
Workflow: IT Service Management
✓ Create transition available
✓ Start Progress transition available
✓ Complete transition available
✓ Reopen transition available
⚠ Custom transition "Escalate" not mapped

Approval Integration

Integrate with Jira approval workflows:

{
  "approval_settings": {
    "require_approval_for": ["SEV-1", "SEV-2"],
    "approval_field": "customfield_10020",
    "auto_proceed_on_approval": true,
    "notify_on_approval": true
  }
}

Monitoring & Troubleshooting

Health Checks 

# Check connector health
./im connector health my-jira-instance

# Output:
Health: Healthy
API Connectivity: ✓ Connected (120ms response time)
Authentication: ✓ Valid API token
Project Access: ✓ ITSM project accessible
Issue Type: ✓ Service Request (10004) available
Webhook: ✓ Receiving events (last: 45s ago)
Sync Status: ✓ Up to date (last sync: 1m ago)
Error Rate: 0% (0 errors in 24h)

Common Issues

Authentication Failures

Symptoms: 401 Unauthorized errors

Solutions:

# Verify API token and email
curl -u your-email@company.com:your-api-token \
     -H "Accept: application/json" \
     https://yourcompany.atlassian.net/rest/api/3/myself

# Check token permissions
# Regenerate token if expired
./im connector update my-jira-instance --api-key new-token

Project/Issue Type Errors

Symptoms: 400 Bad Request when creating issues

Solutions:

# List available projects
curl -u your-email@company.com:your-api-token \
     https://yourcompany.atlassian.net/rest/api/3/project

# List issue types for project
curl -u your-email@company.com:your-api-token \
     https://yourcompany.atlassian.net/rest/api/3/project/ITSM/issuetypes

# Update configuration with correct IDs
./im connector config my-jira-instance --project-key CORRECT_KEY --issue-type CORRECT_ID

Webhook Delivery Issues

Symptoms: Delayed or missing updates from Jira

Solutions:

# Test webhook endpoint
curl -X POST https://your-domain.com/connectors/my-jira-instance/webhook \
     -H "Content-Type: application/json" \
     -d '{"test": "webhook"}'

# Check webhook configuration in Jira
# Verify firewall allows Atlassian IPs
# Review webhook logs in Jira admin

Debug Mode 

# Enable detailed logging
export JIRA_DEBUG=true
./im serve

# View recent API calls
./im logs --component jira-connector --level debug

# Monitor webhook events
./im logs --component webhook --filter jira

Performance Monitoring 

# View connector performance metrics
./im metrics connector my-jira-instance

# Output:
Connector: my-jira-instance
Total Issues: 89
Sync Success Rate: 98.9%
Average Sync Time: 2.4s
API Calls (24h): 567
Rate Limit Usage: 15%
Webhook Events (24h): 34
Conflict Resolution: 2 conflicts (auto-resolved)

Best Practices

Configuration Best Practices

  • Use project-specific service accounts for API access
  • Configure separate projects for different service categories
  • Map custom fields to capture incident-specific metadata
  • Enable webhooks for real-time synchronization
  • Set up appropriate Jira workflows with required transitions

Data Management

  • Use consistent naming conventions across both platforms
  • Map severity levels to appropriate Jira priorities
  • Synchronize attachments for complete incident context
  • Archive resolved incidents according to retention policies

Security & Compliance

  • Rotate API tokens regularly (quarterly recommended)
  • Use HTTPS for all API communications
  • Configure IP whitelisting for webhook endpoints
  • Monitor API usage and rate limiting
  • Maintain audit logs for compliance requirements

Performance Optimization

  • Configure appropriate sync intervals based on volume
  • Use JQL filters to limit webhook scope
  • Implement retry logic with exponential backoff
  • Monitor and tune field mapping complexity
  • Batch operations when possible

Integration Examples

Enterprise Workflow 

# Complete incident lifecycle with Jira integration:
1. Monitoring Alert → Incident declared in IM platform
2. Jira issue created automatically in ITSM project
3. On-call engineer acknowledges → Jira transitions to In Progress
4. Investigation updates → Comments added to Jira issue
5. Resolution deployed → Incident resolved, Jira transitioned to Done
6. Post-mortem attached → File uploaded to both systems
7. Incident closed → Final Jira status update

Custom Field Mapping Example 

{
  "field_mappings": {
    "business_impact": {
      "jira_field": "customfield_10001",
      "type": "select",
      "values": {
        "high": "High Business Impact",
        "medium": "Medium Business Impact",
        "low": "Low Business Impact"
      }
    },
    "customer_count": {
      "jira_field": "customfield_10002",
      "type": "number",
      "validation": "integer"
    },
    "service_category": {
      "jira_field": "customfield_10003",
      "type": "multi_select",
      "values": ["Infrastructure", "Application", "Network", "Security"]
    }
  }
}

Reporting Integration 

# Generate combined reports from both systems
./im report --start 2025-08-01 --end 2025-08-31 \
  --include-jira --format xlsx \
  --output "incident-report-august.xlsx"

# Report includes:
# - Incident timelines with Jira issue links
# - Resolution times from both platforms
# - Comment/update synchronization status
# - Custom field data from Jira
# - Workflow transition history

This comprehensive Jira Service Management integration provides seamless ITSM workflow integration while maintaining the benefits of both platforms’ unique capabilities.

Edit this page on GitHub
Prev
State Machine Developer Guide
Next
Jira Service Management Troubleshooting