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.

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.

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:

Example 2

Parent Child Hierarchy for Views without Associations:

Example 3

Hierarchy Directory Association: