JIRA Integration Patterns

This skill provides comprehensive knowledge about JIRA API usage, JQL query patterns, and best practices for Red Hat AI JIRA integration.

JQL (JIRA Query Language) Reference

Basic Syntax

field operator value [AND|OR field operator value] [ORDER BY field direction]

Common Operators

Functions

Date Formats

• •-1d - 1 day ago
• •-2w - 2 weeks ago
• •-3M - 3 months ago
• •-1y - 1 year ago
• •-30m - 30 minutes ago
• •2025-01-15 - Specific date

Essential JQL Queries for Red Hat AI

My Work

All my assigned issues (unresolved):

assignee = currentUser() AND resolution = Unresolved ORDER BY priority DESC, updated DESC

My issues updated today:

assignee = currentUser() AND updated >= startOfDay() ORDER BY updated DESC

My overdue issues:

assignee = currentUser() AND due < now() AND resolution = Unresolved ORDER BY due ASC

Sprint Queries

Issues in specific sprint:

sprint = "Sprint 25" ORDER BY rank ASC

Issues in current/active sprint:

sprint IN openSprints() AND project = RHAISTRAT ORDER BY rank ASC

Issues not in any sprint (backlog):

sprint IS EMPTY AND project = RHAISTRAT AND resolution = Unresolved ORDER BY priority DESC

Epic Queries

All stories/tasks in an epic:

parent = RHAISTRAT-123 ORDER BY rank ASC

Epics without children:

issuetype = Epic AND issueFunction IN issuesWithoutSubtasks() ORDER BY created DESC

Progress on epic:

parent = RHAISTRAT-123 AND status = Done

Project-Specific Queries

STRAT features needing refinement:

project IN (RHAISTRAT, RHOAISTRAT) AND status = "Refinement In Progress" ORDER BY updated ASC

RFEs pending approval:

project IN (RHAIRFE, RHELAIRFE, RHOAIRFE) AND status = "Pending Review" ORDER BY created DESC

Engineering issues by component:

project = RHAIENG AND component = "Authentication" AND resolution = Unresolved ORDER BY priority DESC

Advanced Queries

Issues with specific label:

labels = requires_architecture_review AND resolution = Unresolved ORDER BY priority DESC

Issues linked to specific issue:

issue IN linkedIssues(RHAISTRAT-123) ORDER BY type ASC

Recently commented issues:

project = RHAISTRAT AND comment ~ "review" AND updated >= -3d ORDER BY updated DESC

Issues by multiple criteria:

project IN (RHAISTRAT, RHOAISTRAT)
AND assignee = currentUser()
AND status IN ("In Progress", "Code Review")
AND sprint IN openSprints()
ORDER BY priority DESC, rank ASC

Field Mappings

Standard Fields

Custom Fields (Red Hat AI)

Note: Custom field IDs vary by JIRA instance. Use /rest/api/2/field endpoint to discover actual IDs.

Status Transitions

Standard Workflow

New → In Progress → Code Review → Testing → Done
         ↓
      Blocked
         ↓
      In Progress

STRAT Workflow

Not Started → Refinement In Progress → Refinement Complete → In Development → Testing → Done
                     ↓
                  Blocked
                     ↓
            Refinement In Progress

Transition Best Practices

1. •

   Always check available transitions before attempting:

   python

   python jira_client.py get_transitions RHAISTRAT-123
   

2. •

   Use transition IDs, not names (names can vary):

   python

   python jira_client.py transition_issue RHAISTRAT-123 "31"
   

3. •

   Required fields may vary by transition - check transition metadata

4. •

   Add comments when transitioning to provide context

Issue Linking

Link Types

Linking Patterns

Link STRAT to RFE:

python jira_client.py link_issue RHAISTRAT-123 RHAIRFE-456 "Clones"

Link feature to epic:

# Set parent field instead of link
python jira_client.py update_issue RHAISTRAT-123 '{"parent": {"key": "RHAISTRAT-100"}}'

Link blocker:

python jira_client.py link_issue RHAISTRAT-123 RHAIENG-789 "Blocks"

API Best Practices

Pagination

For large result sets, use pagination:

# First page
startAt=0&maxResults=50

# Next page
startAt=50&maxResults=50

Rate Limiting

• •Self-hosted JIRA: Typically no rate limits, but be considerate
• •Cloud JIRA: Limits vary by plan
• •Use caching to reduce API calls (jira has 4-hour default cache)

Caching Strategy

When to use cache:

• •✅ Viewing issue lists
• •✅ Reading issue details
• •✅ JQL queries for display

When to bypass cache:

• •❌ After making updates
• •❌ Checking current status before transitions
• •❌ Real-time status monitoring

Bypass cache:

python jira_client.py get_issue RHAISTRAT-123 --no-cache

Error Handling

Common errors:

• •401 Unauthorized - Invalid credentials
• •403 Forbidden - Insufficient permissions
• •404 Not Found - Issue doesn't exist
• •400 Bad Request - Invalid field or value

Best practices:

1. •Validate issue keys before API calls
2. •Check user permissions
3. •Validate field values against JIRA schema
4. •Handle network errors gracefully

Bulk Operations

Batch Issue Updates

For multiple issues, iterate and update one at a time (no batch update in basic API):

for issue in RHAISTRAT-123 RHAISTRAT-124 RHAISTRAT-125; do
    python jira_client.py add_comment "$issue" "Batch update: moving to sprint"
done

Bulk JQL Export

Get all issues matching criteria:

python jira_client.py query_jql "project = RHAISTRAT AND sprint = 'Sprint 25'" > sprint_issues.json

Performance Tips

Optimize JQL Queries

❌ Slow:

summary ~ "authentication" OR description ~ "authentication"

✅ Fast:

text ~ "authentication"

❌ Slow (searches all issues):

assignee = "jdoe"

✅ Fast (limits by project first):

project = RHAISTRAT AND assignee = "jdoe"

Field Selection

Request only needed fields:

# In API calls, use fields parameter
fields=summary,status,assignee,priority

Use Filters

Create saved filters for common queries and reference by ID:

filter = 12345

Integration with Commands

/jira:my-issues

Uses:

assignee = currentUser() AND resolution = Unresolved ORDER BY priority DESC

/jira:sprint

Uses:

sprint = <sprint-id> ORDER BY rank ASC

With current sprint default from config.

/jira:analyze

Combines:

1. •get_issue to fetch issue
2. •Code repository analysis
3. •Web search if needed

/jira:update

Uses:

1. •get_transitions to show options
2. •update_issue for field changes
3. •add_comment for comments
4. •transition_issue for status changes

Troubleshooting

Issue: JQL query returns no results

• •Verify project key exists
• •Check field names (case-sensitive)
• •Simplify query to isolate problem

Issue: Can't update field

• •Check field permissions
• •Verify field is not read-only
• •Check required field validation

Issue: Transition not available

• •Check current status
• •Verify workflow allows transition
• •Check user permissions for transition

Issue: Slow queries

• •Add project filter
• •Use indexed fields (status, priority, assignee)
• •Avoid text searches on large instances

References:

• •Atlassian JQL Documentation: https://support.atlassian.com/jira-software-cloud/docs/use-advanced-search-with-jira-query-language-jql/
• •JIRA REST API: https://docs.atlassian.com/software/jira/docs/api/REST/latest/
• •Plugin JIRA Client: scripts/jira_client.py