Skip to main content

Attachment JQL Function Documentation

Overview​

The attachment JQL function allows you to find issues that have attachments matching specific criteria. This function is useful for filtering issues based on attachment properties such as filename, extension, author, and creation date.

Key Features​

  • Filename Matching: Search for attachments by exact filename or using regex patterns
  • Extension Filtering: Filter attachments by file extension or MIME type
  • Author Filtering: Find attachments created by specific users
  • Date Range Filtering: Search for attachments created within a specific time period
  • Multiple Criteria: Combine multiple criteria to create complex attachment searches

How to Use​

To use the attachment function, construct a JQL query that includes the attachment function. The syntax is as follows:

issue in attachment("subquery", "author", "start_date", "end_date", "filename", "extension")

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 attached the file. The function checks if attachment.author.displayName.toLowerCase().includes("${author}")
  • start_date (optional): The start date for the attachment in format "yyyy/MM/dd HH:mm" or "yyyy/MM/dd". The function compares attachment.created with this date
  • end_date (optional): The end date for the attachment in format "yyyy/MM/dd HH:mm" or "yyyy/MM/dd". The function compares attachment.created with this date
  • filename (optional): The filename to match. Can be either an exact filename or a regex pattern. The function checks if attachment.filename matches this pattern
  • extension (optional): The file extension or MIME type to match. The function checks if attachment.filename.endsWith() this extension or attachment.mimeType.endsWith() this extension

Examples:​

  1. Finding Issues with Specific File Extension:

    issue in attachment("project = TEST", "", "", "", "", "pdf")

  2. Finding Issues with Attachments by Specific User:

    issue in attachment("project = TEST", "john.doe", "", "", "", "")

  3. Finding Issues with Attachments Created in Date Range:

    issue in attachment("project = TEST", "", "2024/01/01", "2024/03/31", "", "")

  4. Finding Issues with Specific Filename Pattern:

    issue in attachment("project = TEST", "", "", "", "report.*", "")

  5. Combining Multiple Criteria:

    issue in attachment("project = TEST", "john.doe", "2024/01/01", "2024/03/31", "report.*", "pdf")

Implementation Details​

Algorithm​

  1. The function creates a Jira expression to evaluate attachment properties
  2. Due to the potentially expensive nature of the operation, the function implements lower limits for performance optimization
  3. The function validates all parameters and returns appropriate errors for invalid inputs
  4. The function processes each issue in the subquery and checks its attachments against the specified criteria

Error Handling​

The function handles various error cases:

  • Invalid date formats
  • Invalid regex patterns in filename
  • Missing subquery
  • Invalid field names
  • Issues without matching attachments

Performance Considerations​

  • The function implements pagination to handle large result sets
  • Results are cached to improve performance for repeated queries
  • The function limits the number of issues processed to prevent timeout issues

Integration with Other Functions​

The attachment function can be combined with other JQL functions to create complex queries:

issue in attachment("project = TEST", "", "", "", "report.*", "pdf") AND issue in commented("project = TEST", "john.doe")

Best Practices​

  1. Always provide a specific subquery to limit the scope of the search
  2. Use date ranges to improve performance when searching for attachments
  3. Consider using regex patterns for flexible filename matching
  4. Combine with other functions for more specific results
  5. Use appropriate error handling in your queries