Skip to main content

commented JQL Function Documentation

Overview​

The commented JQL function allows you to search for issues that have comments matching specific criteria, such as content, author, or time period. This function is useful for tracking discussions, finding issues with specific feedback, and monitoring comment activity within your Jira instance.

Key Features​

  • Comment Content Search: Find issues with comments containing specific text.
  • Author Filtering: Filter comments by the user who wrote them.
  • Time Period Filtering: Specify a start date and optional end date to focus on comments made within a specific time frame.
  • Comprehensive Validation: Validates all input parameters to ensure accurate results and provide clear error messages.
  • JQL Integration: Seamlessly integrates with Jira Query Language (JQL) for complex queries.

How to Use​

To use the commented function, you need to construct a JQL query that includes the commented function. The syntax is as follows:

issue in commented("subquery", "[author]", "[start_date]", ["end_date"], ["content"])

Parameters:​

  • subquery (required): A valid JQL query that defines the set of issues to evaluate.
  • author (optional): The username or user key of the person who wrote the comment. The function will check if comment.author.displayName.toLowerCase().includes("${author}").
  • start_date (optional): The start date for the comment period in format "yyyy/MM/dd HH:mm" or "yyyy/MM/dd".
  • end_date (optional): The end date for the comment period in the same format as start_date.
  • content (optional): Text content to search for in comments. The function will check if comment.body.plainText.toLowerCase().includes(content).

Examples:​

  1. Finding Issues with Comments in a Date Range:

    issue in commented("project = SER and statusCategory = 'In Progress'", "", "2023/01/01", "2023/05/01")

  2. Finding Issues with Comments by a Specific User:

    issue in commented("project = SER", "John Smith", "2023/01/01", "2023/12/31")

  3. Finding Issues with Comments Containing Specific Text:

    issue in commented("project = SER", "", "2023/01/01", "", "urgent")

  4. Finding Issues Without Comments:

    issue not in commented("project = SER", "", "2023/01/01")

Input and Output Details​

  • Input: The commented function takes a subquery, an optional author name, a start date, an optional end date, and an optional content string.
  • Output: The function returns a set of issues that have comments matching the specified criteria.

Error Handling:​

The function validates all input parameters and will return clear error messages for:

  • Invalid date formats (must be "yyyy/MM/dd HH:mm" or "yyyy/MM/dd")
  • Invalid JQL queries

Configuration and Dependencies​

  • Ensures compatibility with the Jira Expressions API
  • Handles batched processing of issues to optimize performance and avoid API limits
  • Coordinates with Jira's comment system to track issue discussions

Performance Considerations​

The function analyzes all comments from issues matching the JQL subquery. It may take a significant amount of time to complete for issues with many comments.

Conclusion​

The commented JQL function enhances the flexibility of Jira queries by allowing users to find issues based on their comment history. This powerful tool can help teams track discussions, monitor feedback, and analyze how issues are being discussed and resolved.