Creating a Formula
Formulas can be used within:
- Formula Columns - the expression is calculated for each visible row in the displayed structure or query result.
- Automation - formulas can be used to filter a structure (Filter by Attribute), sort the structure (Sort by Attribute), or group issues (Group by Text Attribute) based on the results of a formula.
- Effectors - the results of a formula can be written to a Jira field using the Attribute to Issue Field Effector.
In the following guide, we'll show you had to enter a formula in a formula column. The same steps can also be used within Automation, including Effectors.
1. Enter your formula
Formulas should be constructed using the Expr Language, a simple language that supports variables, arithmetic operations and functions. For a brief overview, see Expr Language.
When you're finished, click Save.
2. Check your formula
When you click Save, Structure will review your formula, attempt to link your variables to issue fields or other attributes and notify you of any errors. If the formula is ready to be used, a green mark is displayed. If it's not, the problematic parts are highlighted in the formula editor with red color.
If there are no issues, you're done! If you're working with a formula column, the results will appear next to the editor.
The example above is a simple formula to calculate whether or not we're on target to complete each epic on time:
IF type = "epic" :
originalEstimate - SUM#children { timeSpent + remainingEstimate }In case you're not yet fluent in Expr, we're telling Structure to:
- Check whether the Issue Type is an epic: IF type = "epic" :
- If so, add the Time Spent and Remaining Estimate for each child issue: { timeSpent + remainingEstimate }
- Total that value for all the child issues: SUM#children
- Subtract that total from the epic's Original Estimate: originalEstimate - ...
If you're not sure what formula you want to create, try using one of our bundled formulas - just click Load Formula... to see what's available.
Handling Errors
Formula errors are typically due to one of the following:
- Unmapped Variables - Structure attempts to map your variables to known attributes; however, depending on how you've named a variable, you may need to map it manually.
- Syntax Error - occurs when Structure does not understand something in your formula. Often this is something as simple as missing a closing parenthesis or other punctuation. Review the formula and consult our Expr Language guide if you're unsure how to correct it. The part of the formula that failed to parse will be highlighted in red.
- Function Resolution Error - occurs when the formula contains an unknown function. Review the formula and make sure the functions marked in red are spelled correctly. If so, check our Expr Function Reference and Aggregate Function Reference to ensure you're using a supported function.
- Expr Validation Error - occurs when there is a construct that is not allowed in a formula. Hover over the red highlighted part of the formula to see the error message. If multiple areas are highlighted, there are multiple errors to fix. Check the list of possible validation errors to learn more.
Handling Unexpected Results
In some cases, the formula may pass inspection, but the results aren't what you expected. You may simply need to edit your variables, options or format; or you may need to revise the formula itself by clicking the Edit button.
Full Screen
The initial sizing for the formula editor is rather small. If you need more space, drag the corner of the field or click Full-Screen to expand the window.
Additional Resources