projectdoc Toolbox

Space shortcuts

Page tree

Versions Compared

Old Version 27

changes.mady.by.user Robert Reiner

Saved on

compared with

New Version 28

changes.mady.by.user Robert Reiner

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
titleMacro Body

The body contains the set of formula specifications to calculate values. Each specification of a formula contain a

  1. Name,
  2. the Format,
  3. the Document Formula,
  4. the Result Formula,
  5. the Input Mapping, and
  6. the Output Mapping.

The elements of the specification are provided in any order within the cells of a table.

NameFormatDocument FormulaResult FormulaInput MappingOutput Mapping




Input Format






Output Format








..................


Section
titleName

Identifies the formula and the calculated result.


Section
titleFormat

The format used to 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
titleFormat 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
titleDocument Formula

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
titleExamples for Line Formula


Code Block
languagetext
titleCalculating story points
${Story Points} * ${Story Weight}


Code Block
languagetext
titleAdd up the team sizes
${Team Size}


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
titleExample 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
languagetext
${my-macro-id.a-formula-name}

The following example shows the use of a reference with the Result Formula.

The following example shows the use of a reference with the Document Formula (the source table is unchanged from the previous example):

The formula name of the reference may be qualified as shown in Result Formula.


Section
titleResult Formula

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.

PlaceholderDescription
 ${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
titleExamples for Aggregate Formula


Code Block
languagetext
titleUse the sum
${SUM}


Code Block
languagetext
titleUse the average
${AVG}


Code Block
languagetext
titleSome formula
${PROD}/${COUNT} + 10




Section
titleInput Mapping

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 rendered input form.

Example Box
titleExample configuration for the Input Mapping


Input Mapping


Good2
Great4
Top Notch8



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

In-Document Link
anchorFormat
.

Example Box
titleExample configuration for the Input Mapping with a specific Format


Input Mapping

percent

20%0.2
40%0.4
50%0.5




Example Box
titleExample configuration for the Input Mapping to group Values


Input Mapping


[;10]1
]10;50]2
]50;]3




percent

0.5

Caution Box
titleInput 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.

This is currently not used. We may allow in a future version to have ranges for the input mapping. In this case the value from the document will be parsed with the format specified here. Currently the input mapping is just matching the string value.

Input Mapping
20%0.2
40%0.4
50%



Section
titleOutput Mapping

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 first column allows single numeric values and ranges of the format:

Code Block
languagetext
titleRange format
D MIN ; MAX D


TokenDescription
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
titleRange examples


Code Block
languagetext
titleEvery value greater than or equal to 10 and smaller than or equal to 30 is accepted
[10;30]


Code Block
languagetext
titleAny number smaller than or equal to 30 is accepted
[;30]


Code Block
languagetext
titleThe number must be exactly 30 - both representations are correct
30

[30;30]


Code Block
languagetext
titleEvery value greater than 10 is accepted
]10;]



Example Box
titleExample configuration for the Output Mapping


Output Mapping


[;10]
Status
colourGrey
titleGood
]10;20]
Status
colourBlue
titleGreat
]20;]
Status
colourGreen
titleTop 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

In-Document Link
anchorFormat
.

Example Box
titleExample 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
colourGrey
titleGood (${LIT})
]10%;20%]
Status
colourBlue
titleGreat (${LIT})
]20%;]
Status
colourGreen
titleTop notch! (${LIT})



Caution Box
titleUppercase Issue

The Status Macro is unfortunately altering the input label to upper case. Therefore only properties with uppercase names can be referenced with this macro.




...

About

This site is maintained by smartics.

Imprint / Impressum

Data Privacy / Datenschutz 

End User License Agreement (EULA)


To get in touch please send us an e-mail!

smartics email

Keep up-to-date!

Read our

smartics Blog

Follow us on

Twitter YouTube Prezi

Find us on

Bitbucket GitHub Atlassian Marketplace

Powered by




© 2001-2023 smartics - Kronseder & Reiner GmbH