JIRA Integration Patterns

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

Operator	Description	Example
=	Equals	status = "In Progress"
!=	Not equals	status != Closed
IN	Match any value	project IN (RHAISTRAT, RHOAISTRAT)
NOT IN	Exclude values	status NOT IN (Closed, Resolved)
~	Contains text	summary ~ "authentication"
!~	Does not contain	summary !~ "deprecated"
IS EMPTY	Field is empty	assignee IS EMPTY
IS NOT EMPTY	Field has value	sprint IS NOT EMPTY
> < >= <=	Comparison	created > -7d

Functions

Function	Description	Example
currentUser()	Current logged-in user	assignee = currentUser()
now()	Current date/time	updated > now(-1h)
startOfDay()	Start of day	created >= startOfDay()
endOfDay()	End of day	due <= endOfDay()
startOfWeek()	Start of week	created >= startOfWeek()
membersOf()	Group members	assignee IN membersOf("team-ai")

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

Field	API Name	Type	Example Value
Summary	summary	String	"Add authentication support"
Description	description	String (formatted)	"As a user, I want..."
Status	status.name	String	"In Progress"
Priority	priority.name	String	"High"
Assignee	assignee.name	String	"jdoe"
Reporter	reporter.name	String	"jsmith"
Issue Type	issuetype.name	String	"Feature"
Project	project.key	String	"RHAISTRAT"
Labels	labels	Array	["documentation", "security"]
Components	components	Array of objects	[{"name": "UXD"}]
Fix Versions	fixVersions	Array of objects	[{"name": "1.5.0"}]

Custom Fields (Red Hat AI)

Field	API Name	Type	Notes
Sprint	customfield_xxxxx	Sprint object	Find ID via API
Story Points	customfield_xxxxx	Number	Estimate
Epic Link	customfield_xxxxx	String	Epic key
Feature Owner	customfield_xxxxx	User object	STRAT features
Delivery Owner	customfield_xxxxx	User object	STRAT features
Product Documentation Required	customfield_xxxxx	Boolean	Yes/No
Requires Architecture Review	customfield_xxxxx	Boolean	Yes/No

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 jira_client.py get_transitions RHAISTRAT-123
   

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

   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

Link Type	Meaning	Example
Relates	General relation	Feature relates to another feature
Blocks	Blocks progress	Bug blocks feature
Clones	Copied from	STRAT clones RFE
Duplicates	Same issue	Bug duplicates earlier bug
Causes	Root cause	Issue causes another issue
Depends on	Dependency	Feature depends on infrastructure

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