Consumption Annotations

Define 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;
      procedure : String;
      resultElement : elementRef;
      derivationFilter : String;
      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] 
 {
   filter
   {
      mandatory : Boolean default true;
      defaultValue : String;
      defaultValueHigh : String;
      hidden : Boolean default true;
      selectionType : String(20) enum { SINGLE; INTERVAL; RANGE; HIERARCHY_NODE; };
      multipleSelections : 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 those 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. Note The `defaultValue` annotation is only allowed for View parameters. Elements and default values can only be specified within filters. Hence, the annotation `@Consumption.filter.defaultValue` has to be used.
`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). The relevant attributes of a derivation rule are: `lookupEntity` - Entity which is used to read the result to fill the parameter. `procedure` - Database Procedure which is used to read the result to fill the parameter. `resultElement` - Element of the `lookupEntity` or scalar export parameter of the `procedure` providing the result `derivationFilter` - Filter on the `lookupEntity` to restrict its contents to one row (has no effect on the procedure) `binding` - Is used to provide a parameterization for the (scalar) input parameters of the `lookupEntity` or `procedure` An element can be annotated with `Consumption.derivation` only if for this element `Consumption.filter` is present. The derivation is then used for determining the filter value. An empty derivation of a hidden and mandatory parameter/filter will cause a runtime error. Note Annotation of a non-filtered element of the projection list with a derivation is not allowed. Scope: #ELEMENT, #PARAMETER Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.
`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`. Values:
	Value	Description
	`parameterRef`
`Consumption.derivation.binding.targetElement`	This sub-annotation enables provision of a parametrization for the (scalar) input parameters of `lookupEntity` or `procedure`. Values:
	Value	Description
	`elementRef`
`Consumption.derivation.binding.type`	This sub-annotation specifies how the target is filled (by a constant, a parameter or a (filtered) element). Values: 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. Note If parameter values are used in this sub-annotation, the corresponding parameter must be declared before the parameter, that is to be derived, is declared. Note All provided annotation values are treated case sensitive. Values:
	Value	Description
	`String (512)`	constant value, parameter name (without `:` or `$parameter`) or element name
`Consumption.derivation.derivationFilter`	Filter on the `lookupEntity` to restrict its contents to one row that has no effect on the procedure. This annotation won't be interpreted by the analytic query layer. Values:
	Value	Description
	`Expression`
`Consumption.derivation.lookupEntity`	reads the result to fill the parameter.
	Values:	Description
	`entityRef`
`Consumption.derivation.procedure`	Database procedure to read the result to fill the parameter. This annotation won't be interpreted by the analytic query layer.
	Values:	Description
	`String`
`Consumption.derivation.resultElement`	Element of the entity/scalar export parameter of the procedure providing the result.
	Values:	Description
	`elementRef`
`Consumption.filter`	This annotation enables filtering on elements of the underlying view. A filter should be specified before executing a query on the view. Scope: #ELEMENT Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager. Values: Usually filter values are entered manually by the user on a UI (filter popup) in order to set a filter on an element of the underlying view. Filters are not explicitly known by the Core CDS Layer, but only by the clients like Datapreview, MDX, Advanced Analysis for Office, BO Explorer or OData. It is the task of the consumption (framework) to convert the user input into the `WHERE` condition when accessing the data. Note Filters can only be specified for elements within the projection list. Specify a filter before executing a query on the view.
`Consumption.filter.defaultValue`	This annotation can be used to provide a fix 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 `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. Values:
	Value	Description
	`String`	Characteristic members need to be provided in internal noncompounded format.
`Consumption.filter.defaultValueHigh`	This annotation, together with `Consumption.filter.defaultValue`, allows to specify a default Intervall. Values:
	Value	Description
	`String`	Characteristic members need to be provided in internal noncompounded format.
`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. Values:
	Value	Description
	`Boolean`, 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). Values:
	Value	Description
	`#CONSTANT`
	`#PARAMETER`
	`#ELEMENT`
	`#USER_INPUT`
`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. Values:
	Value	Description
	`String(512)`
`Consumption.filter.hierarchyBinding.variableSequence`	This annotation defines position of the variable generated for the user input field. Values:
	Value	Description
	`#USER_INPUT`
`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). Example The user deletes the proposal for a mandatory filter in the Filter UI. The UI then displays an error message "Please enter a value for filter ...". Finally, the entered value is sent to the engine. Therefore, the Filter UI makes sure that automatic replacement of the engine is never performed for mandatory filters. Values (optional):
	Value	Description
	`Boolean`, default `true`
`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. Values:
	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. Note Whenever such elements are used for querying grouped data, the context-providing elements should also be included in the query's "group by" expression. Values:
	Value	Description
	`elementRef`
`Consumption.hidden`	This annotation prevents fields from being exposed by OData. The annotation therefore prevents fields from being available for the client. This is necessary for system parameters because these parameters need to be filled by the runtime engine, but must not be available for 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 intermediate result and shall not be shown in the Analytic Query result. Note The annotation will not be exposed to UIs. Values:
	Value	Description
	`Boolean`, 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. Note We recommend to use `ObjectModel.text.element[ ]` instead of the `Consumption.labelElement` annotation. Values:
	Value	Description
	`elementRef`
`Consumption.quickInfoElement`	This annotation supports the same scenario 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. Values:
	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. Example SAP Fiori has introduced the concept of intent-based navigation, whereby an intent is a combination `<semanticObject> <action>`. A `semanticObject` annotation is used in SAP Fiori UIs to dynamically derive navigation targets for the annotated view as a source. Scope: #ELEMENT, #PARAMETER, #TABLE FUNCTION, #VIEW Evaluation Runtime (Engine): SADL - Translates CDS annotations into the corresponding OData annotations. Values:
	Value	Description
	`String`	For more information Based on Intent.
`Consumption.valueHelp`	This annotation enables referencing of the association to a CDS view / 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. Values:
	Value	Description
	`elementRef`

Examples

Example 1

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

Sample Code

DEFINE VIEW SalesOrder
AS SELECT FROM sepm_cds_sales_order AS so
{
  key so.sales_order_id AS SalesOrderId,
  
  @Consumption.labelElement: 'CompanyName'
  @Consumption.quickInfoElement: 'CompanyDescription'
  so.buyer_guid AS BuyerGuid,

  so.company_name AS CompanyName,
  
  so.description AS CompanyDescription
}

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:

Sample Code

DEFINE VIEW SalesOrder with parameters
AS SELECT FROM sepm_cds_sales_order AS so
{
  key so.sales_order_key AS NodeKey,
  
  so.buyer_guid AS BuyerGuid,
  
  @Consumption.groupWithElement: 'BuyerGuid'
  so.company_name AS CompanyName,
  
  so.currency_code AS CurrencyCode,

  @DefaultAggregation: #SUM
  so.gross_amount AS GrossAmount
}

Example 3

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

Sample Code

DEFINE VIEW SalesOrder
AS SELECT FROM sepm_cds_sales_order AS so
  ASSOCIATION [0..1] TO sepm_cds_business_partner AS _Customer 
  on $projection.BuyerGuid = _Customer.business_partner_key
{
  
  key so.sales_order_id AS SalesOrderId,
 
  @Consumption.hidden: true
  so.buyer_guid AS BuyerGuid,
 
  _Customer.company_name AS CompanyName
}

Example 4

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

Sample Code

DEFINE VIEW SalesOrder with parameters
    @Consumption.defaultValue: 'EUR' 
    p_TargetCurrency : snwd_curr_code
AS SELECT FROM sepm_cds_sales_order AS so
{
  key so.sales_order_key AS NodeKey,
  
  $parameters.p_TargetCurrency AS CurrencyCode,

  currency_conversion( 
    amount              => so.gross_amount, 
    source_currency     => so.currency_code, 
    target_currency     => $parameters.p_TargetCurrency,
    exchange_rate_date  => CAST( '20150101' AS abap.dats )
  ) AS GrossAmount
}

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:

Sample Code

DEFINE VIEW CurrencyCodeValueHelp
AS SELECT FROM currency_code
{
  key CurrencyCode,
  CurrencyName,
  CurrencyDescription
}

DEFINE VIEW SalesOrder
AS SELECT FROM sepm_cds_sales_order AS so
  ASSOCIATION [0..1] TO CurrencyCodeValueHelp AS _Currency
  on $projection.BuyerGuid = _Customer.business_partner_key    
{
  so.sales_order_id AS SalesOrderId, 

  @Consumption.valueHelp: '_Currency'
  so.currency_code AS CurrencyCode,

  so.gross_amount AS GrossAmount  
}

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.

Sample Code

@Consumption.semanticObject: 'SalesOrder'
DEFINE VIEW SalesOrder    
AS SELECT FROM sepm_cds_sales_order AS so
{
  so.sales_order_id AS SalesOrderId, 

  @Consumption.semanticObject: 'BusinessPartner'
  so.buyer_guid AS BuyerGuid,
}

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.

Sample Code

@Analytics.query : true
DEFINE VIEW product_hierarchy
AS SELECT FROM sales
{  
   ...
   @Consumption.filter : { selectionType : #SINGLE, multipleSelections : true}    
   calendar_day,    //several single values are allowed
   @Consumption.filter : { selectionType : #INTERVAL, multipleSelections : false }  
   product,      	  // single interval allowed  
   ...
}

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.

Sample Code

@Analytics.query : true
DEFINE VIEW costcenter_reporting
  with parameters cost_center_hier_param : String 
AS SELECT FROM costcenters
{
  ...
  @Consumption.filter : {
    selectionType : #HIERARCHY_NODE, 
    multipleSelections : false,
    hierarchyBinding :
    [ { type : #CONSTANT, value : 'CONTR_AREA_10' }, 
      { type : #PARAMETER, value : 'cost_center_hier_param' } ]
  }
  costcenter,     // hierarchy node filter
 
  costs,
  ...
}