Hierarchy Annotations

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 and Definition

@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;
   };
 };

Usage

The parent-child hierarchy is based directly on the master data entities. The hierarchy is time-dependent if the master data entity is as well. The hierarchy is defined either by one parent element (with Hierarchy.parentChild.recurseBy) or by multiple parents (with Hierarchy.parentChild.recurse). A parent element describes a self-referencing relationship within the master data entity and will usually be defined via an association. Only one level needs to be assigned to a parent-child hierarchy, because the levels in the hierarchy are taken from the parent-child relationships between members associated with the parent element. One or more parent-child hierarchies can be defined within the same master data entity.

Note

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: With the annotation `Hierarchy.parentChild.orphanedNode.handling : STEPPARENT_NODE` this annotation contains the node ID(s) of the step parent node(s). With parent-child hierarchies, you need to define a step parent node ID for each component (each parent-child combination).
	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.

Examples

Example 1

Parent Child Hierarchy for Views with Associations:

Sample Code

@Analytics : { dataCategory : #DIMENSION, replicationEnabled }
@Hierarchy.parentChild : [ { name : ‘Organisation’, recurseBy : ‘Manager’} ]
entity Employee {
key ID : String(8);
Manager : Association to this;
...
};

Example 2

Parent Child Hierarchy for Views without Associations:

Sample Code

@Analytics : { dataCategory : #DIMENSION, replicationEnabled }
@Hierarchy.parentChild : [ { name : ‘Organisation’, 
  recurse : {  parent : [ ‘Manager’ ] ,
               child : [ ‘ID’] } 
  } ]
entity Employee {
key ID : String(8);
Manager : String(8);
...
};

Example 3

Hierarchy Directory Association:

Sample Code

@Analytics : { dataCategory : #HIERARCHY }
@Hierarchy.parentChild : { 
    recurseBy : ‘ParentNode’,
    directory: ‘CostCenterHierarchyDirectory’ 
  }
entity CostCenterHierarchyNode {
 key CostCenterHierarchyDirectory : Association to CostCenterHierarchyDirectory;
 key HierarchyNode : CostCenterHierarchyNode;
     ParentNode : Association to this;
...
};