Skip to main content

changedBy JQL Function Documentation

Overview​

The changedBy JQL function allows you to search for issues where specific fields were updated within a given time period, optionally filtered by the user who made the updates. This function is useful for tracking field changes, monitoring updates, and generating reports based on field modifications.

Key Features​

  • Field Update Tracking: Find issues where specific fields were modified.
  • Time Period Filtering: Specify a start date and optional end date to focus on updates made within a specific time frame.
  • User Attribution: Filter updates made by a specific user.
  • 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 changedBy function, you need to construct a JQL query that includes the changedBy function. The syntax is as follows:

issue in changedBy("subquery", "fieldName", ["start_date"], ["end_date"], ["user"])

Parameters:​

  • subquery (required): A valid JQL query that defines the set of issues to evaluate.
  • fieldName (required): The name of the field to check for updates.
  • start_date (optional): The start date for the update period in format "yyyy/MM/dd HH:mm" or "yyyy/MM/dd".
  • end_date (optional): The end date for the update period in the same format as start_date.
  • user (optional): The username or user key of the person who made the update.

Examples:​

  1. Finding Issues Where Description Was Updated Within a Date Range:

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

  2. Finding Issues Where Priority Was Updated by a Specific User:

    issue in changedBy("project = SER", "Priority", "2023/01/01", "2023/12/31", "jsmith")

  3. Finding Issues Where Any Field Was Updated Since a Specific Date:

    issue in changedBy("project = SER", "Description", "2023/06/01 10:00")

  4. Finding Issues Not Updated by a Specific User:

    issue not in changedBy("project = SER", "Description", "2023/01/01", "2023/12/31", "jsmith")

Input and Output Details​

  • Input: The changedBy function takes a subquery, a field name, a start date, an optional end date, and an optional username.
  • Output: The function returns a set of issues where the specified field was updated within the given time period.

Error Handling:​

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

  • Invalid field names
  • Invalid date formats (must be "yyyy/MM/dd HH:mm" or "yyyy/MM/dd")
  • Non-existent users
  • 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 changelog system to track field updates

Jira-Specific Information​

  • Changelog Access: The function analyzes issue changelog data, which contains historical records of all changes made to issues, including field updates.
  • Field Resolution: The function automatically resolves field names to their corresponding IDs.
  • User Resolution: Uses Jira's user resolution API to convert usernames to account IDs.

Performance Considerations​

  • The function analyzes all changelogs from issues matching JQL subquery. It may take significant amount of time to complete.
  • Using specific date ranges can improve performance
  • Including a username filter can significantly reduce the number of issues to process
  • transitionedBy - Search for issues that were transitioned to a specific status
  • commented - Search for issues with specific comment criteria

Conclusion​

The changedBy JQL function enhances the flexibility of Jira queries by allowing users to find issues based on their field update history. This powerful tool can help teams track changes, monitor updates, and analyze how information evolves in their issues.