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.
Screenshot: Jira integration overview dashboard
Initial Setup
Prerequisites
Required Permissions
- PlanningForge: Team Owner or Admin role
- Jira: Project Administrator or higher
- API Access: Ability to create API tokens
- 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
Screenshot: Team integration settings page
Authentication Configuration
Recommended: OAuth 2.0 Authentication
OAuth is the preferred and most secure authentication method. It provides better security, easier setup, and doesn't require sharing passwords or managing API tokens.
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
Screenshot: OAuth authorization flow and success screen
Alternative: API Token Authentication
If OAuth is not available or you prefer API tokens, you can use this method for Jira Cloud:
Jira Cloud API Token Setup
- Go to Atlassian Account Settings
- Click Create API token
- Enter a label like "PlanningForge Integration"
- Copy the generated token (you won't be able to see it again)
- In PlanningForge, select API Token authentication method
- Enter your Jira instance URL (e.g.,
yourcompany.atlassian.net) - Enter your Jira email address
- Paste the API token you created
- Click Test Connection to verify
Jira Server/Data Center Authentication
Personal Access Token (Recommended)
- Log into your Jira Server instance
- Go to Settings → Personal Access Tokens
- Click Create token
- Set expiration and permissions appropriately
- Use the token in PlanningForge configuration
Basic Authentication (Legacy)
For older Jira Server versions without PAT support:
- Use your Jira username and password
- Enable basic authentication in Jira configuration
- Consider creating a dedicated service account
- Ensure account has necessary project permissions
Managing Your Jira Connection
Revoking Access
- OAuth: Go to your Atlassian account apps and revoke PlanningForge access
- API Token: Delete the token from your Atlassian security settings
- In PlanningForge: Click "Disconnect" in integration settings
Reconnecting
- If your connection expires or fails, simply repeat the authentication process
- OAuth connections automatically refresh, but may need re-authorization occasionally
- API tokens may expire based on your organization's security policies
- Check integration status in team settings for connection health
Security Best Practices
OAuth 2.0 is the most secure method as it doesn't require sharing credentials. For API tokens, use dedicated service accounts with minimal required permissions and rotate tokens regularly.
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
Screenshot: Jira story import dialog
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
Screenshot: Story card showing Jira details during estimation
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
Screenshot: Export confirmation and sync status
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.
Story Point Field Configuration
Common Field Names
Standard Fields
- Story Points
- Story Point Estimate
- Estimate
- Points
Custom Field IDs
- customfield_10024
- customfield_10016
- customfield_10002
- Custom naming patterns
Screenshot: Field mapping configuration interface
Advanced Mapping Options
Import Mappings
| PlanningForge Field | Jira Source | Notes |
|---|---|---|
| Story Title | summary | Required |
| Description | description | Supports rich text |
| Acceptance Criteria | Custom field or description | Configurable |
| Current Estimate | Story points field | Shows existing estimates |
| Epic Link | Epic Link or Parent | Hierarchy context |
Export Mappings
| PlanningForge Data | Jira Destination | Options |
|---|---|---|
| Final Estimate | Story points field | Overwrite/Skip existing |
| Session Notes | Comments | Optional |
| Estimation Date | Custom date field | Tracking field |
| Session Participants | Custom field or comments | Audit trail |
Custom Field Discovery
Automatic Field Detection
- PlanningForge scans your Jira project configuration
- Identifies fields with "story point" or "estimate" in the name
- Suggests appropriate mappings based on field types
- Allows manual selection if automatic detection fails
- Validates field permissions and requirements
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
- Verify API token hasn't expired
- Check if Jira user account is still active
- Confirm user has necessary project permissions
- Test credentials directly in Jira REST API
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.