Key Figures¶
As described in the section about key figure formulas, one of the main differences of key figure structures compared to other structures is the definition of formulas. To be able to support more complex formula systems, the definition of formulas will be separated from the model definition. This section describes the separate initial upload, update and export of these key figure formulas.
Structure¶
Key figures uploads and exports have the same structure and are specified in JSON.
{
"rootCubeSegment": {
"formulas": [
<KEY_FIGURE_FORMULAS_DEFINITION>,
...
]
}
}
On the top level, the definition includes the rootCubeSegment
property with a nested formulas
property with set semantics,
i. e. the order of the entries is not relevant.
This top-level structure must always be present, although it is possible for the formulas
set to be empty.
Key figures not present in formulas
have no formula.
Key Figure Formulas Definition¶
One KEY_FIGURE_FORMULAS_DEFINITION
defines the two formulas to be used for a single key figure.
{
"keyFigureReference": {
"businessKey": "CST010P"
},
"formulaForLeavesInAllOtherDimensions": <FORMULA_DEFINITION>,
"formulaForInnerNodeInAtLeastOneOtherDimension": <FORMULA_DEFINITION>
}
All properties must always be present.
keyFigureReference.businessKey
: the business key of the key figure for which the formulas are givenformulaForLeavesInAllOtherDimensions
: the formula to use for calculations of cells where the elements in all other dimensions are leaves in their hierarchy. This is the equivalent of theformula
column in the key figure structure definition (cf. key figure formulas).formulaForInnerNodeInAtLeastOneOtherDimension
: the formula to use for calculations of cells where at least one element in another dimension is an inner node in its hierarchy. This is the equivalent of theformulaForInnerNodes
column in the key figure structure definition (cf. key figure formulas).
Formula Definition¶
There are two possible definitions for a formula.
{
"type": "NONE"
}
If the formula should not be calculated, only the type
property must be present and set to NONE
.
{
"type": "DEFINED",
"formula": "[CST010]/[CST000]*100"
}
If the formula should be calculated, the type
property must be set to DEFINED
and the formula
property must contain a non-blank formula string.
This formula string can use the same constructs as previously shown for the
key figure structure definition.
Upload¶
A key figures upload works similar to an asynchronous model upload.
However, for the key figures uploads, we do not employ multipart uploads, but rather use the content type
application/x.de.qvantum-plan.external-key-figures+json
to upload a single file.
New uploads can be created at the keyFiguresUploads
link in the cube resource
(cf. navigating to a cube).
curl -i -X POST \
-H "Authorization:Bearer ${TOKEN}" \
-H "Content-Type:application/x.de.qvantum-plan.external-key-figures+json" \
-d @/absolute/path/to/key-figures.json \
"${KEY_FIGURES_UPLOADS_URL}"
The response contains a URL in the Location
header.
This URL can be used for status polling.
Important
A full interaction path with the QVANTUM public API regarding key figures
is demonstrated in the script qvantum-key-figures-import-export.sh
in our sample data set.
Export¶
An export of the current key figures is available at the endpoint specified by the
keyFigures
link in the cube resource (cf. navigating to a cube).
curl -s -X GET \
-H "Authorization:Bearer ${TOKEN}" \
-H "Accept:application/x.de.qvantum-plan.external-key-figures+json" \
"${KEY_FIGURES_URL}"
Important
A full interaction path with the QVANTUM public API regarding key figures
is demonstrated in the script qvantum-key-figures-import-export.sh
in our sample data set.