Enables an application developer to specify a parent-child hierarchy that s/he wants to make explicitly accessible in a data model, together with the structure that defines this hierarchy.
@Scope:[#VIEW] Annotation Hierarchy { parentChild : array of { name : String(127); label : String; multipleParents : Boolean default true; recurseBy : elementRef; recurse { parent : array of elementRef; child : array of elementRef; }; siblingsOrder : array of { by : elementRef; direction : String(4) enum { ASC = 'ASC'; DESC = 'DESC'; } default #ASC; }; rootNode { visibility : String(25) enum { ADD_ROOT_NODE_IF_DEFINED; ADD_ROOT_NODE; DO_NOT_ADD_ROOT_NODE; } default #ADD_ROOT_NODE_IF_DEFINED; }; orphanedNode { handling : String(20) enum { ROOT_NODES; ERROR; IGNORE; STEPPARENT_NODE; } default #ROOT_NODES; stepParentNodeId : array of String; }; directory : associationRef; }; };
A simple example of a parent-child hierarchy is the “Employee” master data. A “Manager” is an “Employee” and almost every “Employee” is assigned to a “Manager”.
On entity level the following metadata can be defined:
Annotation | Meaning | |
---|---|---|
Hierarchy.parentChild.directory |
For external hierarchies, the view of hierarchy nodes often contains the nodes for multiple alternative hierarchies. A user is supposed to choose a single hierarchy for display, and his/her selection is used as a filter when selecting from the hierarchy node view. The directory annotation identifies an association, the hierarchy directory association, from the hierarchy node view to a view (the so-called hierarchy directory), providing all available alternative hierarchies for this hierarchy node view. Scope: #VIEW Evaluation Runtime (Engine): Analytic manager: The hierarchy directory is used as user input help, and a chosen hierarchy directory entry is used to filter the nodes via the hierarchy directory association. |
|
Value | Description | |
associationRef | Name of the hierarchy directory that is used to filter the nodes | |
Hierarchy.parentChild.label |
User-friendly name of the hierarchy. Scope: #VIEW Evaluation Runtime (Engine): Analytic manager: This name can be exposed in input help for Hierarchy.parentChild.name. Values (optional): |
|
Value | Description | |
String | Description of the hierarchy. | |
Hierarchy.parentChild.multipleParents |
Indicates that multiple parents might occur in the hierarchy. Note
In a geographic hierarchy for example, you might want to assign the country Turkey to the continents Europe and Asia. Caution
We need to distinguish the above use case from the following one: In a time hierarchy YEAR, QUARTER, MONTH January under 2011 and January under 2012 are not the same member with multiple parents. They are different Januaries. Scope: #VIEW Evaluation Runtime (Engine): The analytic manager can handle hierarchies with multiple roots. This annotation is only relevant for engines that cannot handle multiple roots. |
|
Value | Description | |
Boolean (true, false) |
Defines whether multiple parents occur in the hierarchy or not. Default: true |
|
Hierarchy.parentChild.name |
Technical name of the hierarchy. Only relevant if the view defines one hierarchy only, and Hierarchy.parentChild.directory is not used. Scope: #VIEW Evaluation Runtime (Engine): Analytic manager: The hierarchy is accessed in queries or in program logic later on via this name. |
|
Value | Description | |
String | Technical name of the hierarchy. | |
Hierarchy.parentChild.orphanedNode.handling |
Defines how nodes without a parent (more precisely with a parent that does not occur as a child) are processed. Scope: #VIEW Evaluation Runtime (Engine): Depending on the annotation value, the analytic manager will ignore orphaned nodes, treat them as root nodes, put them under a step parent node or raise an error. |
|
Value | Description | |
ROOT_NODES |
Treat nodes as root nodes (default). |
|
ERROR |
Stop processing and show an error. |
|
IGNORE |
Ignore nodes and remove them from the hierarchy. |
|
STEPPARENT_NODE |
Put nodes under a step parent node |
|
Hierarchy.parentChild.orphanedNode.stepParentNodeId |
Defines how nodes without a parent (more precisely with a parent that does not occur as a child) are processed. Scope: #VIEW Evaluation Runtime (Engine):
Analytic manager:
|
|
Value | Description | |
stepParentNodeId | node ID(s) of the step parent node(s) | |
Hierarchy.parentChild.recurse.child |
If the underlying view definition does not contain an association defining the parent-child relationship but only “normal” elements, this annotation has to be used to define the children. Scope: #VIEW Evaluation Runtime (Engine): Analytic manager |
|
Value | Description | |
array of elementRef; | The element names define the key elements of the “child”. | |
Hierarchy.parentChild.recurse.parent |
If the underlying view definition does not contain an association defining the parent-child relationship but only “normal” elements, this annotation has to be used to define the parents. Scope: #VIEW Evaluation Runtime (Engine): Analytic manager |
|
Value | Description | |
array of elementRef; | The element names define the key elements of the “parent”. | |
Hierarchy.parentChild.recurseBy |
Defines the parent-child relationship in a hierarchy based on an existing association from hierarchy node to its parent node in the same view. Scope: #VIEW Evaluation Runtime (Engine): Analytic manager |
|
Value | Description | |
elementRef | The name of the parent-child association needs to be specified here. | |
Hierarchy.parentChild.rootNode.visibility |
Using this annotation, you can define dedicated metadata for how to handle root node(s) in the hierarchy. Scope: #VIEW Evaluation Runtime (Engine): Depending on the annotation value, the analytic manager might add an extra root node to the hierarchy. The label of this node is the value of Hierarchy.parentChild.label. |
|
Value | Description | |
ADD_ROOT_NODE_IF_DEFINED |
The system will add the root node of the hierarchy if it is explicitly defined, but the system will not add an extra artificial root node. This is the default. |
|
ADD_ROOT_NODE |
The system will always add an artificial single root node to the hierarchy. All other nodes are descendants of this node. |
|
DO_NOT_ADD_ROOT_NODE |
The system will not add an artificial single root node to the hierarchy. |
|
Hierarchy.parentChild.siblingsOrder.by |
Hierarchy.parentChild.siblingsOrder defines the order of values with the same parent. Hierarchy.parentChild.siblingsOrder.by defines the element name, which contains the values to be ordered. Scope: #VIEW Evaluation Runtime (Engine): The analytic manager sorts all children of a node in the given order. |
|
Value | Description | |
elementRef | element name | |
Hierarchy.parentChild.siblingsOrder.direction |
Hierarchy.parentChild.siblingsOrder defines the order of values with the same parent. Hierarchy.parentChild.siblingsOrder.direction defines if the sort order of values with the same parent is “ascending” or “descending”. Scope: #VIEW Evaluation Runtime (Engine): The analytic manager sorts all children of a node in the given order. |
|
Value | Description | |
ASC |
The sort order is ascending (default). |
|
DESC |
The sort order is descending. |
Parent Child Hierarchy for Views with Associations:
@Analytics : { dataCategory : #DIMENSION, replicationEnabled } @Hierarchy.parentChild : [ { name : ‘Organisation’, recurseBy : ‘Manager’} ] entity Employee { key ID : String(8); Manager : Association to this; ... };
Parent Child Hierarchy for Views without Associations:
@Analytics : { dataCategory : #DIMENSION, replicationEnabled } @Hierarchy.parentChild : [ { name : ‘Organisation’, recurse : { parent : [ ‘Manager’ ] , child : [ ‘ID’] } } ] entity Employee { key ID : String(8); Manager : String(8); ... };
Hierarchy Directory Association:
@Analytics : { dataCategory : #HIERARCHY } @Hierarchy.parentChild : { recurseBy : ‘ParentNode’, directory: ‘CostCenterHierarchyDirectory’ } entity CostCenterHierarchyNode { key CostCenterHierarchyDirectory : Association to CostCenterHierarchyDirectory; key HierarchyNode : CostCenterHierarchyNode; ParentNode : Association to this; ... };