Understanding Invalid JQL Detection in Jira Integrity Checker

Owned by Sudhir Kv
Last updated: May 17, 2024
2 min read

Problem

Users need to understand how the Jira Integrity Checker (ICJ) identifies invalid JQL (Jira Query Language) queries, specifically in contexts where the searcher's context or user permissions could affect query validation.

Symptoms

  1. Errors with Invalid JQL: During integrity checks, users encounter errors indicating invalid JQL queries.

  2. Confusion Over Validation Methods: Users are unsure how the ICJ validates JQL queries, especially when Atlassian APIs require user context for query validation.

  3. Unclear Documentation: Existing documentation does not clearly explain how the ICJ bypasses user context to validate JQL queries.

Root Cause Analysis

The core issue arises from the need to validate JQL queries without being constrained by the user context, which can affect access to specific projects and filters. This necessitates a deeper understanding of how ICJ handles and parses JQL queries independently of user permissions.

Resolution

  1. ICJ's Approach to JQL Validation:

    • ICJ does not use the searchService.validateQuery method for validating JQL. Instead, it employs a combination of Jira's API for parsing JQL and specific internal methods to handle this process.

    • The ICJ retrieves all filters across the system, disregarding user share permissions. This ensures that all JQL queries are evaluated uniformly without being affected by user-specific access limitations.

  2. Detailed Steps and Methods:

    • API Usage: ICJ leverages Jira's JqlQueryParser API to parse JQL strings into a structured format, breaking down the query into clauses, operands, and operators.

    • Handling Errors: When parsing fails due to broken JQL, the ICJ records these as invalid JQL errors and provides feedback to users.

    • Comprehensive Checks: ICJ checks all JQL references, including those in filters, boards, and service desk configurations, ensuring that every query is validated regardless of context.

  3. Ensuring Accurate Query Validation:

    • ICJ does not require the ApplicationUser context for validation. It operates on a higher system-wide level, enabling it to check JQL validity without user-specific restrictions.

    • The system uses classes such as SearchRequestManager and SearchRequestStore to manage and evaluate search requests, parsing JQL using visitor APIs like ClauseVisitor.

Conclusion

The Jira Integrity Checker ensures the validity of JQL queries through a robust parsing mechanism that does not depend on user-specific contexts. This approach ensures comprehensive validation across the system, providing accurate feedback on invalid JQL queries without being affected by individual user permissions. For further details on the APIs and methods used, users can refer to Atlassian's public documentation:

This ensures that users can effectively manage and correct invalid JQL entries within their Jira configurations, improving overall system integrity and performance. If further technical clarification is needed, it may be necessary to engage with support for more detailed guidance.