Jira Integration

GuideMode integrates with Jira Cloud to provide visibility into your project management workflow. This integration enables team sync, issue tracking via webhooks, and links Jira work items to your development analytics.

What You Get

• Team Sync: Sync Jira teams or groups to GuideMode for team-based analytics
• Issue Tracking: Real-time updates on issue creation and changes via webhooks
• User Linking: Automatically link Jira users to GuideMode accounts by email
• Work Analytics: Connect Jira issues to your development metrics

Prerequisites

Before setting up the Jira integration, you’ll need:

• A Jira Cloud account (Jira Server/Data Center not currently supported)
• Admin access to your Jira site (for webhooks and team sync)
• Admin permissions in your GuideMode tenant

Setup Overview

The Jira integration uses:

1. OAuth Connection - For user authentication and API access (GuideMode handles the OAuth app)
2. Webhooks - For real-time issue updates (created from GuideMode settings)
3. API Token (optional) - For enhanced team sync capabilities

Step 1: Connect Your Jira Account

1. Navigate to Settings > Integrations > Jira in GuideMode
2. Click Connect with Jira
3. Authorize GuideMode to access your Atlassian account
4. Select which Jira sites to grant access to
5. You’ll be redirected back to GuideMode once connected

Step 2: Admin Authorization

To use webhooks and team sync, you need admin-level permissions:

1. Go to Settings > Integrations > Jira
2. Click Re-authenticate with Admin Permissions
3. Approve the additional permission scopes
4. Your account now has admin capabilities for webhooks and team sync

Team Sync

GuideMode can sync your Jira teams to enable team-based analytics.

Two Sync Methods

GuideMode supports two methods for team sync:

Method	Requires	What’s Synced	Best For
Team API	API Token	Actual Jira teams	Organizations with formal teams
Groups API	OAuth only	Jira groups	Quick setup without API token

Method 1: Team API (Recommended)

The Team API syncs actual Jira teams with full membership data.

Setup:

1. Create an API token at Atlassian Account Settings
2. Go to Settings > Integrations > Jira in GuideMode
3. Enter your:
   • Email address: The email associated with your Atlassian account
   • API Token: The token you generated
   • Organization ID: Found in your Jira admin settings
4. Click Save API Token

Triggering a Sync:

1. Click Sync Teams
2. Wait for the sync to complete
3. Review synced teams in Settings > Teams

Method 2: Groups API (Fallback)

If you don’t want to set up an API token, GuideMode can sync Jira groups instead.

Note: Jira groups are not the same as teams. Groups are typically used for permissions, while teams are project-based. For best results, use the Team API.

How it works:

• Uses your OAuth token (no API token needed)
• Syncs all groups you have access to
• Creates teams in GuideMode for each group
• Links members by email

What Gets Synced

Data	Description
Teams/Groups	Name, description, membership
Members	User profiles, email addresses
Roles	Member roles within teams

User Linking

When syncing, GuideMode links Jira users to existing accounts:

1. By Jira Account ID: If user was previously synced
2. By Email: If emails match between systems
3. New User: Created if no match found (requires email access)

Users with private email settings may not be linkable.

Webhook Configuration

Webhooks provide real-time updates when issues change in Jira.

Creating a Webhook

1. Go to Settings > Integrations > Jira
2. Select the Jira site to configure
3. Click Create Webhook
4. Configure options:
   • Events: Issue created, Issue updated, Issue deleted
   • JQL Filter (optional): Filter which issues trigger webhooks

Webhook Events

Event	When Triggered
jira:issue_created	New issue is created
jira:issue_updated	Issue fields are modified
jira:issue_deleted	Issue is deleted

Webhook Expiration

Jira webhooks expire after 30 days. GuideMode will:

• Notify you before expiration
• Allow you to extend the webhook
• Automatically prompt for refresh

To extend a webhook:

1. Go to Settings > Integrations > Jira
2. Find the webhook in the list
3. Click Refresh to extend by 30 days

JQL Filtering

You can filter which issues trigger webhooks using JQL:

project = "MYPROJECT" AND issuetype != "Sub-task"

This reduces webhook volume and focuses on relevant issues.

Issue Type Mapping

GuideMode maps Jira issue types to canonical categories for consistent analytics.

Jira-Specific Mappings

Jira Type	GuideMode Type
Story, New Feature, Epic	feature
Bug, Defect	bug
Task, Technical Task	chore
Spike, Research	discovery
Incident	incident

See Issues → Type Mapping for default heuristics and how to configure custom mappings.

Custom Mappings

You can configure custom type mappings per project in Settings > Integrations > Jira > Issue Mappings. Custom mappings take priority over defaults.

Issue State Tracking

Jira provides richer state information. GuideMode maps status categories to canonical states:

Jira Category	GuideMode State
To Do	open
In Progress	in_progress
Done	closed

This enables more accurate cycle time and flow metrics.

Troubleshooting

Jira Login Fails

• Try disconnecting and reconnecting your Jira account in Settings > Integrations > Jira
• Ensure you’re logged into the correct Atlassian account
• Check that you have authorized GuideMode to access your account

Cannot Create Webhooks

• Ensure you have admin-level OAuth permissions
• Re-authenticate with admin scopes if needed (see Step 2)
• Check that you have admin access to the Jira site

Team Sync Fails

• With API Token: Verify token is valid and not expired at Atlassian Account Settings
• Without API Token: Ensure you have access to view groups
• Confirm organization ID is correct
• Check that you have access to the teams/groups

Users Not Linking

• Users must have public email addresses in their Atlassian profile
• Verify emails match between Jira and GuideMode
• Check that you have email access permissions

Webhooks Not Received

• Verify webhook hasn’t expired (30-day limit)
• Check webhook status in Settings > Integrations > Jira
• Review JQL filter isn’t too restrictive
• Click Refresh to renew expired webhooks

Stale Webhook Data

• Webhooks only capture changes after creation
• Historical data requires manual import or API sync
• Ensure webhook hasn’t lapsed (30-day expiration)

Limitations

Jira Cloud Only

This integration supports Jira Cloud only. Jira Server and Data Center are not currently supported due to different authentication mechanisms.

API Rate Limits

Atlassian enforces API rate limits. Heavy sync operations may be throttled. Team sync is designed to minimize API calls through batching.

Private Profiles

Users with private email settings cannot be automatically linked. They’ll need to manually connect their accounts or make their email visible in their Atlassian profile.

Related Documentation

Core Concepts

• Issues - Canonical issue types and lifecycle
• Teams - Team structure and sync
• People - User identity linking

Analytics

• Delivery Flow - Issue metrics and cycle time
• How It Works - DX² methodology