Expression customization guide

What are Jira Expressions?

Jira Expressions are custom rules you can create to interact with and get information from Jira. They allow you to write specific conditions to find, filter, and manipulate data within Jira.

What can you track using expressions?

With the power of expressions you can now visualize almost anything as a progress bar or a counter. Thanks to the full power of customization the potential use cases are endless.

Our expression counters show the total amount of results based on your calculation. This can be a number of issues, all of the comments of all the child issues and more.

Our expression progress bars will visualize the chosen calculation and let you compare it based on resolved/unresolved issues. This comparison is an Epic Sum Up default progress bar setting and can’t be changed.

How can you build your own expressions?

Because Jira expressions use JavaScript-like syntax, getting started with Jira expressions is easier when you’re already familiar with JavaScript. 

However, it is not a necessity because Jira expressions are designed to be simple enough to use for non-developers. 

Once you know a few basic building blocks you can easily build your own simple expressions and only ask your admin or Solution Partner for help, when it comes to more complex expressions. 

Here are some of the most commonly used building blocks: 

Variables and Fields: Jira Expressions let you access and use the fields of issues, like issue.assignee, issue.status, or issue.dueDate. For issue properties the structure is always issue.property and there are many more options available. A list of properties can be found here: https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference/

Operators: You can use operators to compare values (==, !=, <, >) or perform logical operations (&&, ||).

Functions: There are built-in functions you can use, like issue.comments.size() to get the number of comments on an issue.

More information about expressions can be found on the Atlassian Developer blog: https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#syntax-and-semantics

To get started, we provide ready to use templates in the app. Additionally, you can find a few templates with step-by-step intructions for implementation below.

Template library

Below we’ve grouped the different expression elements into various colors that will appear in the templates as well. All placeholders are marked with $ and {} e.g. placeholder : issue.${storyPointFieldId} turns into issue.customfield10100.

Adjustable elements

Missing elements/ids that need to be added in order for the expression to work

Expression elements

Expression elements

Counter templates

Issues with an upcoming due date

Expression: !issue.resolution && issue.dueDate && issue.dueDate.minusDays(2) <= new CalendarDate()

This expression counts how many issues are unresolved and have a due date that’s coming up in the next two days. 

If two days is not a fitting timeline for you, you can easily adjust the number of days by changing the number 2 to any number of days you prefer.

Original estimate exceeded

Expression: (issue.originalEstimate ?? 0) > (60*60*4) && (issue.timeSpent ?? 0) >= (issue.originalEstimate * 1.5)

This expression counts how many issues have an original estimate of over 4h and have exceeded their original estimate by 50% or more. 

If you want to remove the 4h benchmark, you will need to remove the first half of the expression. Everything up to and including &&. Alternatively you can replace the 4 in (60*60*4) with a number of hours suitable to you. 

To adjust how much the original estimate has to be exceeded you will need to adjust the factor from 1.5 to e.g. 1.75 to change it to 75%.

Time spent by user group

Expression: issue.worklogs.filter((worklog) => worklog.author.groupIds.includes('${userGroup}')).reduce((timeSpent, worklog) => timeSpent + (worklog.timeSpent / 60 / 60), 0)

This expression counts the time spent in hours of a specific user group. 

In order for this expression to work, you have to fill in the id of the user group. This id is only accessible to admins.

Progress bar templates

Hours per story points

Expression (simple): (issue.${storyPointFieldId} ?? 0) * 3

Expression (complex): (issue.${storyPointFieldId} ?? 0) <=5 ? (issue.${storyPointFieldId} ?? 0) * 2 : issue.${storyPointFieldId} * 3

This expression shows how much time will be needed to complete the number of story points in your hierarchy. 

In order for this expression to work you will need to fill in the custom field id for the story point field of your instance. When you add a custom expression in Epic Sum Up you will be able to access all custom field ids and directly add them to the expression in the editor. 

Please keep in mind that this is not a best practice and generally not recommended. If you want to use this expression you will need to modify the factor (right now 3) to the individual factor of your team.

Custom numerical progress bar for specific issue types

Expression: ${issueTypes}.includes(issue.issueType.id) ? issue.${numberFieldId} : 0

Example: [10001].includes(issue.issueType.id) ? issue.customfield_20101 : 0

This expression visualizes a numerical value for a specific issue type. The progress is counted by issues resolved and unresolved. This is a default Epic Sum Up progress bar setting and can’t be changed.

In order for this expression to work both the ${issueTypes} and the custom field id for the number field you want to track must be filled in. 

A common example would be to track the story points only for the issue type stories.

The issue type id is accessible via the Rest API.

Custom numerical progress bar for standard level issue types

Expression: issue.issueType.hierarchyLevel == 0 ? issue.${storyPointFieldId} : 0

This expression visualizes a numerical metric for standard level issue types. No subtasks or parent issue types will be taken into account. The progress is counted by issues resolved and unresolved. This is a default Epic Sum Up progress bar setting and can’t be changed.

In order for this expression to work you will need to fill in the id of the custom field you want to track. This can be story points, business value or any other numerical value you are tracking.

Personnel costs

Expression: (((issue.timeSpent ?? 0) + (issue.remainingEstimate ?? 0)) / 60 / 60) * ${hourlyRate}

This expression visualizes time spent and remaining estimate multiplied with your company’s hourly rate. 

In order for this expression to work you will need to fill in your custom hourly rate or alternatively use a custom field e.g. (((issue.timeSpent ?? 0) + (issue.remainingEstimate ?? 0)) / 60 / 60) * 50

In case you prefer a simpler solution you can do the same calculation using our calculated progress bar.

Overall costs

Expression: (((issue.timeSpent ?? 0) + (issue.remainingEstimate ?? 0)) / 60 / 60) * 80 + (issue.${additionalExpensesFieldId} ?? 0)

This expression visualizes the total costs spent for the issue you’re currently viewing and its children. Including personnel costs (time spent + remaining estimate * hourly rate) and any additional costs like invoices etc. Additional costs will have to be filled into a custom field. 

In order for this expression to work you will need to fill in your company’s hourly rate and the custom field id for your additional cost custom field.