Consumption Annotations
Define a specific behavior that relates to the consumption of CDS content through domain-specific frameworks.
@Scope:[#ELEMENT, #PARAMETER]
Annotation Consumption
{
labelElement : elementRef;
quickInfoElement : elementRef;
valueHelp : elementRef;
hidden : Boolean default true;
derivation
{
lookupEntity : entityRef;
resultElement : 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]
{
filter
{
mandatory : Boolean default true;
defaultValue : Expression;
defaultValueHigh : Expression;
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;
};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. 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). 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. 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.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. Note If parameter values are used in this sub-annotation, the corresponding
parameter must be declared before the parameter that is to
be derived.i
Note All provided annotation values are treated case sensitive.
|
||
| 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.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):
Note
This element should be exposed by UIs. UIs based on Analytic Manager will offer this element as variables. |
||
| 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 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.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. Note
You can also use the annotation AnalyticsDetails.query.hierarchyBinding.variableSequence. 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). 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 ...". After the user has entered a value , the
entered value is then sent to the engine. Therefore, the
Filter UI ensures that automatic replacement by the engine
is never performed for mandatory filters.
|
||
| 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. 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.
|
||
| 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):
Note
The field will not be exposed to UIs. |
||
| 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.
Note
We recommend to use ObjectModel.text.element[ ] instead of the Consumption.labelElement annotation. |
||
| 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. Example SAP Fiori has introduced the concept of intent-based navigation, whereby an
intent is a combination of <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. |
||
| 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 | |||
The annotations Consumption.labelElement and Consumption.quickInfo are used to link the corresponding text and ID fields:
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
}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:
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
}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:
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
}The annotation Consumption.defaultValue is used to specify default values for parameters. In this example, the currency EUR is used:
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
}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:
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
}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.
@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,
}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.
@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
...
}
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.
@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,
...
}