> For the complete documentation index, see [llms.txt](https://docs.qvantum-plan.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qvantum-plan.de/dev/key-figures.md). # Key Figures As described in the section about [key figure formulas](/dev/model.md#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. {% hint style="info" %} This page documents the JSON schema for cube segments (`rootCubeSegment`, `segmentation`, child/remainder segments). For a conceptual, UI-based introduction to segments — what they are for and how they are created — see the German user documentation: [Segmente und Kennzahlenformeln](/user/owner/planung/modell/segmente_und_kennzahlenformeln.md) (German) {% endhint %} ## Structure Key figures uploads and exports have the same structure and are specified in JSON. **Key Figures Definition** ```json { "rootCubeSegment": { "formulas": [ , ... ], "segmentation": } } ``` On the top level, the definition includes the `rootCubeSegment` property with the following nested properties: * `formulas`: Contains the formulas defined for the root cube segment. Key figures not present in `formulas` have no formula. The property is not optional but it may be empty. The order of the entries is not relevant. * `segmentation`: a division of the root segment into smaller segments along a dimension. This property is optional. ### Key Figure Formulas Definition One `KEY_FIGURE_FORMULAS_DEFINITION` defines the two formulas to be used for a single key figure. **Key Figure Formulas Definition** ```json { "keyFigureReference": { "businessKey": "CST010P" }, "formulaForLeavesInAllOtherDimensions": , "formulaForInnerNodeInAtLeastOneOtherDimension": } ``` All properties must always be present. * `keyFigureReference.businessKey`: the business key of the key figure for which the formulas are given * `formulaForLeavesInAllOtherDimensions`: 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 the `formula` column in the key figure structure definition (cf. [key figure formulas](/dev/model.md#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 the `formulaForInnerNodes` column in the key figure structure definition (cf. [key figure formulas](/dev/model.md#key-figure-formulas)). ### Formula Definition There are three possible definitions for a formula. **No Formula Definition** ```json { "type": "NONE" } ``` If the formula should not be calculated, only the `type` property must be present and set to `NONE`. **String Formula Definition** ```json { "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. {% hint style="info" %} For the general formula syntax and the complete function reference, see the German user documentation: [Formeln](/user/owner/planung/modell/rechenoperationen_und_formelsyntax.md) (German) {% endhint %} **Inherited Formula Definition** ```json { "type": "INHERITED" } ``` If the formula definition of the parent segment should be used, only the `type` property must be present with a value of `INHERITED`. This is not allowed in the root cube segment, since it has no parent segment. ### Segmentation Definition A `SEGMENTATION_DEFINITION` defines how a cube segment is further divided into multiple child segments. **Segmentation Definition** ```json { "dimensionReference": { "pluralName": "Cost Centers" }, "children": [ , ... ], "remainder": } ``` All properties must always be present: * `dimensionReference`: a reference (by plural name) to the dimension along which the "parent" segment is divided into smaller segments. May not reference the key figure or time dimension. * `children`: an ordered list of child segments, each responsible for some trees in the dimension. May be empty. * `remainder`: a non-optional segment for all elements whose roots were not explicitly included in any of the child segments. ### Child Cube Segment A `CHILD_CUBE_SEGMENT_DEFINITION` defines a cube segment for some trees in a dimension. **Child Cube Segment Definition** ```json { "structureElementReferences": [ { "businessKey": "CCT000" }, ... ], "displayName": "a descriptive display name", "formulas": [ , ... ], "segmentation": } ``` All properties are required * `structureElementReferences`: references (by business key) to roots of the segmented dimension. All elements inside the trees under the roots are in this segment. May be empty. * `displayName`: a descriptive name for the segment to be displayed in the application * `formulas`: the formulas for this segment. Key figures which are not listed will behave as if they have the type INHERITED for both formulas. * `segmentation`: a further segmentation of this child segment according to a different dimension ### Remainder Cube Segment A `REMAINDER_CUBE_SEGMENT_DEFINITION` defines a cube segment for all elements in a dimension that were not explicitly assigned to other child cube segments. **Remainder Cube Segment Definition** ```json { "displayName": "a descriptive display name", "formulas": [ , ... ], "segmentation": } ``` The properties are the same as in the child cube segment, except for the missing `structureElementReferences` property since the structure elements in the remainder are implicitly defined by the other child cube segments in the segmentation. ## Upload A key figures upload works similar to an [asynchronous model upload](/dev/model.md#asynchronous-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](/dev/general-information.md#navigating-to-a-cube)). **Upload Key Figures** ```sh curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:application/x.de.qvantum-plan.external-key-figures+json" \ --data @/absolute/path/to/key-figures.json \ "${KEY_FIGURES_UPLOADS_LINK}" ``` The response contains a URL in the `Location` header. This URL can be used for [status polling](/dev/model.md#upload-status-polling). ## 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](/dev/general-information.md#navigating-to-a-cube)). **Export Key Figures** ```sh curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.external-key-figures+json" \ "${KEY_FIGURES_LINK}" ```