Jira Software Integration

Prerequisites

Requirement	Details
Jira Cloud or Server	Project Admin role on target projects
Atlassian account	API token generation requires account access
StackFlow role	super_admin or itsm_manager

Step 1: Generate Jira API Token

1. Log into your Atlassian account at id.atlassian.com
2. Click Create API token
3. Name it StackFlow Integration and click Create
4. Copy the token — it is shown only once
5. Note your Jira Cloud URL (e.g., https://your-org.atlassian.net) and the account email

Step 2: Configure Project Key Mapping

Map Jira project keys to StackFlow modules and assignment groups:

{
  "project_mapping": [
    {
      "jira_project_key": "OPS",
      "jira_issue_type": "Bug",
      "stackflow_module": "incidents",
      "stackflow_assignment_group": "Platform Engineering",
      "stackflow_category": "software",
      "sync_direction": "bidirectional"
    },
    {
      "jira_project_key": "INFRA",
      "jira_issue_type": "Task",
      "stackflow_module": "changes",
      "sync_direction": "jira_to_stackflow"
    }
  ]
}

Step 3: Set Up Webhooks

1. In Jira, go to Settings → System → WebHooks → Create a WebHook
2. Set the URL to: https://your-instance.stackflow-tech.com/prod/api/webhooks/inbound/jira
3. Select the events: Issue Created, Issue Updated, Issue Deleted, Comment Created
4. Set JQL filter (optional): project in (OPS, INFRA) AND labels = stackflow-sync

Step 4: Connect in StackFlow

1. Navigate to Admin → Integration Hub → Jira → Configure
2. Enter the Jira base URL, account email, and API token
3. Configure the project mapping table
4. Set the StackFlow webhook URL in Jira (from step 3)
5. Click Save & Test

Bidirectional Status Sync

StackFlow State	Jira Status
new	To Do / Open
in_progress	In Progress
on_hold	Blocked / On Hold
resolved	Done / Resolved
closed	Closed

Field Mapping

StackFlow Field	Jira Field	Notes
short_description	Summary	Bidirectional
description	Description	Bidirectional
priority	Priority	P1→Highest, P2→High, P3→Medium, P4→Low
assigned_to	Assignee	Matched by email; unmatched defaults to unassigned
work_notes	Comments	StackFlow work notes sync as Jira comments

Field Reference

Field	Required	Description
Jira Base URL	Yes	e.g., https://your-org.atlassian.net
Account Email	Yes	Email of the Atlassian account that owns the API token
API Token	Yes	Atlassian API token
Project Mapping	Yes	Map Jira projects to StackFlow modules
Sync Comments	No	Sync Jira comments as StackFlow work notes (default: true)
Create Jira Label	No	Auto-add label stackflow-sync to synced issues (default: true)

Testing the Integration

1. Create a Jira issue in a mapped project and verify a StackFlow incident/change is created
2. Update the Jira issue status and verify StackFlow state changes
3. Add a comment in Jira and verify it appears as a work note in StackFlow

# Trigger a manual sync for a specific Jira issue
curl -X POST   https://your-instance.stackflow-tech.com/prod/api/integrations/jira/sync   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"jira_issue_key": "OPS-1234"}'

Troubleshooting

Issue	Cause	Fix
401 Unauthorized on Jira API calls	API token expired or invalid	Regenerate token at id.atlassian.com and update in Integration Hub
Assignee not syncing	Email mismatch between Jira and StackFlow	Ensure the Jira user's email matches StackFlow account email exactly
Missing Jira webhook events	JQL filter too restrictive	Remove JQL filter or add the stackflow-sync label to test issues
Duplicate issues created	Both webhook and polling triggering	Disable polling if webhook is configured; check for duplicate webhook subscriptions