how to use odata analytics in sadl-based services · 1 using odata analytics in sadl-based services...

CUSTOMER

SAP NetWeaver 7.40 SP10 and higherDocument Version: 7.40 SP10 V1 – 2015-03-09

How to Use OData Analytics in SADL-Based ServicesOData Version 2.0

Content

1 Using OData Analytics in SADL-Based Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Document History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.1 Related Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4 Background Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.1 Analytical Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Element edm: EntityType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Element edm:Property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5 Step-by-Step Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85.1 Adding a Property for the Generated Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85.2 Mapping Properties to Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85.3 Generating Runtime Artifacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.4 Providing Analytical Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.5 Providing Aggregation Behavior Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.6 Improving Performance by Providing a Business Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.7 Transforming the Analytical ID into Key Values and Vice Versa. . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Transforming the Analytical ID into Key Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Creating the Analytical ID by Using Key Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6 Appendix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156.1 Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156.2 Support and Issue Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2C U S T O M E R© 2015 SAP SE or an SAP affiliate company. All rights reserved.

How to Use OData Analytics in SADL-Based ServicesContent

1 Using OData Analytics in SADL-Based Services

This document provides a detailed guide on how to annotate SADL-based Gateway Services in order to use analytical features.

You will learn how to:

1. Add a property for the generated key2. Map properties to elements3. Generate runtime artifacts4. Provide analytical annotations5. Provide aggregation behavior information

Starting with NW7.40 SP09, you can also perform the following (optional) tasks:6. Improve the runtime performance by providing a business key7. Transform the analytical ID into key value-pairs, or transform key-values into an analytical ID

The result of this tutorial is that you can configure a Gateway Service to return aggregated values, for example, a sum, a minimum value, or a maximum value.

How to Use OData Analytics in SADL-Based ServicesUsing OData Analytics in SADL-Based Services

C U S T O M E R© 2015 SAP SE or an SAP affiliate company. All rights reserved. 3

2 Document History

Table 1:

Document Version Description

7.40 SP07 V1 First official release of this guide, valid for SAP NetWeaver 7.4 SP07

7.40 SP08 V2 Revised and updated

7.40 SP09 V3 Update with new content:

● Business key provision● Transformation GENERATED_ID to key values and

revers


How to Use OData Analytics in SADL-Based ServicesDocument History

3 Prerequisites

Before performing this tutorial, take note of the following prerequisites:

● The SADL integration is provided for SAP NetWeaver 7.4 SP07 and higher.● This guide is only valid for OData Version 2.0.● This guide assumes that a Gateway Service is already configured. For service creation, the reader is kindly

referred to the Model a Gateway-Service based on Business Entities

3.1 Related Documents

This document is provided in the SAP Community Network (SCN), which is the social network for SAP professionals.

In addition to this guide, you will also find the following SADL-related documents in SCN:

● Fine-Tune the Execution of SADL-Based Gateway Services● Enforce Authorizations for SADL-Based Applications● Model a Gateway-Service based on Business Entities

NoteThe related documents might be relevant to each other. This means that if you want to execute the tutorial to model a Gateway-Service based business entities, for example, you will need to consider the authorization concept.

How to Use OData Analytics in SADL-Based ServicesPrerequisites


http://help.sap.com/disclaimer?site=http://scn.sap.com/docs/DOC-51475

http://help.sap.com/disclaimer?site=https://scn.sap.com/docs/DOC-51476

http://help.sap.com/disclaimer?site=https://scn.sap.com/docs/DOC-51474

4 Background Information

4.1 Analytical Annotations

Analytical annotations are semantic information that denotes whether an element is an analytical dimension or a measure, and which kind of aggregation is used in the Gateway Service.

OData services are self-describing in that they provide the semantic information related to their elements in their metadata document. This enables developers, but also generic UIs, to consume the Gateway Service.

4.1.1 Element edm: EntityType

4.1.1.1 Attribute sap:semantics

The sap:semantics attribute can have the following values in the context of edm.EntityType :

Table 2:

Value Meaning

aggregate Entity sets with this type return result feeds with aggregated values for properties annotated with sap:aggregation-role="measure".

The aggregation takes into account the dimension properties specified in the $select system query option of the request. See also description of Attribute sap:aggregation-role [page 7].


How to Use OData Analytics in SADL-Based ServicesBackground Information

4.1.2 Element edm:Property

4.1.2.1 Attribute sap:aggregation-role

A property can be annotated with the sap:aggregation-role attribute if it has an aggregation role.

The attribute can have the following values:

Table 3:

Value Meaning

Dimension The property represents the key of a dimension. Only valid for properties of an entity type that is annotated with sap:semantics=“aggregate“.

Measure The property represents a measure whose values will be aggregated according to the aggregating behavior of the containing entity type. Only valid for properties of an entity type that is annotated with sap:semantics=“aggregate“.

NoteFor more information , see SCN article SAP Annotations for OData Version 2.0 for further details regarding OData annotations and SAP semantics.

How to Use OData Analytics in SADL-Based ServicesBackground Information


http://help.sap.com/disclaimer?site=http://scn.sap.com/docs/DOC-44986

5 Step-by-Step Procedure

5.1 Adding a Property for the Generated Key

Services must provide a unique key that can be used by the client to retrieve a specified entity after receiving a list of entities, in order to conform to the OData standard. Analytical services must provide a dedicated key since the natural keys of the business entity are not usable in aggregated results.

Context

In transaction SEGW, add a property for the unique identifier of the returning results. The name of the property can be freely chosen. The type of the property must be Edm.String and this property needs to carry the ABAP field name ‘GENERATED_ID’.

Figure 1: Example of a returning properties table in the Gateway Service Builder

5.2 Mapping Properties to Elements

Procedure

1. Map the entity sets to a Business Entity. Choose ‘Map to Data Source’ from the context menu of the Service Implementation for the respective Entity Set.

Figure 2: Creation of a new mapping from the context menu


How to Use OData Analytics in SADL-Based ServicesStep-by-Step Procedure

2. Drag and drop the elements of the mapped Business Entity to the mapping table. The identifier and the count property do not need any mapping information. Leave the mapping element empty. The properties that correspond to analytical measures must be mapped against the elements that you want to aggregate.

Figure 3: Creating the mapping through drag-and-drop

5.3 Generating Runtime Artifacts

Context

After the mapping is concluded, check the service by selecting the Check Project Consistency icon from the toolbar.

Finally, generate the runtime artifacts by selecting the Generate Runtime Objects icon from the toolbar. This will generate the MPC and DPC classes corresponding to your service.

5.4 Providing Analytical Annotations

Maintain the analytical role for the entity types that carry aggregation information, and also maintain this role for their dimensions and measures.

Context

To do this, extend the MPC class of your Gateway Service.



Procedure

1. In the MPC_EXT class of your service, overwrite the define method.

PUBLIC SECTION. METHODS define REDEFINITION.

2. Call the super->define method, which will create all the properties and the annotations already maintained.

METHOD define . super->define( ).

3. Supply the aggregate semantics for your entity types.

DATA(lo_entity_type) = model->get_entity_type( 'FlightType' ). lo_entity_type->set_semantic( /iwbep/if_ana_odata_types=>gcs_ana_odata_semantic_value - query - aggregate ).

4. Classify each property of the entity type except the GENERATED_ID as measure or dimension.

An OData entity set is grouped by each requested dimension. Measures are aggregated, for example as sum of a price or as average time.

lo_entity_type = model->get_entity_type( 'FlightType' ). DATA(lo_property) = lo_entity_type->get_property( 'Country' ). DATA(lo_annotation) = lo_property->/iwbep/if_mgw_odata_annotatabl~create_annotation( /iwbep/if_mgw_med_odata_types =>gc_sap_namespace ). lo_annotation -> add( iv_key = /iwbep/if_ana_odata_types=> gcs_ana_odata_annotation_key-aggregation_role iv_value = /iwbep/if_ana_odata_types=> gcs_ana_odata_annotation_value-dimension-dimension ). lo_property = lo_entity_type->get_property( 'AverageFlightTime' ). lo_annotation = lo_property->/iwbep/if_mgw_odata_annotatabl~create_annotation( /iwbep/if_mgw_med_odata_types=>gc_sap_namespace ). lo_annotation->add( iv_key = /iwbep/if_ana_odata_types=>gcs_ana_odata_annotation_key-aggregation_role iv_value = /iwbep/if_ana_odata_types=>gcs_ana_odata_annotation_value-measure-measure ).



5.5 Providing Aggregation Behavior Information

Maintain the information about the aggregation behavior of the defined measures using the query options API.

Context

NoteThis will have no effect on the Odata metadata. For example, it will not result in any annotations.

Procedure

1. In the DPC_EXT class of your service, overwrite the if_sadl_gw_query_control~set_query_options method.

PUBLIC SECTION. METHODS if_sadl_gw_query_control~set_query_options REDEFINITION.

2. In the method implementation, set the count field.

io_query_options-> set_count_field_name ( 'FLIGHT_COUNT' ).

3. Set the aggregation fields.

Provide the measure to be aggregated as ‘element’ and the ABAP field name of the property that contains the result of the aggregation as ‘alias’.

io_query_options->set_aggregation( VALUE #( ( element = 'FLTIME' alias = 'FLTIME' type = if_sadl_gw_query_options=>co_aggregation_type-avg ) ) ).

5.6 Improving Performance by Providing a Business Key

Analytical services require aggregation and grouping to be performed on the database. If the business key (semantic key) of the business entity mapped to the service is part of the properties selected by the client, the groups will contain exactly one record, thus rendering the grouping useless. The runtime of your service is improved by suppressing aggregation and grouping in this case.



Context

If the business entity does not have a key, or no key elements are mapped to the service properties, you should override the business key in order to retain the performance gain.

Procedure

1. In the DPC_EXT class of your service, overwrite the if_sadl_gw_query_control~set_query_options method.

PUBLIC SECTION. METHODS if_sadl_gw_query_control~set_query_options REDEFINITION.

2. In the method implementation, set the elements of the business key.

io_query_options->set_business_key_for_analytics( VALUE #( ( 'ProductID' ) ) ).

3. Save and activate the classes.

Results

The runtime of your Gateway Service is now optimized by avoiding unnecessary database operations.

5.7 Transforming the Analytical ID into Key Values and Vice Versa

The generated analytical ID of each group contains the encoded values of all dimension values corresponding to the group. In some cases, mostly involving own implementation of the get or create methods, it may be necessary to get the key values corresponding to the generated ID, or alternatively, to fill a generated ID based on key values.



5.7.1 Transforming the Analytical ID into Key Values

You can get the dimension values contained in the analytical ID of each group, in case you want to use the key values to retrieve a self-implemented entity.

Procedure

1. In the DPC_EXT class of your service, overwrite the /iwbep/if_mgw_appl_srv_runtime~get_entityset method.

PUBLIC SECTION. METHODS /iwbep/if_mgw_appl_srv_runtime~get_entityset REDEFINITION.

2. In the method implementation, get an instance of the sadl_dpc object, and use it to retrieve the key values corresponding to the generated ID. The method returns the keys as name-value pairs.

if_sadl_gw_dpc_util~get_dpc( )->get_keys_from_analytical_id( EXPORTING io_tech_request_context = io_tech_request_context IMPORTING et_keys = DATA(lt_keys) ).

Perform the same steps in the get_entity method.

Results

You can now use the key values for subsequent processing, for example an own implementation of the get methods.

5.7.2 Creating the Analytical ID by Using Key Values

You can fill the analytical ID based on key values. While this is normally done following the get_entity or get_entityset execution, you need to supply the value of this key for own implementations.

Procedure

In the DPC_EXT class of your service: In the methods that you have overwritten to provide an own implementation, for example a *_CREATE_ENTITY method.

Get an instance of the sadl_dpc object, and set the ID corresponding to the ls_data field.

if_sadl_gw_dpc_util~get_dpc( )->fill_analytical_id( EXPORTING io_tech_request_context = io_tech_request_context iv_count_field_name = 'COUNT' "optional



CHANGING cs_data = ls_data ).

Results

The created entities are now completed, each containing their generated analytical ID.



6 Appendix

6.1 Terms

Table 4:

Term Description

Business Entity ● Entities that are used in business applications – for example, business objects, database tables, search views.

● Business model metadata interface that offers a harmonized metadata consumption of existing and new business models. The interface is implemented for BOPF and DDIC tables and views productively.

Business Entity type (or source) Specific repository or provider for business entity metadata – for example, Business Object Processing Framework, Data Dictionary, Core Data Services

SADL Engine Code performing the query execution, including view-building based on business entities.

6.2 Support and Issue Reporting

If a functional error with the SADL runtime occurs, report an incident for the BC-ESI-ESF-BSA application component.

If you have other technical issues, check the SAP Communication Network (SCN) .

How to Use OData Analytics in SADL-Based ServicesAppendix


http://help.sap.com/disclaimer?site=http://scn.sap.com/community/abap/hana

Important Disclaimers and Legal Information

Coding SamplesAny software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence.

AccessibilityThe information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not apply in cases of wilful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.

Gender-Neutral LanguageAs far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.

Internet HyperlinksThe SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency (see: http://help.sap.com/disclaimer).


How to Use OData Analytics in SADL-Based ServicesImportant Disclaimers and Legal Information

http://help.sap.com/disclaimer/

How to Use OData Analytics in SADL-Based ServicesImportant Disclaimers and Legal Information


www.sap.com/contactsap

© 2015 SAP SE or an SAP affiliate company. All rights reserved.No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.Please see http://www.sap.com/corporate-en/legal/copyright/index.epx for additional trademark information and notices.

http://www.sap.com/contactsap

http://www.sap.com/corporate-en/legal/copyright/index.epx

http://www.sap.com/corporate-en/legal/copyright/index.epx