# How Atlassian-Rovo Implements JQL-Powered Workflows for Issue Management

> Learn how the Atlassian-Rovo plugin uses JQL queries to automate issue management tasks like triage and reporting, eliminating manual Jira navigation. Discover JQL-powered workflows.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-20

---

**The Atlassian-Rovo plugin constructs sanitized JQL queries through reusable builder functions, executes them via the `searchJiraIssuesUsingJql` tool, and processes results to automate triage, status reporting, and Confluence publishing without manual Jira navigation.**

The Atlassian-Rovo plugin demonstrates a production-ready approach to JQL-powered issue management within the OpenAI plugins ecosystem. By separating query construction, execution, and business logic into distinct architectural layers, the plugin transforms natural language requests into precise Jira Query Language commands. This architecture enables automated workflows ranging from duplicate issue detection to executive-level status reports while maintaining strict injection-safety standards.

## Three-Layer Architecture for JQL Automation

The plugin organizes its JQL-powered workflows into three distinct architectural layers that handle query construction, data retrieval, and post-processing actions.

### JQL Construction Layer

At the foundation lies [`plugins/atlassian-rovo/skills/generate-status-report/scripts/jql_builder.py`](https://github.com/openai/plugins/blob/main/plugins/atlassian-rovo/skills/generate-status-report/scripts/jql_builder.py), which exposes reusable helper functions for converting high-level parameters into injection-free JQL strings. Functions like `build_project_query`, `build_blocked_query`, and `build_completed_query` accept parameters including project keys, statuses, priorities, date ranges, and assignee values.

Each function sanitizes inputs through `sanitize_jql_value`, which whitelists characters and escapes double quotes to prevent JQL injection attacks. The builder constructs clause lists that are joined with `AND` operators and appended with optional `ORDER BY` clauses for consistent result ordering.

### Search and Retrieval Layer

The constructed JQL strings feed into the `searchJiraIssuesUsingJql` tool exposed by the OpenAI plugins runtime, as declared in [`plugins/atlassian-rovo/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/atlassian-rovo/.codex-plugin/plugin.json). According to the skill definitions in [`plugins/atlassian-rovo/skills/triage-issue/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/atlassian-rovo/skills/triage-issue/SKILL.md) and [`plugins/atlassian-rovo/skills/generate-status-report/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/atlassian-rovo/skills/generate-status-report/SKILL.md), this tool accepts `cloudId`, `jql`, `fields`, and `maxResults` parameters.

The implementation handles pagination through `nextPageToken` values, allowing the plugin to retrieve large issue sets beyond single-request limits. Standard field requests include `summary`, `status`, `priority`, `assignee`, `created`, and `updated` to provide comprehensive issue context.

### Analysis and Action Layer

Once retrieved, issues undergo domain-specific processing defined in SKILL markdown files. The **triage-issue** workflow calculates duplicate confidence scores by comparing error signatures and component mappings, then branches between adding comments to existing issues via `addCommentToJiraIssue` or creating new tickets via `createJiraIssue`.

The **generate-status-report** workflow aggregates metrics by status and priority, selects appropriate templates (executive, team-level, or daily), and optionally publishes formatted Markdown to Confluence using `createConfluencePage`. This layer transforms raw JQL results into actionable intelligence and automated documentation.

## Implementing Safe JQL Construction

Safety and modularity drive the query building implementation. The [`jql_builder.py`](https://github.com/openai/plugins/blob/main/jql_builder.py) module centralizes all query generation, ensuring consistent sanitization across multiple skills including triage, status reports, and spec-to-backlog workflows.

The `sanitize_jql_value` function serves as the primary defense against injection, processing user-supplied strings before they enter clause construction. New query patterns can be added by extending the builder module or referencing [`plugins/atlassian-rovo/skills/generate-status-report/references/jql-patterns.md`](https://github.com/openai/plugins/blob/main/plugins/atlassian-rovo/skills/generate-status-report/references/jql-patterns.md), which documents common JQL formulations used throughout the plugin.

## Practical Implementation Examples

### Constructing Project-Wide Queries

To fetch open high-priority issues from the past week, developers use the builder pattern:

```python
from plugins.atlassian_rovo.skills.generate_status_report.scripts.jql_builder import build_project_query

jql = build_project_query(
    project_key="PROJ",
    statuses=["To Do", "In Progress"],
    exclude_done=True,
    priorities=["Highest", "High"],
    days_back=7,
    assignee="EMPTY",
    order_by="priority DESC, updated DESC"
)

```

This generates the final JQL string:

```text
project = "PROJ" AND status IN ("To Do", "In Progress") AND priority IN ("Highest", "High") AND updated >= -7d AND assignee is EMPTY ORDER BY priority DESC, updated DESC

```

### Executing Searches

The plugin executes queries through the runtime tool:

```python
search_results = searchJiraIssuesUsingJql(
    cloudId="my-cloud-id",
    jql=jql,
    fields=["summary", "status", "priority", "assignee", "created", "updated"],
    maxResults=50
)

```

### Automating Triage Actions

When duplicate detection triggers, the plugin adds structured comments:

```python
addCommentToJiraIssue(
    cloudId="my-cloud-id",
    issueIdOrKey="PROJ-456",
    commentBody="""

## Additional Instance Reported

**Reporter:** Jane Doe  
**Date:** 2026-06-20  

**Error Details:** Connection timeout during login

*Added via Atlassian-Rovo triage automation*
"""
)

```

### Publishing Status Reports

For executive reporting, the plugin creates Confluence pages:

```python
createConfluencePage(
    cloudId="my-cloud-id",
    spaceId="12345",
    title="Project PROJ - Weekly Status - 2026-06-20",
    body=formatted_markdown_report,
    contentFormat="markdown"
)

```

## Summary

- **Modular JQL Construction**: The [`jql_builder.py`](https://github.com/openai/plugins/blob/main/jql_builder.py) module provides reusable, injection-safe query generation through functions like `build_project_query` and `sanitize_jql_value`.
- **Runtime Integration**: Skills invoke `searchJiraIssuesUsingJql` with constructed queries, handling pagination via `nextPageToken` and requesting standard fields including `summary`, `status`, and `priority`.
- **Automated Action Layer**: Retrieved data drives business logic for duplicate detection, metric aggregation, and automated publishing to Jira and Confluence.
- **Security-First Design**: Input sanitization and declarative workflow definitions in SKILL markdown files ensure safe, maintainable automation.

## Frequently Asked Questions

### How does Atlassian-Rovo prevent JQL injection vulnerabilities?

The plugin passes all user-supplied strings through `sanitize_jql_value` before incorporating them into queries. This function whitelists safe characters and escapes double quotes, ensuring that malicious input cannot break out of JQL string literals or alter query logic. The centralized sanitization in [`jql_builder.py`](https://github.com/openai/plugins/blob/main/jql_builder.py) guarantees consistent security across all skills.

### What determines whether the triage workflow comments on an existing issue or creates a new one?

The triage skill calculates duplicate confidence scores by comparing error signatures, components, and symptoms from the user's request against existing issues retrieved via JQL. If confidence exceeds defined thresholds, the workflow selects `addCommentToJiraIssue` (Option A). Otherwise, it executes `createJiraIssue` (Option B) to generate a new ticket.

### Can the plugin handle complex JQL patterns beyond simple equality checks?

Yes. The [`jql_builder.py`](https://github.com/openai/plugins/blob/main/jql_builder.py) module supports complex patterns including `IN` clauses for multiple statuses or priorities, date range queries using relative time syntax like `-7d`, and `ORDER BY` clauses with multiple sort fields. The [`references/jql-patterns.md`](https://github.com/openai/plugins/blob/main/references/jql-patterns.md) file documents additional patterns for cross-project queries, blocked issue identification, and completed issue retrieval.

### Which specific Jira fields does the plugin request during search operations?

According to the SKILL definitions, the plugin typically requests `summary`, `status`, `priority`, `assignee`, `created`, and `updated` fields. These provide sufficient context for triage decisions and status report generation while minimizing payload size. The `fields` parameter in `searchJiraIssuesUsingJql` accepts custom field identifiers when additional data is required for specific workflows.