How to

Use Functions

Your select, having, group_by, and sort_by sections have access to a wide range of functions as well as to the full breadth of Python syntax. If the built-in functions aren’t enough, you can also just write your own and either register them at runtime or make them persistently available via a setuptools entrypoint.

See Query Functions for a complete list of built-in functions.

Format data using functions

select:
  Status: status
  Summary: summary
  Story Points: "{Story Points}"
  Spring Count: len(customfield_10010)
  Sprint Name: sprint_name(customfield_10010[-1])
from: issues

In the above example, two of the displayed columns are processed with a function:

• Sprint Count: Will render the number of array elements in the field containing the list of sprints in which this issue was present.

• Sprint Name: Will show the name of the last sprint associated with the displayed issue.

Filter results using functions

select:
  Status: status
  Summary: summary
  Story Points: "{Story Points}"
from: issues
having:
  # The quoting below is required only because the first character of line
  # being a double-quote causes YAML parsers to parse the line differently
  - '"Sprint #19" in sprint_name(customfield_10010[-1])'

In the above example, the issues returned from Jira will be compared against each constraint you’ve entered in the having section; in this case, all returned issues not having the string “Sprint #19” in the name of the last sprint associated with the displayed issue will not be written to your output.

Note

having entries are processed locally instead of on the Jira server so filtering using having entries is slower than using standard Jql due to the amount of (potentially) unnecessary data transfer involved. It is recommended that you use having only when your logic cannot be expressed in standard Jql (i.e. in the where section).

Group results & calculate aggregates

You can group and/or aggregate your returned rows by using group_by:

select:
  Status: status
  Count: count(key)
from: issues
group_by:
  - status

You’ll receive just a single result row for each status, and a count of how many records shared that status in the second column.

Sort results using functions

You can order your entries using any expression, too:

select:
  Status: status
  Count: count(key)
from: issues
group_by:
  - status
sort_by:
  - count(key) desc

This will sort all returned tickets, grouped by status, in descending order from the status that has the most tickets to the one that has the fewest.

Note

The sort_by section is evaluated locally instead of by your Jira server. In situations where your expression can be evaluated in Jql, you will have faster performance using the order_by section.

Limit the number of returned results

You can limit the number of results returned by adding a limit to your query:

select:
  Key: key
  Status: status
  Summary: summary
from: issues
where:
  - assignee = "me@adamcoddington.net"
limit: 10

Be aware that this limit is handled by Jira; so only the first N records will be available for downstream steps in the Query Lifecycle.

Expand Jira Issue Fields

You can ask Jira to expand issue fields by adding an expand element to your query:

select:
  Key: key
  Status: status
  Summary: summary
from: issues
expand:
  - transitions

The meaning of these expansions is defined by Jira; you can find more information in Jira’s documentation.