Jira Integration Guide
Complete guide to connecting PlanningForge with Jira for seamless story import and estimate export workflows.
Table of Contents
Integration Overview
PlanningForge's Jira integration streamlines your agile workflow by connecting planning poker sessions directly to your Jira projects. Import user stories, estimate them with your team, and sync the results back to Jira automatically.
What You Can Do
- Import stories from Jira backlogs and epics
- Run planning sessions with imported stories
- Export story point estimates back to Jira
- Sync story status and metadata
- Automate estimation workflows
Supported Jira Versions
- Jira Cloud (Software & Service Management)
- Jira Server 8.5+ (on-premise)
- Jira Data Center 8.5+
- Custom field mapping support
- REST API v2 and v3 compatibility
Integration Benefits
Reduce context switching, maintain a single source of truth for estimates, and eliminate manual data entry between planning sessions and your backlog management.
Initial Setup
Prerequisites
Required Permissions
- PlanningForge: Team Owner or Admin role
- Jira: Project Administrator or higher
- Browse Projects: Access to projects you want to integrate
Before You Begin
- Identify which Jira projects you want to connect
- Decide on story point field mapping strategy
- Determine estimation scale to use (Fibonacci, T-shirt, etc.)
- Plan your import and export workflows
Access Integration Settings
- Navigate to your team dashboard in PlanningForge
- Click on Team Settings in the sidebar
- Select the Integrations tab
- Find Jira in the list of available integrations
- Click Configure Integration
Authentication Configuration
OAuth 2.0 Authentication
PlanningForge uses OAuth 2.0 for secure Jira integration. This provides the best security, easy setup, and doesn't require sharing passwords.
OAuth 2.0 Setup (Recommended)
Step 1: Enable OAuth in PlanningForge
- Go to your team's Jira integration settings in PlanningForge
- Select OAuth 2.0 as the authentication method
- Click Connect with Jira button
- You'll be redirected to Atlassian's authorization page
Step 2: Authorize PlanningForge
- Log into your Atlassian account when prompted
- Review the permissions PlanningForge is requesting:
- View Jira issue data
- Edit issues (for updating story points)
- Access project information
- Click Accept to grant permissions
- You'll be redirected back to PlanningForge with a success message
Step 3: Select Jira Site
- If you have access to multiple Jira sites, select the one you want to integrate
- Choose the specific projects you want to access
- Test the connection to verify everything is working
- Your integration is now ready to use!
OAuth Benefits
- • No need to create or manage API tokens
- • Secure authorization without sharing passwords
- • Easy to revoke access from Atlassian account settings
- • Automatic token refresh for uninterrupted access
- • Respects your existing Jira permissions
Managing Your Jira Connection
Revoking Access
- Go to your Atlassian account apps and revoke PlanningForge access
- In PlanningForge, click "Disconnect" in integration settings
Reconnecting
- If your connection expires or fails, simply repeat the OAuth authorization process
- OAuth connections automatically refresh, but may need re-authorization occasionally
- Check integration status in team settings for connection health
Security Best Practices
OAuth 2.0 is the most secure authentication method as it doesn't require sharing credentials and provides granular permission control.
Importing Stories
Creating an Import Session
- Start creating a new planning session in PlanningForge
- In the story source section, select Import from Jira
- Choose your configured Jira project from the dropdown
- Select your import criteria (see options below)
- Preview the stories that will be imported
- Click Import Stories to proceed
Import Options
By Sprint
- Import all stories from a specific sprint
- Perfect for sprint planning sessions
- Includes story status and current estimates
- Can filter by story type (Story, Bug, Task)
By Epic
- Import all stories linked to an epic
- Great for feature-based estimation
- Maintains epic hierarchy and relationships
- Can include sub-tasks if configured
By Filter/JQL
- Use Jira Query Language for advanced filtering
- Import based on custom criteria
- Supports complex conditions and date ranges
- Save frequently used queries as templates
By Backlog
- Import unestimated stories from project backlog
- Focus on stories without story points
- Ideal for backlog grooming sessions
- Configurable priority and status filters
Import Filtering
Available Filters
Issue Types
- Story
- Bug
- Task
- Epic (for epic-based imports)
- Custom issue types
Status Categories
- To Do
- In Progress
- Done
- Custom statuses
Priority Levels
- Highest
- High
- Medium
- Low
- Lowest
Estimation Status
- Unestimated stories only
- All stories
- Stories with specific estimates
- Stories needing re-estimation
Planning & Estimating
Once stories are imported from Jira, you can run planning poker sessions just like with manually created stories. The integration enriches the estimation process with Jira context and metadata.
Story Display & Context
Enhanced Story Cards
- Jira Key: Clickable link to original issue
- Description: Full Jira description with formatting
- Acceptance Criteria: Imported from Jira custom fields
- Priority & Labels: Visual indicators for context
- Epic Link: Shows parent epic relationship
- Current Estimate: Existing story points if any
Estimation Scale Mapping
PlanningForge supports multiple estimation scales and can map them to Jira's story point fields:
| PlanningForge Scale | Jira Field Type | Export Format |
|---|---|---|
| Fibonacci (0,1,2,3,5,8,13...) | Number Field | Direct numeric value |
| T-Shirt (XS,S,M,L,XL) | Select List | Mapped text values |
| Linear (1,2,3,4,5...) | Number Field | Direct numeric value |
| Custom Scale | Number or Text | User-defined mapping |
Session Management
Real-time Sync
- Session progress is tracked against Jira stories
- Participants can view original Jira issues during voting
- Comments and discussions are captured for export
- Story skipping preserves Jira metadata
Collaborative Features
- Share Jira context during team discussions
- Link to related issues and dependencies
- View epic progress and story relationships
- Access Jira attachments and linked items
Exporting Estimates
Automatic Export
Real-time Updates
By default, estimates are automatically synced back to Jira as soon as consensus is reached:
- Team reaches consensus on story points
- Estimate is immediately sent to Jira
- Jira story point field is updated
- Success confirmation shown in planning session
- Any errors are logged and can be retried
Manual Export Options
Batch Export After Session
- Complete your planning session
- Review all estimated stories in the session summary
- Click Export to Jira button
- Select which estimates to export (can exclude some)
- Choose export options and field mappings
- Confirm the export operation
Export Configuration
What Gets Exported
- Final consensus story point estimates
- Planning session comments and notes
- Participant list (optional)
- Estimation timestamp and session ID
Export Behavior Options
- Overwrite existing estimates
- Only update unestimated stories
- Create planning session comment in Jira
- Update story status (e.g., mark as "Estimated")
Export Validation
Pre-Export Checks
- Verify Jira connection is still active
- Check user permissions for target stories
- Validate story point field configuration
- Confirm stories haven't been moved or deleted
- Handle any field mapping conflicts
Field Mapping
Configure how data flows between PlanningForge and Jira by setting up field mappings that match your team's workflow and Jira configuration.
Accessing Field Mapping
Navigate to Team Settings → Jira Setup after connecting to Jira. The Field Mapping section appears below the project selector.
Story Point Field Configuration
Configuring the Export Field
- Click Refresh Fields from Jira to fetch available fields
- Select the story points field from the dropdown
- Click Save Field Mappings to apply
Common Story Point Fields
customfield_10016- Jira Cloud defaultcustomfield_10020- Legacy/alternative field- Story Points, Story Point Estimate, Estimate
Import Field Mappings
Configure which Jira fields map to story properties when importing issues:
| PlanningForge Field | Default Jira Source | Notes |
|---|---|---|
| Story Title | summary |
Required field |
| Description | description |
Supports rich text conversion |
| Story Type | issuetype |
Maps to Story, Bug, Task, etc. |
Field Cache
Fields are cached for 24 hours to minimize API calls. The cache status is shown next to the refresh button.
- Click Refresh Fields to force an update
- Cache automatically expires after 24 hours
- New fields in Jira require a manual refresh to appear
Automation & Workflows
Workflow Triggers
PlanningForge → Jira
- Estimate completed: Update story points
- Session finished: Transition story status
- Story skipped: Add skip reason comment
- Re-estimation: Update with new estimate
Jira → PlanningForge
- Story updated: Refresh imported data
- New stories added: Auto-import notifications
- Sprint planned: Trigger estimation session
- Epic created: Setup estimation workspace
Status Automation
Automatic Status Transitions
Configure PlanningForge to automatically move stories through your Jira workflow:
After Estimation
- Move from "Backlog" to "Ready for Development"
- Transition to "Estimated" status
- Add to current sprint automatically
- Assign to development team
Session Management
- Mark stories as "In Estimation" when session starts
- Revert status if session is cancelled
- Handle partial session completions
- Batch process multiple story transitions
Screenshot: Workflow automation configuration
Scheduled Tasks
Regular Sync Operations
- Daily Backlog Sync: Check for new unestimated stories
- Sprint Planning Reminders: Notify before sprint starts
- Estimation Drift Detection: Find stories needing re-estimation
- Data Consistency Checks: Verify sync integrity
Reporting Automation
- Weekly estimation velocity reports
- Story point distribution analysis
- Team participation metrics
- Integration health monitoring
Troubleshooting
Connection Issues
Authentication Failures
- Try disconnecting and reconnecting via OAuth
- Check if Jira user account is still active
- Confirm user has necessary project permissions
- Verify OAuth authorization hasn't been revoked
Network/Firewall Issues
- Verify PlanningForge IPs are whitelisted
- Check if corporate firewall blocks API calls
- Test Jira accessibility from different networks
- Confirm HTTPS certificates are valid
Server Configuration
- Ensure Jira REST API is enabled
- Verify correct Jira URL format
- Check for SSL/TLS configuration issues
- Confirm Jira version compatibility
Import/Export Problems
Stories Not Importing
- Check project key and issue type filters
- Verify user has "Browse Project" permission
- Review JQL query syntax and results
- Ensure stories match import criteria
Export Failures
- Confirm story point field exists and is editable
- Check user has "Edit Issues" permission
- Verify field type matches estimate scale
- Look for workflow restrictions on field updates
Field Mapping Errors
- Validate custom field IDs are correct
- Check field context and project association
- Ensure field is visible in issue view
- Test field updates manually in Jira
Data Sync Issues
Estimates Not Updating
- Check if story was moved to different project
- Verify issue key hasn't changed
- Confirm estimation scale mapping is correct
- Review export settings and retry options
Outdated Story Information
- Force refresh story data from Jira
- Check if story was modified after import
- Verify cache settings and expiration
- Re-import if necessary for current data
Debug Mode
Enable debug logging in integration settings to capture detailed API request/response information for troubleshooting.
Contact support with debug logs for faster resolution of complex integration issues.