| Document Properties Marker |
|---|
| doctype | app-macro |
|---|
| override | false |
|---|
|
| Short Description | Run calculations on a set of result documents and renders the results. |
|
|---|
| Name | Calculation Macro | hide |
|---|
| Short Name | | hide |
|---|
| Parent | | hide |
|---|
| Audience | | Name List |
|---|
| doctype | role |
|---|
| render-no-hits-as-blank | true |
|---|
| property-restrict-value-range | true |
|---|
| property | Audience |
|---|
| empty-as-none | true |
|---|
|
|
|
|---|
| Subject | | Name List |
|---|
| doctype | subject |
|---|
| property | Subject |
|---|
|
|
|
|---|
| Categories | | Name List |
|---|
| doctype | category |
|---|
| property-restrict-value-range | true |
|---|
| property | Categories |
|---|
|
|
|
|---|
| Tags | | Tag List |
|---|
| |
|---|
| names | Calculation |
|---|
| property | Tags |
|---|
|
| hide |
|---|
| Flags | | hide |
|---|
| Iteration | | hide |
|---|
| Identifier | projectdoc-calculation-macro |
|
|---|
| Type | | Name List |
|---|
| doctype | app-macro-type |
|---|
| render-no-hits-as-blank | true |
|---|
| property-restrict-value-range | true |
|---|
| property | Type |
|---|
|
|
|
|---|
| Suite | | Name List |
|---|
| doctype | app, app-extension, product-space |
|---|
| render-no-hits-as-blank | true |
|---|
| property-restrict-value-range | true |
|---|
| defaults-to | ancestor |
|---|
| property | Suite |
|---|
|
| hide |
|---|
| App Tool | | Name List |
|---|
| doctype | app-tool |
|---|
| render-no-hits-as-blank | true |
|---|
| property-restrict-value-range | true |
|---|
| defaults-to | ancestor |
|---|
| property | App Tool |
|---|
|
|
|
|---|
| Since |
|---|
52| 0 |
| | Deprecated | |
|
|---|
| Removed | |
|
|---|
| Defined Parameters | | Name List |
|---|
| doctype | app-parameter |
|---|
| render-no-hits-as-blank | true |
|---|
| render-list-as-comma-separated-values | true |
|---|
| no-create-links | true |
|---|
| property-restrict-value-range | false |
|---|
| property | Defined Parameters |
|---|
|
| hide |
|---|
| Page Size Support | |
|
|---|
| Sort Key | | hide |
|---|
|
| Section |
|---|
| show-title | false |
|---|
| title | Description |
|---|
|
Provide a query to select a set of documents and use formulas to calculate a couple of values. One of these values is rendered, the rest can be accessed by additional macros. The advantage is mainly that calculating a couple of values is calculated with a higher performance. |
| Section |
|---|
| title | Parameters |
|---|
| intro-text | The macro is configured by the following parameters. |
|---|
|
| Section |
|---|
| | Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
| ids | Doctype(s) |
|---|
|
|
|
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
| ids | Space Keys |
|---|
|
|
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
| ids | Where |
|---|
|
|
| Section |
|---|
| | Transclusion |
|---|
taget-heading-level | * |
|---|
| document | Sort By Property |
|---|
| ids | Sort By |
|---|
|
|
|
| Section |
|---|
| | Unique Optional identifier of for the rendered contentHTML element. |
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
| ids | Exclude Self |
|---|
|
|
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
| ids | Restrict to immediate ChildrenMax Hit Count |
|---|
|
|
| projectdoc-section |
|---|
| title | Render individual Results |
|---|
| | transclusion-macro |
|---|
| taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
| ids | Restrict to immediate Children |
|---|
| If checked there is a data attribute added to the rendered element for each line result. If not checked only the data attributes provided by default are added. | | Data Attribute |
| Description |
|---|
data-projectdoc-result-count | Provided by Default | The size of the result set. Note that the count of formulas may be smaller than this number if documents in that set do not provide all values required for the Line Document Formula. | data-projectdoc-result-...-N | Requires value of true | The infix for this attribute name (...) is derived from the name of the formula that created it. The 1-based index of the document that provided the values for it. | data-projectdoc-finalresult-... | Provided by Default | The final result of the formula with a derived name of the formula is used as a suffix. |
| | Section |
|---|
| If no Document Formula is specified, then no individual results will be calculated and therefore not added. If not checked only the data attributes provided by default are addedList of HTML class names to be added to the rendered HTML element. |
| Section |
|---|
| title | Render | Restrict to Favored |
|---|
| | Transclusion |
|---|
| document | Display Table Macro |
|---|
| ids | Restrict to Favored |
|---|
|
|
|
| Section |
|---|
| List of HTML class names to be added to the rendered HTML element. |
| Section |
|---|
| Controls the rendering of the calculated value. The following values for this parameter are valid. | Parameter Value | Description |
|---|
first |
Controls the rendering of the calculated value. The following values for this parameter are valid. | Parameter Value | Description |
|---|
first | The value calculated by the first formula is rendered (default). | none | Nothing is rendered as text, but the element with the data elements still is. Choose this option if all calculated values are rendered at different locations down the document. | last | The value calculated by the last first formula is rendered (default). Choose this option if your formula requires the result of prior defined formulas |
| | Transclusion |
|---|
none | Nothing is rendered as text, but the element with the data elements still is. Choose this option if all calculated values are rendered at different locations down the document. | last | The value calculated by the last formula is rendered. Choose this option if your formula requires the result of prior defined formulas |
| | taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
ids | Render no hits as blank |
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
| ids | Render no hits as blank |
|---|
|
|
| Section |
|---|
| Text to be rendered if no result is available. This overrides the default text. |
| Section Index |
|---|
| select | Name, Short Description, Data Type|, Since| |
|---|
| render-counter-column | true |
|---|
| | Section Compiler by Reference |
|---|
| ref | Defined Parameters |
|---|
| render-classes | parameters-sections, section-compiler-by-reference, parameters |
|---|
| force-show | true |
|---|
| ids | -Description, Details |
|---|
| extract-short-desc | true |
|---|
|
|
|
|
| Section |
|---|
|
The body contains the set of formula specifications to calculate values. Each specification of a formula contain a - Name (required),
- the Aggregate FormulaFormat,
- the FormatDocument Formula,
- the Line Result Formula,
- the Input Mapping, and
- the Output Mapping.
The elements of the specification are provided in any order within the cells of a table. Line Aggregate | Result Formula | Input Mapping | Output Mapping |
|---|
|
|
|
| Input Format | Output Format | | ... | ... | ... | ... | ... | ... |
| Section |
|---|
| Identifies the formula and the calculated result. |
| Section |
|---|
| title | Aggregate FormulaFormat |
|---|
| The formula format used to aggregate the single values extracted by the Line Formula. The formula may contain placeholders to values of the document that contains the macro. The formula may use the placeholders ${SUM} and ${COUNT}. Formulas may use values calculated by formulas defined in a line before it. | | Placeholder | Description |
|---|
${SUM} | The sum of values calculated by the Line Formula. | ${COUNT} | The count of documents that provided a value for the Line Formula. For instance if a document does not apply properties for all values of the Line Formula, it does neither contribute to the sum nor to the count. | ${NAME_OF_FORMULA} | Where NAME_OF_FORMULA stands for the name of a formula that has been define above the formula that wants to use it. | ${NAME_OF_FORMULA$} | The sum value calculated by the formula named NAME_OF_FORMULA. | run the calculations of the formulas. The format is also used to translate the calculated value of the Document Formula and the input value to the Result Formula. Per default the format is also used to parse the input value for the Input Mapping and the output value of the Output Mapping, but only if the column is specified left of the mapping columns. This format is also called the Formula Format. The format to parse the input value or to format the output value can be specified with the mapping columns (see below). The value is a valid number format in Java and defaults to decimal. Valid values are integer, decimal, currency, and anything that can be parsed by DecimalFormat. | Caution Box |
|---|
| title | Format applied to Formulas |
|---|
| Note that the format will be applied to the Document Formula (right column) and the Result Formula (left column) in case the Format column is specified left of them. |
| Section |
|---|
| The formula applied to calculate from each document in the result set. Use placeholders, like ${Document_Propery_Name} to select values from the documents in the result set | ${NAME_OF_FORMULA§} | The count value calculated by the formula named NAME_OF_FORMULA. | Example Box |
|---|
| title | Examples for Aggregate Line Formula |
|---|
| | Code Block |
|---|
| language | text |
|---|
| title | Use the sumCalculating story points |
|---|
| ${SUM}Story Points} * ${Story Weight} |
| Code Blockcode |
|---|
| language | text |
|---|
| title | Use Add up the averageteam sizes |
|---|
| ${SUM}/${COUNT} |
|
| Section |
|---|
| The format used to translate the calculated value, both of the Aggregate Formula and the Line Formula. The value is a valid number format in Java and defaults to decimal. Valid values are integer, decimal, currency, and anything that can be parsed by DecimalFormat. |
| Section |
|---|
|
|
The formula applied to calculate from each document in the result set.
Use placeholders, like ${Document_Propery_Name} to select values from the documents in the result set.
| Example Box |
|---|
| title | Examples for Line Formula |
|---|
|
| Code Block |
|---|
| language | text |
|---|
| title | Calculating story points |
|---|
|
${Story Points} * ${Story Weight} |
| Code Block |
|---|
| language | text |
|---|
| title | Add up the team sizes |
|---|
|
${Team Size} |
| Section |
|---|
|
| Pending Box |
|---|
|
A table to map an input to be applied to a value read from the documents. This allows to translate text to double values. |
| Section |
|---|
|
A table to map a double result value to a textual value, such as the Status Macro.
The first column allows single numeric values and ranges of the format:
| Code Block |
|---|
| language | text |
|---|
| title | Range format |
|---|
|
D MIN ; MAX D |
| Token | Description |
|---|
D | The delimiter D may be either [ or ]. - If
[ is specified for- the start value, then the start value is included.
- the end value, then the end value is excluded.
- If
] is specified for- the start value, then the start value is excluded.
- the end value, then the end value included.
|
MIN | The minimum value of the range. If omitted, the minimum value of the range is the absolute minimum value. Any value smaller than MAX is accepted. |
MAX | The maximum value of the range. If omitted, the maximum value of the range is the absolute maximum value. Any value greater than MIN is accepted. |
The defined mappings are processed from top to bottom. The first matching rule provided the representation.
Where one space is shown in the format above there may be any number of spaces, including zero spaces.
| Example Box |
|---|
|
| Code Block |
|---|
| language | text |
|---|
| title | Every value greater than or equal to 10 and smaller than or equal to 30 is accepted |
|---|
|
[10;30] |
| Code Block |
|---|
| language | text |
|---|
| title | Any number smaller than or equal to 30 is accepted |
|---|
|
[;30] |
| Code Block |
|---|
| language | text |
|---|
| title | The number must be exactly 30 - both representations are correct |
|---|
|
30
[30;30] |
| Code Block |
|---|
| language | text |
|---|
| title | Every value greater than 10 is accepted |
|---|
|
]10;] |
| Example Box |
|---|
| title | Example configuration for the Output Mapping |
|---|
|
| Output Mapping |
|---|
[;10] | | Status |
|---|
| colour | Grey |
|---|
| title | Good |
|---|
]10;20] | | Status |
|---|
| colour | Blue |
|---|
| title | Great |
|---|
| ]20;] | | Status |
|---|
| colour | Green |
|---|
| title | Top notch! |
|---|
|
|
The Document Formula may also access the result of formulas specified in a line prior to this one. Also the results of formulas in Calculation Macros already processed can be accessed. | Example Box |
|---|
| title | Example to reference the Result of a previous Macro |
|---|
| The following example access the result value of a formula named a-formula-name within the Calculation Macro identified by my-macro-id. | Code Block |
|---|
| ${my-macro-id.a-formula-name} |
The following example shows the use of a reference with the Result Formula.  Image Added
The following example shows the use of a reference with the Document Formula (the source table is unchanged from the previous example):  Image Added
|
The formula name of the reference may be qualified as shown in Result Formula. |
| Section |
|---|
|
The formula to be applied to the result of the Document Formulas. The formula may contain placeholders to values of the document that contains the macro. The formula may use the placeholders ${SUM}, ${PROD}, ${COUNT}, ${MIN}, and ${MAX}. Formulas may use values calculated by formulas defined in a line before it. | Placeholder | Description |
|---|
${SUM} | The sum of values calculated by the Document Formula. | ${PROD} | The product of values calculated by the Document Formula. | ${MIN} | The minimum value calculated by the Document Formula. | ${MAX} | The maximum value calculated by the Document Formula. | ${COUNT} | The count of documents that provided a value for the Document Formula. For instance if a document does not apply properties for all values of the Document Formula, it does neither contribute to the sum nor to the count. | ${AVG} | The average value calculated by the Document Formula. | ${name-of-formula_LIT} | The literal value calculated by the formula named name-of-formula. Useful if the calculated value is rendered in an HTML element without value or if the output mapping maps the result values to an array of values. The value is rendered in the Output Format. | ${name-of-formula} | The result value of the formula. The value is rendered in the Formula Format. | ${name-of-formula_SUM} | The sum value calculated by the formula named name-of-formula. The value is rendered in the Formula Format. | ${name-of-formula_PROD} | The product value calculated by the formula named name-of-formula. The value is rendered in the Formula Format. | ${name-of-formula_MIN} | The minimum value calculated by the Document Formula of name-of-formula. The value is rendered in the Formula Format. | ${name-of-formula_MAX} | The maximum value calculated by the Document Formula of name-of-formula. The value is rendered in the Formula Format. | ${name-of-formula_COUNT} | The count value calculated by the formula named name-of-formula. The value is rendered in the Formula Format. |
| Example Box |
|---|
| title | Examples for Aggregate Formula |
|---|
| | Code Block |
|---|
| language | text |
|---|
| title | Use the sum |
|---|
| ${SUM} |
| Code Block |
|---|
| language | text |
|---|
| title | Use the average |
|---|
| ${AVG} |
| Code Block |
|---|
| language | text |
|---|
| title | Some formula |
|---|
| ${PROD}/${COUNT} + 10 |
|
|
| Section |
|---|
|
A two-column table to map an input to be applied to a value read from the documents. This allows to translate text to double values and map values provided in the Input Format to be grouped by ranges. The mapping is applied to the documents of the result set and the document that contains the macro. The first column contains the value in its normalized rendered form or a range specification. The second value is the numeric value to replace that input form. The identifier (first column) must be unique within the Input Mapping of a Formula Specification. | Example Box |
|---|
| title | Example configuration for the Input Mapping |
|---|
| |
Above the table the Input Format may be specified. If it is not specified, the Input Format defaults to the Formula Format provided with the parameter . | Example Box |
|---|
| title | Example configuration for the Input Mapping with a specific Format |
|---|
| |
| Example Box |
|---|
| title | Example configuration for the Input Mapping to group Values |
|---|
| |
| Caution Box |
|---|
| title | Input Format may clash with Formula Format |
|---|
| If the values are numeric, it is recommended to use an Input Format that is compatible with the Formula Format. |
|
| Section |
|---|
|
A two-column table to map a double result value to a textual value, such as the Status Macro. The mapping is applied to the final result of the Result Formula. The identifier (first column) must be unique within the Output Mapping of a Formula Specification. The first column allows single numeric values and ranges of the format: | Code Block |
|---|
| language | text |
|---|
| title | Range format |
|---|
| D MIN ; MAX D |
| Token | Description |
|---|
D | The delimiter D may be either [ or ]. - If
[ is specified for- the start value, then the start value is included.
- the end value, then the end value is excluded.
- If
] is specified for- the start value, then the start value is excluded.
- the end value, then the end value included.
| MIN | The minimum value of the range. If omitted, the minimum value of the range is the absolute minimum value. Any value smaller than MAX is accepted. | MAX | The maximum value of the range. If omitted, the maximum value of the range is the absolute maximum value. Any value greater than MIN is accepted. |
The defined mappings are processed from top to bottom. The first matching rule provided the representation. Where one space is shown in the format above there may be any number of spaces, including zero spaces. | Example Box |
|---|
| | Code Block |
|---|
| language | text |
|---|
| title | Every value greater than or equal to 10 and smaller than or equal to 30 is accepted |
|---|
| [10;30] |
| Code Block |
|---|
| language | text |
|---|
| title | Any number smaller than or equal to 30 is accepted |
|---|
| [;30] |
| Code Block |
|---|
| language | text |
|---|
| title | The number must be exactly 30 - both representations are correct |
|---|
| 30
[30;30] |
| Code Block |
|---|
| language | text |
|---|
| title | Every value greater than 10 is accepted |
|---|
| ]10;] |
|
| Example Box |
|---|
| title | Example configuration for the Output Mapping |
|---|
| | Output Mapping |
|---|
| [;10] | | | ]10;20] | | | ]20;] | | Status |
|---|
| colour | Green |
|---|
| title | Top notch! |
|---|
|
|
|
|
Above the table the Output Format may be specified. If it is not specified, the Output Format defaults to the Formula Format provided with the parameter . | Example Box |
|---|
| title | Example configuration for the Output Mapping with specific Format |
|---|
| This example adds the placeholder for the Literal Value of the result. The value is referenced with the placeholder ${LIT}. The label has the suffix (${LIT}) in the following example. | Output Mapping |
|---|
percent | [;10%] | | Status |
|---|
| |
|---|
| colour | Grey |
|---|
| title | Good (${LIT}) |
|---|
|
| | ]10%;20%] | | Status |
|---|
| |
|---|
| colour | Blue |
|---|
| title | Great (${LIT}) |
|---|
|
| | ]20%;] | | Status |
|---|
| |
|---|
| colour | Green |
|---|
| title | Top notch! (${LIT}) |
|---|
|
|
|
| Caution Box |
|---|
| The Status Macro is unfortunately altering the input label to upper case. Therefore only properties with uppercase names can be referenced with this macro. |
|
|
| Section |
|---|
|
| Section |
|---|
| All calculations are run with double precision, therefore the macro is not suitable for formulas require with discrete values, not allowing limited precision. For instance use cases requiring calculations based on currencies (integer values) are not supported. |
| Section |
|---|
| title | Access Results from other Calculation Macros |
|---|
| To access the result from another Calculation Macro simply prefix the placeholder reference with the identifier of the macro like this: | Code Block |
|---|
${macro-id.formula-name} |
All values of a formula can be accessed as defined in . |
| Section |
|---|
| title | Result Calculation only |
|---|
| The macro allows to skip the Document Formula and only provide a Result Formula. This way a value can be calculated by the use of results previously calculated - either by a formula above in the table or by other instances of the Calculation Macro specified previously on the same page. If no Document Formula is specified, the default results, like SUM or AVG are not present, because the formula does not iterate over the documents in the result set. Only the representation, the literal, and the result are provided. | Example Box |
|---|
| This example shows how the formula named main uses the value of the revelvance-factor formula of the macro result-repo. | Name | Format | Result Formula |
|---|
| main | percent | ${result-repo.relevance-factor}*2 + 10% |
|
|
| Section |
|---|
| title | Data Center Compatibility |
|---|
| To support Atlassian Data Center the macro will limit the number of documents to use in a calculation. If the result set is larger than the maximum number of documents, an error message is rendered. For more information, please refer to | Static Document Link |
|---|
| document | Limitations on Query Results |
|---|
|
.| Version Box |
|---|
| The limitation is checked since version 6.0. |
|
|
| Section |
|---|
| title | Details |
|---|
| Section |
|---|
|
| Display Table |
|---|
| doctype | app-macro |
|---|
| render-no-hits-as-blank | true |
|---|
| render-mode | definition |
|---|
| select | Name, Short Description |
|---|
| render-classes | related-macros-table, display-table, related-macros |
|---|
| where | $<Tags>~(${Tags}) |
|---|
|
|
...
| Section |
|---|
| title | References |
|---|
| intro-text | Evidence for the information is available by the following references. |
|---|
|
| Tour |
|---|
| render-no-hits-as-blank | true |
|---|
| render-as-definition-list | true |
|---|
| marker-column-property-name | Title |
|---|
| replace-title-with-name | true |
|---|
| |
|
| Section |
|---|
| title | Resources |
|---|
| intro-text | More information on this topic is available by the following resources. |
|---|
|
| Tour |
|---|
| render-no-hits-as-blank | true |
|---|
| render-as-definition-list | true |
|---|
| marker-column-property-name | Title |
|---|
| replace-title-with-name | true |
|---|
| |
|
