Jira Workitem Search

Jira Workitem Search

Search for Jira tickets using JQL (Jira Query Language) queries with the acli CLI.

Prerequisites

• acli must be installed and authenticated (acli jira auth)

Implementation

Step 1: Verify ACLi Setup

Before proceeding, verify that acli is installed and authenticated by invoking the acli-setup-check skill:

/acli-setup-check

If the setup check fails, stop execution and guide the user to fix the issue.

Step 2: Determine JQL Query

1. Direct JQL: If the user provides a JQL query, use it as-is
2. Natural Language: Convert user's natural language request to JQL using templates below. Extract project names, statuses, components, and other values from the user's request and substitute them into the templates.
3. Interactive: If unclear, ask the user what they want to find

Input Validation

Before substituting user-provided values into JQL templates, validate and sanitize the inputs:

1. Project keys: Validate against pattern [A-Z]+ (e.g., AIPCC, RHOAIENG).
2. Status values: Quote multi-word statuses (e.g., "In Progress", "Code Review"). Common statuses: To Do, In Progress, Code Review, Done, Blocked.
3. Ticket keys: Validate against pattern [A-Z]+-[0-9]+ (e.g., AIPCC-1234).
4. Numeric values: Validate that N in -d is a positive integer.
5. Issue types: Whitelist common types: Bug, Story, Epic, Feature, Spike, Initiative, Task.
6. Components: Quote multi-word components (e.g., "Wheel Package Index").

If validation fails, prompt the user with a clear error message explaining the expected format.

Common JQL Templates

Replace placeholders like `, , ` with actual values from the user's request or conversation context.

My open tickets:

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

Team backlog for a project:

project =  AND status != Done ORDER BY priority DESC, updated DESC

Example: project = AIPCC AND status != Done ORDER BY priority DESC, updated DESC

Recent updates in a project (last N days):

project =  AND updatedDate >= -d ORDER BY updated DESC

Example: project = RHOAIENG AND updatedDate >= -7d ORDER BY updated DESC

Tickets by status:

project =  AND status = "" ORDER BY updated DESC

Example: project = AIPCC AND status = "In Progress" ORDER BY updated DESC

Tickets by type (single):

project =  AND type =  ORDER BY updated DESC

Example: project = AIPCC AND type = Feature ORDER BY updated DESC

Tickets by type (multiple):

project =  AND type IN (, , ...) ORDER BY updated DESC

Example: project = AIPCC AND type IN (Feature, Initiative) ORDER BY updated DESC

Blocked tickets:

project =  AND status = Blocked ORDER BY priority DESC

Tickets due soon (next 7 days):

project =  AND dueDate >= now() AND dueDate  AND component = "" ORDER BY priority DESC

Example: project = AIPCC AND component = "Wheel Package Index" ORDER BY priority DESC

Epics and their children:

project =  AND type = Epic ORDER BY created DESC

Unassigned tickets:

project =  AND assignee is EMPTY AND resolution = Unresolved ORDER BY priority DESC

Tickets mentioned in conversation: Search conversation history for ticket keys, then query:

key IN (, , ...) ORDER BY updated DESC

Example: key IN (AIPCC-1234, AIPCC-5678, RHOAIENG-910) ORDER BY updated DESC

Tips for extracting values:

• If user says "AIPCC backlog", use project = AIPCC
• If user says "in progress tickets", use status = "In Progress"
• If user says "last week", use updatedDate >= -7d
• If user says "Wheel Package Index component", use component = "Wheel Package Index"
• If user says "features", use type = Feature
• If user says "features and initiatives", use type IN (Feature, Initiative)
• Common ticket types: Bug, Story, Epic, Feature, Spike, Initiative, Task
• If no project specified, ask the user or search conversation context for project references

Step 3: Execute Search

Build the JQL query from validated inputs and execute the search:

# Validate and sanitize inputs extracted from user request
PROJECT=""
if [[ ! "$PROJECT" =~ ^[A-Z]+$ ]]; then
  echo "Error: Invalid project key format. Expected uppercase letters only (e.g., AIPCC, RHOAIENG)"
  exit 1
fi

# For status values with spaces, add quotes
STATUS=""
if [[ "$STATUS" == *" "* ]]; then
  STATUS="\"$STATUS\""
fi

# Build JQL query using validated variables
JQL_QUERY="project = $PROJECT AND status = $STATUS ORDER BY updated DESC"

# Execute search with validated JQL query
acli jira workitem search \
  --jql "$JQL_QUERY" \
  --fields key,summary,status,assignee,updated,priority \
  --limit 50 \
  --json

Note: The example above shows validation for a simple project + status query. Adapt the validation pattern based on the actual JQL template used (see Step 2 templates). Always validate inputs against expected patterns before building JQL.

Field Options:

• key: Issue key (always include)
• summary: Issue title (always include)
• status: Current status (always include)
• assignee: Assignee name (recommended)
• updated: Last update date (recommended)
• priority: Priority level (optional)
• created: Creation date (optional)
• duedate: Due date (optional)
• labels: Labels (optional)
• components: Components (optional)

Pagination:

• Use --limit N to control number of results (default: 50, max: 100)
• Use --paginate to fetch all results across multiple pages

Step 4: Parse and Format Results

Parse the JSON output and format as a table:

Found 15 tickets matching: project = AIPCC AND status = "In Progress"

KEY          STATUS        ASSIGNEE      UPDATED     SUMMARY
─────────────────────────────────────────────────────────────────────
AIPCC-1234   In Progress   code-samurai      2024-03-20  Fix duplicate CI runs
AIPCC-5678   In Progress   super-picky-reviewer    2024-03-19  Add wheel signing support
AIPCC-910    In Progress   Unassigned    2024-03-18  Update documentation
...

For smaller result sets ( "$TEMPCSV" echo "Results exported to: $TEMPCSV"

### Step 6: Store Ticket Keys for Bulk Operations

Extract the list of ticket keys from results and store them for potential bulk operations:

Ticket keys: AIPCC-1234, AIPCC-5678, AIPCC-910

Use these keys with other skills for bulk operations.

## Advanced Features

### Combining Multiple Criteria

```jql
project = AIPCC
  AND status IN ("To Do", "In Progress")
  AND assignee = currentUser()
  AND priority IN (High, Highest)
  ORDER BY priority DESC, updated DESC

Using Functions

• currentUser(): Current authenticated user
• now(): Current date/time
• startOfWeek(), endOfWeek(): Week boundaries
• startOfMonth(), endOfMonth(): Month boundaries

Text Search

project = AIPCC AND text ~ "wheel building" ORDER BY updated DESC

Custom Fields

For AIPCC-specific fields:

project = AIPCC AND "Color Status" = Red ORDER BY updated DESC

Error Handling

• acli not found: Delegate to acli-setup-check skill
• Authentication failure: Delegate to acli-setup-check skill
• Invalid JQL syntax: Display error and suggest correcting the query
• No results found: Inform user and suggest broadening the search
• Permission denied: User may not have access to queried projects
• Field not found: Verify field name exists in the project schema

Examples

My Open Tickets

User: /jira-workitem-search Show my open tickets
Assistant: [Searches with: assignee = currentUser() AND resolution = Unresolved]
Found 5 open tickets assigned to you:
[Displays results in table format]

Project Backlog

User: What's in the AIPCC backlog?
Assistant: [Searches with: project = AIPCC AND status != Done]
Found 47 tickets in the AIPCC backlog
[Displays results with pagination]

Recent Activity

User: What tickets were updated in the last week?
Assistant: [Searches with: updatedDate >= -7d]
Found 23 tickets updated in the last 7 days
[Displays results ordered by update time]

Export to CSV

User: Export all AIPCC bugs to CSV
Assistant: [Searches and exports]
Exported 156 tickets to /tmp/jira-search-results.csv

Refine Search

User: /jira-workitem-search project = AIPCC AND status = "In Progress"
Assistant: [Shows 15 results]
User: Only show high priority ones
Assistant: [Refines to: project = AIPCC AND status = "In Progress" AND priority = High]
Found 3 high-priority tickets in progress
[Displays refined results]

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: opendatahub-io
• Source: opendatahub-io/ai-helpers
• License: Apache-2.0
• Homepage: https://opendatahub-io.github.io/ai-helpers/

Install and usage instructions live in the source repository linked above.