Consumption Annotations

Define a specific behavior that relates to the consumption of CDS content through domain-specific frameworks.

Scope and Definition

@Scope:[#ELEMENT, #PARAMETER]
Annotation Consumption
 {
   labelElement : elementRef;
   quickInfoElement : elementRef;
   valueHelp : elementRef;
   hidden : Boolean default true;
   derivation
   {
      lookupEntity : entityRef;
      resultElement : elementRef;
      resultElementHigh : elementRef;
      binding : array of
      {
         targetParameter : parameterRef;
         targetElement : elementRef;
         type : String(10) enum { PARAMETER; CONSTANT; };
         value : String(512);
      };
   };
 };
@Scope:[#VIEW, #TABLE_FUNCTION, #PARAMETER, #ELEMENT]
Annotation Consumption
 {
   semanticObject : String;
 };
@Scope:[#ELEMENT] 
 {
   derivation.resultHierarchyNode: 
   {
      nodeTypeElement : elementRef ;
      mapping: array of { hierarchyElement : elementRef ;
                          lookupElement: elementRef } };

   filter
   {
      mandatory : Boolean default true;
      selectionType : String(20) enum { SINGLE; INTERVAL; RANGE; HIERARCHY_NODE; };
      multipleSelections : Boolean default true;
      defaultValue : Expression;
      defaultValueHigh : Expression;
      defaultHierarchyNode: { nodeType : elementRef ;
             				 node : array of { element : elementRef;
                              				  value : expression } };
      hidden : Boolean default true;
      hierarchyBinding : array of
      {
         type : String(10) enum { ELEMENT; PARAMETER; CONSTANT; USER_INPUT; };
         value : String(512);
         variableSequence : Integer;
      };
   };
   groupWithElement: elementRef;
 };
@Scope:[#PARAMETER]
Annotation Consumption
 {
   defaultValue : Expression;
 };

Usage

Via these annotations, the specific behavior is defined which is related to the consumption of CDS content. This metadata makes no assumptions about the concrete consumption technology/infrastructure, but it is applicable across multiple consumption technologies (e.g. Analytics or OData).

Annotation Meaning
Consumption.defaultValue

This annotation enables specification of a default value for a View parameter

Scope: #PARAMETER

Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.

Values:

This value is either proposed to the end user or implicitly set by the consumer (framework) of the view whenever the end user does not explicitly specify a different value. This default value is transparent for the CDS runtime, which means that the View parameter is still mandatory at this level. Therefore, the consumption framework is responsible for passing the specified default value as a parameter binding when the view is invoked.

Consumption.derivation

This annotation enables derivation of the value for a parameter or a filter automatically at runtime by selecting a row from a given entity (table).

An element can be annotated with Consumption.derivation only if for this element Consumption.filter is present. The derivation is then used to determine the filter value. An empty derivation of a hidden and mandatory parameter/filter will cause a runtime error.

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.

Consumption.derivation.binding.targetElement

This sub-annotation enables provision of a parametrization for the (scalar) input parameters of lookupEntity or procedure.

Value Description
elementRef
Consumption.derivation.binding.targetParameter

This annotation enables provision of a parametrization for the (scalar) input parameters of the lookupEntity procedure. This sub-annotation specifies a parameter name of lookupEntity or procedure.

Value Description
parameterRef
Consumption.derivation.binding.type

This sub-annotation specifies how the target is filled (by a constant, a parameter or a (filtered) element).

The following enumerations (String (10)) are provided:

Value Description
#ELEMENT
#PARAMETER
#CONSTANT
Consumption.derivation.binding.value

This sub-annotation contains, depending on the type, the constant value, the parameter name (without : or $parameter) or the element name.

Value Description
String (512) constant value, parameter name (without : or $parameter) or element name
Consumption.derivation.lookupEntity

Reads the result to fill the parameter.

Values:

Description
entityRef
Consumption.derivation.resultElement

Element of the entity/scalar export parameter of the procedure providing the result.

Values:

Description
elementRef
Consumption.derivation.resultElementHigh

Element of the intervall export parameter of the procedure providing the result.

Values:

Description
elementRef
Consumption.derivation.resultHierarchyNode.nodeTypeElement

This annotation has to reference a field in the lookup entity, which returns the node types. In Consumption.derivation either resultElement or resultHierarchyNode can be used.

A chargeable node is a node with node type equal to the element.

There is the need to distinguish between the node (a set of all its leaves) and the pure leaf.

  • If the selected value for Consumption.derivation.resultHierarchyNode.nodeTypeElement is initial, then the leaf will be addressed.

  • If the value is equal to the element, for which it is used, then the node will be addressed.

  • If there is no node with such a name, then the leaf is addressed.

Values:

Description
elementRef

This is a field in the lookup view which returns the element which describes the node type.

Consumption.derivation.resultHierarchyNode.mapping

The view defined in lookupEntity contains fields which can be mapped to the semantic fields of the hierarchy node view. The mapping of the fields is described in Consumption.derivation.resultHierarchyNode.mapping. This annotation is optional and can be omitted, if the fieldnames in the lookup entity correspond to these in the hierarchy node view.

Array of:

Description
hierarchyElement : elementRef
lookupElement: elementRef
Consumption.filter

This annotation enables filtering elements of the underlying view. A filter should be specified before executing a query on the view.

Scope: #ELEMENT

Evaluation Runtime (Engine):
  • Analytic Manager

    • Consumption.filter.defaultValueHigh
    • Consumption.filter.defaultHierarchyNode
    • Consumption.filter.hierarchyBinding.type
    • Consumption.filter.hierarchyBinding.value
    • Consumption.filter.hierarchyBinding.variableSequence
  • SADL - Translates the following CDS annotations into the corresponding OData annotations:
    • Consumption.filter.defaultValue
    • Consumption.filter.hidden
    • Consumption.filter.mandatory
    • Consumption.filter.multipleSelections
    • Consumption.filter.selectionType
Consumption.filter.defaultValue

This annotation can be used to provide a fixed default value for a filter. This value is completely transparent for the CDS runtime, which means that the consumer is responsible for explicitly extending the - This annotation will be interpreted by the analytic manager: WHERE condition.

The default value is either proposed to the end user or implicitly set by the consumer (framework) of the view whenever the end user doesn’t explicitly specify a different value.

Value Description
Expression Characteristic members need to be provided in an internal noncompounded format.
Consumption.filter.defaultValueHigh

This annotation, together with Consumption.filter.defaultValue, allows to specify a default interval.

Value Description
Expression Characteristic members need to be provided in an internal noncompounded format.
Consumption.filter.defaultHierarchyNode.nodeType

Consumption.filter.defaultHierarchyNode can only be used in combination with Consumption.filter.selectionType = #HIERARCHY_NODE.

In Consumption.filter.hierarchyBinding, the hierarchy is specified

The nodeType-annotation references to elements in the hierarchy node view.

Value Description
elementRef
Consumption.filter.defaultHierarchyNode.node

The node - This-annotation references to elements in the hierarchy node view.

Array of: Description
element : elementRef
value : expression Elements with value initial can be omitted in the node array.
Consumption.filter.hidden

The filter will not be shown in the UIs. In combination with a derivation, this leads to a dynamic filter at runtime without user interaction.

Value Description
Boolean (true, false)

Defines whether the filter is hidden for the client or not.

Default: true

Consumption.filter.hierarchyBinding.type

This annotation determines how the key element is filled (by a constant, a parameter, a filtered element or by a user input field).

Value Description
#ELEMENT

Name of an element, which has a unique filter. At runtime, the filter value is used for this hierarchy component.

#PARAMETER

Parameter name

#CONSTANT

Constant

#USER_INPUT

USER_INPUT is optional. It will be requested at runtime of the analytic query. It can contain a name. USER_INPUT with the same name will be provided with the same user input at runtime. The variable is placed in the list of all values in accordance with Consumption.filter.hierarchyBinding.variableSequence.

Consumption.filter.hierarchyBinding.value

This annotation contains, depending on the type, a literal value, the parameter name (without : or $parameter), the element name and an identifier for the user input field, respectively.

Value Description
String(512)
Consumption.filter.hierarchyBinding.variableSequence

This annotation allows you to specify the order of parameters and variables on the variable input UIs.

In case filters or parameters are not annotated, they are displayed after the annotated ones in the order of appearance in the CDS document.

Value Description
Integer

This number defines the position of the variable generated for the user input field.

Consumption.filter.mandatory

To prompt the “Filter UI” to enforce a user entry for a (semantically) mandatory element, even if a default value exists (for example, defined through a CASE expression).

Value Description
Boolean (true, false)
Consumption.filter.multipleSelections This annotation indicates the lines that can be entered on filter input (selection) UIs combined with the following selectionType values:
Value Description
selectionType SINGLE and multipleSelections = true IN list
selectionType INTERVAL and multipleSelections = false Single interval
selectionType INTERVAL and multipleSelections = true Several intervals
selectionType RANGE and multipleSelections = true Several ranges (complete (ABAP-like) SELECT options).
Consumption.filter.selectionType

This annotation determines how values can be entered.

Value Description
SINGLE Single value
INTERVAL Special case of a range with sign = including and operator = BT.
RANGE A range is a complete (ABAP like) SELECT option including sign (including/excluding) and operator (e.g. EQ, CP, BT).
HIERARCHY_NODE Hierarchy node (means everything under the node)
Consumption.groupWithElement

This annotation enables recognition of View/ Entity elements whose values semantically depend on the values of other elements and can only be understood in their context.

Scope: #ELEMENT

Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.

Value Description
elementRef
Consumption.hidden

This annotation prevents fields from being exposed by OData. The annotation, therefore, prevents fields from being available to the client. This is necessary for system parameters because these parameters need to be filled by the runtime engine, but must not be available to the client.

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine):
  • SADL - Prevents fields from being exposed by OData.

  • Analytic Manager - For #ELEMENT: In the Analytic Query Layer, this annotation is only evaluated if the element represents a measure. Typical usecase: An element is a calculated measure, which serves as an intermediate result and shall not be shown in the Analytic Query result.

Value Description
Boolean (true, false)

Defines whether fields are available to the client or not.

Default: true

Consumption.labelElement

This annotation enables consumer frameworks (such as UI or analytical clients) to identify through which elements the explanatory texts for the "identifier" elements can be retrieved.

In cases where both the identifier elements and the text elements are exposed, the identifier elements are annotated with the labelElement annotation. They then point to the element that contains the label text. A labelElement annotation silently implies a groupWithElement annotation of the "text" element pointing to the "identifier" element.

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine): SADL - The referenced element will be handled as descriptive text of the annotated field in OData exposure scenarios.
Value Description
elementRef
Consumption.quickInfoElement

This annotation supports the same function as labelElement.

Through this annotation, the identifier elements are enriched with the information as to which elements contain the corresponding long texts. A quickInfoElement annotation silently implies a group WithElement annotation of the text element pointing to the identifier element.

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.

Value Description
elementRef
Consumption.semanticObject

This annotation enables annotation of SAP-specific business semantics, thus, extending the standardized business semantics covered by the @Semantics domain.

Consumers may leverage this enrichment for enhanced interoperability across applications.

Scope: #ELEMENT, #PARAMETER, #TABLE FUNCTION, #VIEW

Evaluation Runtime (Engine): SADL - Translates CDS annotations into the corresponding OData annotations.

Value Description
String For more information Based on Intent.
Consumption.valueHelp

This annotation enables referencing of the association to a CDS view or CDS entity that provides the value help object for the annotated element.

The ON condition of the referenced association specifies how the value help content needs to be retrieved for the element. Generic UI consumers have to identify these ValueHelp annotations and use the referenced association to retrieve the values.

Instead of defining the "Value element" of the value help view using an equal ON condition of the association, you can also specify the "value element" in the annotation and then have no or non-equal ON conditions for the "value element".

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine): SADL - Derives a default value help support from the annotated association.

Value Description
elementRef

Examples

Example 1

The annotations Consumption.labelElement and Consumption.quickInfo are used to link the corresponding text and ID fields:

Example 2

The annotation Consumption.groupWithElement is used to define that the element CompanyName depends semantically on the element BuyerGuid. In the case of an aggregated table, the fields can be displayed combined:

Example 3

The annotation Consumption.hidden is used to prevent fields from being exposed by OData. The annotation, therefore, prevents fields from being available to the client. This is necessary for system parameters because these parameters need to be filled by the runtime-engine, but must not be available to the client:

Example 4

The annotation Consumption.defaultValue is used to specify default values for parameters. In this example, the currency EUR is used:

Example 5

The annotation Consumption.valueHelp is used to expose an association as a value help. In this example, the CDS view CurrencyCodeValueHelp is used for the field CurrencyCode:

Example 6

The association Consumption.semanticObject is used to assign semantic objects to CDS views or elements that can be used in the UI for intent-based navigation.

Example 7

The annotation Consumption.filter is used to enable filters for values. In this example, product_hierarchy is filtered for several single values of calendar_day, and for one single interval of product.

Example 8

The annotation Consumption.filter is used to enable filters for values. In this example, costcenter_reporting is filtered hierarchically for the constant CONTR_AREA_10 and for the parameter cost_center_hier_param.

Example 9

This example shows how to specify hierarchy nodes as default value in the Consumption.filter annotation. A consumption view should provide a prompt for a hierarchy node of a costcenter hierarchy with default 1000/ALL (HierarchyNode).

Example 10

This example shows how to enable the Consumption.derivation annotation to return hierarchy nodes. The annotation Consumption.derivation.resultHierarchyNode is used to return hierarchy nodes. Given a view CostcenterResponsible with fields field1, field2, field3, field4, and responsible. The query view should filter by the costcenter nodes the given responsible (parameter) is responsible for.

The hierarchy binding is derived from Consumption.filter.hierarchyBinding. Consumption.derivation can only be used in combination with Consumption.filter. Futhermore Consumption.filter.selectionType: #HIERARCHY_NODE has to be true.